Standardize shared subscription content

.eslintrc.js

@@ -49,6 +49,8 @@ module.exports = {
         SchemaProposalPublicationMermaid: 'readonly',
         SetApolloVCSCommit: 'readonly',
         StudioPages: 'readonly',
+        HowSubscriptionsWork: 'readonly',
+        WhatSubscriptionsAreFor: 'readonly',
         TopLevelAwait: 'readonly'
       },
       rules: {

.github/styles/config/vocabularies/Docs/accept.txt

@@ -118,6 +118,7 @@ typings
 [Uu]ntracked
 [Uu]ntrusted
 URI(s)?
+urql
 Uplink
 [Vv]alidator
 Vue

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.
 ---
 
-
 <PreviewFeature >
 
 **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
 
 </PreviewFeature>
 
-
 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 "<b>GraphOS</b>";
-  router(["Cloud<br/>Router"]);
-  end;
-  subgraph "<b>Your infrastructure</b>";
-  subgraphA[Stocks<br/>subgraph];
-  subgraphB[Portfolios<br/>subgraph];
-  router-->|"Subscribes<br/>over WebSocket"|subgraphA;
-  router-.->|Can query for<br/>entity fields<br/>as needed|subgraphB;
-  end;
-  client-->|Subscribes<br/>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).
+<WhatSubscriptionsAreFor />
 
-   - 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.
+<HowSubscriptionsWork />
 
 <Tip>
 
@@ -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!
 

src/content/shared/how-subscriptions-work.mdx

@@ -0,0 +1,35 @@
+
+```mermaid
+flowchart LR;
+  client(Client);
+  router(["GraphOS<br/>Router"]);
+  subgraphA[Stocks<br/>subgraph];
+  subgraphB[Portfolios<br/>subgraph];
+  router-->|"Subscribes<br/>over WebSocket<br/>(or via callback)"|subgraphA;
+  router-.->|Can query for<br/>entity fields<br/>as needed|subgraphB;
+  client-->|Subscribes<br/>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 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 the **Portfolios subgraph** in the diagram above. These queries use HTTP as usual.

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';

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. That 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.