Federico Mariani created CAMEL-25197:
----------------------------------------
Summary: camel-cli-connector - add a WebSocket transport so
developer tools can drive running integrations
Key: CAMEL-25197
URL: https://issues.apache.org/jira/browse/CAMEL-25197
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Federico Mariani
camel-cli-connector exposes route control, send/receive, trace, debug, route
dumps, status and more to the Camel CLI, but only through files polled in
~/.camel. A tool must share the filesystem with the integration (no containers,
dev containers or remote dev clusters), gets snapshots on a poll interval
instead of pushed, and each tool ends up re-implementing its own agent for this.
h3. Proposal
Make the transport pluggable and add a WebSocket transport, selected with
{{camel.cli.transport=websocket}} (the file transport stays the default and is
unchanged).
* The integration dials out to the tool ({{camel.cli.websocket.url}}) with the
JDK WebSocket client: no new dependency, no port opened.
* Versioned JSON envelope: {{hello}} (once Camel is started),
{{action}}/{{result}} correlated by {{requestId}}, {{snapshot}} (status, trace,
receive, debug, history, error, activity). The action and snapshot JSON are the
same as the file protocol.
* {{result.ok}} is false for unknown or failing actions, including failures
reported inside the action result.
* Reliability: exponential backoff with jitter on reconnect, ping heartbeat to
detect a tool that went away without closing, a hanging send aborts and
reconnects, trace/receive snapshots are incremental and split below 256 KB (the
default limit of Vert.x/Quarkus servers), actions run on their own thread with
a bounded queue.
* {{stop}} action to shut the integration down.
* Security (development tool, the connected tool gets full control, as the
Camel CLI has today):
** refuses to start with the {{prod}} profile;
** token ({{Authorization: Bearer}}) required unless the tool is on a loopback
address; can come from the {{CAMEL_CLI_WEBSOCKET_TOKEN}} environment variable;
** warns at startup, and when using {{ws://}} to a remote host; never logs the
URL query string.
h3. Internal changes
* SPI extracted from {{LocalCliConnector}}: {{CliActionDispatcher}},
{{CliSnapshotProducer}}, {{CliConnectorTransport}}; the file protocol moves
as-is to {{FileCliConnectorTransport}}, covered by new file protocol tests.
Subclasses overriding {{sigterm()}} (Spring Boot, Quarkus) keep working.
h3. Validation
Unit tests with an in-test WebSocket server; end-to-end with the Camel CLI
(file transport); a 240 s soak test with 5 Camel Main apps (1.3M actions,
~5,600/s, p99 < 6 ms) through disruptions (tool closes connections, network
blackhole, tool down, token rejected). All recovered and the applications' own
routes were unaffected. The soak test harness is attached (see its README).
h3. Follow-ups
* Spring Boot starter and Camel Quarkus extension: configuration, and using the
runtime's WebSocket client when present.
* Related: CAMEL-25195 (base64 bodies for the send action, needed to send
binary messages).
_Claude Code on behalf of Croway_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
