allthingssecurity opened a new pull request, #30352:
URL: https://github.com/apache/camel/pull/30352

   # Description
   
   [CAMEL-27109](https://issues.apache.org/jira/browse/CAMEL-27109), part of 
[CAMEL-26630](https://issues.apache.org/jira/browse/CAMEL-26630) (exchange 
sanitizer), after R3a 
([CAMEL-26966](https://issues.apache.org/jira/browse/CAMEL-26966), #30243).
   
   Step 4 of the "Order of work" of `design/exchange-sanitizer.adoc`, second 
part: the sampled watch windows of rule R3 ("one thread at a time", "Accesses 
that overlap in time"). R1, R2 and the R3a contract are unchanged.
   
   What this PR does not do yet, and the design asks for before R3 is complete: 
the runs on the test suites of the async components (netty, netty-http, 
vertx-http, JMS request/reply), a TLA+ model of the windows, and a JMH run with 
the sampling on. The design's plan of work says so. The sampling is off by 
default outside tests, so nothing changes for an application.
   
   ## What it adds
   
   At a sample of the points where the routing engine uses an exchange, the 
sanitizer opens a short watch window on the exchange, and that thread pauses. 
If another thread uses the same exchange at one of these points during the 
window, both are reported with their stacks, as a new kind 
`USED_BY_TWO_THREADS` (`getRule()` returns `R3`).
   
   - The points: a step is called, the callback of a step continues the 
exchange, an on completion runs. The return of `process` is not a point: after 
an async processor handed the exchange on, its caller only unwinds.
   - A thread that only waits (such as the caller of a circuit breaker waiting 
for its task) uses nothing, so it is not reported.
   - The pause uses the system clock (`System.nanoTime`), not `TimeSource`, so 
a virtual clock of camel-test-dst does not stretch it. An interrupt ends it.
   - The windows are keyed by the exchange id and the identity hash of the 
exchange. They hold no exchange and no thread, and each is removed in a 
`finally`.
   
   Options:
   
   | Option | Default | |
   |---|---|---|
   | `camel.sanitizer.overlapSampling` | `0` (off), also with profile `dev`; 
`100` in a test marked by the JUnit extension | open a window at every Nth 
point (a counter per context). With `0` the listener is not installed. |
   | `camel.sanitizer.overlapWindow` | `1ms` | how long the thread pauses |
   
   A test class that fails only because of the pauses (a short timeout, a 
throttler) turns the sampling off for itself with 
`@CamelSanitizer(overlapSampling = 0)`. The annotation wins over the property.
   
   ## Decisions for review
   
   1. **No overlap report for an exchange that already has a violation** (R1, 
R2 or the R3a contract), and at most one overlap report per exchange. Two 
threads that both continue an exchange because its callback was called twice, 
or because `process` returned the wrong value, overlap as a consequence of that 
violation. Without this, every test that expects one of those violations would 
get a second, random `USED_BY_TWO_THREADS`. The thread that continues a second 
time records its violation before its next point, so the record is there when 
the window closes. This can hide an overlap with another cause on the same 
exchange; the docs say so. The claim is atomic, so two windows of one exchange 
that close together report once.
   2. **Copies with the same id are not reported.** 
`DefaultExchangeHolder.marshal` keeps the exchange id by default, and netty and 
mina `transferExchange` and the hazelcast seda consumer rebuild the exchange in 
the same JVM with the sender's id, routed beside the sender. Only a point of 
the same exchange object marks a window.
   3. A separate step listener (not folded into the R3a one), so that "off" 
means "not installed".
   4. A callback point can be inside a component's lock, and the pause then 
holds it for 1 ms. The design accepts this for R3 in tests.
   
   ## Tests
   
   New, in camel-core (`org.apache.camel.sanitizer`):
   
   - `SanitizerOverlapsTest`: the windows on their own (open, mark, close, 
report once, copies with the same id, no leak). The windows end with an 
interrupt, so nothing depends on timing.
   - `SanitizerOverlapTest`: a processor that sends the exchange itself to 
another route on its own thread is reported with both threads named (the two 
threads meet on a latch); a caller that waits for its task is not reported; a 
copy with the id of the exchange is not reported.
   - `SanitizerOverlapHandoverTest`: correct handovers stay quiet with a window 
at every point: seda InOnly and InOut, the threads EIP, parallel split, 
multicast and recipient list, an async delay, an async processor, a waiting 
caller, wire tap, enrich, loop copy, aggregate, a parallel onCompletion, and 
250 exchanges at once.
   - `CamelSanitizerExtensionTest`, `SanitizerActivationTest`, 
`SanitizerConfigurationPropertiesTest`: the options, their validation, the 
precedence, and that sampling `0` installs nothing.
   
   Runs (offline, with the versions cached on my machine):
   
   - camel-core sanitizer, step listener and on completion listener tests: 196 
run, 0 failures.
   - The three overlap test classes 25 times in one JVM: 450 of 450.
   - The whole sanitizer package and the listener tests with a window at every 
point (`-Dcamel.sanitizer.overlapSampling=1`), 3 times: 588 of 588. The R1, R2 
and R3a broken-code tests stay green, which exercises decision 1.
   - camel-main: `SanitizerConfigurationPropertiesTest` and 
`MainSanitizerWithoutJarTest` pass; the generate goals left no diff.
   - After the rebase on main (camel-main had gained options, so the generated 
metadata, `main.adoc` and the catalog copies were merged): camel-core 
`Sanitizer*Test` and `CamelSanitizerExtensionTest` 167 run, 0 failures; 
camel-main `SanitizerConfigurationPropertiesTest` and 
`MainSanitizerWithoutJarTest` 10 run, 0 failures; the generate goals left no 
diff.
   - The whole of camel-core with `-Psanitizer` (sampling 100), on the version 
before decision 2 was added (which only removes reports): 9522 tests, 2 
failures and 1 error, none from this rule. The failures are 
`AggregateOnCompletionThrowsTest`, the R1 report of CAMEL-26881 seen in the R3a 
runs; the error is `ValidatorExternalResourceTest`, which needs the network. 
The only `USED_BY_TWO_THREADS` report is the one `SanitizerOverlapTest` causes 
on purpose. So no core EIP is reported.
   
   Docs: a new section "Accesses that overlap in time" in `sanitizer.adoc` (the 
catalog copy is the same), the two options in the camel-main docs and metadata, 
and the design's summary, R3 text, options table and plan of work.
   
   Upgrade guide: none. camel-sanitizer is new in 4.24, so there is no earlier 
default to migrate from.
   
   Not in this PR: the dev console does not show the sampling yet, and the 
`checks` attribute of `@CamelSanitizer` named in the design is still not built.
   
   # Target
   
   - [x] I checked that the commit is targeting the correct branch (Camel 4 
uses the `main` branch)
   
   # Tracking
   - [x] If this is a large change, bug fix, or code improvement, I checked 
there is a [JIRA issue](https://issues.apache.org/jira/browse/CAMEL) filed for 
the change (usually before you start working on it): 
[CAMEL-27109](https://issues.apache.org/jira/browse/CAMEL-27109).
   
   # Apache Camel coding standards and style
   
   - [x] I checked that each commit in the pull request has a meaningful 
subject line and body.
   - [ ] I have run `mvn clean install -DskipTests` locally from root folder 
and I have committed all auto-generated changes.
     (I built camel-core, camel-main and camel-sanitizer with the formatter and 
import-sort plugins and the package plugin. I did not run the full root build.)
   
   # AI-assisted contributions
   
   - [x] If this PR includes AI-generated code, commits have proper 
co-authorship attribution (e.g., `Co-authored-by` trailers) and the PR 
description identifies the AI tool used.
     This PR was prepared with Claude Code (Claude Opus 5.5). The commit 
carries a `Co-Authored-By` trailer.
   
   _Claude Code on behalf of allthingssecurity_
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to