[productdevbook]

Closes #131. The last of the leads left open by the driver audit — and it turned out to be the worst defect in the set.

The hang

sendInternal() waited for backpressure to clear with a promise that had exactly one way to settle:

if (!socket.write(payload)) {
  await new Promise<void>((resolve) => socket.once("drain", () => resolve()))
}

If the peer vanished while the write buffer was still full, drain never fired and nothing else could reach that promise. failAll() only rejects waiters queued for a reply, and commandTimeoutMs belongs to those same waiters — neither covers this one.

Reproduced against a server that completes the handshake, stops reading once DATA begins so the client backs up, then destroys the socket:

P> HUNG — never settled

Four seconds is only where the probe gave up. The promise stays pending indefinitely.

Why it is the worst kind. A hang is not a failure, so nothing downstream can react to it: withRetry never gets control, and the pooled connection is never released. maxConnections slots leak one at a time until every acquire() queues behind a connection that will never come back, and the driver stops entirely. Getting there needs a message past the socket's 16 KB write buffer — any real attachment — and a connection that dies mid-transfer, which is an ordinary flaky-network event.

It is the same shape as #117 and the other half of it: a promise with a single settlement path and a peer that can disappear before it is taken. Both are now closed.

The fix races drain against error and close, removing all three listeners whichever wins, so a long-lived pooled connection does not accumulate a listener per write.

P> rejected: [unemail] [smtp] read ECONNRESET

STARTTLS listeners, as hardening

tls.connect({ socket }) leaves the pre-upgrade listeners on the socket underneath. Measured directly:

before wrap  data: 1 error: 1 close: 1
after  wrap  data: 1 error: 2 close: 2
raw still flowing (isPaused=false): true
our onData still attached: true

Anything the raw socket delivers after the upgrade is TLS records, which would go into the reply parser as noise, and the stale close handler would report the failure a second time. They are detached on upgrade now.

I could not settle whether those bytes actually reach the listener — that needs a TLS-capable fake server, and Node cannot mint a self-signed certificate without a dependency. So this is written up as hardening rather than as a fix for an observed failure. Removing listeners that should not be there cannot be wrong; claiming a bug I did not reproduce would be.

Verification

294 tests, including a regression test that drives the 4 MB stalling-server scenario end to end. Lint, format, typecheck, JSR dry run, build, bundle budgets and coverage floors all clean. connection.ts moved from 60% to 67% statements.

Still open

The remaining uncovered region of connection.ts is the STARTTLS upgrade path itself. Extending the fake server to speak TLS would close both that coverage gap and the question above — worth doing, and larger than this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQAPDWLnDrdYHKhou3Ntvb