Add advisory backpressure to Writable

[jackyzha0]

Summary

Adds node-style cooperative backpressure to river's Writable, sender-side only, no wire/protocol changes. Bumps the minor version to 0.220.0.

• Writable.write() now returns boolean instead of undefined — false means the session's send buffer is at/above the new sendBufferHighWaterMark transport option (default 1024 messages). The signal is purely advisory: values are still buffered and delivered, exactly like node's stream.Writable.write(). No existing caller used the return value, so this is source-compatible.
• New Writable.waitForWriteReady(): Promise<void> is the drain signal (river streams have no EventEmitter, so a promise replaces node's 'drain' event). It resolves once acks trim the buffer back below the high-water mark, immediately when there's no pressure, and always resolves (never rejects) when the session/transport closes so producers can't hang — they exit via isWritable() or the next write() throwing.

Canonical producer loop:

while (writable.isWritable()) {
  if (!writable.write(next())) await writable.waitForWriteReady();
}

Implementation

• Drain waiters are a Set<() => void> on the session, carried across state-machine transitions alongside sendBuffer itself. They're woken at the only two points pressure releases: SessionConnected.updateBookkeeping (acks trimming the buffer) and IdentifiedSession._handleClose.
• Routers reach the signal via a new transport.getSessionBackpressure(to, sessionId) accessor returning a SessionBackpressure interface (isSendBufferFull / waitForSendBufferDrain). Unlike getSessionBoundSendFn it never throws after the session scope ends, since writables are torn down separately via session status events.
• WritableImpl takes an optional backpressure: SessionBackpressure, defaulting to an inert implementation (keeps the pre-closed stub and unit tests unchanged). All four construction sites (router + protobuf, client + server) pass the session-scoped one.
• Multiple streams on one session share the pressure; drain wakes all waiters.

Known limitation

Pressure derives from transport-level acks (receipt), not app-level consumption on the peer — a slow for await consumer whose transport keeps acking won't create pressure, because the receiver's ReadableImpl queue is still unbounded. Fixing that needs protocol-level credits; the SessionBackpressure interface is the seam to swap that in later.

Testing

• Unit tests for WritableImpl backpressure semantics (__tests__/streams.test.ts).
• Session-level tests: fullness/drain reflect buffer size, waiters survive state transitions and resolve on ack-trim and on close (stateMachine.test.ts).
• New __tests__/backpressure.test.ts integration suite across the ws/mock × naive/binary matrix: deterministic over-HWM writes return false and recover after acks; messages written under pressure while disconnected survive a transparent reconnect in order; a parked waitForWriteReady resolves on transport close.
• Full suite: 768 passed, 1 skipped (pre-existing). Typecheck, eslint, and prettier clean.

🤖 Generated with Claude Code

[masad-frost]

Acks, the gift that keeps on giving.