WebSockets
Use the GraphQL over WebSocket protocol with Hive Router for real-time subscriptions, for both client-to-router and router-to-subgraph communication.
The router supports the GraphQL over WebSocket protocol for both client-to-router and router-to-subgraph communication, covering everything from simple queries and mutations to long-lived subscriptions over a single connection.
Subgraphs
To forward subscriptions to subgraphs over WebSockets, configure the subscriptions.websocket section. Subgraphs must implement the GraphQL over WebSocket protocol for the router to connect to them over WebSockets. By default, subscriptions that share the same subgraph, resolved WebSocket endpoint, and inbound connection identity multiplex over one pooled WebSocket connection to the subgraph instead of each opening a dedicated socket. See Connection reuse and execution mode below to control or disable this.
Headers are forwarded to the subgraph WebSocket connection according to your header propagation configuration. The same rules that apply to regular HTTP requests apply here, so authorization headers, tracing headers, and any other propagated headers are carried through to the subgraph.
Configuration
You can configure a default for all subgraphs and optionally override it per-subgraph:
The path option controls the URL path used for the WebSocket connection to the subgraph. If not set, the subgraph’s default URL path is used with the scheme changed to ws (or wss for HTTPS). For example, if the subgraph URL is http://example.com/graphql and path is /ws, the router will connect to ws://example.com/ws.
Connection reuse and execution mode
Reuse and transport selection are controlled separately from the endpoint path, under
traffic_shaping.all.websocket
(or per-subgraph under traffic_shaping.subgraphs.<name>.websocket):
See traffic_shaping.<>.websocket.websocketexecute_mode configuration flag for additional information and options.
Compression
The router can offer the permessage-deflate extension when connecting to WebSocket-enabled subgraphs. When the subgraph accepts it, messages are compressed in both directions. A subgraph that does not support the extension declines it and the connection continues uncompressed.
It is disabled by default. Enable it for all subgraphs under traffic_shaping.all.websocket.permessage_deflate and override it per subgraph:
Compression trades CPU and memory for bandwidth. Each compressed connection allocates its own compressor and decompressor, which use about 420KiB together.
Clients
Client WebSocket support is configured at the root level under websocket - it is completely separate from the subscriptions configuration. A client can connect to the router over WebSockets and execute only queries and mutations without subscriptions ever being involved.
Synthetic HTTP Requests
Each WebSocket connection from a client is long-lived and can carry multiple GraphQL operations. For every operation sent over the connection - including single-shot operations like queries and mutations - the router creates a synthetic HTTP request. This means every operation goes through the full plugin system exactly as if it were a regular HTTP request. Authorization, header manipulation, rate limiting, and all other plugins apply uniformly regardless of whether the client connected over HTTP or WebSocket.
The WebSocket upgrade request itself is a regular HTTP request. It goes through the on_http_request plugin hook and the router.request coprocessor stage once per connection, and the request context they set is shared by all operations on that connection. Because the connection is served inside the upgrade request, that request finishes only when the socket closes, see on_http_request for what that means for its on_end callback.
Because operations are processed as synthetic HTTP requests, they share the same fingerprint space as regular HTTP requests. A query sent over WebSocket can deduplicate with the same query sent over HTTP, and a WebSocket subscription can deduplicate with the same subscription started over SSE (when the Accept header is excluded from the fingerprint). See Inbound Deduplication for details.
Configuration
TLS and wss://
When the router has inbound TLS enabled, WebSocket clients must use wss:// instead of ws://. The router accepts secure WebSocket upgrades on the same port as HTTPS.
enabled
Enables or disables WebSocket support for clients. Defaults to false. Can also be set via the WEBSOCKET_ENABLED environment variable.
path
The URL path the router listens on for WebSocket connections. Defaults to the same path as the GraphQL endpoint (i.e. /graphql). Must be an absolute path starting with /.
headers.source
WebSocket connections don’t carry HTTP headers beyond the initial upgrade handshake, so the router needs to know where to read headers from. The source option controls this:
-
connection(default) - Headers are read from theconnection_initmessage payload. After the WebSocket connection is established, the client sends aconnection_initmessage and all fields in its payload are treated as headers. This is the recommended approach for browser clients, which cannot set arbitrary headers on WebSocket connections.These headers are then validated against JWT rules and forwarded to subgraphs according to your header propagation configuration.
-
operation- Headers are read from theheadersfield inside each GraphQL operation’sextensions. This allows per-operation header overrides. -
both- Headers are accepted from both theconnection_initpayload and each operation’s extensions. Headers from operation extensions take precedence over those fromconnection_initwhen both are present. This is useful when the connection-level token needs to be overridable per-operation. -
none- No headers are accepted from inside the WebSocket connection. Use this when you don’t need to pass any auth or context headers through WebSocket messages. Headers listed inheaders.upgradeare still taken from the upgrade request.
headers.persist
Only has effect when source is both.
When persist is true, headers received from operation extensions are stored and reused for all subsequent operations on the same connection. When false (the default), each operation only uses its own extensions headers merged with the original connection_init headers - extensions headers from a previous operation are discarded.
This is particularly useful for handling tokens that expire during a long-lived connection. For example:
- The client connects and sends a
connection_initwith anAuthorizationheader containing a short-lived token. - The token expires. The client obtains a new token and sends the next operation with the updated
Authorizationheader in its extensions. - With
persist: true, the router stores the updated token and uses it for all subsequent operations on that connection, so the client doesn’t need to reconnect or repeat the token on every single operation.
The persisted headers only ever hold what the client sent. Headers listed in headers.upgrade are never persisted, they are always taken from the upgrade request.
headers.upgrade
The headers of an operation come from the client, either from the connection_init payload or from the operation extensions. Headers set by trusted infrastructure on the HTTP upgrade request, like the X-Real-IP header set by a reverse proxy, are not part of them.
The upgrade option lists the headers taken from the upgrade request and added to every operation on the connection. Defaults to an empty list.
- The listed headers are taken only from the upgrade request. Values with the same name sent by the client in the
connection_initpayload or in the operation extensions are discarded, regardless of thesourcesetting, so the client cannot spoof them. A listed header missing from the upgrade request is missing from the operation too. - They are read once per connection, after the
router.requestcoprocessor stage ran on the upgrade request, so a coprocessor can set or normalize them there. - They are visible to plugins, coprocessor stages, JWT authentication and expressions, and respect the header propagation rules, just like the headers of a regular HTTP request.
permessage_deflate
Accepts the permessage-deflate extension offered by WebSocket clients. When a client offers it, messages are compressed in both directions. Clients that do not offer it are not affected. Defaults to false.
Compression trades CPU and memory for bandwidth. Each compressed connection allocates its own compressor and decompressor, which use about 420KiB together.
graphql-ws
We recommend using graphql-ws on the client side. It handles all connection management, message framing, and reconnection logic automatically.
Apollo Client
Please refer to the Apollo Client WebSocket integration.
Relay
Please refer to the graphql-ws Relay integration recipe.
urql
Please refer to the graphql-ws urql integration recipe.