Skip to main content
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.
OptionEnv varDefaultPurpose
websocket_client_write_timeoutENGINE_WEBSOCKET_CLIENT_WRITE_TIMEOUT10sThe timeout for the websocket write of the WebSocket client implementation.
websocket_client_ping_intervalENGINE_WEBSOCKET_CLIENT_PING_INTERVAL15sThe 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_timeoutENGINE_WEBSOCKET_CLIENT_PING_TIMEOUT30sThe Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph.
websocket_client_ack_timeoutENGINE_WEBSOCKET_CLIENT_ACK_TIMEOUT30sHow long the router waits for connection_ack from a subgraph after sending connection_init.
websocket_client_read_limitENGINE_WEBSOCKET_CLIENT_READ_LIMIT1MBMaximum 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.
OptionEnv varDefaultPurpose
websocket_server_read_timeoutENGINE_WEBSOCKET_SERVER_READ_TIMEOUT5sRead timeout for the server-side WebSocket handler.
websocket_server_write_timeoutENGINE_WEBSOCKET_SERVER_WRITE_TIMEOUT10sWrite timeout for the server-side WebSocket handler.
websocket_server_poll_timeoutENGINE_WEBSOCKET_SERVER_POLL_TIMEOUT1sTimeout for the poll loop of the server-side WebSocket handler.
websocket_server_conn_buffer_sizeENGINE_WEBSOCKET_SERVER_CONN_BUFFER_SIZE128Buffer size for the poll buffer of the server-side WebSocket handler. Determines how many connections can be handled in one loop.
enable_net_pollENGINE_ENABLE_NET_POLLtrueEnables 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.