review: reject stateless reuse before delegating to getRequestListener so the caller keeps control of the response

Author: felixweinberger

packages/middleware/node/src/streamableHttp.ts

@@ -196,6 +196,13 @@ export class NodeStreamableHTTPServerTransport implements Transport {
      * @param parsedBody - Optional pre-parsed body from body-parser middleware
      */
     async handleRequest(req: IncomingMessage & { auth?: AuthInfo }, res: ServerResponse, parsedBody?: unknown): Promise<void> {
+        // Fail fast before delegating: once getRequestListener is invoked, a
+        // rejected dispatch is committed to `res` as an empty 500 before the
+        // rejection can surface, leaving the caller unable to shape its own
+        // error response. Checking up front rejects with nothing written to
+        // `res`. The check lives on the wrapped transport (single source).
+        this._webStandardTransport.assertNotReused();
+
         // Store context for this request to pass through auth and parsedBody
         // We need to intercept the request creation to attach this context
         const authInfo = req.auth;
@@ -223,14 +230,15 @@ export class NodeStreamableHTTPServerTransport implements Transport {
         // including proper SSE streaming support
         await handler(req, res);
 
-        // getRequestListener absorbs a rejected dispatch into a generic 500
-        // response, which would swallow the wrapped transport's single-use
-        // throw. Re-raise it so the documented behavior (reusing a stateless
-        // transport across requests throws at the call site) holds for the
-        // Node adapter too. Other dispatch errors keep the existing
-        // 500-response behavior. Matched by code, not `instanceof`, so the
-        // check also holds if bundling ever yields two copies of the error
-        // class.
+        // Backstop for concurrent calls racing the up-front check (the
+        // single-use flag is set inside the wrapped handleRequest, after the
+        // request conversion): getRequestListener absorbs a rejected dispatch
+        // into a generic 500, which would swallow the single-use throw.
+        // Re-raise it so the documented behavior (reusing a stateless
+        // transport across requests throws at the call site) holds on this
+        // path too. Other dispatch errors keep the existing 500-response
+        // behavior. Matched by code, not `instanceof`, so the check also
+        // holds if bundling ever yields two copies of the error class.
         if (dispatchError instanceof Error && (dispatchError as { code?: unknown }).code === SdkErrorCode.StatelessTransportReuse) {
             throw dispatchError;
         }

packages/middleware/node/test/streamableHttp.test.ts

@@ -1667,11 +1667,13 @@ describe('Zod v4', () => {
             perRequestServers.push(mcpServer);
 
             const callSiteErrors: Error[] = [];
+            const headersSentAtRejection: boolean[] = [];
             const sharedServer = createServer(async (req, res) => {
                 try {
                     await transport.handleRequest(req, res);
                 } catch (error) {
                     callSiteErrors.push(error as Error);
+                    headersSentAtRejection.push(res.headersSent);
                     if (!res.headersSent) res.writeHead(500);
                     res.end();
                 }
@@ -1686,6 +1688,10 @@ describe('Zod v4', () => {
                 expect(callSiteErrors).toHaveLength(1);
                 expect(callSiteErrors[0]!.message).toContain('Stateless transport cannot be reused across requests');
                 expect((callSiteErrors[0] as { code?: unknown }).code).toBe('STATELESS_TRANSPORT_REUSE');
+                // The rejection reached the caller before anything was
+                // committed to `res` — the caller keeps control of the
+                // response it sends for the rejected request.
+                expect(headersSentAtRejection).toEqual([false]);
             } finally {
                 sharedServer.close();
             }

packages/server/src/server/streamableHttp.ts

@@ -374,7 +374,15 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
      * Handles an incoming HTTP request, whether `GET`, `POST`, or `DELETE`
      * Returns a `Response` object (Web Standard)
      */
-    async handleRequest(req: Request, options?: HandleRequestOptions): Promise<Response> {
+    /**
+     * Throws when a stateless transport has already handled its single
+     * request exchange. This is the same check `handleRequest()` performs on
+     * entry; exposed so wrapping adapters (e.g. the Node middleware) can fail
+     * fast before committing anything to their own response stream.
+     *
+     * @internal
+     */
+    assertNotReused(): void {
         // 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) {
@@ -383,6 +391,10 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 'Stateless transport cannot be reused across requests. Create a new transport per request.'
             );
         }
+    }
+
+    async handleRequest(req: Request, options?: HandleRequestOptions): Promise<Response> {
+        this.assertNotReused();
         this._hasHandledRequest = true;
 
         // Validate request headers for DNS rebinding protection