Subscriptions Configuration

This section explains how you can configure Subscriptions both for local development and using Cosmo Studio.

When using Subscriptions with Cosmo Router locally or through Cosmo Studio, you’d need to configure the correct protocol to talk to your Subgraphs. Cosmo Router Supports WebSockets as well as the SSE (Server-Sent Events) for transport. When using WebSockets, the Router automatically negotiates with the Subgraph what protocol to use. The protocols “graphql-ws” and “graphql-transport-ws” are both supported.

Configure Subscriptions for local development

When composing a Graph locally, you can supply the protocol using the following configuration.

version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "ws"

If your Subgraph uses SSE, use the following configuration.

version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "sse"

If your Subgraph uses SSE over HTTP POST, the config should look like this.

version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      protocol: "sse_post"

If your Subscriptions Endpoint differs from the default routing URL, you can use the following configuration.

version: 1
subgraphs:
  - name: employees
    routing_url: "http://localhost:4001/graphql"
    subscription:
      url: "http://localhost:4001/subscriptions"
      protocol: "sse_post"

Configure Subscriptions using wgc

When using Cosmo Studio as a target to publish your Subgraphs, you’ll be using “wgc publish” to upload the Subgraph configuration to the Studio. In this case, you can supply the protocol using the following config.

Setting a custom Subscriptions protocol on wgc publish

npx wgc subgraph publish products --subscription-protocol sse --schema ../demo/subgraphs/products/products.graphql

Available options are “sse”, “sse_post”, and “ws”.

Setting a custom Subscriptions URL on wgc publish

npx wgc subgraph publish products --subscription-url "http://localhost:4001/subscriptions" --schema ../demo/subgraphs/products/products.graphql

You can also use `wgc subgraph update …` to update the Subscriptions protocol or URL for a specific Subgraph.

Tuning the upstream subscription client

The router’s upstream WebSocket client (the one that connects to subgraphs for subscriptions) is configured under the engine block. The defaults suit most deployments. The options below are listed with their YAML field and the matching environment variable.

Option	Env var	Default	Purpose
websocket_client_write_timeout	ENGINE_WEBSOCKET_CLIENT_WRITE_TIMEOUT	10s	The timeout for the websocket write of the WebSocket client implementation.
websocket_client_ping_interval	ENGINE_WEBSOCKET_CLIENT_PING_INTERVAL	15s	The Websocket client ping interval to the subgraph. Defines how often the router will ping the subgraph to signal that the connection is still alive.
websocket_client_ping_timeout	ENGINE_WEBSOCKET_CLIENT_PING_TIMEOUT	30s	The Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph.
websocket_client_ack_timeout	ENGINE_WEBSOCKET_CLIENT_ACK_TIMEOUT	30s	How long the router waits for connection_ack from a subgraph after sending connection_init.
websocket_client_read_limit	ENGINE_WEBSOCKET_CLIENT_READ_LIMIT	1MB	Maximum size of a single incoming WebSocket message from a subgraph.

Example:

version: "1"

engine:
  websocket_client_write_timeout: 10s
  websocket_client_ping_interval: 15s
  websocket_client_ping_timeout: 30s
  websocket_client_ack_timeout: 30s
  websocket_client_read_limit: 1MB

Tuning the server-side WebSocket handler

These options apply to the router’s own WebSocket endpoint (the one clients connect to). They are separate from the upstream client options above.

Option	Env var	Default	Purpose
websocket_server_read_timeout	ENGINE_WEBSOCKET_SERVER_READ_TIMEOUT	5s	Read timeout for the server-side WebSocket handler.
websocket_server_write_timeout	ENGINE_WEBSOCKET_SERVER_WRITE_TIMEOUT	10s	Write timeout for the server-side WebSocket handler.
websocket_server_poll_timeout	ENGINE_WEBSOCKET_SERVER_POLL_TIMEOUT	1s	Timeout for the poll loop of the server-side WebSocket handler.
websocket_server_conn_buffer_size	ENGINE_WEBSOCKET_SERVER_CONN_BUFFER_SIZE	128	Buffer size for the poll buffer of the server-side WebSocket handler. Determines how many connections can be handled in one loop.
enable_net_poll	ENGINE_ENABLE_NET_POLL	true	Enables the more efficient poll implementation for the server-side WebSocket handler. Linux and macOS only. Has no effect on upstream subgraph connections.

Subject to change. enable_net_poll, websocket_server_poll_timeout, and websocket_server_conn_buffer_size may be removed or changed in a future release without a standard deprecation cycle. Avoid depending on them.

If you are upgrading from an older release and your configuration sets websocket_client_poll_timeout, websocket_client_read_timeout, websocket_client_conn_buffer_size, or websocket_client_frame_timeout, see the Subscriptions Overhaul migration guide.