@mcpwarp/ws-mixer 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to `@mcpwarp/ws-mixer` (the JS/TypeScript client SDK) are documented here.
 
+## 0.7.0 - 2026-09-26
+
+- A write issued in the same tick as the app's own `destroy()`/`reset()` (or `closeWrite()`) no
+  longer puts its DATA on the wire after the stream's `RESET`/`CLOSE` and reports success: the chunk
+  is never sent, and the write callback gets the stream's error exactly once --
+  `StreamError(CANCEL)` for `destroy()`/`reset()`, `StreamError(STREAM_CLOSED)` after
+  `closeWrite()`. DATA still queued when a stream is retired is now rejected the same way instead of
+  being dropped (its write callback used to hang forever).
+- A stream CLOSE'd in both directions (the peer's `CLOSE` plus the app's own `closeWrite()`/`end()`,
+  in either order) is now destroyed once its read side has emitted `'end'` (and, after `end()`, once
+  `'finish'` has fired), so `'close'` fires; previously it never did. `'end'` still precedes
+  `'close'` when data is buffered. `reset()` on such a stream, before it gets there, now destroys it
+  (discarding what is still buffered) instead of doing nothing.
+- `closeWrite()` now fails a write that was waiting on send credit with `StreamError(STREAM_CLOSED)`
+  instead of leaving it waiting for a `WINDOW` -- forever, once the stream was CLOSE'd both ways, not
+  even `destroy()` settled it. The callback is called right away unless the peer's `CLOSE` has
+  arrived and its data is still unread; then it is held like the writes in the next item.
+- A failed write on a stream whose peer `CLOSE` already arrived is now held whatever this side's own
+  write state: after `closeWrite()` it used to fail immediately, erroring the read side and losing
+  the peer's buffered data (and `'end'`). The same now applies to a write issued after
+  `closeWrite()`. A held write callback is settled once `'end'` fires, when the app calls
+  `destroy()`/`reset()`, or when the connection is torn down with nothing left unread on the stream;
+  while data is still unread it waits for `'end'` (or `destroy()`/`reset()`), even past the
+  connection's teardown.
+- A stream CLOSE'd both ways but not yet destroyed (its reader hasn't reached `'end'`) is now still
+  reached by the connection's teardown: with nothing left unread it is destroyed there, so `'close'`
+  fires and a held write callback settles. It keeps its clean end: the teardown's error is not
+  applied to it (no `resetCode`, a held write keeps its own `STREAM_CLOSED` or socket error).
+  Previously such a stream was never reached, and a write held on it hung (0.6.0 failed it
+  immediately instead, losing the peer's buffered data and `'end'`). The connection tracks such
+  streams only weakly, except while one owes a write callback: that one is held until its callback
+  settles, even if the app dropped it. One the app dropped with no write pending (say, `end()`'d but
+  never read) can still be garbage-collected on a long-lived connection, in which case its `'close'`
+  listeners never run -- as in 0.6.0, where such streams were unreachable from the teardown
+  entirely.
+- On a drain hand-over, a write whose DATA was still queued behind another stream's in-flight write,
+  or whose in-flight socket send failed after the hand-over, now fails with its stream's own
+  `StreamError(CANCEL, "connection drained")`, the same error as `stream.errored`. Previously it got
+  the superseded connection's `NO_ERROR`, or the raw socket error.
+- Connection-death errors seen by a stream are now always a `ConnError` (`stream.errored`, its
+  `'error'`, write callbacks, and `sendApp()` rejections): the socket's own close (previously a plain
+  `WsMixerError`), a graceful `close()`'s `NO_ERROR` (likewise), and a raw `ws` send failure such as
+  `Error("WebSocket is not open")` (previously leaked as-is) are wrapped, keeping the original as
+  `cause` and copying `code`/`wsCode`/`closeReason`. `ConnError`/`WsMixerError` accept `cause`. A
+  drain hand-over still gives `StreamError(CANCEL, "connection drained")`; README's "Errors" section
+  now spells out which class means what.
+- `conn.once(...)` listeners for `'stream'`/`'app'`/`'drain'` (and `events.once(conn, ...)`) were
+  never detached: the ordered delivery loop called the unwrapped listener, so it fired again on every
+  later event and leaked, pinning whatever it closed over (e.g. its stream) for the connection's lifetime.
+  Fixed; they now fire once and detach.
+- An incoming `RESET` message longer than 256 UTF-8 bytes is now clamped to 256 bytes on a character
+  boundary (in `'reset'` and the stream's `StreamError`). WIRE.md section 2.3's limit is a
+  sender-side SHOULD, so it stays tolerated, not a protocol error.
+- Tests: `test/stream-matrix.test.ts`, a generated 600-cell matrix over the stream teardown seam
+  (state x trigger x `'error'` listener x read buffer x pending write, including DATA queued behind
+  a second stream's in-flight write, plus a no-reader variant for peer-CLOSE'd streams) through a
+  real `MixerConn`, checking write callbacks settle exactly once and only report success for bytes
+  on the wire, no DATA after `CLOSE`/`RESET`, buffered data and `'end'` before `'close'`, `'close'`
+  exactly once and last, and the class and code of `stream.errored` and of any write-callback error
+  per trigger.
+- ci: publish workflow now runs typecheck + tests (test job, on Node 20 and 24) before npm publish; a failing tag no longer ships.
+- Code comments now point to ws-mixer-go (`ws-mixer-go/wsmixer/...`) and ws-mixer-spec (`ws-mixer-spec/docs/research/...`) instead of the old monorepo paths.
+
 ## 0.6.0 - 2026-09-26
 
 - A stream write that fails outside stream termination now reports that error to its write callback,

package/README.md

@@ -254,11 +254,22 @@ Also true regardless of trigger:
   preserves buffered data; `RESET` discards it" rule:
   - The peer's `CLOSE` had already arrived (its read side had already legitimately finished on the
     wire, independent of the connection dying): the response DID complete. Whatever was buffered is
