Subscriptions

Hive Gateway fully supports federated subscriptions and behaves just like Federation GraphQL subscriptions in Apollo Router.

Subgraphs providing subscriptions can communicate with Hive Gateway through one of the following protocols:

Clients connecting to the Hive Gateway may use either:

When to use subscriptions

GraphQL subscriptions allows to keep the client updated in real time.

Most of the time, a PubSub system is used to propagate events in the backend system. A client can use subscriptions to receive those events, augmented with all the data it needs using the GraphQL ability to resolve additional fields.

Subscriptions can be used for applications that relies on events or live data, such as chats, IoT sensors, alerting, stock prices, etc…

Learn more about Subscriptions

Subscriptions in Gateways

In the context of a gateway, subscriptions are forwarded from the client to the subgraph implementing the subscribed field.

With the power of the Gateway, each events received from the upstream subgraph will be augmented with the requested data from other subgraphs, and then sent to the client.

The Hive Gateway also abstract away the underlying protocol used to transport the data. A client can use a different transport than the one used to connect with the upstream subgraph.

Configure subgraph transport

By default, Hive Gateway will always try to use the same transport for queries, mutations and subscriptions.

In the case of HTTP, the default is to protocol is GraphQL over SSE. We highly recommend it, since it’s the most performant and idiomatic.

If your subgraph doesn’t implement subscriptions over SSE, you can configure Hive Gateway to use GraphQL over WebSocket or HTTP Callback.

Whichever protocol is used by Hive Gateway to subscribe to the upstream subgraphs, downstream clients can subscribe to the gateway using any supported protocol.

Subscriptions using WebSockets

If your subgraph uses WebSockets for subscriptions support (like with Apollo Server), Hive Gateway will need additional configuration pointing to the WebSocket server path on the subgraph.

Please note that WebSocket for communications between Hive Gateway and subgraphs are suboptimal compared to other possible transports. We recommend using either SSE or HTTP Callbacks instead.

gateway.config.ts

import { defineConfig, type WSTransportOptions } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  supergraph: 'supergraph.graphql',
  transportEntries: {
    // use "*.http" to apply options to all subgraphs with HTTP
    '*.http': {
      options: {
        subscriptions: {
          kind: 'ws',
          // override the path if it is different than normal http
          location: '/subscriptions'
        }
      }
    }
  }
})

Subscriptions using HTTP Callback

If your subgraph uses HTTP Callback protocol for subscriptions, Hive Gateway will need additional configuration.

gateway.config.ts

import { defineConfig, type HTTPCallbackTransportOptions } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  supergraph: 'supergraph.graphql',
  // Setup Hive Gateway to listen for webhook callbacks, and emit the payloads through PubSub engine
  webhooks: true,
  transportEntries: {
    // use "*.http" to apply options to all subgraphs with HTTP
    '*.http': {
      options: {
        subscriptions: {
          kind: 'http-callback',
          options: {
            // The gateway's public URL, which your subgraphs access, must include the path configured on the gateway.
            public_url: 'http://localhost:4000/callback',
            // The path of the router's callback endpoint
            path: '/callback',
            // Heartbeat interval to make sure the subgraph is still alive, and avoid hanging requests
            heartbeat_interval: 5000
          } satisfies HTTPCallbackTransportOptions
        }
      }
    }
  }
})

Subscriptions using mixed protocols

Hive Gateway supports using different transport for different subgraphs. By default, subscriptions will use the same transport than queries and mutation. This can be change using the transportEntries option.

The key of each entry determine which subgraph will be impacted:

*: all subgraphs
*.{transportKind}: all subgraphs using transportKind. For example, *.http will impact all subgraph using the http transport.
{subgraphName}: a specific subgraph.

Configuration are inherited and merged from the least specific to the most specific matcher. Only exception is the headers which is not inherited for the ws transport.

For example, let be 4 subgraphs:

products: using http transport for queries, and HTTP callbacks for subscriptions
views: using http transport for queries, and WS for subscriptions
stocks: using http transport for queries, and WS for subscriptions
stores: using mysql transport

gateway.config.ts

import { defineConfig, type WSTransportOptions } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  transportEntries: {
    '*.http': {
      // Will be applied to products, views and stocks subgraphs, but not stores.
      options: {
        subscriptions: {
          kind: 'ws',
          options: {
            connectionParams: {
              token: '{context.headers.authorization}'
            }
          } satisfies WSTransportOptions
        }
      }
    },
    products: {
      // Will override the subscriptions configuration for products subgraph only
      options: {
        subscriptions: {
          kind: 'http-callback',
          location: '/subscriptions',
          headers: [['authorization', 'context.headers.authorization']]
        }
      }
    }
  }
})

Propagation of authentication and headers

Hive Gateway can propagate the downstream client’s Authorization header (or any other header) to the upstream subgraph.

The propagation of headers is different if you use pure HTTP transports (SSE or HTTP Callbacks) or WebSockets.

