fix: preserve POST lifecycle ownership

Reject work resuming after transport close, ownership-guard request-map cleanup, and align no-transform response headers across GET, POST, and replay streams.

Author: mattzcarey

.changeset/keepalive-lifecycle-hardening.md

@@ -2,4 +2,4 @@
 '@modelcontextprotocol/sdk': patch
 ---
 
-Hardens the Streamable HTTP server transport's SSE keep-alive lifecycle: timers can no longer be armed after transport close or leak when a priming event write fails, invalid timer delays safely disable keep-alive, and SSE responses disable nginx-style proxy buffering.
+Hardens the Streamable HTTP server transport's SSE lifecycle: deferred work cannot register streams after transport close, error cleanup preserves successor request mappings, invalid timer delays safely disable keep-alive, and SSE responses disable proxy buffering.

src/server/webStandardStreamableHttp.ts

@@ -382,6 +382,10 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
      * Returns a Response object (Web Standard)
      */
     async handleRequest(req: Request, options?: HandleRequestOptions): Promise<Response> {
+        if (this._closed) {
+            return this.createJsonErrorResponse(404, -32001, 'Session not found');
+        }
+
         // In stateless mode (no sessionIdGenerator), each request must use a fresh transport.
         // Reusing a stateless transport causes message ID collisions between clients.
         if (!this.sessionIdGenerator && this._hasHandledRequest) {
@@ -779,6 +783,12 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 }
             }
 
+            // Request parsing and session initialization may await user/runtime
+            // work. Do not register or dispatch after close() has swept state.
+            if (this._closed) {
+                return this.createJsonErrorResponse(404, -32001, 'Session not found');
+            }
+
             // check if it contains requests
             const hasRequests = messages.some(isJSONRPCRequest);
 
@@ -841,7 +851,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
 
             const headers: Record<string, string> = {
                 'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
+                'Cache-Control': 'no-cache, no-transform',
                 Connection: 'keep-alive',
                 'X-Accel-Buffering': 'no'
             };
@@ -875,7 +885,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             reclaimSseBookkeeping = () => {
                 this._streamMapping.get(streamId)?.cleanup();
                 for (const message of messages) {
-                    if (isJSONRPCRequest(message)) {
+                    if (isJSONRPCRequest(message) && this._requestToStreamMapping.get(message.id) === streamId) {
                         this._requestToStreamMapping.delete(message.id);
                     }
                 }

test/server/streamableHttp.test.ts

@@ -270,6 +270,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
 
             expect(response.status).toBe(200);
             expect(response.headers.get('content-type')).toBe('text/event-stream');
+            expect(response.headers.get('cache-control')).toBe('no-cache, no-transform');
             expect(response.headers.get('x-accel-buffering')).toBe('no');
             expect(response.headers.get('mcp-session-id')).toBeDefined();
         });
@@ -487,6 +488,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
 
             expect(sseResponse.status).toBe(200);
             expect(sseResponse.headers.get('content-type')).toBe('text/event-stream');
+            expect(sseResponse.headers.get('cache-control')).toBe('no-cache, no-transform');
             expect(sseResponse.headers.get('x-accel-buffering')).toBe('no');
 
             // Send a notification (server-initiated message) that should appear on SSE stream
@@ -1446,6 +1448,7 @@ describe.each(zodTestMatrix)('$zodVersionLabel', (entry: ZodMatrixEntry) => {
             });
 
             expect(reconnectResponse.status).toBe(200);
+            expect(reconnectResponse.headers.get('cache-control')).toBe('no-cache, no-transform');
             expect(reconnectResponse.headers.get('x-accel-buffering')).toBe('no');
 
             // Read the replayed notification
@@ -3567,4 +3570,86 @@ describe('WebStandardStreamableHTTPServerTransport SSE keep-alive', () => {
 
         await transport.close();
     });
+
+    it('should not reclaim a successor mapping that reused the failed POST request id', async () => {
+        let failPriming = false;
+        let rejectPriming: (() => void) | undefined;
+        const eventStore: EventStore = {
+            async storeEvent(): Promise<EventId> {
+                if (failPriming) {
+                    return new Promise<EventId>((_resolve, reject) => {
+                        rejectPriming = () => reject(new Error('event store unavailable'));
+                    });
+                }
+                return `evt-${randomUUID()}`;
+            },
+            async replayEventsAfter(): Promise<StreamId> {
+                return 'stream-1';
+            }
+        };
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), eventStore });
+        const mcpServer = new McpServer({ name: 'test-server', version: '1.0.0' });
+        mcpServer.registerTool('noop', { description: 'noop' }, async () => ({ content: [] }));
+        await mcpServer.connect(transport);
+
+        const initResponse = await transport.handleRequest(req('POST', { body: TEST_MESSAGES.initialize }));
+        const sessionId = initResponse.headers.get('mcp-session-id') as string;
+        await vi.advanceTimersByTimeAsync(0);
+        failPriming = true;
+
+        const pending = transport.handleRequest(
+            req('POST', {
+                body: { jsonrpc: '2.0', method: 'tools/call', params: { name: 'noop', arguments: {} }, id: 'same-id' },
+                headers: withSession(sessionId)
+            })
+        );
+        await vi.advanceTimersByTimeAsync(0);
+        expect(rejectPriming).toBeDefined();
+
+        const internals = transport as unknown as {
+            _streamMapping: Map<string, unknown>;
+            _requestToStreamMapping: Map<unknown, string>;
+        };
+        const failedStreamId = internals._requestToStreamMapping.get('same-id');
+        expect(failedStreamId).toBeDefined();
+        internals._requestToStreamMapping.set('same-id', 'successor-stream');
+
+        rejectPriming?.();
+        await pending;
+
+        expect(internals._streamMapping.has(failedStreamId!)).toBe(false);
+        expect(internals._requestToStreamMapping.get('same-id')).toBe('successor-stream');
+        internals._requestToStreamMapping.delete('same-id');
+        await transport.close();
+    });
+
+    it('should not register a POST stream after close races session initialization', async () => {
+        let releaseInitialization: (() => void) | undefined;
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: async () => {
+                await new Promise<void>(resolve => {
+                    releaseInitialization = resolve;
+                });
+            }
+        });
+        await new McpServer({ name: 'test-server', version: '1.0.0' }).connect(transport);
+
+        const pendingInit = transport.handleRequest(req('POST', { body: TEST_MESSAGES.initialize }));
+        await vi.advanceTimersByTimeAsync(0);
+        expect(releaseInitialization).toBeDefined();
+
+        await transport.close();
+        releaseInitialization?.();
+        const response = await pendingInit;
+
+        expect(response.status).toBe(404);
+        expect(vi.getTimerCount()).toBe(0);
+        const internals = transport as unknown as {
+            _streamMapping: Map<string, unknown>;
+            _requestToStreamMapping: Map<unknown, string>;
+        };
+        expect(internals._streamMapping.size).toBe(0);
+        expect(internals._requestToStreamMapping.size).toBe(0);
+    });
 });