@statewalker/webrun-http-streams 0.1.1 → 0.2.2

package/dist/message.d.ts

@@ -0,0 +1,50 @@
+/** Anything the codecs will read bytes from. */
+export type ByteSource = AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+export type RequestEnvelope = {
+    url: string;
+    method: string;
+    headers: [string, string][];
+};
+export type ResponseEnvelope = {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+};
+export type DecodedRequest = {
+    envelope: RequestEnvelope;
+    body: AsyncIterable<Uint8Array>;
+    /** The codec that actually read this message; set by the sniffing codec. */
+    codec?: MessageCodec;
+};
+export type DecodedResponse = {
+    envelope: ResponseEnvelope;
+    body: AsyncIterable<Uint8Array>;
+};
+/** Extra context a codec may need that the envelope does not carry. */
+export type ResponseCodecOptions = {
+    /**
+     * Method of the request this response answers. Required by HTTP/1.1: a
+     * response to HEAD carries framing headers but no body, and no parser can
+     * know that from the response bytes alone.
+     */
+    method: string;
+};
+/**
+ * One wire format. Requests and responses are separate operations because
+ * HTTP/1.1 serialises them differently — a codec cannot be generic over the
+ * envelope the way the JSON format was.
+ */
+export interface MessageCodec {
+    readonly name: string;
+    /**
+     * True if a message in this format may begin with `byte`. Used by the
+     * sniffing codec to dispatch without a negotiation handshake. Implementations
+     * must be mutually exclusive with every other codec they are paired with.
+     */
+    sniff(byte: number): boolean;
+    encodeRequest(env: RequestEnvelope, body?: ByteSource): AsyncGenerator<Uint8Array>;
+    encodeResponse(env: ResponseEnvelope, body?: ByteSource, options?: ResponseCodecOptions): AsyncGenerator<Uint8Array>;
+    decodeRequest(input: ByteSource): Promise<DecodedRequest>;
+    decodeResponse(input: ByteSource, options: ResponseCodecOptions): Promise<DecodedResponse>;
+}
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAE1E,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACjC,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACnF,cAAc,CACZ,GAAG,EAAE,gBAAgB,EACrB,IAAI,CAAC,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAAC,UAAU,CAAC,CAAC;IAE9B,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5F"}

package/dist/request-streams.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The one place that knows a runtime may not implement request body streams,
+ * and the buffering both fallbacks need. `fetch.ts` and `http-stubs.ts` each
+ * carry a client and a server direction that must agree on the answer, so the
+ * predicate lives here rather than being written out four times.
+ */
+/**
+ * Whether `Request.prototype` exposes a `body` accessor. Two call sites read
+ * that property, and two more depend on the constructor accepting a
+ * `ReadableStream` as `init.body`; this predicate answers for all four.
+ *
+ * What was verified, and all that is claimed here: Firefox (146 at the time of
+ * writing) has *neither*, and Chromium and Node have *both*. On Firefox it is
+ * not that `body` is `undefined` on the instance —
+ * `Object.getOwnPropertyDescriptor(Request.prototype, "body")` is `null`, the
+ * accessor is genuinely absent — and because a `ReadableStream` is then not a
+ * recognised `BodyInit`, the constructor falls through to the string branch and
+ * stores the literal text `[object ReadableStream]`.
+ *
+ * The two halves are NOT guaranteed to ship together, so do not read this as a
+ * test for "request streams" in general. Safari is the counterexample: it has
+ * had `Request.body` since 11.1 but only accepts a stream as `init.body` from
+ * Technology Preview 250, so a shipping Safari has the reader half without the
+ * upload half and this returns `true` there. That looks benign — WebKit appears
+ * to store the stream on the `Request` rather than stringify it, and its error
+ * comes from `fetch()`, which this package never calls on the objects it builds
+ * — but it is untested, and it is the case to look at first if a Safari report
+ * arrives. The sharper probe, if one is ever needed, is whether
+ * `new Request(url, {method:"POST", body:new ReadableStream(), duplex:"half"})`
+ * has a `content-type` of `text/plain;charset=UTF-8` (stringified) or `null`
+ * (stored); it is not used here because it costs a `Request` and a
+ * `ReadableStream` per call and agrees with the descriptor check on every
+ * runtime measured.
+ *
+ * A capability check, never a user-agent test: the question is what this
+ * runtime does, and the answer flips on its own the day Firefox ships request
+ * streams. Evaluated per call rather than cached at module load so that a test
+ * can install a `Request` without the capability and exercise the real branch
+ * under Node.
+ */
+export declare function supportsRequestStreams(): boolean;
+/**
+ * Drain a body iterable into one contiguous buffer. Only the fallbacks need it.
+ * Allocates its own buffer rather than reusing `bytes.ts`'s `concatChunks`,
+ * which passes a single chunk straight through: that chunk is a view onto the
+ * decoder's own read buffer, and the result here is handed to `new Request` and
+ * outlives the decode. The allocation is also what makes it a
+ * `Uint8Array<ArrayBuffer>`, which `BodyInit` accepts and the looser
+ * `Uint8Array<ArrayBufferLike>` does not.
+ */
+export declare function collectBytes(source: AsyncIterable<Uint8Array>): Promise<Uint8Array<ArrayBuffer>>;
+//# sourceMappingURL=request-streams.d.ts.map

