@mcpwarp/ws-mixer 0.6.0

package/dist/stream.d.ts

@@ -0,0 +1,124 @@
+/**
+ * MixerStream: one ws-mixer byte stream, exposed as a Node Duplex.
+ * Mirrors `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.
+ *
+ * Three ways a stream ends in RESET, all converging on the same terminal
+ * state and `resetCode`, but differing in whether `'reset'` fires:
+ *  - the peer sends RESET (handleReset()) -- `'reset'` fires; the stream's
+ *    owner didn't choose this.
+ *  - the SDK itself detects a violation on this stream (abort(), called from
+ *    MixerConn's dispatch loop) -- `'reset'` fires, same reasoning as above:
+ *    the app didn't choose it either.
+ *  - the app calls the public reset() -- `'reset'` does NOT fire; the caller
+ *    already knows why, by definition.
+ * `resetCode` is set by all three, always, whether or not an `'error'`
+ * listener is attached.
+ */
+import { Duplex } from "node:stream";
+export type StreamState = "idle" | "open" | "half_closed_local" | "half_closed_remote" | "closed";
+/** Payload of the `'reset'` event: fired once, whenever this stream is RESET by something other than the app's own reset() call -- a peer RESET (handleReset()) or an SDK-detected violation (abort()) -- whether or not an `'error'` listener is attached. */
+export interface StreamResetInfo {
+    code: number;
+    message: string;
+}
+/** Callback the stream uses to hand an outbound DATA/WINDOW/CLOSE/RESET frame to the connection. */
+export interface StreamHost {
+    /** Enqueue a DATA chunk for round-robin transmission; resolves once written (or rejects on failure). */
+    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. */
+    retireStream(streamId: number): void;
+}
+export declare class MixerStream extends Duplex {
+    readonly id: number;
+    private readonly host;
+    private state;
+    private sendWindow;
+    private recvWindow;
+    private readonly initialWindow;
+    private unacked;
+    private remoteClosed;
+    private terminalError;
+    /** Resolved when sendWindow becomes > 0 or the stream can no longer send. */
+    private sendWaiters;
+    /** 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. */
+    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;
+    constructor(id: number, host: StreamHost, initialRecvWindow: number, initialSendWindow: number);
+    getState(): StreamState;
+    getSendWindow(): number;
+    getRecvWindow(): number;
+    _read(_size: number): void;
+    _write(chunk: Uint8Array, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    _destroy(err: Error | null, callback: (error?: Error | null) => void): void;
+    private pumpWriteQueue;
+    private drainWriteQueue;
+    /** Waits until send credit is available, then reserves and returns min(want, sendWindow, MAX_CHUNK). */
+    private reserveSendCredit;
+    private wakeSendWaiters;
+    /**
+     * Credits the peer back once bytes leave the internal buffer, mirroring Go
+     * `Stream.creditConsumed` (stream.go) and its half-window threshold.
+     */
+    private creditConsumed;
+    private eofDelivered;
+    private internalBufferEmpty;
+    /**
+     * Covers every consumption mode that goes through the buffer: explicit
+     * paused-mode `.read()` calls, and Node's internal flow loop -- which
+     * calls this same public `read()` method to back `on('data')`, `pipe()`
+     * and `for await` once bytes are actually sitting in the buffer (as
+     * opposed to handleData()'s synchronous fast-path bypass above, which
+     * never reaches the buffer at all). Between the two, every byte is
+     * credited exactly once: whatever left the buffer here, plus whatever
+     * never entered it there.
+     */
+    read(size?: number): unknown;
+    private maybeDeliverEOF;
+    /** True once something is listening for `'error'`: gates attaching the internal no-op `'error'` listener (terminateNoThrow, drainWriteQueue). */
+    private hasErrorListener;
+    /** Sends CLOSE: "I will send no more DATA on this stream." end() is sugar for this via _final. */
+    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()).
+     */
+    close(): void;
+    /**
+     * Aborts the stream in both directions with the given error code and
+     * message, discarding buffered data. `code` may be a numeric ws-mixer.v1
+     * error code or its wire name (e.g. `"CANCEL"`); `message` is truncated to
+     * 256 UTF-8 bytes on a character boundary (WIRE.md section 2.3: a RESET
+     * message SHOULD be <= 256 B).
+     *
+     * Same "don't throw with nobody listening" rule as handleReset(): an
+     * internal no-op 'error' listener (attached by terminateNoThrow() when
+     * nothing else is) keeps this from crashing a consumer with no 'error' of
+     * its own, while still surfacing the code via `resetCode`/`stream.errored`
+     * (buffered data discarded, per RESET's own semantics: terminateNoThrow()
+     * is called with `{discardBuffered: true}`).
+     *
+     * This is the app-facing API: calling code already knows why it's
+     * resetting its own stream, so unlike a peer-sent RESET (handleReset()) or
+     * 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. */
+    private applyReset;
+    /**
+     * Wraps this stream as Web Streams API `{ readable, writable }`, e.g. for
+     * `fetch`'s `duplex` option or any other Web Streams consumer.
+     */
+    toWeb(): ReturnType<typeof Duplex.toWeb>;
+}

package/dist/util.d.ts

@@ -0,0 +1,3 @@
+/** Small helpers shared by stream.ts and conn.ts. */
+/** Truncates `message` to at most `maxBytes` UTF-8 bytes, backing off to the nearest character boundary. */
+export declare function truncateUtf8(message: string, maxBytes: number): string;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@mcpwarp/ws-mixer",
+  "version": "0.6.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "ws-mixer.v1 client SDK: N byte streams over one WebSocket, JS/TypeScript client.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcpwarp/ws-mixer-js.git"
+  },
+  "homepage": "https://github.com/mcpwarp/ws-mixer-js#readme",
+  "bugs": {
+    "url": "https://github.com/mcpwarp/ws-mixer-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "node scripts/check-registry.mjs && npm run build",
+    "build": "tsup && npm run build:types",
+    "build:types": "tsc src/index.ts --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --declaration --emitDeclarationOnly --stripInternal --esModuleInterop --skipLibCheck --outDir dist --rootDir src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "fetch-spec": "node scripts/fetch-spec.mjs",
+    "fetch-goserver": "node scripts/fetch-goserver.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "ajv": "^8.20.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}