allthingssecurity opened a new pull request, #29296: URL: https://github.com/apache/camel/pull/29296
# Description [CAMEL-26630](https://issues.apache.org/jira/browse/CAMEL-26630) A design document for an exchange sanitizer: `design/exchange-sanitizer.adoc`, in the format of the other design documents. It is a design-only pull request, as the chaos design was (#28539); the code follows in its own pull requests, in the order the document lists. It follows the feedback Claus gave on Zulip on the first proposal. What the document proposes, in short: - **A dev-mode checker** that reports, when it happens, that the contracts of `AsyncProcessor` and of on completions are broken, with the exchange, route, step, class, threads and stacks. It checks user code (custom processors, components, aggregation strategies) as much as Camel's, in the tests users already have. - **The rules:** - R1: the callback of each call of a step's processor is called exactly once. Completed twice (logged at the second call, before it continues the exchange, with the first call's stack kept), threw before calling the callback, a callback after the throw, and "still pending" as a warning next to the inflight console. - R2: each consumer commit runs once, in the unit of work that holds it. "Commit" is defined: an on completion the consumer adds before routing, which can be handed over (seda) or shared (`shareUnitOfWork`), not `UnitOfWork.done`. - R3: one thread at a time, built on the `AsyncProcessor` contract (`doneSync` equals what `process` returned) and on sampled overlaps in time, as KCSAN does, with no dependency on a handover API. - R4: tasks an executor drops at shutdown are listed. - **Two listener SPIs in camel-api**, `StepListener` and `OnCompletionListener`. They only observe, and more than one can be installed, so the sanitizer runs with chaos (which uses the one-per-context `StepHook`, CAMEL-26338), the debugger, the tracer and JMX. The step wrapper is built by the channel only when a listener is installed, so with none a step costs nothing more. The document says how they relate to `StepHook`, `InterceptStrategy`, the advices of the channel and `EventNotifier`. - **Switched on like chaos:** a `camel-sanitizer` module with a `ContextServicePlugin`, on with profile `dev` or `camel.sanitizer.enabled=true`, never with `prod`. - **JUnit and CI from the start:** `@CamelSanitizer` fails a test on the first violation; the test dependency and system properties run an existing suite with it in CI; a Maven profile does it in the Camel build. - **Validation before each code PR:** the tests of this year's fixes run on the commits before the fixes, to show each is reported at the right step; the camel-core suite and the netty, netty-http, vertx-http and JMS request/reply suites on main, to show it is quiet; JMH in camel-performance-tests for the cost. - Pooled exchanges, production use and MCP tools are non-goals. Open questions at the end of the document: the names of the SPIs, where the step listener is called, the module location, the Maven profile, and whether R2 covers every on completion. AGENTS.md lists the document with the other design documents, marked as proposed. # 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-26630](https://issues.apache.org/jira/browse/CAMEL-26630). # 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. (Documentation only: `design/exchange-sanitizer.adoc` and one line in `AGENTS.md`; nothing is generated from them.) # 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]