-    still delivered, `'end'` still fires once it's drained, `stream.errored` stays `null`, and no
-    `'error'` event fires -- exactly as if the connection hadn't died. Only the **write** side fails:
-    a write already pending, or started afterward, fails promptly (its callback receives the
-    connection's error) instead of hanging or silently succeeding, since the connection is gone even
-    though this stream's response was already complete.
+    still delivered, `'end'` still fires once it's drained, and no `'error'` event fires -- exactly
+    as if the connection hadn't died. Only the **write** side fails: a write already pending, or
+    started afterward, fails (its callback receives the connection's `ConnError`, or
+    `StreamError(CANCEL, "connection drained")` on a drain hand-over) instead of hanging or silently
+    succeeding, since the connection is gone even though this stream's response was already
+    complete. `stream.errored` stays `null` unless such a write failed, in which case Node's own
+    Writable machinery sets it to that same error. If this side had also already closed its
+    write side (`closeWrite()`/`end()`), the stream's exchange was complete before the connection
+    died: a write fails with its own `StreamError(STREAM_CLOSED)` (or its own socket error) instead.
+    When the callback is called: with nothing left unread, as part of the teardown, and `'close'`
+    fires then too; with data still unread, only once the reader drains it and `'end'` fires (an
+    error any earlier would discard that data and suppress `'end'`), or when the app calls
+    `destroy()`/`reset()`. A stream with unread data that nobody ever reads keeps both pending until
+    the app does one or the other. The connection tracks a stream CLOSE'd both ways only weakly,
+    except while it owes a write callback: one the app dropped with no write pending may be
+    garbage-collected before the teardown, and then its `'close'` listeners never run.
   - Otherwise (a peer `RESET`, or the connection ending abnormally -- `1006`, or any other way other
     than that stream's own clean `CLOSE` -- with this stream's read side never having legitimately
     finished): the stream always ends with an error, never a false clean end. `stream.errored`
@@ -316,6 +327,19 @@ only when this particular error was built from an actually-observed close frame
 locally-raised protocol violation), and under the same "never this side's own outgoing reason" rule
 as `closeReason`.
 
