@statewalker/webrun-streams 0.1.0 → 0.2.0

package/src/readable-streams.ts

@@ -1,21 +1,44 @@
+/**
+ * The iterator ↔ `ReadableStream` boundary.
+ *
+ * Both adapters must carry CANCELLATION, not just data: a response body leaves
+ * a handler as a `ReadableStream`, crosses a transport as an iterator, and
+ * becomes a `ReadableStream` again at the caller — so when the caller walks
+ * away, the only path back to the handler's producer runs through both of
+ * these functions. Teardown that stops at an adapter leaves a producer running
+ * for ever.
+ */
+
 export function toReadableStream(it: AsyncIterator<Uint8Array>): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
+    /**
+     * One chunk per pull. An earlier version drained the whole iterator inside
+     * a single `pull`, which defeated the stream's own backpressure (every
+     * chunk was enqueued as fast as the producer could make them, however slow
+     * the reader was) and left no point between chunks at which a cancellation
+     * could take effect.
+     */
     async pull(controller) {
-      let handled = false;
       try {
-        while (true) {
-          const slot = await it.next();
-          if (!slot || slot.done) break;
-          const value = (await slot.value) as Uint8Array;
-          controller.enqueue(value);
+        const slot = await it.next();
+        if (!slot || slot.done) {
+          controller.close();
+          return;
         }
+        controller.enqueue((await slot.value) as Uint8Array);
       } catch (error) {
-        handled = true;
         controller.error(error);
-      } finally {
-        if (!handled) controller.close();
       }
     },
+    /**
+     * Release the source. NOT awaited: `.return()` on an async generator that
+     * is parked awaiting its own source is queued behind that pending
+     * `next()`, so awaiting it here would hang `reader.cancel()` on exactly
+     * the producers that most need cancelling.
+     */
+    cancel(reason) {
+      void Promise.resolve(it.return?.(reason)).catch(() => {});
+    },
   });
 }
 
@@ -23,9 +46,22 @@ export async function* fromReadableStream(
   stream: ReadableStream<Uint8Array>,
 ): AsyncGenerator<Uint8Array, void, unknown> {
   const reader = stream.getReader();
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value !== undefined) yield value;
+  let drained = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        drained = true;
+        break;
+      }
+      if (value !== undefined) yield value;
+    }
+  } finally {
+    // A consumer that stops early (`break`, `.return()`, an error) must cancel
+    // the source, or whatever fills it keeps filling it. A stream that ended
+    // on its own is merely released — cancelling it would be a lie to any
+    // `cancel()` hook watching for an abandoned reader.
+    if (drained) reader.releaseLock();
+    else await reader.cancel().catch(() => {});
   }
 }

package/src/uint32.ts

@@ -0,0 +1,34 @@
+/**
+ * Credit payloads are a single big-endian uint32, matching the frame header's
+ * byte order.
+ *
+ * Deliberately **not** re-exported from `index.ts`: this is an internal codec
+ * for the `emulateMux` wire format, not a compatibility commitment. Tests
+ * import it by path.
+ */
+/** The largest credit a single frame can advertise or grant: 2^32 - 1. */
+export const MAX_UINT32 = 0xffffffff;
+
+/**
+ * Clamps rather than wraps. `n >>> 0` is the obvious spelling and it is wrong
+ * here: 2^32 becomes **0**, so a 4 GiB window advertises *zero credit* and the
+ * peer stalls forever with no error — the exact silent hang credit exists to
+ * remove. 2^32 + 5 becomes 5, which looks like a working window and is worse.
+ * Anything above the ceiling is advertised as the ceiling.
+ */
+export function encodeUint32(n: number): Uint8Array {
+  const bytes = new Uint8Array(4);
+  const clamped = Number.isFinite(n) ? Math.min(MAX_UINT32, Math.max(0, Math.floor(n))) : 0;
+  new DataView(bytes.buffer).setUint32(0, clamped, false);
+  return bytes;
+}
+
+/**
+ * Returns `undefined` rather than a garbage number when the payload is too
+ * short, so a truncated frame — or one from a peer predating credit — is
+ * detectable at the call site instead of silently granting nonsense.
+ */
+export function decodeUint32(bytes: Uint8Array): number | undefined {
+  if (bytes.byteLength < 4) return undefined;
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, false);
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022-2026 statewalker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.