@mcpwarp/ws-mixer 0.6.0 → 0.7.0

package/dist/stream.d.ts

@@ -1,6 +1,6 @@
 /**
  * MixerStream: one ws-mixer byte stream, exposed as a Node Duplex.
- * Mirrors `go/wsmixer/stream.go`'s state machine, credit accounting and
+ * Mirrors `ws-mixer-go/wsmixer/stream.go`'s state machine, credit accounting and
  * half-close semantics (WIRE.md section 2.5-2.6). The JS SDK is always
  * the answering peer: it never opens streams, only receives OPEN from the
  * server and reads/writes/closes/resets what arrives.
@@ -30,8 +30,10 @@ export interface StreamHost {
     sendData(streamId: number, chunk: Uint8Array): Promise<void>;
     /** Send a control-priority frame (WINDOW/CLOSE/RESET) immediately. */
     sendControlFrame(frame: Uint8Array): void;
-    /** Called when the stream is fully closed so the connection can retire its id. */
+    /** Called when the stream is fully closed so the connection can retire its id (a connection teardown still reaches it until it is destroyed). */
     retireStream(streamId: number): void;
+    /** Called when the stream starts holding a write callback, so the connection holds a retired stream strongly until that callback is settled (a no-op for one not yet retired). Optional: a host that tracks no retired streams has nothing to pin. */
+    pinRetired?(streamId: number): void;
 }
 export declare class MixerStream extends Duplex {
     readonly id: number;
@@ -48,7 +50,7 @@ export declare class MixerStream extends Duplex {
     /** Bytes queued via _write, waiting on credit; drives backpressure. */
     private writeQueue;
     private draining;
-    /** Write callbacks (_write's own terminal-error branch, or drainWriteQueue's catch) whose error must wait until the read side has finished delivering buffered data and emitted 'end' -- see terminateNoThrow's doc comment. Non-null exactly while that wait is pending; flushed (and reset to null) from _destroy(), or from the 'end' listener drainWriteQueue's catch installs. */
+    /** Write callbacks (_write's own terminal-error branch, or failWrite()) whose error must wait until the read side has finished delivering buffered data and emitted 'end' -- see terminateNoThrow's doc comment. Non-null exactly while that wait is pending; flushed (and reset to null) from _destroy(), or from the 'end' listener failWrite() installs. */
     private heldWriteCallbacks;
     /** Set once this stream is RESET -- by the peer (handleReset), the SDK (abort()), or the app itself (reset()); undefined until then. Set even when no `'error'` listener is attached. */
     resetCode?: number;
@@ -62,6 +64,35 @@ export declare class MixerStream extends Duplex {
     _destroy(err: Error | null, callback: (error?: Error | null) => void): void;
     private pumpWriteQueue;
     private drainWriteQueue;
+    /**
+     * Settles a failed write's callback with `failure` -- now, or held until
+     * the read side can no longer be hurt by it. Calling a write callback with
+     * an error marks the READABLE side errored too (Node's own Writable/Duplex
+     * machinery), which drops whatever is still buffered and blocks 'end'.
+     *
+     * - terminateNoThrow is already holding write errors for the read side
+     *   (`heldWriteCallbacks` non-null): join that hold -- see its doc comment.
+     * - The peer's CLOSE has arrived and 'end' hasn't fired yet, whatever this
+     *   side's own write state (`half_closed_remote`, or `closed` after
+     *   closeWrite()): the read side may still be delivering buffered data, so
+     *   hold the callback until 'end', without relying on teardown to flush it
+     *   -- there may be no teardown at all. A connection teardown that does
+     *   come (it also reaches a stream closeWrite() retired) flushes it once
+     *   nothing is left unread; so do destroy()/reset(). `failure` is the
+     *   fallback for a flush with no terminalError of its own (always, on a
+     *   stream CLOSE'd both ways -- see terminateNoThrow).
+     * - Otherwise (peer still sending, 'end' already fired or never will --
+     *   destroyed, or already errored): fail it now.
+     *
+     * Node's Writable machinery re-emits a write callback's error as 'error',
+     * so -- same rationale as terminateNoThrow() -- the internal no-op listener
+     * is attached first if nothing else is listening: a failure is also
+     * reachable before terminateNoThrow() has run at all (the connection's
+     * writer failed this chunk's socket write, and teardown follows from the
+     * socket's own 'close'), and a dying connection must not crash a consumer
+     * that never attached its own 'error'.
+     */
+    private failWrite;
     /** Waits until send credit is available, then reserves and returns min(want, sendWindow, MAX_CHUNK). */
     private reserveSendCredit;
     private wakeSendWaiters;
@@ -83,16 +114,37 @@ export declare class MixerStream extends Duplex {
      * never entered it there.
      */
     read(size?: number): unknown;
+    /**
+     * Both directions CLOSE'd cleanly (closeWrite() + the peer's CLOSE, in
+     * either order): the stream is retired, so only a connection teardown
+     * (which may never come) would otherwise reach it, and 'close' needs a
+     * destroy() on an `autoDestroy: false` Duplex. Mirrors
+     * what autoDestroy itself would do: destroy once the readable has emitted
+     * 'end' (a tick later, like failWrite()'s hold, so every 'end' listener
+     * runs first and 'end' always precedes 'close'), and, when the write side
+     * was closed by end(), once 'finish' has fired too -- destroying inside
+     * _final() would suppress 'finish' and turn finished()/pipeline() into a
+     * premature close. A readable that already errored never emits 'end', so
+     * that destroys right away. A consumer that never reads never sees 'end',
+     * and so never 'close' -- same as any other Readable.
+     */
+    private destroyWhenDone;
     private maybeDeliverEOF;
-    /** True once something is listening for `'error'`: gates attaching the internal no-op `'error'` listener (terminateNoThrow, drainWriteQueue). */
+    /** True once something is listening for `'error'`: gates attaching the internal no-op `'error'` listener (terminateNoThrow, failWrite). */
     private hasErrorListener;
-    /** Sends CLOSE: "I will send no more DATA on this stream." end() is sugar for this via _final. */
+    /**
+     * Sends CLOSE: "I will send no more DATA on this stream." end() is sugar
+     * for this via _final. A write still waiting on send credit can never go
+     * out now, so it is woken to fail with STREAM_CLOSED (reserveSendCredit)
+     * instead of waiting on a WINDOW that, once this stream is retired, would
+     * never reach it.
+     */
     closeWrite(): void;
     /**
      * Sends CLOSE (if not already sent) and stops delivering further reads. If
      * the peer has not yet half-closed its own send side, a plain closeWrite()
      * would leave it writing into a window nobody drains, so close() also
-     * RESETs with CANCEL in that case (mirrors go/wsmixer/stream.go Close()).
+     * RESETs with CANCEL in that case (mirrors ws-mixer-go/wsmixer/stream.go Close()).
      */
     close(): void;
     /**
@@ -114,7 +166,7 @@ export declare class MixerStream extends Duplex {
      * an SDK-detected violation (abort()), `reset()` does NOT emit `'reset'`.
      */
     reset(code: number | string, message?: string): void;
-    /** Shared implementation behind reset()/abort(); returns false (no-op) if the stream was already closed. */
+    /** Shared implementation behind reset()/abort(); returns false (nothing sent) if the stream was already closed. */
     private applyReset;
     /**
      * Wraps this stream as Web Streams API `{ readable, writable }`, e.g. for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpwarp/ws-mixer",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "sideEffects": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",