GraphQL subscriptions with a self-hosted router

With GraphOS Enterprise, self-hosted instances of the Apollo Router provide support for GraphQL subscription operations:

1
subscription OnStockPricesChanged {
2
  stockPricesChanged {
3
    symbol
4
    price
5
  }
6
}

With subscription support enabled, you can add Subscription fields to the schema of any subgraph that supports common WebSocket protocols for subscription communication:

1
type Subscription {
2
  stockPricesChanged: [Stock!]!
3
}

What are subscriptions for?

GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. This means a client can receive multiple updates from a single subscription:

Subscriptions are best suited to apps that rely on frequently-changing, time-sensitive data (such as stock prices, IoT sensor readings, live chat, or sports scores).

How it works

1. A client executes a GraphQL subscription operation against your self-hosted router over HTTP:

   GraphQL

   Example subscription

   1
   subscription OnStockPricesChanged {
   2
     stockPricesChanged {
   3
       symbol
   4
       price
   5
     }
   6
   }

   Copy
   • The client does not use a WebSocket protocol! Instead, it receives updates via multipart HTTP responses.
   • By using HTTP for subscriptions, clients can execute all GraphQL operation types over HTTP instead of using two different protocols.
   • Apollo Client for Web, Kotlin, and iOS all support GraphQL subscriptions over HTTP with minimal configuration. See each library's documentation for details.

2. When your router receives a subscription, it executes that same subscription against whichever subgraph defines the requested field (stockPricesChanged in the example above).

   • This communication usually does use a WebSocket subprotocol, for compatibility with most subgraph libraries.
   • An HTTP-callback-based protocol is also available in preview. See HTTP callback setup.

3. The subgraph periodically sends new data to your router. Whenever it does, the router returns that data to the client in an additional HTTP response "chunk".

   • A subscription can include federated entity fields that are defined in other subgraphs. If it does, the router first fetches those fields by querying the corresponding subgraphs (such as Portfolios in the diagram above). These queries use HTTP as usual.

Special considerations

• Whenever your router updates its supergraph schema at runtime, it terminates all active subscriptions. Clients can detect this special-case termination via an error code and execute a new subscription.

  See Termination on schema update.

Prerequisites

⚠️ Before you add Subscription fields to your subgraphs, do all of the following in the order shown to prevent schema composition errors:

1. Update your Apollo Router instances to version 1.22.0 or later. Download the latest version.

   • Previous versions of the Apollo Router don't support subscription operations.

2. Make sure your router is connected to a GraphOS Enterprise organization.

   • Subscription support is an Enterprise feature of self-hosted routers.

3. If you compose your router's supergraph schema with GraphOS (instead of with the Rover CLI), update your build pipeline to use Apollo Federation 2.4 or later.

   • Previous versions of Apollo Federation don't support subscription operations.

4. Modify your subgraph schemas to use Apollo Federation 2.4 or later:

   GraphQL

   stocks.graphql

   1
   extend schema
   2
   @link(url: "https://specs.apollo.dev/federation/v2.4", 
   3
         import: ["@key", "@shareable"])
   4
   
   5
   type Subscription {
   6
     stockPricesChanged: [Stock!]!
   7
   }

   Copy
   • You can skip modifying subgraph schemas that don't define any Subscription fields.

After you complete these prerequisites, you can safely configure your router for subscriptions.

Router setup

In your router's YAML config file, you configure how the router communicates with each of your subgraphs when executing GraphQL subscriptions.

The Apollo Router supports two popular WebSocket protocols for subscriptions, and it also provides preview support for an HTTP-callback-based protocol. Your router must use whichever protocol is expected by each subgraph!

WebSocket setup

Here's an example router configuration snippet that sets up subgraph subscriptions over WebSocket:

1
subscription:
2
  enabled: true
3
  mode:
4
    passthrough:
5
      all: # The router uses these subscription settings UNLESS overridden per-subgraph
6
        path: /subscriptions # The URL path to use for subgraph subscription endpoints (Default: /ws)
7
      subgraphs: # Overrides subscription settings for individual subgraphs
8
        reviews: # Overrides settings for the 'reviews' subgraph
9
          path: /ws # Overrides '/subscriptions' defined above
10
          protocol: graphql_transport_ws # The WebSocket-based subprotocol to use for subscription communication (Default: graphql_ws)

This example enables subscriptions in passthrough mode, which uses long-lived WebSocket connections.

The router supports the following WebSocket subprotocols, specified via the protocol option:

• graphql_ws
  • Legacy subprotocol used by the subscriptions-transport-ws library, which is unmaintained
  • For backward compatibility, this is the default value.
• graphql_transport_ws
  • Used by the graphql-ws library
  • This subprotocol is recommended for GraphQL server libraries implementing WebSocket-based subscriptions.

By default, the router uses graphql_ws for all subgraphs. You can change this global default and/or override it for individual subgraphs by setting the protocol key as shown above.

Your router creates a separate WebSocket connection for each client subscription, unless it can perform subscription deduplication.

HTTP callback setup (preview)

The Apollo Router provides preview support for receiving subgraph subscription events via HTTP callbacks, instead of over a persistent WebSocket connection. This callback mode provides the following advantages over WebSocket-based subscriptions:

• The router doesn't need to maintain a persistent connection for each distinct subscription.
• You can publish events directly to the router from a pubsub system, instead of routing those events through the subgraph.

Callback mode requires your subgraph library to support the router's HTTP callback protocol.

Here's an example configuration that sets up subgraph subscriptions in callback mode:

1
subscription:
2
  enabled: true
3
  mode:
4
    preview_callback:
5
      public_url: https://example.com:4000 # The router's public URL
6
      listen: 0.0.0.0:4000 # The IP address and port the router will listen on for subscription callbacks
7
      path: /callback # The path of the router's callback endpoint
8
      subgraphs: # The list of subgraphs that use the HTTP callback protocol
9
        - accounts

Using a combination of modes

If some of your subgraphs require passthrough mode and others require callback mode for subscriptions, you can apply different modes to different subgraphs in your configuration:

1
subscription:
2
  enabled: true
3
  mode:
4
    passthrough:
5
      subgraphs:
6
        reviews: 
7
          path: /ws
8
          protocol: graphql_transport_ws
9
    preview_callback:
10
      public_url: http://public_url_of_my_router_instance:4000
11
      listen: 0.0.0.0:4000
12
      path: /callback
13
      subgraphs:
14
        - accounts 

In this example, the reviews subgraph uses WebSocket and the accounts subgraph uses HTTP-based callbacks.

Example execution

Let's say our supergraph includes the following subgraphs and partial schemas:

type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Int!
}

type Subscription {
  productPriceChanged: Product!
}

type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  score: Int!
}

Now, let's say a client executes the following subscription against our router (over HTTP!):

1
subscription OnProductPriceChanged {
2
  productPriceChanged {
3
    # Defined in Products subgraph
4
    name
5
    price
6
    reviews {
7
      # Defined in Reviews subgraph!
8
      score
9
    }
10
  }
11
}

When our router receives this operation, it executes a corresponding subscription operation against the Products subgraph (over a new WebSocket connection):

1
subscription {
2
  productPriceChanged {
3
    id # Added for entity fetching
4
    name
5
    price
6
    # Reviews fields removed!
7
  }
8
}

At any point after the subscription is initiated, the Products subgraph might send updated data to our router. Whenever this happens, the router does not immediately return this data to the client, because it's missing requested fields from the Reviews subgraph!

Instead, our router executes a standard GraphQL query against the Reviews subgraph to fetch the missing entity fields:

1
query {
2
  _entities(representations: [...]) {
3
    ... on Product {
4
      reviews {
5
        score
6
      }
7
    }
8
  }
9
}

After receiving this query result from the Reviews subgraph, our router combines it with the data from Products and returns the combination to the subscribing client.

Trying subscriptions with curl

To quickly try out the Apollo Router's HTTP-based subscriptions without setting up an Apollo Client library, you can execute a curl command against your router with the following format:

1
curl 'http://localhost:4000/' -v \
2
  -H 'accept: multipart/mixed; boundary="graphql"; subscriptionSpec=1.0, application/json' \
3
  -H 'content-type: application/json' \
4
  --data-raw '{"query":"subscription OnProductPriceChanged { productPriceChanged { name price reviews { score } } }","operationName":"OnProductPriceChanged"}'

This command creates an HTTP multipart request and keeps an open connection that receives new subscription data in response "chunks":

