WS component

Q: How do I connect over TLS?

Use wss://host/path. The certificate is checked against the system trust store, or the trust store in sslContextParameters.

Q: How do I send a message to the server?

to: ws://host:port/path sends the body on the connection; a consumer on the same URI receives the replies.

Q: What happens when the server goes away?

Without reconnectInterval the consumer stops receiving. With it, the client reconnects on that interval.

The ws component is a WebSocket client: it connects to a WebSocket server, receives the server's messages as exchanges and sends messages on the same connection.

Scheme: ws: · Also: wss: · Crate: cameleer-protocols · Cargo feature: protocols · Consumer: yes · Producer: yes · Apache Camel: AHC WebSocket

wss: connects over TLS and always verifies the server certificate. To run a WebSocket server, use websocket or vertx-websocket.

When to use it

Subscribe to a streaming API (market data, chat, a realtime events feed) and route each message.
Connect an edge device to a central WebSocket hub and receive commands.
Send messages to a WebSocket service from any route.

URI format

text

ws://host[:port]/path[?options]
wss://host[:port]/path[?options]

Default ports: 80 for ws, 443 for wss. A consumer and a producer with the same URI share one connection.

Example

An edge agent that connects to a central hub, receives commands and keeps only those addressed to its site. reconnectInterval makes the client reconnect after the connection drops.

yaml example: ws-edge-commands

- route:
    id: hub-commands
    from:
      uri: "ws://{{env:HUB_ADDRESS:localhost:9292}}/commands?reconnectInterval=5s"
      steps:
        - filter:
            simple: "${body} starts with '{{env:SITE_ID:site-1}}:'"
            steps:
              - log: "command for this site: ${body}"

Rust DSL

rust

fn hub_commands_route(b: &mut RouteBuilder, hub: &str) {
    b.from(&format!("ws://{}/commands?reconnectInterval=5s", hub))
        .route_id("hub-commands")
        .filter(simple("${body} starts with 'site-1:'"))
        .log("command for this site: ${body}");
}

Options

option	default	description
`connectTimeout`	`10s`	Connect and handshake timeout.
`reconnectInterval`	`0`	Consumer: reconnect after this delay when the connection drops (`0` = no reconnect).
`subProtocol`		Subprotocols to request. Aliases `subProtocols`, `clientSubProtocols`.
`maxTextMessageSize`, `maxBinaryMessageSize`, `maxMessageSize`	64 MiB	Largest incoming message.
`maxFrameSize`	65536	Fragment outgoing messages into frames of this size.
`sslContextParameters`		`wss`: `#bean` with the trust store (and a key store for client certificates).
`useGlobalSslContextParameters`	`false`	`wss`: use the global `camel.ssl.*` parameters.

Options of Apache Camel's AHC client (clientOptions, reconnectMaxAttempts, ...) are accepted and ignored.

Message headers

header	direction	description
`CamelWebsocketConnectionKey`	out	Key of the client connection.

Text messages arrive as strings and binary messages as bytes. The producer sends byte bodies as binary messages and anything else as text.

Run it with Docker

docker run --rm -e HUB_ADDRESS=hub.example.com:9292 -e SITE_ID=site-7 \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/hub-commands.camel.yaml

Common questions

How do I connect over TLS?

Use wss://host/path. The certificate is checked against the system trust store, or the trust store in sslContextParameters.

How do I send a message to the server?

to: ws://host:port/path sends the body on the connection; a consumer on the same URI receives the replies.

What happens when the server goes away?

Without reconnectInterval the consumer stops receiving. With it, the client reconnects on that interval.

websocket, vertx-websocket: WebSocket servers.
http: request/response HTTP calls.
Apache Camel: AHC WebSocket component.

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.