[graphql-stream] Cap concurrent subscriptions with a configurable max_subscribers limit [23/n]

[tpham-mysten]

Description

Subscriptions currently open without any aggregate limit, so a burst of subscribers can drive server CPU and memory unbounded. This adds a configurable max_subscribers (default 1024): each subscription claims a slot from a shared semaphore held for its lifetime by the lifecycle guard, and a subscription opened while all slots are taken is refused with a resource_exhausted error so the client can retry later. Refusals are counted by graphql_subscription_rejected{type, reason}.

Guard creation moves out of the driver stream! bodies up to the resolver, so admission happens once at connect time before any work begins.

Test plan

New rejects_at_capacity unit test covers admission, the at-capacity refusal and its metric, and slot release on drop. Existing subscription lib tests cover the guard threaded through the drivers.

Stack

• [graphql-stream] WebSocket subscription infrastructure [1/n] #26019
• [graphql-stream] Implement checkpoint subscription streaming [2/n] #26094
• [graphql-stream] Propagate transactions fields for checkpoint subscription streaming [3/n] #26117
• [graphql-stream] Add object resolution to checkpoint subscription transactions [4/n] #26170
• [graphql-stream] Add package caching from streamed checkpoints [5/n] #26194
• [graphql-stream] Add top-level transaction subscription [6/n] #26202
• [graphql-stream] Recover from upstream gRPC gaps via kv-rpc [7/n] #26414
• [graphql-stream] Add top-level events subscription [8/n] #26453
• [graphql-stream] Lift streamed checkpoint payload onto Scope [9/n] #26476
• [graphql-stream] Resolve Event.transaction in streaming mode [10/n] #26487
• [graphql-stream] SSE transport + SSE-aware GraphiQL [11/n] #26425
• [graphql-stream] Add Address.asTransactionObject [12/n] #26495
• [graphql-stream] Add cursor field to Checkpoint [13/n] #26731
• [graphql-stream] Resumable checkpoints subscription [14/n] #26714
• [graphql-stream] Resumable transactions subscription [15/n] #27140
• [graphql-stream] resolve subscription payloads concurrently [16/n] #27537
• [graphql-stream] per-subscriber delivery throttle for subscriptions [17/n] #27564
• [graphql-stream] Resumable event subscriptions on a shared scan-then-live driver [18/n] #27580
• [graphql-stream] Reject subscriptions that start too far ahead of the tip [19/n] #27635
• [graphql-stream] Support previousTransaction with cached streamed transactions [20/n] #27709
• [graphql-stream-metrics] Add metrics for the subscription upstream checkpoint stream [21/n] #27669
• [graphql-stream-metrics] Add per-subscriber subscription metrics [22/n] #27756
• [graphql-stream] Cap concurrent subscriptions with a configurable max_subscribers limit [23/n] #27787

Release notes

Check each box that your change affects. If none of the boxes relate to your changes, release notes aren't required.

For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates.

• Protocol:
• Nodes (Validators and Full nodes):
• gRPC:
• JSON-RPC:
• GraphQL:
• CLI:
• Rust SDK:
• REST API:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sui-docs	Ready	Preview	Aug 26, 2026 7:41pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
multisig-toolkit	Ignored	Preview	Aug 26, 2026 7:41pm
sui-kiosk	Ignored	Preview	Aug 26, 2026 7:41pm

[datadog-mystenlabs]

⚠️ Warnings

🚦 5 Pipeline jobs failed

Native Bridge | test (ubuntu-ghcloud)

View in Datadog · View in GitHub Actions

Unbound variable: FOUNDRY_BIN_DIR during script execution.

Release Notes | Validate Release Notes in 27787

View in Datadog · View in GitHub Actions

Found issues with release notes in PR 27787: unfamiliar impact area 'REST API'.

Rust | simtest

View in Datadog · View in GitHub Actions

4 tests failed due to panic: 'there is no reactor running, must be called from the context of a Madsim runtime' at /home/runner/.cargo/git/checkouts/mysten-sim-84667d6d927bc7b7/6b8e1e8/msim/src/sim/runtime/context.rs:15:55.

View all 5 failed jobs.

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: ebcb2a5 | Docs | View more details | Give us feedback!}

[amnn]

Would consider allowing requests to wait a little bit for a semaphore token, but broadly looks good, thanks @tpham-mysten

[tpham-mysten]

Thanks @amnn!

Doing this on the GraphQL server side is probably not the right place, mainly because it's tricky to decide which request we should hold. From the infra side, I think the per-IP rate limit should be partially sufficient to prevent it.

[amnn]

I think if we take the view that we should not be hitting this limit under normal operation, and we can rely on health checks and auto-scaling, then I can get behind this (but then we should probably set a more generous upper limit at this layer and leave the more conservative limit for the gateway to enforce).