+On a stream (`stream.errored`, its `'error'` event, a write callback) the subclass says what ended
+it (a `sendApp()` rejection is always the `ConnError` case):
+
+- `ConnError` -- the connection under it ended: an abnormal closure, a graceful `close()`, a
+  protocol failure, or a failed socket write. Whatever the connection's own terminal error was
+  (the socket's `WsMixerError`, a raw `ws` send error) is kept as `cause`; `code`, `wsCode` and
+  `closeReason` are copied from it.
+- `StreamError` -- this stream alone was reset: a peer `RESET`, the app's own `reset()`/
+  `destroy()`/`close()` (`CANCEL`), a write after `closeWrite()` (`STREAM_CLOSED`), or a drain
+  hand-over (`CANCEL`, `"connection drained"`, see above).
+- `null` (`stream.errored`) -- a clean end: the peer's `CLOSE` arrived and nothing pending failed,
+  or the app's own `destroy()` with no error and no write pending.
+
 The `'fatal'` event's `WsMixerError.code` follows the same "present only when a ws-mixer error code
 actually applies" rule as `DisconnectReason.errorCode` above (D-2026-09-20-09) -- it is `INTERNAL_ERROR`
 whenever no ws-mixer code exists for the underlying failure (an HTTP `401`/`403` upgrade rejection,

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * Public client entry point: `connect(url, opts)`. Owns the WebSocket
  * handshake (subprotocol, headers, size limits), and the reconnect/backoff
- * policy from docs/research/2026-08-26-control-channel-and-connection-lifecycle.md
+ * policy from ws-mixer-spec/docs/research/2026-08-26-control-channel-and-connection-lifecycle.md
  * and WIRE.md section 2.9's reconnect table. `MixerConn` (conn.ts) owns
  * everything about one already-connected socket; this file owns the loop
  * that replaces it.
@@ -19,7 +19,7 @@ import { WsMixerError } from "./errors.js";
 import { MixerConn, type WSLike } from "./conn.js";
 import type { MixerStream } from "./stream.js";
 export declare const SUBPROTOCOL = "ws-mixer.v1";
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.7.0";
 export type ClientState = "idle" | "dialing" | "connected" | "backoff" | "closed";
 export interface ReconnectOptions {
     /** Base delay for exponential backoff, ms. Default 1000. */
@@ -111,7 +111,7 @@ export interface DisconnectReason {
      * application-layer code that is legal for a stream RESET but never was
      * for a connection close), that can differ from the *actual* bytes this
      * side puts on the wire, which are clamped to `4000+INTERNAL_ERROR` (4002)
-     * instead (conn.ts's `wireCloseCode`, mirroring go/wsmixer's
+     * instead (conn.ts's `wireCloseCode`, mirroring ws-mixer-go/wsmixer's
      * `wsCloseCode`) -- `errorCode` always keeps the real, unclamped code
      * either way. When instead observed directly from a bare close frame
      * (`onSocketClose`, no preceding `error{}`), `wsCode` is exactly what was
@@ -231,7 +231,7 @@ export declare interface MixerClient {
 /**
  * MixerClient owns the reconnect loop: it replaces `conn` with a fresh
  * MixerConn on every disconnect, per the policy in
- * docs/research/2026-08-26-control-channel-and-connection-lifecycle.md.
+ * ws-mixer-spec/docs/research/2026-08-26-control-channel-and-connection-lifecycle.md.
  *
  * In-flight streams are lost on reconnect -- there is no resumption
  * (WIRE.md section 2.9). A handler must tell "the response ended" (EOF)

package/dist/conn.d.ts

@@ -5,7 +5,7 @@
  * The JS SDK is always the answering peer (client): it never calls
  * OpenStream, only receives OPEN from the server.
  *
- * Mirrors `go/wsmixer/conn.go`, `dispatch.go`, `sched.go`, `keepalive.go` and
+ * Mirrors `ws-mixer-go/wsmixer/conn.go`, `dispatch.go`, `sched.go`, `keepalive.go` and
  * `drain.go`, adapted to Node's single-threaded event loop (no goroutines:
  * one write scheduler driven by a wake/notify queue instead of channels).
  */
@@ -78,6 +78,23 @@ export declare class MixerConn extends EventEmitter {
     /** The `last_stream_id` from the most recently received `drain`; set only once draining. */
     private lastStreamId?;
     private readonly streams;
+    /**
+     * Retired (out of `streams`: no frame or DATA is ever routed to them again)
+     * but not yet destroyed -- in practice a stream CLOSE'd both ways, waiting
+     * on its reader's 'end'. Tracked only so rejectOutstanding() still tears
+     * them down; each leaves on its own 'close', and teardown clears the rest.
+     * Weak by default: a stream never read never emits 'end', so never
+     * 'close', and a strong ref would pin every such stream the app abandoned
+     * for the connection's lifetime. Strong while the stream holds a write
+     * callback (retireStream(), or pinRetired() when one is held after
+     * retirement): the stream owns that callback, not the other way round, and
+     * the callback is what the app is waiting on -- collecting the stream
+     * would leave it unsettled forever. A retired stream's held callbacks are
+     * only ever flushed by destroy(), so a strong entry leaves on 'close' and
+     * is never unpinned.
+     * Dead weak refs are pruned whenever the map is touched.
+     */
+    private readonly retired;
     private highestOpened;
     /**
      * Minimal "ignore and count" counters (item 11 of the review: full
@@ -99,7 +116,7 @@ export declare class MixerConn extends EventEmitter {
     private deliveryRunning;
     private readonly stream0Bucket;
     private nextPingId;
-    /** Watermark: every id below this has been acked (or pruned as stale) at least once. Mirrors go/wsmixer's Conn.lowestUnacked. */
+    /** Watermark: every id below this has been acked (or pruned as stale) at least once. Mirrors ws-mixer-go/wsmixer's Conn.lowestUnacked. */
     private lowestUnacked;
     private lastPongAt;
     private readonly outstandingPings;
@@ -124,7 +141,7 @@ export declare class MixerConn extends EventEmitter {
     private dispatchControl;
     /**
      * Queues one `'stream'`/`'app'`/`'drain'` event for in-order, async
-     * delivery, mirroring go/wsmixer's deliveryLoop: the read/dispatch path
+     * delivery, mirroring ws-mixer-go/wsmixer's deliveryLoop: the read/dispatch path
      * above never blocks on application code, but all three still fire in
      * wire order, off a single loop, one at a time. Handlers registered via
      * `on('stream'|'app'|'drain', ...)` must not block for long -- a handler
@@ -168,6 +185,10 @@ export declare class MixerConn extends EventEmitter {
      * caught here, counted (stats().handlerErrors) and surfaced via a guarded
      * `'handlerError'` emit -- never an unhandled rejection, and never fatal
      * to delivery: the next queued stream/app/drain event still runs.
+     *
+     * Iterates rawListeners(), not listeners(): for a once() registration that
+     * is the self-removing wrapper, so it detaches on first delivery (it
+     * returns and throws exactly what the wrapped listener does).
      */
     private emitOrdered;
     /**
@@ -193,8 +214,19 @@ export declare class MixerConn extends EventEmitter {
     private sendControlFrame;
     /** Backs `streamHost.sendData`: enqueue a DATA chunk for round-robin transmission. */
     private sendData;
-    /** Backs `streamHost.retireStream`: retire a fully-closed stream's id. */
+    /**
+     * Backs `streamHost.retireStream`: retire a fully-closed stream's id. DATA
+     * still queued for it is rejected, never dropped (a dropped item's write
+     * callback would hang forever) -- with the stream's own sendDone() error
+     * (its RESET's, or STREAM_CLOSED after its CLOSE). A stream not yet
+     * destroyed moves to `retired` until its 'close' -- strongly if it holds
+     * a write callback, else weakly (see `retired`).
+     */
     private retireStream;
+    /** Backs `streamHost.pinRetired`: a retired stream now holding a write callback is held strongly until its 'close'. */
+    private pinRetired;
+    /** Drops weak `retired` entries whose stream has been garbage-collected. */
+    private pruneRetired;
     /** Resolves every pending close()'s wait for the stream table to empty, instead of polling. */
     private notifyIdle;
     private waitForEmpty;
@@ -219,7 +251,7 @@ export declare class MixerConn extends EventEmitter {
     private startKeepalive;
     private sendPing;
     /**
-     * Pong watermark scheme, mirroring go/wsmixer/dispatch.go's handlePong:
+     * Pong watermark scheme, mirroring ws-mixer-go/wsmixer/dispatch.go's handlePong:
      * every id below lowestUnacked has been acked (or pruned as stale) at
      * least once, and no id >= nextPingId has ever been sent.
      *  - id >= nextPingId: never sent -> PROTOCOL_ERROR, connection-fatal.
@@ -266,7 +298,7 @@ export declare class MixerConn extends EventEmitter {
     /**
      * The peer sent `error{code,message}`: record it and close with
      * `4000 + code` immediately, without waiting for the peer to do anything
-     * else -- mirrors go/wsmixer/dispatch.go's handlePeerError. `error` is
+     * else -- mirrors ws-mixer-go/wsmixer/dispatch.go's handlePeerError. `error` is
      * always the last message on the wire (WIRE.md section 2.7), so
      * there is nothing left to negotiate.
      */

package/dist/errors.d.ts

@@ -57,17 +57,27 @@ export declare class WsMixerError extends Error {
         streamId?: number;
         wsCode?: number;
         closeReason?: string;
+        cause?: unknown;
     });
     get codeName(): string;
     toString(): string;
 }
-/** A connection-fatal error: desynchronizes shared connection state. Always error{code} + WS close. */
+/**
+ * A connection-level error: a locally-detected violation that desynchronizes
+ * shared connection state (always error{code} + WS close), and also what every
+ * stream still live when the connection ends -- and every write/send pending
+ * on it -- is failed with, whatever ended it (MixerConn.rejectOutstanding
+ * wraps a non-ConnError teardown error, keeping the original as `cause`).
+ */
 export declare class ConnError extends WsMixerError {
     readonly lastStreamId?: number;
     constructor(code: number, message: string, opts?: {
         streamId?: number;
         lastStreamId?: number;
         fatal?: boolean;
+        wsCode?: number;
+        closeReason?: string;
+        cause?: unknown;
     });
 }
 /** A stream-scoped error: produces RESET(code, message) on one stream; the connection stays up. */