Subscription Lifecycle and Event Flow

Why One Response Is Not Enough

A query returns one payload and then the connection closes. A support dashboard that must show incoming tickets as they arrive has only three bad options: poll every 500 ms and burn traffic nobody looks at, hold a long request that proxies silently kill at 30 seconds, or hand-roll a socket protocol that no GraphQL client, gateway, or tracer understands.

A subscription is the fourth option: the client sends its GraphQL document once, and the server pushes responses until the client unsubscribes or the transport dies.

subscription OnOrderShipped($orderId: ID!) {
  orderShipped(orderId: $orderId) {
    id
    status
    trackingNumber
    eta { day window }
  }
}

That document travels once. What comes back is zero or more { data: { orderShipped: ... } } payloads, each shaped exactly like the selection set above, followed by a completion signal. Two structural facts matter for everything after this: the operation kind is subscription, and the root field takes arguments (orderId) exactly the way a query field does, so arguments decide which events this stream can ever see.

What actually changes

A query resolver may assume the database, the auth token, and the process are healthy for the 40 milliseconds it runs. A subscription runs as long as the tab stays open, so each of those assumptions has to survive deploys, token refresh, and a commute through a tunnel.

Server-side, the stream is driven by an event source that sits outside GraphQL: an in-process emitter, a Redis channel, a Kafka topic. GraphQL's job is to translate "something happened on channel X" into "here is another response matching the document you sent." Whether a feature earns that machinery is decided in realtime feature patterns.

The Subscribe Function and the Async Iterator

Server frameworks split a subscription root field into two jobs that a query field performs as one.

const resolvers = {
  Subscription: {
    orderShipped: {
      // runs ONCE, when the operation starts
      subscribe: (_, args, { pubsub }) =>
        pubsub.asyncIterator('ORDER_SHIPPED:' + args.orderId),

      // runs for EVERY event that flows through the iterator
      resolve: (payload) => payload.orderShipped,
    },
  },
};

subscribe must return an object implementing the async iterator protocol ([Symbol.asyncIterator]()), and it is the only function that touches the event source. The event source itself knows nothing about GraphQL; it pushes plain objects and lets this adapter interpret them.

resolve is the per-event mapper. Publishers usually send an envelope carrying more than one key:

await pubsub.publish('ORDER_SHIPPED:' + orderId, {
  orderShipped: order,
  audit: { at: Date.now(), actor: 'shipping-service' },
});

Publishing audit on the same topic lets a second subscription read its own field without a second publish. Omit resolve and the envelope object is used as-is, which only works when it has exactly one key matching the field name.

Every event re-runs the selection set

Once resolve produces the value, GraphQL executes the subscription selection against it exactly as it would a query result: arguments are applied, nested field resolvers run, non-null violations propagate, and errors attach to that response only. A nested resolver that took 3 ms in GraphiQL now runs thirty times a second per subscriber, so the per-event cost — not the handshake — is the capacity number that matters.

An error in one event does not end the stream: it produces an error payload for that response, and the next event still arrives. The stream ends only on complete, an operation-level failure, or the transport closing.

Filtering belongs in two places

Filters the event source can use belong in the topic name, because they cut work before GraphQL sees anything. Filters that must inspect payload contents use withFilter:

subscribe: withFilter(
  () => pubsub.asyncIterator('MESSAGE_ADDED'),
  (payload, vars) => payload.messageAdded.roomId === vars.roomId,
),

That predicate runs inside the server on every event for every subscriber. A broadcast topic plus a selective filter still pays the fan-out cost on each instance, so scope the topic whenever the argument exists on the root field.

Teardown, Leaks, and the Per-Client Cap

When a client unsubscribes — or its socket simply drops — the server calls return() on the iterator. A generator runs its finally block at that moment, which is where cleanup belongs:

async function* orderEvents(orderId) {
  const timer = setInterval(pollShipmentFeed, 1000);
  try {
    while (true) yield await nextShipment(orderId);
  } finally {
    clearInterval(timer); // unsubscribe, error, and socket close all land here
  }
}

Skip this and the symptom is quiet: departed clients leave live timers, open cursors, and broker subscriptions behind. Finding ten thousand "connected" users who are not connected usually happens during an incident, not during a code review. A hand-written iterator must expose return() so framework-driven cancellation reaches the same finally path.

The cap is a feature, not a courtesy

Connections are cheap to open and expensive to keep:

function makeContext(user, registry) {
  return {
    user,
    claimSlot() {
      const active = registry.count(user.id);
      if (active >= MAX_STREAMS_PER_USER) {
        throw new GraphQLError(
          'STREAM_LIMIT: ' + active + '/' + MAX_STREAMS_PER_USER,
          { extensions: { code: 'STREAM_LIMIT' } },
        );
      }
      registry.increment(user.id);
      return () => registry.decrement(user.id); // invoked from the iterator finally
    },
  };
}

Rejecting loudly at subscribe time beats accepting everything and letting one client swap your sockets for its memory. Enforce two ceilings: per connection, so a single socket cannot open a thousand operations, and per authenticated user, so reconnect storms and duplicate tabs do not multiply. Rate-limit the subscribe messages themselves — a client starting streams in a loop churns your event source faster than a downstream cap can catch.

Signals worth watching

Export active_streams as a gauge per instance and per user, plus streams_started and streams_closed as counters. If the gauge keeps climbing after clients disconnect, the cleanup path is not running — the difference between a leak found in staging and a leak found at 3 a.m.

Interview framing: define a subscription as an event source plus a selection set, name the cleanup hook (return() triggering finally), and state the resource you cap along with why the cap is enforced at subscribe time.