@statewalker/webrun-http-streams 0.1.1 → 0.2.1

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);
+    },
+  };
+}