1
--graphql
2
content-type: application/json
3

4
{}
5
--graphql
6
content-type: application/json
7

8
{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":400,"reviews":[{"score":5}]}}}}
9
--graphql
10
content-type: application/json
11

12
{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":375,"reviews":[{"score":5}]}}}}
13
--graphql
14
content-type: application/json
15

16
{"payload":{"data":{"productPriceChanged":{"name":"Croissant","price":425,"reviews":[{"score":5}]}}}}
17
--graphql--

Subscription deduplication

By default, the Apollo Router deduplicates identical subscriptions. This can dramatically reduce load on both your router and your subgraphs, because the router doesn't need to open a new connection if an existing connection is already handling the exact same subscription.

The router considers subscription operations identical if all of the following are true:

• The operations sent to the subgraph have identical GraphQL selection sets (i.e., requested fields).
• The operations provide identical values for all headers that the router sends to the subgraph.

Disabling deduplication

You can disable subscription deduplication by adding the following to your router's YAML config file under the subscription key:

1
subscription:
2
  enabled: true
3
  enable_deduplication: false # default: true

Note that this is a global setting (not per-subgraph or per-operation).

Why disable deduplication?

Disabling deduplication is useful if you need to create a separate connection to your subgraph for each client-initiated subscription. For example:

• Your subgraph needs to trigger an important event every time a new client subscribes to its data.
  • This event doesn't trigger whenever the router reuses an existing connection.
• Your subscription needs to start by receiving the first value in a particular sequence, instead of the most recent value.
  • If a subscription reuses an existing connection, it starts by receiving the next value for that connection.
  • As a basic example, let's say a subscription should always fire events returning the integers 0 through 1000, in order. If a new subscription reuses an existing subgraph connection, it starts by receiving whichever value is next for the original connection, which is almost definitely not 0.

Advanced configuration

Termination on schema update

Whenever your router's supergraph schema is updated, the router terminates all active subscriptions.

When the router terminates subscriptions this way, it sends the following as a final response payload to all active subscribing clients:

1
{
2
  "errors": [
3
    {
4
      "message": "subscription has been closed due to a schema reload",
5
      "extensions": {
6
        "code": "SUBSCRIPTION_SCHEMA_RELOAD"
7
      }
8
    }
9
  ]
10
}

A client that receives this SUBSCRIPTION_SCHEMA_RELOAD error code can reconnect by executing a new subscription operation.

WebSocket auth support

By default, if you've configured your router to propagate HTTP Authorization headers to your subgraph, then the router automatically sets corresponding connectionParams when initiating a WebSocket connection to that subgraph.

For example, when your router sends the connection_init message to a subgraph, it includes the value of the Authorization header via the following payload:

1
{
2
  "connectionParams": {
3
    "token": "CONTENTS_OF_AUTHORIZATION_HEADER"
4
  }
5
}

To specify a custom payload for theconnection_init message, you can write a Rhai script and use the context directly:

1
fn subgraph_service(service, subgraph) {
2
  let params = Router.APOLLO_SUBSCRIPTION_WS_CUSTOM_CONNECTION_PARAMS;
3
  let f = |request| {
4
    request.context[params] = #{
5
            my_token: "here is my token"
6
        };
7
  };
8

9
  service.map_request(f);
10
}

Expanding event queue capacity

If your router receives a high volume of events for a particular subscription, it might accumulate a backlog of those events to send to clients. To handle this backlog, the router maintains an in-memory queue of unsent events.

You can configure the size of each event queue in your router's YAML config file, like so:

1
subscription:
2
  enabled: true
3
  queue_capacity: 100000 # Default: 128

Whenever your router receives a subscription event when its queue is full, it discards the oldest unsent event in the queue and enqueues the newly received event. The discarded event is not sent to subscribing clients.

If it's absolutely necessary for clients to receive every subscription event, increase the size of your event queue as needed.

Limiting the number of client connections

Client subscriptions are long-lived HTTP connections, which means they might remain open indefinitely. You can limit the number of simultaneous client subscription connections in your router's YAML config file, like so:

1
subscription:
2
  enabled: true
3
  max_opened_subscriptions: 150 # Only 150 simultaneous connections allowed

If a client attempts to execute a subscription on your router when it's already at max_open_subscriptions, the router rejects the client's request with an error.