[jira] [Resolved] (CAMEL-25197) camel-cli-connector - add a WebSocket transport so developer tools can drive running integrations

["Federico Mariani (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CAMEL-25197?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Federico Mariani resolved CAMEL-25197.
--------------------------------------
    Resolution: Fixed

> 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
>            Assignee: Federico Mariani
>            Priority: Major
>             Fix For: 4.18.5, 4.22.2, 4.23.0
>
>         Attachments: camel-cli-connector-websocket-soak-test.zip
>
>
> 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)