fix(client): allow transport restart after close()#1828
fix(client): allow transport restart after close()#1828felixweinberger wants to merge 5 commits intomainfrom
Conversation
StreamableHTTPClientTransport: change start() guard from 'controller exists' to 'controller exists and not aborted', allowing restart after close(). Also clear _sessionId in close() so the stale server-assigned ID is not sent on post-restart requests. SSEClientTransport: clear _eventSource, _endpoint, _abortController in close() so start()'s guard allows restart. Fixes #1641
🦋 Changeset detectedLatest commit: 57d2cbf The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/server
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
… reconnects after restart - close() now resets _serverRetryMs and _lastUpscopingHeader so a restarted transport does not inherit the previous session's server-provided retry delay or upscoping-loop guard state. - _scheduleReconnection and _handleSseStream capture the abort signal at schedule time instead of re-reading this._abortController. After close() + start() the field points at the new session's controller, so the previous read allowed a stale reconnect to fire into the restarted transport. - Added tests for both cases.
| } finally { | ||
| this._cancelReconnection = undefined; | ||
| this._abortController?.abort(); | ||
| this._sessionId = undefined; | ||
| this._lastUpscopingHeader = undefined; | ||
| this._serverRetryMs = undefined; | ||
| this.onclose?.(); | ||
| } | ||
| } |
There was a problem hiding this comment.
🔴 close() clears _sessionId, _lastUpscopingHeader, and _serverRetryMs but does NOT clear _resourceMetadataUrl or _scope. After a restart, if the new lifecycle receives a 401 without a WWW-Authenticate header (valid per spec), stale values flow into finishAuth() or the 403 upscoping auth() call, targeting the wrong OAuth server. Fix: add this._resourceMetadataUrl = undefined and this._scope = undefined to the finally block in close().
Extended reasoning...
The PR establishes a clear pattern: all per-lifecycle state must be reset in close() so the transport can be safely reused after restart. It correctly adds this._sessionId = undefined, this._lastUpscopingHeader = undefined, and this._serverRetryMs = undefined to the finally block. However, _resourceMetadataUrl (initialized to undefined in the constructor at line ~194) and _scope (line ~195) are omitted from this cleanup, breaking the same invariant.
Where these fields are set: _resourceMetadataUrl and _scope are set during 401 handling in _startOrAuthSse() (lines 260-261) and _send() (lines 580-581). _scope is also updated in the 403/insufficient_scope path (lines 620, 624). The 403 path is especially subtle: _resourceMetadataUrl is only updated conditionally (if (resourceMetadataUrl) { this._resourceMetadataUrl = resourceMetadataUrl; }), so if a new lifecycle 403 response omits the resource_metadata parameter, the stale lifecycle-1 URL persists.
Where these fields are consumed: Both are passed directly to auth() in finishAuth() (lines 508-509: resourceMetadataUrl: this._resourceMetadataUrl, scope: this._scope) and in the 403 upscoping path (lines 631-632). These values drive token endpoint discovery; using the wrong URL means the client contacts the wrong OAuth authorization server.
Step-by-step failure scenario: (1) Lifecycle 1: server returns 401 with WWW-Authenticate header containing resource_metadata=https://old-server/resource, setting _resourceMetadataUrl. (2) close() is called; _resourceMetadataUrl is NOT cleared. (3) OAuth server config changes to a new resource metadata URL. (4) start() is called (newly enabled by this PR). (5) New lifecycle triggers a 401 WITHOUT a www-authenticate header, which is valid per spec when the server assumes the client already has the metadata. The guard at line 258 (if response.headers.has('www-authenticate')) is false, so _resourceMetadataUrl is NOT refreshed. (6) finishAuth() or onUnauthorized calls auth() with the stale _resourceMetadataUrl, performing token endpoint discovery against the wrong server.
Why existing code does not prevent this: The 401 path only updates _resourceMetadataUrl/_scope when the www-authenticate header is present. A spec-compliant server may omit this header on subsequent 401s after the client has already received the metadata. Before this PR, start() after close() threw already started, so users always created a new transport instance that re-initialized both fields to undefined in the constructor. This PR enables same-instance restart without the corresponding field resets, the same class of omission as _sessionId, _lastUpscopingHeader, and _serverRetryMs already fixed by this PR.
Fix: Add this._resourceMetadataUrl = undefined and this._scope = undefined to the finally block in close(), alongside the existing this._sessionId = undefined, following the exact same pattern the PR already uses for the other per-lifecycle fields.
There was a problem hiding this comment.
These need to survive close(). The OAuth re-auth flow this PR enables is 401 sets fields -> close() -> finishAuth() reads them at L508-509 -> start(). Clearing them in close() breaks finishAuth(). They're discovery metadata for the fixed _url, not per-session state like _sessionId.
…sistent with restart invariant)
| private async _startOrAuthSse(options: StartSSEOptions, isAuthRetry = false): Promise<void> { | ||
| const { resumptionToken } = options; | ||
|
|
||
| // Capture the signal active when this call started so a close()/start() during the awaits | ||
| // below doesn't bind this stale GET to the restarted transport's controller. | ||
| const signal = this._abortController?.signal; | ||
|
|
||
| try { | ||
| // Try to open an initial SSE stream with GET to listen for server messages | ||
| // This is optional according to the spec - server may not support it | ||
| const headers = await this._commonHeaders(); | ||
| if (signal?.aborted) return; | ||
| const userAccept = headers.get('accept'); | ||
| const types = [...(userAccept?.split(',').map(s => s.trim().toLowerCase()) ?? []), 'text/event-stream']; | ||
| headers.set('accept', [...new Set(types)].join(', ')); |
There was a problem hiding this comment.
🔴 The 401 auth-retry path in _startOrAuthSse is missing a signal?.aborted guard before the recursive return this._startOrAuthSse(options, true) call, allowing a ghost SSE stream to open on the new lifecycle after a close()+start() during token refresh. Add if (signal?.aborted) return; immediately before the recursive call to prevent the stale reconnect from binding to the new lifecycle's controller.
Extended reasoning...
What the bug is and how it manifests
At the top of _startOrAuthSse (line 238), the PR correctly captures const signal = this._abortController?.signal to prevent a close()+start() during async work from binding a stale GET to the new lifecycle. There is an existing if (signal?.aborted) return; check after await this._commonHeaders() (line 246). However, the 401 auth-retry path (lines 270-277) contains its own async suspension — await this._authProvider.onUnauthorized({...}) — without any corresponding guard before the recursive call.
The specific code path that triggers it
The relevant code is:
if (this._authProvider.onUnauthorized && \!isAuthRetry) {
await this._authProvider.onUnauthorized({ // async, can suspend hundreds of ms
response,
serverUrl: this._url,
fetchFn: this._fetchWithInit
});
await response.text?.().catch(() => {});
// NO signal?.aborted check here
return this._startOrAuthSse(options, true); // recursive call captures fresh S2
}
Why existing code does not prevent it
The signal variable captured at line 238 IS S1 (the old lifecycle). After onUnauthorized() resolves, signal (S1) is already aborted. But the code never inspects signal at this point — it proceeds directly to the recursive call. The recursive invocation then runs const signal = this._abortController?.signal at ITS line 238, which now captures S2 (the new non-aborted controller). The subsequent if (signal?.aborted) return check sees S2 (not aborted) and proceeds to open the GET fetch with S2 as its signal, fully binding the ghost stream to the new lifecycle.
Step-by-step proof
- Old-lifecycle _startOrAuthSse(options, false) starts; signal = S1 is captured at line 238.
- The GET fetch completes with 401; onUnauthorized() is awaited at line 270 — this triggers a token-refresh network call, suspending for hundreds of ms.
- While suspended, user calls transport.close(): S1 is aborted. Then transport.start(): this._abortController = new AbortController() (S2, not aborted).
- onUnauthorized() resolves. response.text() is consumed.
- return this._startOrAuthSse(options, true) executes at line 277 with NO check of signal (S1).
- In the recursive invocation, line 238 runs: const signal = this._abortController?.signal — now S2.
- await this._commonHeaders() completes; if (signal?.aborted) return checks S2 — not aborted — passes.
- A new GET fetch is issued with signal: S2, opening a ghost SSE stream bound to the new lifecycle.
Impact
The ghost stream is associated with the new lifecycle's controller (S2), so it IS cleaned up on the next close(). However, it carries the old-lifecycle's options — including a potentially stale resumptionToken / Last-Event-ID — to the server, which may replay stale events into the new session or confuse server-side session state. This is precisely the ghost SSE pattern the PR's signal-capture design was meant to prevent, but the auth-retry path was missed.
How to fix it
Add if (signal?.aborted) return; immediately before return this._startOrAuthSse(options, true):
await this._authProvider.onUnauthorized({ response, serverUrl: this._url, fetchFn: this._fetchWithInit });
await response.text?.().catch(() => {});
if (signal?.aborted) return; // add this guard
return this._startOrAuthSse(options, true);
This mirrors the existing guard after _commonHeaders() and correctly uses the already-captured S1 which is aborted at this point, preventing the recursive call from re-reading the replaced controller.
|
|
||
| async close(): Promise<void> { | ||
| this._abortController?.abort(); | ||
| this._abortController = undefined; | ||
| this._eventSource?.close(); | ||
| this._eventSource = undefined; | ||
| this._endpoint = undefined; | ||
| this.onclose?.(); | ||
| } |
There was a problem hiding this comment.
🔴 SSEClientTransport.close() now clears _eventSource (enabling restart), but omits _resourceMetadataUrl and _scope — after close()+start(), if the new lifecycle's 401 arrives without a WWW-Authenticate header (valid per RFC 9110), stale values from the prior lifecycle are passed directly to auth() in finishAuth(), targeting the wrong OAuth server. Fix: add this._resourceMetadataUrl = undefined and this._scope = undefined to close().
Extended reasoning...
What the bug is and how it manifests
SSEClientTransport declares _resourceMetadataUrl (line 71) and _scope (line 72) as instance fields. The PR's change to close() correctly adds this._eventSource = undefined (enabling restart via the start() guard at line 219) and this._abortController = undefined, but does NOT add this._resourceMetadataUrl = undefined or this._scope = undefined. These fields carry OAuth discovery state from one lifecycle and silently contaminate the next.
The specific code path that triggers it
_resourceMetadataUrl and _scope are set in two places: (1) inside _startOrAuth()'s EventSource fetch interceptor at lines 138–139, guarded by if (response.headers.has('www-authenticate')); and (2) inside _send() at lines 276–277, same guard. Both assignments only fire when the 401 response includes a WWW-Authenticate header. The stale values are consumed in finishAuth() at lines 233–234 where they are passed directly to auth() for OAuth token endpoint discovery.
Why existing code does not prevent it
The 401 handling in both _startOrAuth() and _send() only refreshes _resourceMetadataUrl and _scope when www-authenticate is present. Per RFC 9110 §11.6.1 and the MCP OAuth spec, a server may omit the WWW-Authenticate header on subsequent 401 responses once the client has previously received the resource metadata — the server may assume the client already knows where to go. In that case, the conditional assignments are skipped and the stale values from the prior lifecycle persist unchecked.
Impact
Before this PR, start() after close() always threw 'SSEClientTransport already started!' because the start() guard (if (this._eventSource)) saw the non-null _eventSource that close() did not clear. Users were forced to instantiate a new transport, which re-initializes _resourceMetadataUrl = undefined and _scope = undefined in the constructor (lines 87–88). This PR adds this._eventSource = undefined to close(), making same-instance restart possible — but without the corresponding field resets. The primary scenario this PR targets (start → 401 → close → OAuth → start) is exactly the path that triggers the stale-state bug.
Step-by-step proof
- Lifecycle 1: transport.start() → SSE GET returns 401 with WWW-Authenticate: Bearer realm="old-auth", resource_metadata="https://old-server/.well-known/resource" → _resourceMetadataUrl is set to the old server URL; _scope is set if provided.
- User calls close(). The PR's new code sets _eventSource = undefined, _abortController = undefined, _endpoint = undefined. _resourceMetadataUrl and _scope are NOT cleared — they still point to the old server.
- OAuth server is reconfigured. The resource is now served from a different authorization server.
- User calls start() — succeeds (newly enabled by this PR; _eventSource is undefined so guard passes).
- New SSE GET returns 401 WITHOUT a WWW-Authenticate header (server assumes client already has the resource metadata from lifecycle 1).
- The if (response.headers.has('www-authenticate')) guard at line 138 is false; _resourceMetadataUrl is NOT refreshed.
- The 401 path reaches finishAuth() or the auth retry → auth() is called with the stale _resourceMetadataUrl (old server URL) and stale _scope. The client attempts token endpoint discovery against the wrong OAuth authorization server, failing to authenticate with the new one.
How to fix it
Add the two missing resets to close():
This mirrors the exact pattern the PR already uses for _sessionId, _lastUpscopingHeader, and _serverRetryMs in StreamableHTTPClientTransport.close(), and follows what the constructor already does at lines 87–88.
1 participant
Allows
StreamableHTTPClientTransportandSSEClientTransportto restart afterclose().Motivation and Context
Fixes #1641.
start()throws"already started"afterclose()because the start guard checks whether_abortControllerexists, not whether it was aborted. This breaks OAuth re-authentication flows: start → 401 → close → OAuth → start (throws).StreamableHTTPClientTransport: Changed the
start()guard fromif (this._abortController)toif (this._abortController && !this._abortController.signal.aborted). This is safer than clearing_abortControllerinclose(), which would break thesignal.abortedchecks at :344, :437, :456 used by late-firing reconnection callbacks. Also clears_sessionIdinclose()so the stale server-assigned ID is not sent on post-restart requests (would 404).SSEClientTransport: Clears
_eventSource,_endpoint,_abortControllerinclose(). SSE's start guard checks_eventSource, and there are nosignal.aborteddependencies.How Has This Been Tested?
Added a test that receives a session ID, closes, restarts, and asserts both
start()succeeds and the stale session ID is not sent. Test fails on main (expected 'stale-session-abc' to be undefined), passes with the fix. All 347 client tests pass.Breaking Changes
None.
Types of changes
Checklist
Additional context
Credit to @matantsach for #1647 which identified the issue and the SSE state-reset approach.