SubscriptionSession
Defined in: packages/client/src/circuits/subscription-client.ts:93
Properties
Section titled “Properties”close: () =>
void
Defined in: packages/client/src/circuits/subscription-client.ts:135
Close the session and hand its engine shape claims back — promptly, best-effort.
Synchronous and fire-and-forget by design. Every grant this session was given is a named claim on
an engine shape (a POST /shapes join), and a live claim blocks both dormancy and eviction, so
releasing at close is what lets an idle shape be reclaimed now rather than at the end of its lease
window.
Not reporting whether it landed is a consequence of WHEN this runs, not of a correctness trade.
The release is idempotent — each grant names its own claim, so a repeat is the same act once
(fork ADR-0008) — but the most common close is a page unload, which cannot await anything or
retry anything. So it fires once, silently, and the lease covers the rest: a release lost with the
document leaves claims the engine reclaims within its lease window (leaseSeconds), because
nothing renews them once the session is gone.
Returns
Section titled “Returns”void
granted
Section titled “granted”granted:
GrantedStream[]
Defined in: packages/client/src/circuits/subscription-client.ts:94
refresh
Section titled “refresh”refresh: () =>
Promise<string|null>
Defined in: packages/client/src/circuits/subscription-client.ts:119
Force a re-mint now — what a 403 from the edge should trigger. Null when nothing survived.
A re-mint that FAILS (the control plane is down, unreachable, or answering 5xx) resolves with the
token already held rather than rejecting. This is the ADR-0013 “the deployment being down is not
the subject’s problem” rule applied at the one place it is easy to get wrong: the stream reader
awaits this promise (through token and onTokenRejected) before its requests, and a rejection
there ends the read — every stream of the group then re-subscribes over a blip the held token
would have ridden out. The held token is still good for up to refreshSkewSeconds, and when it
truly lapses the edge answers 403, the stream ends, and the group re-subscribes
(startCircuitsSync’s scheduleRestart) — which is where a 401 surfaces as onAuthError and a
503 as a retried subscribe, both of them recoverable and both of them visible.
Returns
Section titled “Returns”Promise<string | null>
refused
Section titled “refused”refused:
RefusedStream[]
Defined in: packages/client/src/circuits/subscription-client.ts:95
token: () =>
Promise<string>
Defined in: packages/client/src/circuits/subscription-client.ts:105
The current stream token, re-minted on demand.
Hand this straight to the sync engine: it is called per request, so a token that expires mid-poll is replaced without the subscription noticing.
It rejects for exactly one reason — every grant was revoked, so there is no bearer left to send. A control plane that could not be reached is NOT that reason: see SubscriptionSession.refresh.
Returns
Section titled “Returns”Promise<string>