package/dist/request-streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-streams.d.ts","sourceRoot":"","sources":["../src/request-streams.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAKhD;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAelC"}

package/dist/sniff.d.ts

@@ -0,0 +1,18 @@
+import type { MessageCodec } from "./message.js";
+export type SniffingCodecOptions = {
+    /** Codec used for everything this peer writes. */
+    write: MessageCodec;
+    /** Codecs this peer accepts on read, tried in order. */
+    accept: MessageCodec[];
+};
+/**
+ * Dispatches on byte 0. The formats are self-identifying — a JSON envelope
+ * always begins `{`, which is not a token character and so can never begin an
+ * HTTP start-line — so no negotiation handshake, magic prefix, or version byte
+ * is needed.
+ *
+ * This is what makes a mixed-version peer pair safe: readers accept either
+ * format, so the two ends can be upgraded in any order.
+ */
+export declare function newSniffingCodec(options: SniffingCodecOptions): MessageCodec;
+//# sourceMappingURL=sniff.d.ts.map

package/dist/sniff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sniff.d.ts","sourceRoot":"","sources":["../src/sniff.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,cAAc,CAAC;AAE7D,MAAM,MAAM,oBAAoB,GAAG;IACjC,kDAAkD;IAClD,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,CA+C5E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-http-streams",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "description": "HTTP request/response over Duplex — merge of webrun-http + webrun-http-port",
@@ -15,29 +15,35 @@
     "url": "git@github.com:statewalker/webrun-wire.git"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "0.1.0"
+    "@statewalker/webrun-streams": "0.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.2.0",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.0.0-rc.16",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "lint": "biome check src tests"
   }
 }

package/src/bytes.ts

