Overview

GraphQL subscriptions enable your clients to receive real-time data. This is essential for applications that need live updates - like notifications, live chat, stock tickers, collaborative editing, or IoT dashboards.

Hive Router provides full support for federated subscriptions out of the box. It works as a drop-in replacement for other federation routers, making it easy to add real-time capabilities to your federated GraphQL architecture.

How Subscriptions Work

Consider this subscription query against Hive Router:

subscription {
  reviewAdded {
    rating
    body
    author {
      name
    }
  }
}

This creates the following data flow:

Your client executes a subscription operation against Hive Router using any of the supported subscription protocols. The router then independently executes the same subscription against whichever subgraph defines the requested field - in this case, the Reviews subgraph that provides the reviewAdded field. The router communicates with subgraphs using whatever subscription protocol the subgraph supports, which does not have to match the protocol used by the client. For example, your client can subscribe using WebSockets while the router subscribes to subgraphs using HTTP callbacks or SSE.

When the Reviews subgraph sends new data, the router receives it and forwards it to the client. If the subscription includes federated entity fields from other subgraphs - like the author field that comes from the Users subgraph in this example - the router automatically resolves those fields by querying the corresponding subgraphs over HTTP. This allows you to subscribe to data that spans multiple subgraphs while maintaining a single subscription connection between your Router and the client.

Entity Resolution

One of the most powerful features of federated subscriptions is automatic entity resolution. Your subscription can include fields from multiple subgraphs, and Hive Router handles all the coordination automatically.

subscription {
  reviewAdded {
    # From the reviews subgraph
    id
    body
    rating
    # Entity field from the products subgraph
    product {
      name
      price
    }
    # Entity field from the users subgraph
    author {
      name
      email
    }
  }
}

In this example:

• The reviewAdded subscription is defined in the reviews subgraph
• The product fields are resolved from the products subgraph
• The author fields are resolved from the users subgraph

Hive Router intelligently determines the optimal way to resolve these entity fields, querying the necessary subgraphs as subscription events arrive. This works exactly like entity resolution for regular queries - no special configuration or considerations needed.

Supported Protocols

Hive Router supports all subscriptions protocols in the ecosystem, both for client-to-router and router-to-subgraph communication.

Server-Sent Events (SSE)

A simple, unidirectional protocol built on standard HTTP where the server streams events to the client over a persistent connection. Clients send a regular HTTP request with Accept: text/event-stream and the router keeps the response open, responding with a stream of events implementing the "distinct connections mode" of the GraphQL over SSE spec. No special transport library is needed - it works with the browser-native EventSource API or any HTTP client.

Incremental Delivery over HTTP

A multipart HTTP protocol from the Official GraphQL over HTTP spec RFC where each subscription event is delivered as a separate part in a streamed multipart/mixed response. Clients send Accept: multipart/mixed and the router streams JSON payloads separated by boundary markers.

Multipart HTTP

Apollo's Multipart HTTP protocol where subscription events are streamed as multipart/mixed response chunks with subscriptionSpec=1.0. Clients send Accept: multipart/mixed;subscriptionSpec=1.0 and the router delivers events as boundary-separated JSON payloads. This is the router's preferred protocol when connecting to subgraphs, and it is supported natively by Apollo Client with no extra configuration.

WebSockets

A full-duplex transport where clients and the router communicate over a persistent WebSocket connection using the GraphQL over WebSocket protocol. Unlike HTTP-based protocols, a single WebSocket connection can carry multiple concurrent operations - queries, mutations, and subscriptions alike. Every operation is treated as a synthetic HTTP request so all plugins, authorization, and header propagation apply uniformly. Requires explicit configuration and is disabled by default.

HTTP Callback

Instead of keeping a long-lived connection open to a subgraph, the router registers a callback URL with the subgraph over HTTP and the subgraph pushes events to that URL as they become available, as defined in the Apollo HTTP Callback Protocol spec. This avoids the overhead of maintaining persistent connections per subscription, making it a better fit than WebSockets or HTTP streams at high subscription counts. Subgraphs send periodic heartbeats to confirm the subscription is still alive, and the router can bind the callback endpoint to a dedicated port to isolate subgraph traffic from client traffic.

Choosing a Transport

Use SSE, Incremental Delivery, or Multipart HTTP when you want the simplest possible setup - they all work over standard HTTP, require no configuration, and are auto-negotiated by the router. The main difference between them is which client library you're using: Apollo Client works best with Multipart HTTP, urql and Relay work best with Incremental Delivery or SSE, and anything else can use SSE with graphql-sse.

Use WebSockets when you need to multiplex multiple GraphQL operations over a single connection, or when your client environment requires it. There is always graphql-ws to bridge the gap.

The same protocols apply for router-to-subgraph communication, with one addition: HTTP Callback is a subgraph-only protocol where the router registers a callback URL with the subgraph and the subgraph pushes events to it as they arrive. Because it avoids holding a persistent connection open per subscription, it is the preferred choice for subscriptions at scale.

Protocol Negotiation

HTTP-based subscription protocols (SSE, Incremental Delivery, and Multipart HTTP) are not individually activated or configured. Once subscriptions are enabled, all three are available simultaneously - the router determines which one to use for each request based on the client's Accept header:

The protocols used between the router and subgraphs are independent from those used between clients and the router. For example, a client can use SSE while the router communicates with a subgraph over multipart HTTP. When connecting to subgraphs, the router prefers multipart first, then falls back to SSE.

If a client requests a subscription over an unsupported transport, the router returns 406 Not Acceptable.

Configuration

Subscriptions are disabled by default. To enable them, set enabled: true in the subscriptions section of your router configuration:

subscriptions:
  enabled: true

You can also enable subscriptions using the SUBSCRIPTIONS_ENABLED environment variable:

SUBSCRIPTIONS_ENABLED=true