Propagation of headers for pure HTTP subscription transports follow the same configuration than normal upstream requests.

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  propagateHeaders: {
    fromClientToSubgraphs({ request }) {
      return {
        authorization: request.headers.get('authorization')
      }
    }
  }
})

The recommended way is to use the ConnectionInit message payload. It is also possible, but not recommended, to propagate HTTP headers by sending them alongside the WebSocket upgrade request.

⚠️

If either connectionParams or headers are used with dynamic values, it can drastically increase the number of upstream WebSockets connections.
Since headers and connectionParams can only be applied at connection time, a new connection is required for each different set of values provided.

gateway.config.ts

import { defineConfig, type WSTransportOptions } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  supergraph: 'supergraph.graphql',
  transportEntries: {
    // use "*.http" to apply options to all subgraphs with HTTP
    '*.http': {
      options: {
        subscriptions: {
          kind: 'ws',
          location: '/subscriptions',
          options: {
            connectionParams: {
              token: '{context.headers.authorization}'
              // You can also add any other field here.
              // The only limitation is that value must be serializable with JSON.stringify.
            }
          } satisfies WSTransportOptions
        }
      }
    }
  }
})

On subgraph side, the contents of the payload will be available in the graphql-ws context field connectionParams:

{
  "connectionParams": {
    "token": "<CONTENTS_OF_AUTHORIZATION_HEADER>"
  }
}

This is also what Apollo Router do when propagating auth on WebSockets.

Configure Client subscriptions

Client subscriptions are enabled by default and compatible with both GraphQL over SSE and GraphQL over WebSocket with graphql-ws.

The default endpoint for subscriptions is /graphql and follow the graphqlEndpoint option, as for queries and mutations.

You can disable WebSockets server by using disableWebsockets option in the config file or by providing --disable-websockets option to the hive-gateway CLI.

Closing active subscriptions on schema change

When the schema changes in Hive Gateway, all active subscriptions will be completed after emitting the following execution error:

{
  "errors": [
    {
      "message": "subscription has been closed due to a schema reload",
      "extensions": {
        "code": "SUBSCRIPTION_SCHEMA_RELOAD"
      }
    }
  ]
}

This is also what Apollo Router when terminating subscriptions on schema update.

Example

We’ll implement two GraphQL Yoga federation services behaving as subgraphs. The “products” service exposes a subscription operation type for subscribing to product changes, while the “reviews” service simply exposes review stats about products.

The example is somewhat similar to Apollo’s documentation, except for that we use GraphQL Yoga here and significantly reduce the setup requirements.

You can find this example source on GitHub.

Install dependencies

npm i graphql-yoga @apollo/subgraph graphql

pnpm add graphql-yoga @apollo/subgraph graphql

yarn add graphql-yoga @apollo/subgraph graphql

bun add graphql-yoga @apollo/subgraph graphql

Services

In this example, we will compose 2 services:

Products which contains the products data
Reviews which contains reviews of products

Those 2 services needs to be run in parallel of the gateway.

products.ts

import { createServer } from 'http'
import { parse } from 'graphql'
import { createYoga } from 'graphql-yoga'
import { buildSubgraphSchema } from '@apollo/subgraph'
import { resolvers } from './my-resolvers'
 
const typeDefs = parse(/* GraphQL */ `
  type Product @key(fields: "id") {
    id: ID!
    name: String!
    price: Int!
  }
 
  type Subscription {
    productPriceChanged: Product!
  }
`)
 
const yoga = createYoga({ schema: buildSubgraphSchema([{ typeDefs, resolvers }]) })
 
const server = createServer(yoga)
 
server.listen(40001, () => {
  console.log('Products subgraph ready at http://localhost:40001')
})

Supergraph

Once all services have been started, we can generate a supergraph schema. It will then be served by the Hive Gateway.

You can generate this schema with either GraphQL Mesh or Apollo Rover.

To generate a supergraph with Apollo Rover, you first need to create a configuration file describing the list of subgraphs:

supergraph.yaml

federation_version: =2.3.2
subgraphs:
  products:
    routing_url: http://localhost:40001
    schema:
      subgraph_url: http://localhost:40001
  inventory:
    routing_url: http://localhost:40002
    schema:
      subgraph_url: http://localhost:40002

You can then run the Rover command to generate the supegraph schema SDL:

rover supergraph compose --config ./supergraph.yaml > supergraph.graphql

For more details about how to use Apollo Rover, please refer to the official documentation.

Start Gateway

You can now start the Hive Gateway. Without any configuration provided, the Gateway will load the supergraph file supergraph.yaml from the current directory, and serve it with a set of sensible default features enabled.

hive-gateway supergraph

By default, subscriptions are enabled and handles both WebSockets and SSE transport.

Let’s now subscribe to the product price changes by executing the following query:

subscription {
  productPriceChanged {
    # Defined in Products subgraph
    name
    price
    reviews {
      # Defined in Reviews subgraph
      score
    }
  }
}

Hive Gateway will inteligently resolve all fields on subscription events and deliver you the complete result.

