ok encorporate news

Author: enisdenjo

packages/documentation/content/docs/router/configuration/traffic_shaping.mdx

@@ -29,8 +29,12 @@ itself (i.e. how it handles incoming client requests).
 
 Configures inbound in-flight request deduplication. When enabled, identical concurrent
 incoming GraphQL `query` requests are coalesced into a single execution, with the result shared
-among all waiting clients. This is distinct from the outbound `dedupe_enabled`, which
-deduplicates the requests the router sends to subgraphs.
+among all waiting clients. Subscriptions are also deduplicated: N clients subscribing to the same
+operation with the same variables result in exactly one upstream subgraph connection, with events
+fanned out to all connected clients via a broadcast channel.
+
+This is distinct from the outbound `dedupe_enabled`, which deduplicates the requests the router
+sends to subgraphs.
 
 For a detailed explanation and tuning guidance see the
 [Request Deduplication section](/docs/router/guides/performance-tuning#request-deduplication) of
@@ -107,6 +111,25 @@ traffic_shaping:
 
 </Tabs>
 
+### `router.max_long_lived_clients`
+
+- **Type:** `integer`
+- **Default:** `128`
+
+```yaml
+traffic_shaping:
+  router:
+    max_long_lived_clients: 256
+```
+
+Limits the maximum number of concurrent long-lived client connections: WebSocket connections and
+HTTP streaming responses (SSE, Incremental Delivery, Multipart HTTP). When the limit is reached,
+new long-lived connection attempts are rejected with `503 Service Unavailable` and a
+`Retry-After: 5` response header. Regular HTTP requests (queries and mutations) are not affected.
+
+This limit only activates when at least one of WebSocket or Subscriptions is enabled. Setting it
+to `0` disables the limit entirely.
+
 ## Outbound Options
 
 The following options (`dedupe_enabled`, `pool_idle_timeout`, and `request_timeout`) can be set

packages/documentation/content/docs/router/guides/performance-tuning.mdx

@@ -93,10 +93,8 @@ independently: **inbound** and **outbound**.
 
 ### Inbound Deduplication
 
-Inbound deduplication (`traffic_shaping.router.dedupe`) operates at the entry point of the
-router. When multiple clients send identical GraphQL `query` operations simultaneously, the router
-executes the operation only once and shares the result with all waiting clients — subgraphs receive
-just a single request regardless of how many clients are waiting.
+Inbound deduplication (`traffic_shaping.router.dedupe`) operates at the entry point of the router
+and applies to both queries and subscriptions.
 
 - **Default:** `false` (opt-in)
 
@@ -107,7 +105,65 @@ traffic_shaping:
       enabled: true
 ```
 
-**Deduplication key**
+#### Queries
+
+When multiple clients send identical GraphQL `query` operations simultaneously, the router
+executes the operation only once and shares the result with all waiting clients - subgraphs receive
+just a single request regardless of how many clients are waiting.
+
+#### Subscriptions
+
+When multiple clients subscribe to the same operation with the same variables, the router opens
+exactly one upstream subgraph connection. Events from that upstream are broadcast to all connected
+clients via a shared channel.
+
+This is fundamentally different from query deduplication because subscriptions are long-lived
+streams. The upstream connection stays open as long as at least one client is subscribed. When
+the upstream finishes or all clients disconnect, the entry is removed and the next matching client
+starts a fresh upstream.
+
+One consequence: **late joiners do not receive replayed events.** A client that joins an
+already-running subscription receives events from the moment it subscribes onward. Events already
+delivered to earlier clients are not replayed.
+
+##### Transport-agnostic deduplication
+
+The fingerprint space is shared between HTTP and WebSocket transports. A subscription started over
+HTTP and an identical one over WebSocket produce the same fingerprint and can deduplicate against
+each other. The same applies to queries: a query sent over WebSocket deduplicates with the same
+query sent over HTTP.
+
+However, the `Accept` header is part of the fingerprint when `headers` is set to `all` (the
+default). HTTP streaming clients send `Accept: text/event-stream` or `Accept: multipart/mixed`
+while WebSocket clients send no `Accept` header, so they produce different fingerprints by default
+and do not deduplicate against each other.
+
+To achieve cross-transport subscription deduplication - where a WebSocket subscription and an SSE
+subscription for the same operation share one upstream connection - configure `headers: none` or
+use an explicit include list that omits transport-specific headers:
+
+```yaml
+traffic_shaping:
+  router:
+    dedupe:
+      enabled: true
+      headers: none
+```
+
+or with an explicit include list:
+
+```yaml
+traffic_shaping:
+  router:
+    dedupe:
+      enabled: true
+      headers:
+        include:
+          - authorization
+          - x-tenant-id
+```
+
+#### Deduplication key
 
 Two requests are considered identical when the following all match:
 
@@ -118,7 +174,7 @@ Two requests are considered identical when the following all match:
 - Schema checksum (prevents sharing across schema reload transitions)
 - Selected request headers (controlled by the `headers` policy below)
 
-**Header policy**
+#### Header policy
 
 By default all headers are included in the fingerprint, so requests with different `Authorization`
 or `Cookie` headers are **not** deduplicated with each other. You can narrow this down:
@@ -170,11 +226,12 @@ traffic_shaping:
 
 - Many clients frequently issue the same popular queries (dashboards, landing pages, product
   listings)
-- You want to reduce overall query execution pressure on your subgraphs under concurrent load
+- Many clients subscribe to the same data (live scoreboards, shared feeds, broadcast events)
+- You want to reduce overall execution pressure on your subgraphs under concurrent load
 
 **When you might leave it disabled:**
 
-- All queries are highly personalised and rarely identical
+- All operations are highly personalised and rarely identical
 - You're debugging and want every request to execute independently
 
 ### Outbound Deduplication

packages/documentation/content/docs/router/subscriptions/index.mdx

@@ -184,6 +184,16 @@ The protocols used between the router and subgraphs are independent from those u
 
 If a client requests a subscription over an unsupported transport, the router returns `406 Not Acceptable`.
 
+## Deduplication
+
+Subscriptions participate in the same inbound deduplication mechanism as queries. When multiple clients subscribe to the same operation with the same deduplication parameters, the router opens exactly one upstream subgraph connection and fans events out to all connected clients via a broadcast channel.
+
+See [Inbound Deduplication](/docs/router/guides/performance-tuning#inbound-deduplication) for how to enable and configure it.
+
+## Schema Reload
+
+When a new supergraph schema is loaded, the router closes all active subscriptions before the schema is swapped in. Each client receives a final error event with the `SUBSCRIPTION_SCHEMA_RELOAD` error code. Clients are expected to handle this code by reconnecting and re-subscribing. After reconnecting, the subscription runs against the new schema.
+
 ## Configuration
 
 Subscriptions are disabled by default. To enable them, set `enabled: true` in the `subscriptions` section of your router configuration:
@@ -198,3 +208,38 @@ You can also enable subscriptions using the `SUBSCRIPTIONS_ENABLED` environment
 ```bash
 SUBSCRIPTIONS_ENABLED=true
 ```
+
+### Broadcast Capacity
+
+Controls the buffer size of the internal broadcast channel used to fan subscription events out to clients.
+
+When a consumer falls behind and the buffer fills up, it skips missed messages and continues from
+the latest available event. The consumer is not disconnected - there is a trace log when this
+happens. Increase this value if consumers are frequently falling behind on high-throughput
+subscriptions.
+
+```yaml
+subscriptions:
+  enabled: true
+  broadcast_capacity: 64 # defaults to 32
+```
+
+### Long-Lived Client Limit
+
+HTTP streaming responses (SSE, Incremental Delivery, Multipart HTTP) and WebSocket connections are
+long-lived - they hold an open connection for the duration of the subscription. To protect the
+router from resource exhaustion, a global limit caps the number of these connections that can be
+active at the same time. Regular HTTP requests (queries and mutations) are not counted toward this
+limit.
+
+When the limit is reached, new long-lived connection attempts are rejected with
+`503 Service Unavailable` and a `Retry-After: 5` response header. The limit defaults to `128` and
+is configurable via [`traffic_shaping.router.max_long_lived_clients`](/docs/router/configuration/traffic_shaping#routermax_long_lived_clients):
+
+```yaml
+traffic_shaping:
+  router:
+    max_long_lived_clients: 256
+```
+
+Set it to `0` to disable the limit entirely.

packages/documentation/content/docs/router/subscriptions/websockets.mdx

@@ -52,6 +52,8 @@ Client WebSocket support is configured at the root level under `websocket` - it
 
 Each WebSocket connection from a client is long-lived and can carry multiple GraphQL operations. For every operation sent over the connection - including single-shot operations like queries and mutations - the router creates a **synthetic HTTP request**. This means every operation goes through the full [plugin system](/docs/router/plugin-system) exactly as if it were a regular HTTP request. Authorization, header manipulation, rate limiting, and all other plugins apply uniformly regardless of whether the client connected over HTTP or WebSocket.
 
+Because operations are processed as synthetic HTTP requests, they share the same fingerprint space as regular HTTP requests. A query sent over WebSocket can deduplicate with the same query sent over HTTP, and a WebSocket subscription can deduplicate with the same subscription started over SSE (when the `Accept` header is excluded from the fingerprint). See [Inbound Deduplication](/docs/router/guides/performance-tuning#inbound-deduplication) for details.
+
 ### Configuration
 
 ```yaml