NodeHttpServer: requests on keep-alive connections hang during graceful shutdown #8728

Activity

1. eugene1g

   added

   bugSomething isn't workingSomething isn't working

   on Oct 4, 2026
2. eugene1g commented on Oct 4, 2026

   

   eugene1g

   on Oct 4, 2026

   Last edited by eugene1g

   Author

   More actions

   Note

   AI-generated follow-up. from the issue author Claude 5.5 wrote this analysis while helping me prepare this issue

   Why the two-line fix in this issue is incomplete

   Keeping the listeners attached until draining ends fixes the repro, but two problems remain:

   1. The bug returns when gracefulShutdownTimeout runs out. The timeout only stops waiting for server.close(). Nothing closes the sockets. The listeners are then removed while connections are still open, and the next request on any of them hangs as before.
   2. Busy keep-alive connections never finish draining. After server.close(), Node keeps sending Connection: keep-alive and reusing the socket (verified with plain node:http). A pooled client or proxy keeps the connection busy, so every shutdown runs the full timeout and then hits problem 1. In testing, a client that reused its connection got 15 responses during a 1.5 s drain, and the drain never finished on its own.

   Related bug: a timed-out shutdown makes dispose() reject

   shutdown is Effect.cached:

   effect/packages/platform/node/src/NodeHttpServer.ts

   Lines 104 to 124 in bc44526

   	const shutdown = yield* Effect.callback<void>((resume) => {
   	if (!server.listening) {
   	return resume(Effect.void)
   	}
   	server.close((error) => {
   	if (error) {
   	resume(Effect.die(error))
   	} else {
   	resume(Effect.void)
   	}
   	})
   	}).pipe(Effect.cached)
   	const preemptiveShutdown = options.disablePreemptiveShutdown ?
   	Effect.void :
   	Effect.timeoutOrElse(shutdown, {
   	duration: options.gracefulShutdownTimeout ?? Duration.seconds(20),
   	orElse: () => Effect.void
   	})
   	yield* Scope.addFinalizer(scope, shutdown)

   When the timeout interrupts the first run, Effect.cached remembers the interruption. The outer Scope.addFinalizer(scope, shutdown) gets that interruption back, so ManagedRuntime.dispose() rejects with All fibers interrupted without error. This happens on every shutdown that reaches the timeout, independent of the keep-alive bug.

   Suggested fix

   Four changes:

   • keep the listeners attached until draining ends;
   • send Connection: close while draining;
   • close all connections when the timeout runs out;
   • replace Effect.cached with a Deferred.

   // make()
   const closed = Deferred.makeUnsafe<void>()
   let closeStarted = false
   const shutdown = Effect.suspend(() => {
     if (!closeStarted) {
       closeStarted = true
       if (!server.listening) {
         Deferred.doneUnsafe(closed, Exit.void)
       } else {
         server.close((error) => Deferred.doneUnsafe(closed, error ? Exit.die(error) : Exit.void))
       }
     }
     return Deferred.await(closed)
   })
   
   const preemptiveShutdown = options.disablePreemptiveShutdown ?
     Effect.void :
     Effect.timeoutOrElse(shutdown, {
       duration: options.gracefulShutdownTimeout ?? Duration.seconds(20),
       orElse: () => Effect.sync(() => server.closeAllConnections())
     })

   // serve()
   let draining = false
   const pending = new Set<Http.ServerResponse>()
   const onRequest = (nodeRequest: Http.IncomingMessage, nodeResponse: Http.ServerResponse) => {
     if (draining) {
       nodeResponse.setHeader("Connection", "close")
     } else {
       pending.add(nodeResponse)
       nodeResponse.once("close", () => pending.delete(nodeResponse))
     }
     handler(nodeRequest, nodeResponse)
   }
   yield* Scope.addFinalizerExit(serveScope, () =>
     Effect.suspend(() => {
       draining = true
       for (const nodeResponse of pending) {
         if (!nodeResponse.headersSent) nodeResponse.setHeader("Connection", "close")
       }
       return preemptiveShutdown
     }).pipe(
       Effect.ensuring(Effect.sync(() => {
         server.off("request", onRequest)
         server.off("upgrade", upgradeHandler)
       }))
     )
   )
   server.on("request", onRequest)
   server.on("upgrade", upgradeHandler)

   disablePreemptiveShutdown behaves as before.

   Results (gracefulShutdownTimeout: 1.5s)

   Scenario	4.0.0	Two-line fix	Suggested fix
   Repro from this issue	2nd request hangs; dispose() rejects at 1.5 s	answered; dispose() rejects at 1.5 s	connection closes after 1st response; disposed in 2 ms
   Client keeps reusing its connection	hangs; dispose() rejects at 1.5 s	served until timeout; dispose() rejects	Connection: close after one response; disposed in 2 ms
   Handler never finishes (wrapped in Effect.interruptible, see below)	dispose() rejects at 1.5 s	dispose() rejects at 1.5 s	sockets closed at timeout; disposed at 1.5 s

   Rejected alternative

   Calling server.closeIdleConnections() when a response finishes during the drain looks attractive, but it destroys the socket before the last body chunk is sent, which truncates streamed responses. Without it, a response whose keep-alive headers went out before shutdown leaves its connection open until keepAliveTimeout or the drain timeout.

   Separate bug, probably worth its own issue: handlers run uninterruptibly

   HttpEffect.toHandled switches the fiber to uninterruptible and, on the fast path (no middleware, native tracer), runs the handler without switching back:

   effect/packages/effect/src/http/HttpEffect.ts

   Lines 172 to 186 in bc44526

   	return Effect.withFiber((fiber) => {
   	fiberEnterUninterruptibleUnsafe(fiber)
   	const scope = Scope.makeUnsafe()
   	const frame = new RequestFrame(scope, fiber.context, Context.getUnsafe(fiber.context, HttpServerRequest))
   	fiber.setContext(Context.add(frame.prev, Scope.Scope, scope))
   	// The native tracer has no backend, so its spans are unobservable.
   	const currentTracer = fiber.cache.tracer
   	if (
   	middleware === undefined &&
   	(currentTracer === undefined || currentTracer === nativeTracer || isTracerDisabledUnsafe(fiber, frame.request))
   	) {
   	;(fiber as any)._stack.push(frame)
   	return self
   	}
   	return finishAfter(frame, fiber, middleware === undefined ? traced(frame) : withMiddleware(frame))

   Effects:

   • A client disconnect calls fiber.interruptUnsafe(...) in makeHandler, but the handler is never interrupted. Reproduced: an Effect.never handler's onInterrupt never runs.
   • A stuck handler blocks dispose() forever, even with the fix above. The "never finishes" row only passes because the test handler is wrapped in Effect.interruptible.

   Not tested

   • WebSocket upgrades during the drain
   • HTTP pipelining
   • this repo's test suite
3. mvanhorn commented on Oct 6, 2026

   

   mvanhorn

   on Oct 6, 2026

   More actions

   The serve finalizer removed the request and upgrade listeners before server.close(), so Node still emitted request events for connections it was draining and nothing handled them. shutdown was Effect.cached, so the interruption from timeoutOrElse was stored as the close result, and the timeout branch was Effect.void, which left those sockets open.

   server.close now starts once and completes a Deferred, so a timed-out waiter does not record the close as abandoned.
4. tim-smart

   closed this as completedin #8846on Oct 6, 2026