GraphQL subscriptions API

[kettanaito]

With the introduction of WebSocket support (#156), it's time to draft the GraphQL subscriptions API in MSW. I'd like to use this document to propose a public API and have any related discussions with the community.

• Implementation: feat: support GraphQL subscriptions #2357

Proposed API

import { graphql } from 'msw'

const service = graphql.link('*')

export const handlers = [
  // Listen to a subscription being established in the app.
  // This can only work for named subscriptions. Unnamed subscriptions
  // are triggered by `service.pubsub.publish` directly.
  service.subscription('NotifyOnComments', ({ query, variables }) => {
    // Send events directly from the subscription handler.
    // This is handy for events that don't correspond to any
    // queries/mutations (e.g. outsourced events).
    service.pubsub.publish('EVENT_NAME', {})
  }),

  service.mutation('CreateComment', () => {
    // Publish an event to the subscription to notify all subscribers.
    service.pubsub.publish('EVENT_NAME', {})
  })
]

I'm not the biggest fan of .pubsub. but if that's a widely known pattern, I don't mind. We need to scope the subscription events emitting to something in any case.

Usage

First, you create a GraphQL link via graphql.link(). Only GraphQL links will get the .subscription() method. This aligns with our direction to drop link-less GraphQL support (#1892) and also acts as a requirement for a granular WebSocket endpoint interception.

From here, you have multiple ways to interact with subscriptions:

1. You can handle an exact subscription query via .subscription(queryName, resolver). This is handy if you want to react to when your app establishes that subscription. In this scenario, your resolver acts as the source of truth that can publish data to that subscription on demand.
2. You can publish data to the subscription in other queries/mutations you have. You use the GraphQL link directly to do that: link.pubsub.publish(event, data).

Example

• add apollo (subscriptions) example examples#127

Resources

• graphql-ws protocol specification

Questions

• Verify this approach with the folks working with GraphQL subscriptions extensively. I want the mocking API to resemble the actual usage as closely as possible.
• Gather more use cases around GraphQL subscriptions (and mocking it) to make sure it's supported by the API.
• Do you expect subscriptions to be returned from graphql.link() to stay consistent? Should MSW implicitly add a WebSocket handler to the same link URL but with a switched protocol? Would you prefer a standalone graphql.wsLink(url) instead?

[kettanaito]

Question: Using AsyncIterator

A lot of resources I find promote the usage of AsyncIterator as a resolver for GraphQL subscriptions. I fail to see how that's intended to work. Does this concern mostly polling-based transports? Because in event-based architectures you rely on listeners not iterators.

Who calls this iterator then? The polling client when checking if any updates occurred? But I thought subscriptions are mostly based on the graphql-ws package that relies on WebSockets.

[ducin]

API design question: since you subscribe directly on service: service.subscription(..., why do you publish via an additional pubsub object: service.pubsub.publish? Usually the pubsub thing exposes both publish and subscribe, so in this case I'd expect service.subscribe and service.publish - or both service.pubsub.subscribe and service.pubsub.publish.

Anyway, an immediate question arises (for me): what's the difference (in the API) between the service object and the pubsub object. And it seems one could be unnecessary. But most probably I lack some context or something 😄

[kettanaito]

why do you publish via an additional pubsub object: service.pubsub.publish?

Because service is just a link, it's not specific to subscriptions. You use it to intercept queries and mutations too! That's why putting root-level .publish() on the service feels out of place.

const service = graphql.link(endpoint)

service.query('GetComment', resolver)
service.mutation('CreateComment', resolver)
service.subscription('NotifyOnComment', resolver)

what's the difference (in the API) between the service object and the pubsub object

You use the service object to intercept a subscription your app establishes. You use its .pubsub. to push events to any subscription from anywhere. service.subscription() is read, service.pubsub.publish() is write.

The goal here is to distinguish somehow the use case of (1) listening to a subscription by name and controlling it from the mock; (2) pushing any events to the underlying socket to trigger any subscriptions (not necessarily those explicitly intercepted to in the mock).

Does it make more sense this way?