@johnhenry/wsh 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/wsh",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Web Shell \u2014 browser-native remote command execution over WebTransport and WebSocket with Ed25519 authentication",
   "type": "module",
   "main": "./src/index.mjs",

package/src/index.d.ts

@@ -127,9 +127,6 @@ export const MSG: {
   readonly REVERSE_ACCEPT: 0x54;
   readonly REVERSE_REJECT: 0x55;
 
-  // Framing
-  readonly WS_DATA: 0x60;
-
   // Gateway
   readonly OPEN_TCP: 0x70;
   readonly OPEN_UDP: 0x71;

package/src/messages.gen.mjs

@@ -66,11 +66,6 @@ export const MSG = Object.freeze({
   // Session
   SESSION_LIST:      0x5f,
   DETACH:            0x60,
-
-  // Framing
-  WS_DATA:           0x60,
-
-  // Session
   DETACH_OK:         0x61,
   DETACH_FAIL:       0x62,
 

package/src/transport-ws.mjs

@@ -16,17 +16,13 @@
  */
 
 import { frameEncode, FrameDecoder, FrameSizeError } from './cbor.mjs';
-import { WshTransport } from './transport.mjs';
+import { WshTransport, dispatchSerially, SerialQueue } from './transport.mjs';
 
 // ── Frame type constants ─────────────────────────────────────────────
 //
-// NOTE: these are unrelated to MSG.WS_DATA (0x60) in messages.gen.mjs.
-// WS_DATA is a JS-only, CBOR-layer bookkeeping marker (it shares its
-// opcode with MSG.DETACH and is explicitly excluded from the Rust
-// message enum by spec/codegen.mjs) — it is never sent as the outer
-// envelope's frame-type byte below. See spec/wsh-v1.yaml's
-// `transport.websocket` section for the authoritative outer-envelope
-// framing docs.
+// Unrelated to the CBOR-layer MSG opcodes (messages.gen.mjs) -- these are
+// the outer envelope's frame-type byte. See spec/wsh-v1.yaml's
+// `transport.websocket` section for the authoritative framing docs.
 
 const FRAME_CONTROL      = 0x01;
 const FRAME_DATA         = 0x02;
@@ -207,25 +203,15 @@ export class WebSocketTransport extends WshTransport {
   #closedByUs = false;
 
   /**
-   * Queue of raw inbound messages awaiting dispatch, plus a drain-in-progress
-   * flag. Needed because some `WebSocket` implementations (notably Node's
-   * `ws` package parsing several frames out of one TCP read) can fire
-   * multiple synchronous `message` events within a single JS task, all
-   * before any microtask gets to run. If we dispatched each message inline,
-   * a handler that resolves a pending waiter (e.g. SERVER_HELLO resolving
-   * the "wait for SERVER_HELLO or CHALLENGE" promise) wouldn't get a chance
-   * to run its `await`'d continuation — which registers the *next* waiter
-   * (e.g. for CHALLENGE) — before the next queued message arrives. That
-   * continuation is a microtask; a same-task, no-yield dispatch loop starves
-   * it, so the next message's waiter isn't registered yet and gets dropped.
-   * Draining the queue with an `await Promise.resolve()` between each
-   * message yields to the microtask queue after every dispatch, and since
-   * microtasks run FIFO, any continuation queued by handling message N
-   * (which runs first) completes before message N+1 is dispatched.
-   * @type {ArrayBuffer[]}
+   * Serializes dispatch of raw inbound WebSocket messages. Needed because
+   * some `WebSocket` implementations (notably Node's `ws` package parsing
+   * several frames out of one TCP read) can fire multiple synchronous
+   * `message` events within a single JS task, all before any microtask
+   * gets to run — see `SerialQueue`'s doc comment in transport.mjs for
+   * why dispatching those inline would be unsafe.
+   * @type {SerialQueue}
    */
-  #messageQueue = [];
-  #draining = false;
+  #inbox = new SerialQueue((raw) => this.#handleMessage(raw));
 
   // ── Lifecycle ──────────────────────────────────────────────────────
 
@@ -236,8 +222,7 @@ export class WebSocketTransport extends WshTransport {
     this.#nextLocalId = 1;
     this.#openResolvers.clear();
     this.#closedByUs = false;
-    this.#messageQueue.length = 0;
-    this.#draining = false;
+    this.#inbox.clear();
 
     return new Promise((resolve, reject) => {
       // Normalize URL scheme: wsh:// → wss://, http:// → ws://.
@@ -265,8 +250,7 @@ export class WebSocketTransport extends WshTransport {
       });
 
       ws.addEventListener('message', (ev) => {
-        this.#messageQueue.push(ev.data);
-        this.#drainMessageQueue();
+        this.#inbox.push(ev.data);
       });
     });
   }
@@ -320,33 +304,14 @@ export class WebSocketTransport extends WshTransport {
   // ── Inbound message dispatch ───────────────────────────────────────
 
   /**
-   * Drain `#messageQueue` one message at a time, yielding to the microtask
-   * queue between each dispatch. See the `#messageQueue` field doc for why:
-   * this is what lets a waiter registered by an earlier message's `await`
-   * continuation (e.g. registering the CHALLENGE waiter after SERVER_HELLO
-   * resolves) actually be in place before the next queued message arrives,
-   * even when the underlying WebSocket implementation delivered several
-   * messages synchronously in one task.
-   */
-  async #drainMessageQueue() {
-    if (this.#draining) return;
-    this.#draining = true;
-    try {
-      while (this.#messageQueue.length > 0) {
-        const raw = this.#messageQueue.shift();
-        this.#handleMessage(raw);
-        await Promise.resolve();
-      }
-    } finally {
-      this.#draining = false;
-    }
-  }
-
-  /**
-   * Handle a raw WebSocket message (ArrayBuffer).
+   * Handle a raw WebSocket message (ArrayBuffer). Called serially by
+   * `#inbox` — never invoked directly from the `message` event listener.
+   * Async (and awaited by `#inbox`'s SerialQueue) because the
+   * FRAME_CONTROL case can itself dispatch several decoded messages —
+   * see `#handleControlFrame`.
    * @param {ArrayBuffer} raw
    */
-  #handleMessage(raw) {
+  async #handleMessage(raw) {
     if (typeof raw === 'string') {
       this._emitError(new Error('Received text WebSocket frame; expected binary'));
       return;
@@ -363,7 +328,7 @@ export class WebSocketTransport extends WshTransport {
 
     switch (frame.type) {
       case FRAME_CONTROL:
-        this.#handleControlFrame(frame.payload);
+        await this.#handleControlFrame(frame.payload);
         break;
       case FRAME_DATA:
         this.#handleDataFrame(frame.streamId, frame.payload);
@@ -380,10 +345,14 @@ export class WebSocketTransport extends WshTransport {
   }
 
   /**
-   * Decode CBOR-framed control messages from stream 0.
+   * Decode CBOR-framed control messages from stream 0. A single mux
+   * frame's payload can decode into more than one protocol message (the
+   * CBOR decoder is stateful/streaming), so dispatch uses
+   * `dispatchSerially` — see its doc comment for why a plain for-loop
+   * here would be unsafe.
    * @param {Uint8Array} payload
    */
-  #handleControlFrame(payload) {
+  async #handleControlFrame(payload) {
     let messages;
     try {
       messages = this.#decoder.feed(payload);
@@ -396,9 +365,7 @@ export class WebSocketTransport extends WshTransport {
       }
       return;
     }
-    for (const msg of messages) {
-      this._emitControl(msg);
-    }
+    await dispatchSerially(messages, (msg) => this._emitControl(msg));
   }
 
   /**

package/src/transport.mjs

@@ -7,6 +7,97 @@
 
 import { frameEncode, FrameDecoder, cborEncode, FrameSizeError } from './cbor.mjs';
 
+// ── Serial dispatch (shared by both transports) ───────────────────────
+//
+// A push-based transport can hand this library more than one decoded
+// protocol message at once — either because several arrived in a single
+// underlying read (e.g. multiple WebSocket `message` events fired
+// synchronously from one TCP read, or one CBOR decoder call returning
+// several frames from one already-received chunk) — with no guaranteed
+// yield to the microtask queue between them. That matters because a
+// message handler can be `async`: it resolves a pending waiter
+// synchronously, but the code that runs *after* that resolution (e.g.
+// registering the *next* waiter) only runs as a microtask continuation.
+// Dispatching message N+1 before that continuation gets a turn means
+// N+1 arrives with state that N's handling hasn't finished setting up
+// yet — most visibly, a dropped CHALLENGE that arrived batched with
+// SERVER_HELLO (see CHANGELOG 0.3.0). `dispatchSerially` and
+// `SerialQueue` both fix this the same way: yield to the microtask
+// queue after every single dispatch, so FIFO microtask ordering
+// guarantees any continuation queued by message N runs before message
+// N+1 is handled.
+
+/**
+ * Invoke `handler` once per item in `items`, awaiting each call before
+ * starting the next. Use this for a *fixed* batch that's already fully
+ * available (e.g. everything a single decoder.feed() call returned) —
+ * see `SerialQueue` for items that arrive incrementally over time via a
+ * push callback.
+ *
+ * `handler` may be sync or async — either way, `await handler(item)`
+ * yields to the microtask queue at least once before the next item is
+ * dispatched (awaiting any value does, even a plain `undefined`), and if
+ * `handler` is itself async, this also waits for its *own* internal work
+ * (including any nested dispatchSerially/SerialQueue use) to fully
+ * settle first. That matters when a handler for item N does async work
+ * that must complete before N+1 is safe to dispatch — a fire-and-forget
+ * (non-awaited) handler call wouldn't provide that guarantee, only a
+ * same-tick yield.
+ * @param {Iterable<*>} items
+ * @param {(item: *) => (void | Promise<void>)} handler
+ */
+export async function dispatchSerially(items, handler) {
+  for (const item of items) {
+    await handler(item);
+  }
+}
+
+/**
+ * A queue drained one item at a time, awaiting each dispatch before
+ * starting the next (see `dispatchSerially`'s doc comment for exactly
+ * what that guarantees for sync vs. async handlers). Use this where
+ * items arrive incrementally over time via a push callback (e.g. a
+ * transport's raw `message` event) rather than as one fixed,
+ * already-available batch (see `dispatchSerially` for that case).
+ * `push()` is safe to call at any time, including while a previous
+ * drain is still in progress — the same drain loop just picks up the
+ * newly-pushed item in its next iteration.
+ */
+export class SerialQueue {
+  #items = [];
+  #handler;
+  #draining = false;
+
+  /** @param {(item: *) => (void | Promise<void>)} handler */
+  constructor(handler) {
+    this.#handler = handler;
+  }
+
+  /** @param {*} item */
+  push(item) {
+    this.#items.push(item);
+    this.#drain();
+  }
+
+  /** Discard any queued-but-not-yet-dispatched items (e.g. on reconnect). */
+  clear() {
+    this.#items.length = 0;
+  }
+
+  async #drain() {
+    if (this.#draining) return;
+    this.#draining = true;
+    try {
+      while (this.#items.length > 0) {
+        const item = this.#items.shift();
+        await this.#handler(item);
+      }
+    } finally {
+      this.#draining = false;
+    }
+  }
+}
+
 // ── Transport states ─────────────────────────────────────────────────
 
 const STATE_DISCONNECTED = 'disconnected';
@@ -278,23 +369,13 @@ export class WebTransportTransport extends WshTransport {
         const { done, value } = await reader.read();
         if (done) break;
 
+        // A QUIC stream has no per-message framing at the transport layer,
+        // so a single read() can return bytes for several messages at
+        // once (e.g. SERVER_HELLO immediately followed by CHALLENGE).
+        // dispatchSerially yields between each — see its doc comment for
+        // why that matters.
         const messages = this.#decoder.feed(value);
-        for (const msg of messages) {
-          this._emitControl(msg);
-          // Yield to the microtask queue between messages. A QUIC stream
-          // has no per-message framing at the transport layer, so a single
-          // read() can return bytes for several messages at once (e.g.
-          // SERVER_HELLO immediately followed by CHALLENGE). Emitting them
-          // in a tight synchronous loop starves any `await`'d continuation
-          // triggered by handling an earlier message (e.g. registering the
-          // CHALLENGE waiter after SERVER_HELLO resolves) — that
-          // continuation is a microtask, and without a yield here it never
-          // gets to run before the next message is dispatched. Since
-          // microtasks run FIFO, a continuation queued while handling msg
-          // N always completes before this yield's own continuation
-          // resumes to dispatch msg N+1.
-          await Promise.resolve();
-        }
+        await dispatchSerially(messages, (msg) => this._emitControl(msg));
       }
     } catch (err) {
       if (!this.#abort.signal.aborted) {