`closeIdleConnections()` severs a completed-but-unflushed reply and the drain reports it clean

[codeslake]

proxy/server.mjs:1150 on main (verified still present at 78ca948)

What happens

A drain calls closeIdleConnections(). Node's notion of "idle" is res.end()
having been CALLED, not its bytes having reached the client. A reply that is
finished but still flushing is therefore destroyed at drain start, and
server.close(cb) fires immediately afterwards, so the drain announces success.

Measured end to end against this proxy:

client received       4,217,792 bytes
reply declared       67,108,872 bytes
stderr               [cache-fix] shutdown: drained clean in 0.0s of 9s budget

Reproduced in isolation on plain Node 24 with no proxy involved:
res.finished === true, writableFinished === false, ~63 MB queued —
srv.close(cb) fires the callback in 0 ms and the socket is destroyed.

Why it is the worst shape of this class

The drain exists to stop a handover cutting live replies. Here it cuts one to
6% of its length and prints the phrase that means it cut nothing. The report is
the defect's disguise, so no monitor and no operator sees it: a reader greping
drained clean in counts this as a success.

Every other number the drain produces sits downstream of it.

A second consequence, not obvious from the above

It also masks the stall predicate for finished-but-unflushed responses.
Such a response never survives to be judged, so the branch that would decline
to claim a cut for it is unreachable while this stands. Found while building a
fixture for that branch — the fixture walked into this instead.

Scope

• NOT the reload path. The reload correctly asks the proxy to drain; the proxy
  answers by severing and reporting success. Whoever triggers a drain gets it.
• NOT introduced by the per-connection drain work — it predates it. The
  per-connection change tightened the numbers that sit on top of it.
• Client-detectable, and therefore retryable: a short body against
  Content-Length. That is the only reason it is not worse.

Sketch of a fix

Do not treat "end() called" as idle. Either wait for writableFinished on
responses that have unflushed bytes, or exclude them from the idle sweep and
leave them to the drain predicate, which already ages a connection by bytes
delivered and would end a genuinely stalled one on its own window.

Needs a case in test/shutdown-exit-code.test.mjs: a reply larger than the
socket buffers, a client that stops reading, end() upstream, then signal —
assert the client receives the whole body, and that a drain that truncated one
does not print drained clean.

🤖 Generated with Claude Code

[codeslake]

Withdrawing this — it is wrong on the cause, and the defect it describes is
already fixed in an open PR. Both were knowable before I filed it, and I filed
it from a stale draft without checking either.

Wrong agent. The three-arm discrimination on plain Node, no proxy involved:

no close()                   100.0% delivered
server.close() alone           6.2%
server.close() + closeIdle     6.2%

close() is what severs the finished-but-unflushed reply. Adding the idle sweep
changes nothing. This issue's title and body name closeIdleConnections(), which
the third arm rules out.

Already fixed. #356 carries fix(drain): deliver a finished-but-unflushed reply instead of severing it — an _unflushed() predicate beside _live, and
both paths that reach Node's close() wait on it, with no timer of its own
(the drain budget and its forced-close backstop already bound the wait).

What I verified before filing was that closeIdleConnections?.() is still on
main. That is true and it is not the question — the call being present says
nothing about whether it is the agent, and the experiment that settles it had
already been run and recorded in the commit message above.

The symptom in the body is real, and the measurement of it stands. Everything
this issue says about the mechanism does not. #356 is the place to review it.

🤖 Generated with Claude Code

[codeslake]

Correcting my own withdrawal above: its central claim was wrong, and this
issue's original title named the right thing.

I withdrew this on a three-arm discrimination that reported close() alone and
close() + closeIdleConnections() as identical, and concluded the sweep was
innocent. That experiment could not answer the question it was asked. Every arm
in it that closed the server also swept, because from node 19 http.Server.close()
runs the idle sweep itself. The two arms were the same arm.

The missing arm is a close that does NOT sweep. With it:

no close at all                       delivered 100.0%   port=STILL LISTENING
http server.close()                   delivered  24.9%   port=ECONNREFUSED
http close() + closeIdleConnections   delivered  24.9%   port=ECONNREFUSED
net close only                        delivered 100.0%   port=ECONNREFUSED
net close + closeIdleConnections      delivered  24.9%   port=ECONNREFUSED

net.Server.prototype.close stops accepting and delivers the whole reply.
Adding the sweep to that same arm drops delivery to 24.9%. The sweep is what
severs a finished-but-unflushed reply; close() looked like the agent only
because it performs the sweep on its way.

The correction is not academic — it moved the fix. #356 now unbinds at the net
layer and leaves the sweep behind the flush guard, so the listening socket is
released immediately while the reply still completes. Under the previous
reading the unbind was deferred behind the flush, which held the port for the
whole drain after announcing it had been released: a successor binding it got
EADDRINUSE, and the drainer kept accepting requests it would cut.

Staying closed — the defect is fixed in #356, which is where the measurement
and the code both live. Reopening would split them. This note is here so the
record does not carry a wrong cause under a correct title.

🤖 Generated with Claude Code