@statewalker/webrun-http-streams 0.1.1 → 0.2.2

package/src/http1/index.ts

@@ -0,0 +1,40 @@
+import type { MessageCodec } from "../message.js";
+import { decodeRequest, decodeResponse } from "./decode.js";
+import { encodeRequest, encodeResponse, type ResolvedHttpCodecOptions } from "./encode.js";
+import { isTokenChar } from "./headers.js";
+
+export type HttpCodecOptions = {
+  /**
+   * Scheme used to rebuild an absolute url on decode. HTTP/1.1 origin-form
+   * carries no scheme, so this is configuration, not wire data — a peer
+   * configured `http` rebuilds an `https` url as `http`. Accepted cost of
+   * decision 6; see ADR-0006.
+   */
+  scheme?: "http" | "https";
+  /** Authority used when a url carries none. Also fills the mandatory Host header. */
+  host?: string;
+  /** Bound on the whole head section, start line included. Default 65536. */
+  maxHeaderBytes?: number;
+};
+
+export function newHttpCodec(options: HttpCodecOptions = {}): MessageCodec {
+  const opts: ResolvedHttpCodecOptions = {
+    scheme: options.scheme ?? "http",
+    host: options.host ?? "localhost",
+    maxHeaderBytes: options.maxHeaderBytes ?? 65536,
+  };
+  return {
+    name: "http/1.1",
+    // A request starts with a method token, a response with "HTTP/1.1" — both
+    // begin with a token character. "{" is not a token character, so this is
+    // disjoint from jsonEnvelopeCodec by construction, not by convention.
+    sniff: (byte: number): boolean => isTokenChar(byte),
+    encodeRequest: (env, body) => encodeRequest(env, body, opts),
+    encodeResponse: (env, body, o) => encodeResponse(env, body, opts, o?.method),
+    decodeRequest: (input) => decodeRequest(input, opts),
+    decodeResponse: (input, o) => decodeResponse(input, opts, o.method),
+  };
+}
+
+export const httpCodec: MessageCodec = newHttpCodec();
+export { HttpParseError } from "./errors.js";

package/src/index.ts

@@ -1,7 +1,9 @@
+export { defaultCodec } from "./codec-default.js";
 export { DuplexSiteBuilder, type SiteHandler } from "./duplex-site-builder.js";
 export {
   decodeMessage,
   encodeMessage,
+  jsonEnvelopeCodec,
   type RequestEnvelope,
   type ResponseEnvelope,
 } from "./envelope.js";
@@ -9,9 +11,11 @@ export { fetchOverDuplex, serveFetchOverDuplex } from "./fetch.js";
 export {
   type HttpDataHandler,
   type HttpDataHandlerResult,
+  type HttpDataOptions,
   type HttpFetchResult,
   httpFetch,
   httpServe,
+  PEER_ERROR_HEADER,
 } from "./http-data.js";
 export { HttpError, type HttpErrorOptions } from "./http-error.js";
 export {
@@ -22,3 +26,17 @@ export {
   type SerializedHttpRequest,
   type SerializedHttpResponse,
 } from "./http-stubs.js";
+export {
+  type HttpCodecOptions,
+  HttpParseError,
+  httpCodec,
+  newHttpCodec,
+} from "./http1/index.js";
+export type {
+  ByteSource,
+  DecodedRequest,
+  DecodedResponse,
+  MessageCodec,
+  ResponseCodecOptions,
+} from "./message.js";
+export { newSniffingCodec, type SniffingCodecOptions } from "./sniff.js";

package/src/message.ts

@@ -0,0 +1,62 @@
+/** 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>;
+}

package/src/request-streams.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 function supportsRequestStreams(): boolean {
+  return (
+    typeof Request === "function" &&
+    Object.getOwnPropertyDescriptor(Request.prototype, "body") != null
+  );
+}
+
+/**
+ * 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 async function collectBytes(
+  source: AsyncIterable<Uint8Array>,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of source) {
+    if (chunk.byteLength === 0) continue;
+    parts.push(chunk);
+    total += chunk.byteLength;
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  return out;
+}

package/src/sniff.ts

@@ -0,0 +1,68 @@
+import { ByteReader } from "./bytes.js";
+import { HttpParseError } from "./http1/errors.js";
+import type { ByteSource, 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 function newSniffingCodec(options: SniffingCodecOptions): MessageCodec {
+  const { write, accept } = options;
+
+  async function pick(input: ByteSource): Promise<{ codec: MessageCodec; input: ByteSource }> {
+    const reader = new ByteReader(input);
+    const first = await reader.peekByte();
+    if (first === undefined) {
+      throw new HttpParseError("sniff: stream ended before any bytes arrived");
+    }
+    const codec = accept.find((c) => c.sniff(first));
+    if (!codec) {
+      throw new HttpParseError(
+        `sniff: no accepted codec recognises a message starting with byte 0x${first
+          .toString(16)
+          .padStart(2, "0")}`,
+      );
+    }
+    return { codec, input: reader.rest() };
+  }
+
+  return {
+    name: `sniff(write=${write.name}; accept=${accept.map((c) => c.name).join(",")})`,
+    sniff: (byte) => accept.some((c) => c.sniff(byte)),
+    encodeRequest: (env, body) => write.encodeRequest(env, body),
+    encodeResponse: (env, body, o) => write.encodeResponse(env, body, o),
+    decodeRequest: async (input) => {
+      const picked = await pick(input);
+      try {
+        const decoded = await picked.codec.decodeRequest(picked.input);
+        return { ...decoded, codec: picked.codec };
+      } catch (error) {
+        // Sniffing already told us which format the peer is speaking. Carry
+        // that on the error so a refusal can be answered in the peer's own
+        // format — otherwise a peer pinned to the legacy envelope receives its
+        // error response as HTTP/1.1, the same mismatch reply-in-kind avoids
+        // on the success path.
+        if (error !== null && typeof error === "object") {
+          (error as { codec?: MessageCodec }).codec = picked.codec;
+        }
+        throw error;
+      }
+    },
+    decodeResponse: async (input, o) => {
+      const picked = await pick(input);
+      return picked.codec.decodeResponse(picked.input, o);
+    },
+  };
+}

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.