@@ -0,0 +1,157 @@
+import type { ByteSource } from "./message.js";
+
+const CR = 0x0d;
+const LF = 0x0a;
+const EMPTY = new Uint8Array(0);
+
+export class ByteStreamError extends Error {
+  override readonly name = "ByteStreamError";
+}
+
+export function toAsyncIterator(input: ByteSource): AsyncIterator<Uint8Array> {
+  const asyncIter = (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator];
+  if (asyncIter) return asyncIter.call(input as AsyncIterable<Uint8Array>);
+  const syncIter = (input as Iterable<Uint8Array>)[Symbol.iterator]();
+  return {
+    next(): Promise<IteratorResult<Uint8Array>> {
+      return Promise.resolve(syncIter.next());
+    },
+  };
+}
+
+/**
+ * Discard an iterable we are contractually forbidden from consuming — a body
+ * skipped for HEAD/204, or one abandoned because the peer reported an error.
+ *
+ * The `.next()` is not optional: `.return()` on a generator still in suspended
+ * start is a no-op, so the body never runs and its `try/finally` never unwinds.
+ * Without it a wrapped ReadableStream or socket is never cancelled.
+ */
+export async function discard(source: ByteSource | undefined): Promise<void> {
+  if (source === undefined) return;
+  const it = toAsyncIterator(source);
+  try {
+    await it.next();
+    await it.return?.();
+  } catch {
+    /* the source is being discarded; its failures are not ours to surface */
+  }
+}
+
+export function concatChunks(parts: Uint8Array[], totalLen: number): Uint8Array {
+  if (parts.length === 1) {
+    const only = parts[0];
+    // `parts.length === 1` guarantees index 0 exists; falls through to the
+    // general path below in the unreachable case where it somehow doesn't.
+    if (only !== undefined) return only;
+  }
+  const out = new Uint8Array(totalLen);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.byteLength;
+  }
+  return out;
+}
+
+/**
+ * Pull-based reader over a byte source. Holds at most one pending buffer, and
+ * hands out `subarray` views rather than copies — a body never passes through
+ * an allocation here.
+ */
+export class ByteReader {
+  #iter: AsyncIterator<Uint8Array>;
+  #buf: Uint8Array = EMPTY;
+  #done = false;
+
+  constructor(input: ByteSource) {
+    this.#iter = toAsyncIterator(input);
+  }
+
+  /** Bytes already pulled from the source but not yet consumed. */
+  bufferedLength(): number {
+    return this.#buf.byteLength;
+  }
+
+  /** Pull one more non-empty chunk. Returns false at end of stream. */
+  async #pull(): Promise<boolean> {
+    if (this.#done) return false;
+    while (true) {
+      const next = await this.#iter.next();
+      if (next.done) {
+        this.#done = true;
+        return false;
+      }
+      const chunk = next.value;
+      if (chunk.byteLength === 0) continue;
+      this.#buf =
+        this.#buf.byteLength === 0
+          ? chunk
+          : concatChunks([this.#buf, chunk], this.#buf.byteLength + chunk.byteLength);
+      return true;
+    }
+  }
+
+  async peekByte(): Promise<number | undefined> {
+    while (this.#buf.byteLength === 0) {
+      if (!(await this.#pull())) return undefined;
+    }
+    return this.#buf[0];
+  }
+
+  /** Up to `max` bytes. `undefined` means end of stream. */
+  async readSome(max: number): Promise<Uint8Array | undefined> {
+    while (this.#buf.byteLength === 0) {
+      if (!(await this.#pull())) return undefined;
+    }
+    const take = Math.min(max, this.#buf.byteLength);
+    const out = this.#buf.subarray(0, take);
+    this.#buf = this.#buf.subarray(take);
+    return out;
+  }
+
+  /**
+   * One CRLF-terminated line, without the CRLF. A bare LF is rejected: real
+   * peers always send CRLF, and tolerating a bare LF is precisely the lenience
+   * that lets request smuggling through a proxy pair.
+   *
+   * The `maxBytes` bound is best-effort: it only rejects a line if the check
+   * happens to run before the line is fully buffered. A line already sitting in
+   * the buffer bypasses the check. Callers needing a hard per-line limit or
+   * aggregate bounds must keep their own running total.
+   */
+  async readLine(maxBytes: number): Promise<Uint8Array> {
+    let searched = 0;
+    while (true) {
+      const idx = this.#buf.indexOf(LF, searched);
+      if (idx !== -1) {
+        if (idx === 0 || this.#buf[idx - 1] !== CR) {
+          throw new ByteStreamError("bare LF line terminator; CRLF required");
+        }
+        const line = this.#buf.subarray(0, idx - 1);
+        this.#buf = this.#buf.subarray(idx + 1);
+        return line;
+      }
+      searched = this.#buf.byteLength;
+      if (searched > maxBytes) {
+        throw new ByteStreamError(`line exceeds ${maxBytes} bytes without CRLF`);
+      }
+      if (!(await this.#pull())) {
+        throw new ByteStreamError(`stream ended after ${searched} bytes without CRLF`);
+      }
+    }
+  }
+
+  /** Everything not yet consumed, lazily. */
+  async *rest(): AsyncGenerator<Uint8Array> {
+    while (true) {
+      if (this.#buf.byteLength > 0) {
+        const out = this.#buf;
+        this.#buf = EMPTY;
+        yield out;
+        continue;
+      }
+      if (!(await this.#pull())) return;
+    }
+  }
+}

package/src/codec-default.ts

@@ -0,0 +1,13 @@
+import { jsonEnvelopeCodec } from "./envelope.js";
+import { httpCodec } from "./http1/index.js";
+import type { MessageCodec } from "./message.js";
+import { newSniffingCodec } from "./sniff.js";
+
+/**
+ * Writes HTTP/1.1; accepts HTTP/1.1 or the legacy JSON envelope. Used whenever
+ * no `codec` option is supplied.
+ */
+export const defaultCodec: MessageCodec = newSniffingCodec({
+  write: httpCodec,
+  accept: [httpCodec, jsonEnvelopeCodec],
+});

package/src/duplex-site-builder.ts

@@ -1,5 +1,6 @@
 import type { Serve } from "@statewalker/webrun-streams";
 import { serveFetchOverDuplex } from "./fetch.js";
+import type { MessageCodec } from "./message.js";
 
 /**
  * Structural alias of `SiteHandler` from `@statewalker/webrun-site-builder`.
@@ -14,7 +15,7 @@ export type SiteHandler = (request: Request) => Promise<Response>;
  * ```ts
  * import { SiteBuilder } from "@statewalker/webrun-site-builder";
  * import { DuplexSiteBuilder } from "@statewalker/webrun-http-streams";
- * import { serve } from "@statewalker/webrun-streams-port";
+ * import { serve } from "@statewalker/webrun-rpc";
  *
  * const handler = new SiteBuilder()
  *   .setEndpoint("/api/time", () => new Response(new Date().toISOString()))
@@ -29,12 +30,19 @@ export type SiteHandler = (request: Request) => Promise<Response>;
  */
 export class DuplexSiteBuilder {
   #handler?: SiteHandler;
+  #codec?: MessageCodec;
 
   setHandler(handler: SiteHandler): this {
     this.#handler = handler;
     return this;
   }
 
+  /** Pin the wire format. Defaults to HTTP/1.1 with legacy acceptance. */
+  setCodec(codec: MessageCodec): this {
+    this.#codec = codec;
+    return this;
+  }
+
   async start<P>(serve: Serve<P>, params: P): Promise<() => Promise<void>> {
     if (!this.#handler) {
       throw new Error("DuplexSiteBuilder.start: setHandler(handler) must be called before start()");
@@ -42,7 +50,7 @@ export class DuplexSiteBuilder {
     const handler = this.#handler;
     return serve(
       params,
-      serveFetchOverDuplex(async (req) => handler(req)),
+      serveFetchOverDuplex(async (req) => handler(req), { codec: this.#codec }),
     );
   }
 }

package/src/envelope.ts

@@ -1,16 +1,20 @@
-export type RequestEnvelope = {
-  url: string;
-  method: string;
-  headers: [string, string][];
-};
+import { concatChunks, toAsyncIterator } from "./bytes.js";
+import { HttpParseError } from "./http1/errors.js";
+import type {
+  ByteSource,
+  DecodedRequest,
+  DecodedResponse,
+  MessageCodec,
+  RequestEnvelope,
+  ResponseEnvelope,
+} from "./message.js";
 
-export type ResponseEnvelope = {
-  status: number;
-  statusText: string;
-  headers: [string, string][];
-};
+export type { RequestEnvelope, ResponseEnvelope } from "./message.js";
 
 const NEWLINE = 0x0a;
+
+/** Mirrors the HTTP/1.1 codec's default `maxHeaderBytes`. */
+const MAX_ENVELOPE_BYTES = 65536;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
@@ -51,7 +55,7 @@ export async function decodeMessage<E>(
   while (true) {
     const next = await iter.next();
     if (next.done) {
-      throw new Error(
+      throw new HttpParseError(
         `decodeMessage: stream ended after ${accumLen} bytes without delimiter (\\n)`,
       );
     }
@@ -61,6 +65,15 @@ export async function decodeMessage<E>(
     if (nl === -1) {
       accum.push(chunk);
       accumLen += chunk.byteLength;
+      // The envelope is one line, so a peer that never sends the delimiter is
+      // sending garbage — without a bound this loop buffers it all and then
+      // concatenates a second copy. The HTTP/1.1 path refuses the same flood
+      // via maxHeaderBytes; this is its counterpart.
+      if (accumLen > MAX_ENVELOPE_BYTES) {
+        throw new HttpParseError(
+          `decodeMessage: envelope exceeds ${MAX_ENVELOPE_BYTES} bytes without delimiter (\\n)`,
+        );
+      }
       continue;
     }
     accum.push(chunk.subarray(0, nl));
@@ -74,7 +87,7 @@ export async function decodeMessage<E>(
   try {
     envelope = JSON.parse(decoder.decode(before)) as E;
   } catch (err) {
-    throw new Error(
+    throw new HttpParseError(
       `decodeMessage: malformed envelope JSON at bytes 0..${before.byteLength}: ${(err as Error).message}`,
     );
   }
@@ -91,26 +104,22 @@ export async function decodeMessage<E>(
   return { envelope, body: body() };
 }
 
-function toAsyncIterator(
-  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
-): AsyncIterator<Uint8Array> {
-  const asyncIter = (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator];
-  if (asyncIter) return asyncIter.call(input as AsyncIterable<Uint8Array>);
-  const syncIter = (input as Iterable<Uint8Array>)[Symbol.iterator]();
-  return {
-    next(): Promise<IteratorResult<Uint8Array>> {
-      return Promise.resolve(syncIter.next());
-    },
-  };
-}
+const OPEN_BRACE = 0x7b;
 
-function concatChunks(parts: Uint8Array[], totalLen: number): Uint8Array {
-  if (parts.length === 1) return parts[0];
-  const out = new Uint8Array(totalLen);
-  let off = 0;
-  for (const p of parts) {
-    out.set(p, off);
-    off += p.byteLength;
-  }
-  return out;
-}
+/**
+ * The original wire format — `<JSON.stringify(envelope)>\n<body bytes…>` —
+ * expressed as a `MessageCodec`. Direction-agnostic: requests and responses
+ * serialise identically.
+ *
+ * Retained so a peer pair can be upgraded in either order; see ADR-0006.
+ */
+export const jsonEnvelopeCodec: MessageCodec = {
+  name: "json-envelope",
+  sniff: (byte: number): boolean => byte === OPEN_BRACE,
+  encodeRequest: (env: RequestEnvelope, body?: ByteSource) => encodeMessage(env, body),
+  encodeResponse: (env: ResponseEnvelope, body?: ByteSource) => encodeMessage(env, body),
+  decodeRequest: (input: ByteSource): Promise<DecodedRequest> =>
+    decodeMessage<RequestEnvelope>(input),
+  decodeResponse: (input: ByteSource): Promise<DecodedResponse> =>
+    decodeMessage<ResponseEnvelope>(input),
+};