Skip to content

ws://

WebSocket client (RFC 6455). Built on github.com/gorilla/websocket. For TLS, use wss://. For server-side, use ws-server:// or wss-server://.

URI shape

ws://host[:port][/path]?…

Two roles in one scheme:

  • Producer (default): connects on the first Process call and sends each message body as a single frame.
  • Consumer (when consumeAsClient=true): connects out and emits each inbound frame as an Exchange.

Parameters

Common

Param Type Default Description
host string from URI WebSocket host.
port integer 80 WebSocket port (443 on wss://).
path string / HTTP path for the upgrade request.
handshakeTimeout duration 45s Handshake timeout.
pingInterval duration 30s Ping/keepalive interval. 0 disables.
maxMessageSize integer 0 Max inbound message bytes. 0 = unlimited.

TLS

Param Type Default Description
tls boolean false Enable TLS. Auto-set on wss://.
tlsInsecure boolean false Skip cert verification (testing only).
tlsServerName string host SNI override.
tlsCert / tlsKey / tlsCA string — Client cert + key + CA.

Consumer (consumeAsClient=true)

Param Type Default Description
consumeAsClient boolean false Required for client-side consumer.
maxReconnectAttempts integer 0 (∞) Cap on reconnect attempts.
reconnectInitialDelay duration 0 Delay before first reconnect.
reconnectInterval duration 1s Delay between attempts.
fireWebSocketConnectionEvents boolean false Emit HelixWsEvent=onOpen/onClose/onError synthetic Exchanges.

Producer

Param Type Default Description
clientSubProtocols string — CSV of sub-protocols advertised via Sec-WebSocket-Protocol.
handshakeHeaders string — CSV of Key:Value pairs added to the handshake request.
originHeaderUrl string — Override Origin on outbound connect.

Headers

Header Direction
HelixWsConnectionKey Both
HelixWsEvent Written by consumer (onOpen/onClose/onMessage/onError)
HelixWsRemoteAddress Written by consumer
HelixWsSubProtocol Written by consumer (negotiated sub-protocol)
HelixWsPath Written by consumer

Body shape

  • Producer: body is string → text frame; []byte → binary frame (or text when Content-Type: text/*).
  • Consumer: body is the inbound frame bytes; Content-Type set to text/plain for text frames, application/octet-stream for binary.

YAML examples

workflows:
  # 1. Outbound client producer — push each direct:// message to a remote WS server.
  - id: ws-push
    description: Send messages to wss://api.example.com/stream
    trigger:
      uri: direct://outbound
    steps:
      - to: wss://api.example.com:443/stream?clientSubProtocols=v1.json

  # 2. Inbound client consumer — connect out and stream messages.
  - id: ws-pull
    description: Connect to wss://api.example.com/feed and emit each frame.
    trigger:
      uri: wss://api.example.com:443/feed
      params:
        consumeAsClient: "true"
        maxReconnectAttempts: "10"
        reconnectInterval: "5s"
        clientSubProtocols: "v1.stream,v1.compact"
        originHeaderUrl: "https://helix.example.com"
        fireWebSocketConnectionEvents: "true"
    steps:
      - log:
          message: "WS ${headers.HelixWsEvent}: ${body}"

  # 3. Custom handshake headers (auth token).
  - id: ws-auth
    description: Pass an Authorization header in the handshake.
    trigger:
      uri: wss://api.example.com/stream?consumeAsClient=true&handshakeHeaders=Authorization:Bearer%20abc123,X-Tenant:helix
    steps:
      - log:
          message: "${body}"

See also