edfs

Author: enisdenjo

packages/web/docs/src/content/gateway/subscriptions.mdx

@@ -789,6 +789,149 @@ export const network = Network.create(fetchQuery, subscribe)
 
 </Tabs>
 
+
+## Event-Driven Federated Subscriptions (EDFS)
+
+Hive Gateway supports event-driven federated subscriptions, allowing you to publish events to a
+message broker (NATS, Kafka, Redis, etc.) and have those events automatically routed to the
+appropriate Hive Gateway subscribers.
+
+If you do not know what Event-Driven Federated Subscriptions (EDFS) are, please refer to
+[this great article by Wundergraph](https://wundergraph.com/blog/distributed_graphql_subscriptions_with_nats_and_event_driven_architecture).
+
+Lets go over how you would set up EDFS with [Mesh Compose](https://the-guild.dev/graphql/mesh) and
+Hive Gateway using Redis as the message broker.
+
+### Composing the Supergraph With Mesh Compose
+
+Lets compose our supergraph with [Mesh Compose](https://the-guild.dev/graphql/mesh) and add the
+subscription fields to the schema.
+
+First we need to make sure we have a "products" subgraph ready and running on
+`http://localhost:3000/graphql`:
+
+```gql filename="products.graphql"
+type Query {
+  hello: String!
+}
+type Product @key(fields: "id") {
+  id: ID!
+  name: String!
+  price: Float!
+}
+```
+
+And then we need to add the subscription fields like this:
+
+```ts filename="mesh.config.ts"
+import { defineConfig, loadGraphQLHTTPSubgraph } from '@graphql-mesh/compose-cli'
+
+export const composeConfig = defineConfig({
+  subgraphs: [
+    {
+      sourceHandler: loadGraphQLHTTPSubgraph('products', {
+        endpoint: `http://localhost:3000/graphql`
+      })
+    }
+  ],
+  additionalTypeDefs: /* GraphQL */ `
+    extend schema {
+      subscription: Subscription
+    }
+    type Subscription {
+      newProduct: Product! @resolveTo(pubsubTopic: "new_product", sourceName: "products")
+    }
+  `
+})
+```
+
+The composed supergraph schema will now contain a `newProduct` subscription field that will have the
+gateway subscribe to the `new_product` topic. This is done by the `@resolveTo` directive, the
+`pubsubTopic` argument specifies the topic to subscribe to, and the `sourceName` argument specifies
+the subgraph that owns the `Product` type, i.e. the subgraph to use to resolve missing fields.
+
+### Configuring Hive Gateway With Redis PubSub
+
+Next step is to configure Hive Gateway to use Redis PubSub as the message broker and consume the
+Mesh Compose generated supergraph. This is how the configuration would look like:
+
+Redis PubSub does not come with Hive Gateway, you have to install the package and the Redis PubSub
+peer dependency of `ioredis` which you need to install first:
+
+```sh npm2yarn
+npm i @graphql-hive/pubsub ioredis
+```
+
+```ts filename="gateway.config.ts"
+import Redis from 'ioredis'
+import { defineConfig } from '@graphql-hive/gateway'
+import { RedisPubSub } from '@graphql-hive/pubsub/redis'
+
+/**
+ * When a Redis connection enters "subscriber mode" (after calling SUBSCRIBE), it can only execute
+ * subscriber commands (SUBSCRIBE, UNSUBSCRIBE, etc.). Meaning, it cannot execute other commands like PUBLISH.
+ * To avoid this, we use two separate Redis clients: one for publishing and one for subscribing.
+ */
+const pub = new Redis()
+const sub = new Redis()
+
+export const gatewayConfig = defineConfig({
+  supergraph: 'supergraph.graphql', // the supergraph generated by Mesh Compose
+  pubsub: new RedisPubSub(
+    { pub, sub },
+    {
+      // we make sure to use the same prefix for all gateways to share the same channels and pubsub
+      // meaning, all gateways using this channel prefix will receive and publish to the same topics
+      channelPrefix: 'edfs'
+    }
+  )
+})
+```
+
+### Subscribing and Publishing Events
+
+We're now ready to subscribe to the `newProduct` subscription field and publish events to the
+`new_product` topic. The publishing of events can happen from **anywhere**, it doesn't have to be
+from within Hive Gateway or any perticular subgraph, you can, for example, implement a separate
+service that is only responsible for emitting subscription events.
+
+You can subscribe to the `newProduct` subscription from a client using any of the
+[transports supported by Hive Gateway](#configure-client-subscriptions), lets subscribe with this
+query:
+
+```graphql
+subscription {
+  newProduct {
+    name
+    price
+  }
+}
+```
+
+and then emit an event to the Redis instance on the `new_product` topic with the `edfs` prefix like
+this:
+
+```redis
+PUBLISH edfs:new_product '{"id":"roomba70x"}'
+```
+
+The subscriber will then receive the following event:
+
+```json
+{
+  "data": {
+    "newProduct": {
+      "name": "Roomba 70x",
+      "price": 279.99
+    }
+  }
+}
+```
+
+Note that the event payload only contains the `id` field, which is the only required field to
+resolve the `Product` type. Hive Gateway will then fetch the missing fields from the "products"
+subgraph.
+
 ## PubSub
 
 Hive Gateway internally uses a PubSub system to handle subscriptions. By default, an in-memory
@@ -873,9 +1016,11 @@ In case you have distributed instances of Hive Gateway, using a distributed PubS
 required to make sure all instances are aware of all active subscriptions and can publish events to
 the correct subscribers.
 
-For example, when using the webhooks transport for subscriptions, the subgraph will send events to
-only one instance of Hive Gateway. If that instance doesn't have any active subscription for the
-topic, the event will be lost. Using a distributed PubSub engine solves this problem.
+For example, when using the
+[webhooks transport for subscriptions](https://the-guild.dev/graphql/mesh/v1/subscriptions-webhooks),
+the subgraph will send events to only one instance of Hive Gateway. If that instance doesn't have
+any active subscription for the topic, the event will be lost. Using a distributed PubSub engine
+solves this problem.
 
 Redis PubSub does not come with Hive Gateway, you have to install the package and the Redis PubSub
 peer dependency of `ioredis` which you need to install first: