Subscriptions Configuration - WunderGraph

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.