Federated GraphQL Subscriptions in Hive Router

Hive Router now supports federated GraphQL subscriptions out of the box. Real-time data across multiple subgraphs, with automatic entity resolution, full protocol coverage, and zero special configuration required on the client side.

This is the most complete GraphQL subscriptions implementation available - covering every major protocol, transport, and delivery model in the ecosystem. It was built by Denis, the maintainer of graphql-ws, graphql-sse, and graphql-http - the libraries that power subscriptions across most of the GraphQL ecosystem today.

All Protocols, One Router

Hive Router covers the entire subscriptions protocol landscape - both for client-to-router and router-to-subgraph communication:

The three HTTP-based protocols (SSE, Incremental Delivery, Multipart HTTP) are all active simultaneously once subscriptions are enabled. No per-protocol configuration needed - the router negotiates which one to use per request based on the client's Accept header.

Federated Entity Resolution

Subscription events can span multiple subgraphs. When a subscription field comes from one subgraph and the response includes entity fields owned by others, Hive Router resolves them automatically on every event - no special setup needed.

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

WebSockets via Synthetic HTTP Requests

Every operation sent over a WebSocket connection - queries, mutations, and subscriptions - is converted into a synthetic HTTP request internally. This means the operation goes through exactly the same processing pipeline as a regular HTTP request: the same routing, the same authorization checks, the same header propagation rules. No special cases for WebSocket traffic.

Because WebSocket connections don't carry HTTP headers beyond the initial upgrade handshake, the router needs to know where to read headers from. The headers.source option controls this:

• connection - Headers come from the connection_init message payload. Recommended default for most clients.
• operation - Headers come from the headers field inside each operation's extensions. Allows per-operation overrides.
• both - Headers accepted from both sources. Operation extensions take precedence.
• none - No headers accepted from inside the WebSocket messages.

The headers.persist flag only applies when source is both. When true, headers received from operation extensions are stored and reused for all subsequent operations on that connection. This handles token refresh without requiring a reconnect: the client sends an updated Authorization header in one operation's extensions, and the router carries it forward automatically from that point on.

websocket:
  enabled: true
  headers:
    source: both
    persist: true

HTTP Callback for Scale

HTTP Callback is a subgraph-only protocol where the router registers a callback URL with the subgraph instead of holding a persistent connection open. The subgraph pushes events to that URL as they arrive. This makes it significantly more efficient at high subscription counts.

The callback endpoint can be bound to a dedicated port to isolate subgraph traffic from client traffic:

subscriptions:
  enabled: true
  callback:
    public_url: https://router.internal:4001/callback
    listen: 0.0.0.0:4001
    subgraphs:
      - reviews
      - products

Deduplication and Schema Reload

Subscriptions participate in inbound deduplication. Multiple clients subscribing to the same operation share a single upstream subgraph connection - the router broadcasts events to all of them via an internal channel.

When a new supergraph schema loads, all active subscriptions are closed with a SUBSCRIPTION_SCHEMA_RELOAD error code. Clients reconnect and re-subscribe against the new schema.

Get Started

Make sure you're running Hive Router 0.0.49 or above, then enable subscriptions with a single config option:

subscriptions:
  enabled: true

and/or WebSocket support:

websocket:
  enabled: true

Also worth noting if you haven't seen them yet - the Hive Router plugin system lets you extend and customize the router with native Rust plugins, the new Laboratory brings a redesigned, editor-driven GraphQL IDE experience, and OpenTelemetry tracing and Prometheus metrics are now production-ready in Hive Router.

• Subscriptions overview
• Server-Sent Events
• Incremental Delivery over HTTP
• Multipart HTTP
• WebSockets
• HTTP Callback