You can subscribe to the gateway through Server-Sent Events (SSE) (in JavaScript, using EventSource or graphql-sse).

Most clients offers a way to use subscriptions over SSE. You can find here examples for Apollo Client and Relay, please refer to the Recipes for Clients Usage section of graphql-sse documentation for other clients setups.

To quickly test subscriptions, you can use curl in your terminal to subscribe to the gateway. curl has native support of SSE.

curl 'http://localhost:4000/graphql' \
  -H 'accept: text/event-stream' \
  -H 'content-type: application/json' \
  --data-raw '{"query":"subscription OnProductPriceChanged { productPriceChanged { name price reviews { score } } }","operationName":"OnProductPriceChanged"}'

To enable SSE support using Apollo Client, you can create a simple Apollo Link using graphql-sse library.

client.ts

import { GraphQLError, print } from 'graphql'
import { Client, ClientOptions, createClient } from 'graphql-sse'
import { ApolloClient } from '@apollo/client'
import { ApolloLink, FetchResult, Observable, Operation } from '@apollo/client/core'
 
class SSELink extends ApolloLink {
  private client: Client
 
  constructor(options: ClientOptions) {
    super()
    this.client = createClient(options)
  }
 
  public request(operation: Operation): Observable<FetchResult> {
    return new Observable(sink => {
      return this.client.subscribe<FetchResult>(
        { ...operation, query: print(operation.query) },
        {
          next: sink.next.bind(sink),
          complete: sink.complete.bind(sink),
          error: sink.error.bind(sink)
        }
      )
    })
  }
}
 
export const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: new SSELink({ url: 'http://localhost:4000/graphql' })
})

Learn more on graphql-sse documentation.

To enable support of SSE using Relay, you can create a custom Network Layer with graphql-sse library.

network.ts

import { createClient } from 'graphql-sse'
import { Network, Observable, RequestParameters, Variables } from 'relay-runtime'
 
const subscriptionsClient = createClient({
  url: 'http://localhost:4000/graphql'
})
 
// yes, both fetch AND subscribe can be handled in one implementation
function fetchOrSubscribe(operation: RequestParameters, variables: Variables) {
  return Observable.create(sink => {
    if (!operation.text) {
      return sink.error(new Error('Operation text cannot be empty'))
    }
    return subscriptionsClient.subscribe(
      { operationName: operation.name, query: operation.text, variables },
      sink
    )
  })
}
 
export const network = Network.create(fetchOrSubscribe, fetchOrSubscribe)

Learn more on graphql-sse documentation.

You can subscribe to the gateway through WebSockets.

Most clients offers a way to use subscriptions over WebSockets. You can find here examples for Apollo Client and Relay, please refer to the [Recipes section of graphql-ws documentation]https://the-guild.dev/graphql/ws/recipes) for other clients setups.

To quickly test subscriptions, you can use wscat in your terminal to subscribe to the gateway.

First, begin the connection with:

npx wscat \
  -c http://localhost:4000/graphql \
  -s graphql-ws \
  --wait 600 -x '{"type": "connection_init"}' # Send this message directly, to avoid initialization timeout

Once connected, you can start a subscription:

> {"type": "subscribe", "id": "operation-1", "payload": {"query":"subscription OnProductPriceChanged { productPriceChanged { name price reviews { score } } }","operationName":"OnProductPriceChanged"}}

To enable subscriptions over WebSockets with Apollo Client, you have to use the GraphQLWsLink, which relies on graphql-ws library.

You will need to use a split link to either use classic HTTP for queries and mutation, or WebSockets for subscriptions if you don’t want to use WebSockets for all operations (which is the most common approach).

client.ts

import { createClient } from 'graphql-ws'
import { HttpLink, split } from '@apollo/client'
import { GraphQLWsLink } from '@apollo/client/link/subscriptions'
import { getMainDefinition } from '@apollo/client/utilities'
 
export const client = new ApolloClient({
  cache: new InMemoryCache(),
  // Use the `split` link to send queries and subscription with a different link.
  link: split(
    ({ query }) => {
      const definition = getMainDefinition(query)
      return definition.kind === 'OperationDefinition' && definition.operation === 'subscription'
    },
    new GraphQLWsLink(createClient({ url: 'ws://localhost:4000/graphql' })),
    new HttpLink({ uri: 'http://localhost:4000/graphql' })
  )
})

Learn more about this on official documentation.

Relay doesn’t support WebSockets out of the box, but you can easily enable this feature by setting up a Network Layer using graphql-ws library.

network.ts

import { createClient } from 'graphql-ws'
import { Network, Observable } from 'relay-runtime'
 
const wsClient = createClient({
  url: 'ws://localhost:3000'
})
 
const subscribe = (operation, variables) => {
  return Observable.create(sink => {
    return wsClient.subscribe(
      {
        operationName: operation.name,
        query: operation.text,
        variables
      },
      sink
    )
  })
}
 
export const network = Network.create(fetchQuery, subscribe)

Learn more on official Relay documentation.

Incremental Delivery (Defer & Stream)Overview