From 438f6864925b544a3f87b8bdbc3548b26030cf65 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 21 Feb 2024 17:24:39 -0700 Subject: [PATCH 1/4] Create shared subscription components --- .eslintrc.js | 2 ++ src/content/shared/how-subscriptions-work.mdx | 35 +++++++++++++++++++ src/content/shared/index.js | 2 ++ .../shared/what-subscriptions-are-for.mdx | 15 ++++++++ 4 files changed, 54 insertions(+) create mode 100644 src/content/shared/how-subscriptions-work.mdx create mode 100644 src/content/shared/what-subscriptions-are-for.mdx diff --git a/.eslintrc.js b/.eslintrc.js index d447bb8eb..75d8c6e59 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -49,6 +49,8 @@ module.exports = { SchemaProposalPublicationMermaid: 'readonly', SetApolloVCSCommit: 'readonly', StudioPages: 'readonly', + HowSubscriptionsWork: 'readonly', + WhatSubscriptionsAreFor: 'readonly', TopLevelAwait: 'readonly' }, rules: { diff --git a/src/content/shared/how-subscriptions-work.mdx b/src/content/shared/how-subscriptions-work.mdx new file mode 100644 index 000000000..66baeb6f2 --- /dev/null +++ b/src/content/shared/how-subscriptions-work.mdx @@ -0,0 +1,35 @@ + +```mermaid +flowchart LR; + client(Client); + router(["GraphOS
Router"]); + subgraphA[Stocks
subgraph]; + subgraphB[Portfolios
subgraph]; + router-->|"Subscribes
over WebSocket
(or via callback)"|subgraphA; + router-.->|Can query for
entity fields
as needed|subgraphB; + client-->|Subscribes
over HTTP|router; + class client secondary; +``` + +1. A client executes a GraphQL subscription operation against your router over HTTP: + + ```graphql title="Example subscription" + subscription OnStockPricesChanged { + stockPricesChanged { + symbol + price + } + } + ``` + + - The client doesn't use a WebSocket protocol. Instead, it receives updates via [multipart HTTP responses](https://www.apollographql.com/docs/router/executing-operations/subscription-multipart-protocol/). + - By using HTTP for subscriptions, clients can execute all GraphQL operation types over HTTP instead of using two different protocols. + - [Apollo Client](https://www.apollographql.com/docs/react/data/subscriptions#http), [Apollo Kotlin](https://www.apollographql.com/docs/kotlin/essentials/subscriptions#configuring-http-subscriptions), and [Apollo iOS](https://www.apollographql.com/docs/ios/fetching/subscriptions#http) all support GraphQL subscriptions over HTTP with minimal configuration. See each library's documentation for details. Apollo Client also provides network adapters for the [Relay](https://www.apollographql.com/docs/react/data/subscriptions#relay) and [urql](https://www.apollographql.com/docs/react/data/subscriptions#urql) libraries. + +2. When your router receives a subscription, it executes that same subscription against whichever subgraph defines the requested field—`stockPricesChanged` in the example above. + + - This communication usually does use a WebSocket subprotocol, for compatibility with most subgraph libraries. + - With a self-hosted router, you can also configure an [HTTP-callback-based protocol](https://www.apollographql.com/docs/router/executing-operations/subscription-support/#http-callback-setup). + +3. The subgraph periodically sends new data to your router. Whenever it does, the router returns that data to the client in an additional HTTP response part. + - A subscription can include federated entity fields that are defined in other subgraphs. If it does, the router first fetches those fields by querying the corresponding subgraphs, such as **Portfolios** in the diagram above. These queries use HTTP as usual. \ No newline at end of file diff --git a/src/content/shared/index.js b/src/content/shared/index.js index 069fcb5cb..e8c0dd70c 100644 --- a/src/content/shared/index.js +++ b/src/content/shared/index.js @@ -26,4 +26,6 @@ export {default as SchemaProposalPublicationMermaid} from './schema-proposal-pub export {default as SchemaProposalReviewMermaid} from './schema-proposal-review-mermaid.mdx'; export {default as SetApolloVCSCommit} from './set-apollo-vcs-commit.mdx'; export {default as StudioPages} from './studio-pages.mdx'; +export {default as HowSubscriptionsWork} from './how-subscriptions-work.mdx' +export {default as WhatSubscriptionsAreFor} from './what-subscriptions-are-for.mdx'; export {default as TopLevelAwait} from './top-level-await.mdx'; diff --git a/src/content/shared/what-subscriptions-are-for.mdx b/src/content/shared/what-subscriptions-are-for.mdx new file mode 100644 index 000000000..0ddcc576b --- /dev/null +++ b/src/content/shared/what-subscriptions-are-for.mdx @@ -0,0 +1,15 @@ + +GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. This means a client can receive multiple updates from a single subscription: + +```mermaid +sequenceDiagram + participant Client as GraphQL Client + participant Router as GraphOS Router + Client->>Router: Initiates subscription + Note over Router: New data available + Router->>Client: Sends new data + Note over Router: New data available + Router->>Client: Sends new data +``` + +Subscriptions are best suited to apps that rely on frequently-changing, time-sensitive data such as stock prices, IoT sensor readings, live chat, or sports scores. \ No newline at end of file From 6673c96604243619f7153523cd1de6d121ace9e0 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 21 Feb 2024 17:25:26 -0700 Subject: [PATCH 2/4] Use shared components --- .../basics/operations/subscriptions.mdx | 64 ++----------------- 1 file changed, 7 insertions(+), 57 deletions(-) diff --git a/src/content/graphos/basics/operations/subscriptions.mdx b/src/content/graphos/basics/operations/subscriptions.mdx index a52da9539..f45eb2cdc 100644 --- a/src/content/graphos/basics/operations/subscriptions.mdx +++ b/src/content/graphos/basics/operations/subscriptions.mdx @@ -1,9 +1,9 @@ --- -title: GraphQL subscriptions with a cloud supergraph -description: Real-time data delivery from across your services +title: GraphQL subscriptions in cloud supergraphs +subtitle: Real-time data delivery across your services +description: Cloud routers support GraphQL subscriptions by default, enabling clients to receive real-time updates via WebSocket or HTTP callbacks. --- - **Cloud supergraph support for GraphQL subscriptions is currently in [preview](/resources/product-launch-stages#preview).** @@ -12,7 +12,6 @@ You can also use subscriptions with an Enterprise self-hosted supergraph. See th - Cloud supergraphs provide preview support for GraphQL subscription operations: ```graphql @@ -42,60 +41,11 @@ To use subscriptions with your cloud supergraph, you must first complete certain ## What are subscriptions for? -GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. This means a client can receive multiple updates from a single subscription: - -```mermaid -sequenceDiagram - participant Client as GraphQL Client - participant Router as Cloud Router - Client->>Router: Initiates subscription - Note over Router: New data available - Router->>Client: Sends new data - Note over Router: New data available - Router->>Client: Sends new data -``` - -Subscriptions are best suited to apps that rely on frequently changing, time-sensitive data (such as stock prices, IoT sensor readings, live chat, or sports scores). - -## How it works - -```mermaid -flowchart LR; - client(Client); - subgraph "GraphOS"; - router(["Cloud
Router"]); - end; - subgraph "Your infrastructure"; - subgraphA[Stocks
subgraph]; - subgraphB[Portfolios
subgraph]; - router-->|"Subscribes
over WebSocket"|subgraphA; - router-.->|Can query for
entity fields
as needed|subgraphB; - end; - client-->|Subscribes
over HTTP|router; - class client secondary; -``` - -1. A client executes a GraphQL subscription operation against your cloud router over HTTP: - - ```graphql title="Example subscription" - subscription OnStockPricesChanged { - stockPricesChanged { - symbol - price - } - } - ``` - - - **The client does not use a WebSocket protocol!** Instead, it receives updates via [multipart HTTP responses](/router/executing-operations/subscription-multipart-protocol/). - - By using HTTP for subscriptions, clients can execute all GraphQL operation types over HTTP instead of using two different protocols. - - Apollo Client for [Web](/react/data/subscriptions#http), [Kotlin](/kotlin/essentials/subscriptions#configuring-http-subscriptions), and [iOS](/ios/fetching/subscriptions#http) all support GraphQL subscriptions over HTTP with minimal configuration. See each library's documentation for details. - -2. When your cloud router receives a subscription, it executes that same subscription against whichever subgraph defines the requested field (`stockPricesChanged` in the example above). + - - This communication does use a WebSocket subprotocol (specifically, [`graphql-transport-ws`](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md)). +## How subscriptions work -3. The subgraph periodically sends new data to your router. Whenever it does, the router returns that data to the client in an additional HTTP response part. - - A subscription can include federated entity fields that are defined in other subgraphs. If it does, the router first fetches those fields by querying the corresponding subgraphs (such as **Portfolios** in the diagram above). These queries use HTTP as usual. + @@ -105,7 +55,7 @@ flowchart LR; ## Prerequisites -⚠️ **Before you add `Subscription` fields to your subgraphs,** do all the following in the order shown to prevent errors: +Before you add `Subscription` fields to your subgraphs, do all the following in the order shown to prevent errors: 1. Make sure you've [created a cloud supergraph](../quickstart/cloud) and connected your GraphQL API to it! From 4036b766b986ba6f22e6305dfbee25698fd7b900 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 21 Feb 2024 17:35:52 -0700 Subject: [PATCH 3/4] Vale --- .github/styles/config/vocabularies/Docs/accept.txt | 1 + src/content/shared/what-subscriptions-are-for.mdx | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/styles/config/vocabularies/Docs/accept.txt b/.github/styles/config/vocabularies/Docs/accept.txt index c83140209..e617150af 100644 --- a/.github/styles/config/vocabularies/Docs/accept.txt +++ b/.github/styles/config/vocabularies/Docs/accept.txt @@ -118,6 +118,7 @@ typings [Uu]ntracked [Uu]ntrusted URI(s)? +urql Uplink [Vv]alidator Vue diff --git a/src/content/shared/what-subscriptions-are-for.mdx b/src/content/shared/what-subscriptions-are-for.mdx index 0ddcc576b..4b94ae4d0 100644 --- a/src/content/shared/what-subscriptions-are-for.mdx +++ b/src/content/shared/what-subscriptions-are-for.mdx @@ -12,4 +12,4 @@ sequenceDiagram Router->>Client: Sends new data ``` -Subscriptions are best suited to apps that rely on frequently-changing, time-sensitive data such as stock prices, IoT sensor readings, live chat, or sports scores. \ No newline at end of file +Subscriptions are best suited to apps that rely on frequently changing, time-sensitive data such as stock prices, IoT sensor readings, live chat, or sports scores. \ No newline at end of file From fe76d14406a568915db6128ae6b421b9f6999cab Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 22 Feb 2024 08:58:56 -0700 Subject: [PATCH 4/4] Copyedit --- src/content/shared/how-subscriptions-work.mdx | 4 ++-- src/content/shared/what-subscriptions-are-for.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/shared/how-subscriptions-work.mdx b/src/content/shared/how-subscriptions-work.mdx index 66baeb6f2..aeaa8a7bd 100644 --- a/src/content/shared/how-subscriptions-work.mdx +++ b/src/content/shared/how-subscriptions-work.mdx @@ -26,10 +26,10 @@ flowchart LR; - By using HTTP for subscriptions, clients can execute all GraphQL operation types over HTTP instead of using two different protocols. - [Apollo Client](https://www.apollographql.com/docs/react/data/subscriptions#http), [Apollo Kotlin](https://www.apollographql.com/docs/kotlin/essentials/subscriptions#configuring-http-subscriptions), and [Apollo iOS](https://www.apollographql.com/docs/ios/fetching/subscriptions#http) all support GraphQL subscriptions over HTTP with minimal configuration. See each library's documentation for details. Apollo Client also provides network adapters for the [Relay](https://www.apollographql.com/docs/react/data/subscriptions#relay) and [urql](https://www.apollographql.com/docs/react/data/subscriptions#urql) libraries. -2. When your router receives a subscription, it executes that same subscription against whichever subgraph defines the requested field—`stockPricesChanged` in the example above. +2. When your router receives a subscription, it executes that same subscription against whichever subgraph defines the requested field—`stockPricesChanged` in the code snippet above. - This communication usually does use a WebSocket subprotocol, for compatibility with most subgraph libraries. - With a self-hosted router, you can also configure an [HTTP-callback-based protocol](https://www.apollographql.com/docs/router/executing-operations/subscription-support/#http-callback-setup). 3. The subgraph periodically sends new data to your router. Whenever it does, the router returns that data to the client in an additional HTTP response part. - - A subscription can include federated entity fields that are defined in other subgraphs. If it does, the router first fetches those fields by querying the corresponding subgraphs, such as **Portfolios** in the diagram above. These queries use HTTP as usual. \ No newline at end of file + - A subscription can include federated entity fields that are defined in other subgraphs. If it does, the router first fetches those fields by querying the corresponding subgraphs, such as the **Portfolios subgraph** in the diagram above. These queries use HTTP as usual. \ No newline at end of file diff --git a/src/content/shared/what-subscriptions-are-for.mdx b/src/content/shared/what-subscriptions-are-for.mdx index 4b94ae4d0..e2a6bc46c 100644 --- a/src/content/shared/what-subscriptions-are-for.mdx +++ b/src/content/shared/what-subscriptions-are-for.mdx @@ -1,5 +1,5 @@ -GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. This means a client can receive multiple updates from a single subscription: +GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. That means a client can receive multiple updates from a single subscription: ```mermaid sequenceDiagram