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]
