Skip to content

Agent Mesh

sdk/js: speak /libp2p-http on the stream itself

Antonio Ojeabc61021c06e7
diff --git a/sdk/js/src/bytes.ts b/sdk/js/src/bytes.ts
index ef8f0bea..f33245f2 100644
--- a/sdk/js/src/bytes.ts
+++ b/sdk/js/src/bytes.ts
@@ -46,7 +46,7 @@ export function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
return a.length === b.length && a.every((v, i) => v === b[i]);
}
-export function concatBytes(...parts: Uint8Array[]): Uint8Array {
+export function concatBytes(...parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
let offset = 0;
for (const p of parts) {
diff --git a/sdk/js/src/http1.test.ts b/sdk/js/src/http1.test.ts
new file mode 100644
index 00000000..68ee6bbb
--- /dev/null
+++ b/sdk/js/src/http1.test.ts
@@ -0,0 +1,160 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// The HTTP/1.1 codec on its own: what the ingress and the client agree on
+// with go-libp2p-http, fed byte by byte so every split point is exercised.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+ ByteReader,
+ HTTPParseError,
+ LAST_CHUNK,
+ MAX_HEAD_BYTES,
+ bodyStream,
+ encodeChunk,
+ encodeRequestHead,
+ encodeResponseHead,
+ readBody,
+ readRequestHead,
+ readResponseHead,
+ requestBodyFraming,
+ responseBodyFraming,
+ type ByteSource,
+} from "./http1.ts";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/** A source that hands out the text in pieces of the given size. */
+function source(text: string | Uint8Array, pieceSize = 1): ByteSource {
+ const bytes = typeof text === "string" ? enc.encode(text) : text;
+ let offset = 0;
+ return {
+ async read() {
+ if (offset >= bytes.length) {
+ return null;
+ }
+ const next = bytes.subarray(offset, offset + pieceSize);
+ offset += pieceSize;
+ return next;
+ },
+ };
+}
+
+test("a request head parses however the bytes are split", async () => {
+ const wire = "POST /a2a/agent/tasks?x=1 HTTP/1.1\r\nHost: 12D3KooW\r\nX-Sam-Biscuit: abc=\r\nContent-Length: 2\r\n\r\n{}";
+ for (const size of [1, 3, 7, 1000]) {
+ const reader = new ByteReader(source(wire, size));
+ const head = await readRequestHead(reader);
+ assert.ok(head);
+ assert.equal(head.method, "POST");
+ assert.equal(head.target, "/a2a/agent/tasks?x=1");
+ assert.equal(head.headers.get("host"), "12D3KooW");
+ assert.equal(head.headers.get("x-sam-biscuit"), "abc=");
+ assert.deepEqual(requestBodyFraming(head), { kind: "length", length: 2 });
+ assert.equal(dec.decode(await readBody(reader, requestBodyFraming(head), 1024)), "{}");
+ }
+ // Nothing at all is a closed stream, not an error.
+ assert.equal(await readRequestHead(new ByteReader(source(""))), null);
+});
+
+test("a request without a length has no body; malformed heads are refused", async () => {
+ const head = await readRequestHead(new ByteReader(source("GET /a2a/agent HTTP/1.1\r\nHost: x\r\n\r\n")));
+ assert.deepEqual(requestBodyFraming(head!), { kind: "none" });
+ for (const bad of ["GET /x\r\n\r\n", "GET /x HTTP/2\r\n\r\n", "GET /x HTTP/1.1\r\nbad header\r\n\r\n", "GET /x HTTP/1.1\r\n bad: fold\r\n\r\n", "GET /x HTTP/1.1\r\nHost: x"]) {
+ await assert.rejects(readRequestHead(new ByteReader(source(bad, 64))), HTTPParseError, bad);
+ }
+ const huge = "GET /x HTTP/1.1\r\n" + "X-Pad: " + "a".repeat(MAX_HEAD_BYTES) + "\r\n\r\n";
+ await assert.rejects(readRequestHead(new ByteReader(source(huge, 4096))), HTTPParseError);
+ await assert.rejects(readRequestHead(new ByteReader(source("GET /x HTTP/1.1\r\nContent-Length: 1, 2\r\n\r\n"))).then((h) => requestBodyFraming(h!)), HTTPParseError);
+ await assert.rejects(readRequestHead(new ByteReader(source("GET /x HTTP/1.1\r\nTransfer-Encoding: gzip, chunked\r\n\r\n"))).then((h) => requestBodyFraming(h!)), HTTPParseError);
+});
+
+test("a chunked body is reassembled, extensions and trailers skipped, and streamed piece by piece", async () => {
+ const wire = "HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nTransfer-Encoding: chunked\r\n\r\n" + "5;ext=1\r\nhello\r\n" + "6\r\n world\r\n" + "0\r\nX-Trailer: t\r\n\r\n";
+ for (const size of [1, 2, 5, 64]) {
+ const reader = new ByteReader(source(wire, size));
+ const head = await readResponseHead(reader);
+ assert.equal(head.status, 200);
+ assert.equal(head.statusText, "OK");
+ const framing = responseBodyFraming("GET", head);
+ assert.deepEqual(framing, { kind: "chunked" });
+ assert.equal(dec.decode(await readBody(reader, framing, 1024)), "hello world");
+ }
+ let finished = false;
+ const reader = new ByteReader(source(wire, 1000));
+ const head = await readResponseHead(reader);
+ const pieces: string[] = [];
+ const stream = bodyStream(reader, responseBodyFraming("GET", head), () => (finished = true));
+ for await (const piece of stream) {
+ pieces.push(dec.decode(piece));
+ }
+ assert.deepEqual(pieces, ["hello", " world"]);
+ assert.ok(finished);
+ // Each malformed size line is followed by a body that would otherwise
+ // parse, so only the size check can be what refuses it.
+ for (const bad of ["zz\r\nhello\r\n0\r\n\r\n", "5g\r\nhello\r\n0\r\n\r\n", "5 g\r\nhello\r\n0\r\n\r\n", "-5\r\nhello\r\n0\r\n\r\n", "\r\nhello\r\n0\r\n\r\n", "123456789\r\n0\r\n\r\n"]) {
+ await assert.rejects(readBody(new ByteReader(source(bad)), { kind: "chunked" }, 1024), HTTPParseError, bad);
+ }
+ for (const bad of ["5\r\nhello\r\n", "5\r\nhelloXX", "5\r\nhel"]) {
+ await assert.rejects(readBody(new ByteReader(source(bad)), { kind: "chunked" }, 1024), HTTPParseError, bad);
+ }
+ // Whitespace around the extension separator is allowed (RFC 9112 section 7.1.1).
+ assert.equal(dec.decode(await readBody(new ByteReader(source("5 ; ext=1\r\nhello\r\n0\r\n\r\n")), { kind: "chunked" }, 1024)), "hello");
+});
+
+test("a response without framing runs to the end of the stream; some have no body at all", async () => {
+ const reader = new ByteReader(source("HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\n\r\nuntil the end", 3));
+ const head = await readResponseHead(reader);
+ const framing = responseBodyFraming("GET", head);
+ assert.deepEqual(framing, { kind: "until-close" });
+ assert.equal(dec.decode(await readBody(reader, framing, 1024)), "until the end");
+ for (const [method, status] of [["HEAD", 200], ["GET", 204], ["GET", 304], ["GET", 101]] as const) {
+ const h = await readResponseHead(new ByteReader(source(`HTTP/1.1 ${status} X\r\nContent-Length: 10\r\n\r\n`)));
+ assert.deepEqual(responseBodyFraming(method, h), { kind: "none" }, `${method} ${status}`);
+ }
+ // A status line with no reason phrase is still a status line.
+ assert.equal((await readResponseHead(new ByteReader(source("HTTP/1.1 204\r\n\r\n")))).status, 204);
+ await assert.rejects(readResponseHead(new ByteReader(source("HTTP/1.1 twenty\r\n\r\n"))), HTTPParseError);
+ await assert.rejects(readResponseHead(new ByteReader(source(""))), HTTPParseError);
+});
+
+test("a line past the limit is refused however the bytes arrive", async () => {
+ assert.equal(await new ByteReader(source("abcde\r\nrest", 1000)).readLine(5), "abcde");
+ assert.equal(await new ByteReader(source("abcde\r\nrest", 1)).readLine(5), "abcde");
+ // In one piece, so the line is complete before the limit is compared.
+ await assert.rejects(new ByteReader(source("abcdef\r\nrest", 1000)).readLine(5), HTTPParseError);
+ await assert.rejects(new ByteReader(source("abcdef\r\nrest", 1)).readLine(5), HTTPParseError);
+ await assert.rejects(new ByteReader(source("a".repeat(100), 1)).readLine(5), HTTPParseError);
+});
+
+test("bodies past the limit are refused, up front when the length says so", async () => {
+ await assert.rejects(readBody(new ByteReader(source("x".repeat(20))), { kind: "length", length: 20 }, 10), HTTPParseError);
+ await assert.rejects(readBody(new ByteReader(source("x".repeat(20))), { kind: "until-close" }, 10), HTTPParseError);
+ await assert.rejects(readBody(new ByteReader(source("x".repeat(5))), { kind: "length", length: 20 }, 100), HTTPParseError);
+});
+
+test("heads and chunks are written as the other side reads them", async () => {
+ const headers = new Headers({ Host: "peer", "X-Sam-Biscuit": "abc=", "Content-Length": "0" });
+ assert.equal(dec.decode(encodeRequestHead("GET", "/a2a/agent/card", headers)), "GET /a2a/agent/card HTTP/1.1\r\ncontent-length: 0\r\nhost: peer\r\nx-sam-biscuit: abc=\r\n\r\n");
+ assert.equal(dec.decode(encodeResponseHead(404, "Not Found", new Headers({ "Content-Type": "text/plain" }))), "HTTP/1.1 404 Not Found\r\ncontent-type: text/plain\r\n\r\n");
+ assert.equal(dec.decode(encodeResponseHead(200, "", new Headers())), "HTTP/1.1 200 \r\n\r\n");
+ // Headers itself refuses a line break in a value; a stray one in the reason phrase is flattened.
+ assert.throws(() => new Headers({ "X-Bad": "a\r\nInjected: 1" }), TypeError);
+ assert.equal(dec.decode(encodeResponseHead(200, "OK\r\nInjected: 1", new Headers())), "HTTP/1.1 200 OK Injected: 1\r\n\r\n");
+ const body = new Uint8Array([...encodeChunk(enc.encode("hello")), ...encodeChunk(enc.encode(" world")), ...LAST_CHUNK]);
+ assert.equal(dec.decode(body), "5\r\nhello\r\n6\r\n world\r\n0\r\n\r\n");
+ assert.equal(dec.decode(await readBody(new ByteReader(source(body, 4)), { kind: "chunked" }, 1024)), "hello world");
+});
diff --git a/sdk/js/src/http1.ts b/sdk/js/src/http1.ts
new file mode 100644
index 00000000..a0519be0
--- /dev/null
+++ b/sdk/js/src/http1.ts
@@ -0,0 +1,423 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// HTTP/1.1 on a libp2p stream, as go-libp2p-http speaks it: one request and
+// one response per stream, the body framed by Content-Length or chunked
+// (RFC 9112 section 6), a response without either running to the end of the
+// stream. This is the whole of what a member needs to call a service or
+// answer as one, so it is written here rather than borrowed from Node and
+// runs wherever the SDK does, a browser included.
+
+import type { Stream } from "@libp2p/interface";
+import { concatBytes } from "./bytes.ts";
+
+/** Longest request or response head (start line and headers) accepted. */
+export const MAX_HEAD_BYTES = 64 * 1024;
+const MAX_CHUNK_LINE_BYTES = 1024;
+
+const CR = 0x0d;
+const LF = 0x0a;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Where bytes come from: a chunk, or null when no more will arrive. */
+export interface ByteSource {
+ read(): Promise<Uint8Array | null>;
+}
+
+/** Reads a libp2p stream, holding the remote back while nobody is reading. */
+export function streamSource(stream: Stream): ByteSource {
+ const queue: Uint8Array[] = [];
+ let ended = false;
+ let waiter: (() => void) | undefined;
+ const wake = () => {
+ waiter?.();
+ waiter = undefined;
+ };
+ stream.addEventListener("message", (evt) => {
+ queue.push(evt.data.subarray());
+ stream.pause();
+ wake();
+ });
+ const end = () => {
+ ended = true;
+ wake();
+ };
+ // 'end' fires once the read buffer has drained after the remote closed its
+ // writable end; 'remoteCloseWrite' can fire while data is still buffered.
+ stream.addEventListener("end", end);
+ stream.addEventListener("close", end);
+ if (stream.readableEnded) {
+ ended = true;
+ }
+ return {
+ async read() {
+ for (;;) {
+ const next = queue.shift();
+ if (next !== undefined) {
+ if (queue.length === 0 && !ended) {
+ stream.resume();
+ }
+ return next;
+ }
+ if (ended) {
+ return null;
+ }
+ stream.resume();
+ await new Promise<void>((resolve) => {
+ waiter = resolve;
+ });
+ }
+ },
+ };
+}
+
+/** Sends to a libp2p stream, waiting for the remote when the send buffer is full. */
+export async function sendAll(stream: Stream, data: Uint8Array): Promise<void> {
+ if (data.length === 0) {
+ return;
+ }
+ if (!stream.send(data)) {
+ await stream.onDrain();
+ }
+}
+
+export class HTTPParseError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "HTTPParseError";
+ }
+}
+
+/** Bytes from a source with lookahead: lines and exact counts. */
+export class ByteReader {
+ #source: ByteSource;
+ #buf: Uint8Array = new Uint8Array(0);
+ #eof = false;
+
+ constructor(source: ByteSource) {
+ this.#source = source;
+ }
+
+ async #fill(): Promise<boolean> {
+ if (this.#eof) {
+ return false;
+ }
+ const next = await this.#source.read();
+ if (next === null) {
+ this.#eof = true;
+ return false;
+ }
+ this.#buf = this.#buf.length === 0 ? next : concatBytes(this.#buf, next);
+ return true;
+ }
+
+ /** One CRLF-terminated line without its terminator, at most limit bytes; null at end of input before any byte. */
+ async readLine(limit: number): Promise<string | null> {
+ for (;;) {
+ const lf = this.#buf.indexOf(LF);
+ if (lf !== -1) {
+ const end = lf > 0 && this.#buf[lf - 1] === CR ? lf - 1 : lf;
+ if (end > limit) {
+ throw new HTTPParseError(`line exceeds ${limit} bytes`);
+ }
+ const line = decoder.decode(this.#buf.subarray(0, end));
+ this.#buf = this.#buf.subarray(lf + 1);
+ return line;
+ }
+ // Room for the CRLF of a line exactly at the limit.
+ if (this.#buf.length > limit + 2) {
+ throw new HTTPParseError(`line exceeds ${limit} bytes`);
+ }
+ if (!(await this.#fill())) {
+ if (this.#buf.length === 0) {
+ return null;
+ }
+ throw new HTTPParseError("unexpected end of input in a line");
+ }
+ }
+ }
+
+ /** Exactly n bytes, or throws at end of input. */
+ async readExactly(n: number): Promise<Uint8Array> {
+ while (this.#buf.length < n) {
+ if (!(await this.#fill())) {
+ throw new HTTPParseError(`unexpected end of input after ${this.#buf.length} of ${n} bytes`);
+ }
+ }
+ const out = this.#buf.slice(0, n);
+ this.#buf = this.#buf.subarray(n);
+ return out;
+ }
+
+ /** Whatever is available next, at most n bytes; null at end of input. */
+ async readSome(n: number): Promise<Uint8Array | null> {
+ if (this.#buf.length === 0 && !(await this.#fill())) {
+ return null;
+ }
+ const take = Math.min(n, this.#buf.length);
+ const out = this.#buf.slice(0, take);
+ this.#buf = this.#buf.subarray(take);
+ return out;
+ }
+}
+
+export interface RequestHead {
+ method: string;
+ target: string;
+ headers: Headers;
+}
+
+export interface ResponseHead {
+ status: number;
+ statusText: string;
+ headers: Headers;
+}
+
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+async function readHeaders(reader: ByteReader, budget: number): Promise<Headers> {
+ const headers = new Headers();
+ for (;;) {
+ const line = await reader.readLine(budget);
+ if (line === null) {
+ throw new HTTPParseError("unexpected end of input in headers");
+ }
+ if (line === "") {
+ return headers;
+ }
+ budget -= line.length + 2;
+ if (budget < 0) {
+ throw new HTTPParseError(`head exceeds ${MAX_HEAD_BYTES} bytes`);
+ }
+ const colon = line.indexOf(":");
+ if (colon <= 0 || line[0] === " " || line[0] === "\t") {
+ throw new HTTPParseError(`malformed header line ${JSON.stringify(line)}`);
+ }
+ const name = line.slice(0, colon);
+ if (!TOKEN.test(name)) {
+ throw new HTTPParseError(`malformed header name ${JSON.stringify(name)}`);
+ }
+ headers.append(name, line.slice(colon + 1).trim());
+ }
+}
+
+/** The request line and headers, as a server reads them. */
+export async function readRequestHead(reader: ByteReader): Promise<RequestHead | null> {
+ const line = await reader.readLine(MAX_HEAD_BYTES);
+ if (line === null) {
+ return null;
+ }
+ const parts = line.split(" ");
+ if (parts.length !== 3 || !TOKEN.test(parts[0] as string) || parts[1] === "" || !/^HTTP\/1\.[01]$/.test(parts[2] as string)) {
+ throw new HTTPParseError(`malformed request line ${JSON.stringify(line)}`);
+ }
+ const headers = await readHeaders(reader, MAX_HEAD_BYTES - line.length - 2);
+ return { method: parts[0] as string, target: parts[1] as string, headers };
+}
+
+/** The status line and headers, as a client reads them. */
+export async function readResponseHead(reader: ByteReader): Promise<ResponseHead> {
+ const line = await reader.readLine(MAX_HEAD_BYTES);
+ if (line === null) {
+ throw new HTTPParseError("no response");
+ }
+ const m = /^HTTP\/1\.[01] (\d{3})(?: (.*))?$/.exec(line);
+ if (m === null) {
+ throw new HTTPParseError(`malformed status line ${JSON.stringify(line)}`);
+ }
+ const headers = await readHeaders(reader, MAX_HEAD_BYTES - line.length - 2);
+ return { status: Number(m[1]), statusText: m[2] ?? "", headers };
+}
+
+/** How the bytes after a head are delimited. */
+export type BodyFraming = { kind: "none" } | { kind: "length"; length: number } | { kind: "chunked" } | { kind: "until-close" };
+
+function framingOf(headers: Headers, whenUnframed: BodyFraming): BodyFraming {
+ const te = headers.get("transfer-encoding");
+ if (te !== null) {
+ const codings = te.split(",").map((c) => c.trim().toLowerCase());
+ if (codings.at(-1) !== "chunked" || codings.length !== 1) {
+ throw new HTTPParseError(`unsupported transfer-encoding ${JSON.stringify(te)}`);
+ }
+ return { kind: "chunked" };
+ }
+ const cl = headers.get("content-length");
+ if (cl !== null) {
+ const values = new Set(cl.split(",").map((v) => v.trim()));
+ if (values.size !== 1 || !/^\d{1,15}$/.test(cl.split(",")[0]?.trim() ?? "")) {
+ throw new HTTPParseError(`malformed content-length ${JSON.stringify(cl)}`);
+ }
+ const length = Number(values.values().next().value);
+ return length === 0 ? { kind: "none" } : { kind: "length", length };
+ }
+ return whenUnframed;
+}
+
+/** A request body without Content-Length or Transfer-Encoding is empty (RFC 9112 section 6.3). */
+export function requestBodyFraming(head: RequestHead): BodyFraming {
+ return framingOf(head.headers, { kind: "none" });
+}
+
+/** A response body ends where the sender says, or with the stream. */
+export function responseBodyFraming(method: string, head: ResponseHead): BodyFraming {
+ if (method === "HEAD" || head.status === 204 || head.status === 304 || (head.status >= 100 && head.status < 200)) {
+ return { kind: "none" };
+ }
+ return framingOf(head.headers, { kind: "until-close" });
+}
+
+async function* chunkedBody(reader: ByteReader): AsyncGenerator<Uint8Array> {
+ for (;;) {
+ const line = await reader.readLine(MAX_CHUNK_LINE_BYTES);
+ if (line === null) {
+ throw new HTTPParseError("unexpected end of input in chunked body");
+ }
+ // The whole size token must be hex, else "5g" would read as 5 and the
+ // two ends would disagree on where the chunk ends. Eight digits bound
+ // the size to 4 GiB, well within what parseInt represents exactly.
+ const sizeText = (line.split(";")[0] as string).trim();
+ if (!/^[0-9A-Fa-f]{1,8}$/.test(sizeText)) {
+ throw new HTTPParseError(`malformed chunk size ${JSON.stringify(line)}`);
+ }
+ const size = parseInt(sizeText, 16);
+ if (size === 0) {
+ // Trailer fields, then the empty line that ends the message.
+ for (let t = await reader.readLine(MAX_HEAD_BYTES); t !== ""; t = await reader.readLine(MAX_HEAD_BYTES)) {
+ if (t === null) {
+ throw new HTTPParseError("unexpected end of input in trailers");
+ }
+ }
+ return;
+ }
+ let remaining = size;
+ while (remaining > 0) {
+ const part = await reader.readSome(remaining);
+ if (part === null) {
+ throw new HTTPParseError("unexpected end of input in a chunk");
+ }
+ remaining -= part.length;
+ yield part;
+ }
+ if ((await reader.readLine(2)) !== "") {
+ throw new HTTPParseError("chunk data not followed by CRLF");
+ }
+ }
+}
+
+/** The body bytes, as the framing delimits them, in the pieces they arrive. */
+export async function* bodyChunks(reader: ByteReader, framing: BodyFraming): AsyncGenerator<Uint8Array> {
+ switch (framing.kind) {
+ case "none":
+ return;
+ case "length": {
+ let remaining = framing.length;
+ while (remaining > 0) {
+ const part = await reader.readSome(remaining);
+ if (part === null) {
+ throw new HTTPParseError(`body ended ${remaining} bytes short of content-length`);
+ }
+ remaining -= part.length;
+ yield part;
+ }
+ return;
+ }
+ case "chunked":
+ yield* chunkedBody(reader);
+ return;
+ case "until-close":
+ for (let part = await reader.readSome(64 * 1024); part !== null; part = await reader.readSome(64 * 1024)) {
+ yield part;
+ }
+ return;
+ }
+}
+
+/** A whole body, refused past the limit. */
+export async function readBody(reader: ByteReader, framing: BodyFraming, limit: number): Promise<Uint8Array<ArrayBuffer>> {
+ if (framing.kind === "length" && framing.length > limit) {
+ throw new HTTPParseError(`body of ${framing.length} bytes exceeds ${limit}`);
+ }
+ const parts: Uint8Array[] = [];
+ let size = 0;
+ for await (const part of bodyChunks(reader, framing)) {
+ size += part.length;
+ if (size > limit) {
+ throw new HTTPParseError(`body exceeds ${limit} bytes`);
+ }
+ parts.push(part);
+ }
+ return concatBytes(...parts);
+}
+
+/** The body as a web stream; onDone runs once it is drained, failed or cancelled. */
+export function bodyStream(reader: ByteReader, framing: BodyFraming, onDone: (err?: Error) => void): ReadableStream<Uint8Array> {
+ const chunks = bodyChunks(reader, framing);
+ let done = false;
+ const finish = (err?: Error) => {
+ if (!done) {
+ done = true;
+ onDone(err);
+ }
+ };
+ return new ReadableStream<Uint8Array>({
+ async pull(controller) {
+ try {
+ const next = await chunks.next();
+ if (next.done) {
+ controller.close();
+ finish();
+ } else {
+ controller.enqueue(next.value);
+ }
+ } catch (err) {
+ const e = err instanceof Error ? err : new Error(String(err));
+ controller.error(e);
+ finish(e);
+ }
+ },
+ cancel(reason) {
+ finish(reason instanceof Error ? reason : new Error(String(reason)));
+ },
+ });
+}
+
+function headerLines(headers: Headers): string {
+ let out = "";
+ headers.forEach((value, name) => {
+ if (/[\r\n]/.test(value)) {
+ throw new HTTPParseError(`header ${name} contains a line break`);
+ }
+ out += `${name}: ${value}\r\n`;
+ });
+ return out;
+}
+
+/** A request head on the wire. */
+export function encodeRequestHead(method: string, target: string, headers: Headers): Uint8Array {
+ return encoder.encode(`${method} ${target} HTTP/1.1\r\n${headerLines(headers)}\r\n`);
+}
+
+/** A response head on the wire. */
+export function encodeResponseHead(status: number, statusText: string, headers: Headers): Uint8Array {
+ return encoder.encode(`HTTP/1.1 ${status} ${statusText.replace(/[\r\n]/g, " ")}\r\n${headerLines(headers)}\r\n`);
+}
+
+/** One chunk of a chunked body. */
+export function encodeChunk(data: Uint8Array): Uint8Array {
+ return concatBytes(encoder.encode(`${data.length.toString(16)}\r\n`), data, encoder.encode("\r\n"));
+}
+
+/** The end of a chunked body. */
+export const LAST_CHUNK = encoder.encode("0\r\n\r\n");
diff --git a/sdk/js/src/index.ts b/sdk/js/src/index.ts
index 91bbaa8a..5648df3b 100644
--- a/sdk/js/src/index.ts
+++ b/sdk/js/src/index.ts
@@ -51,13 +51,13 @@ export {
HTTP_PROTOCOL,
MESH_PATH_PREFIX,
a2aEndpoint,
+ admitIngress,
fetchOverStream,
httpIngressHandler,
httpRequestOverStream,
meshHTTPTarget,
meshURL,
splitMeshURL,
- streamToNodeDuplex,
type A2AEndpoint,
type A2AEndpointSpec,
type HTTPHandler,
@@ -67,5 +67,6 @@ export {
type NodeRequestListener,
type ProviderOptions,
} from "./libp2p-http.ts";
+export { nodeIngressHandler, streamToNodeDuplex } from "./libp2p-http-node.ts";
export { BASELINE_DATALOG } from "./gen/datalog.ts";
export { BanSet, EVENT_FRESHNESS_MS, GOSSIP_EVENTS_TOPIC, verifyMeshEvent, type VerifiedMeshEvent } from "./sync.ts";
diff --git a/sdk/js/src/libp2p-http-node.ts b/sdk/js/src/libp2p-http-node.ts
new file mode 100644
index 00000000..3b4bbebc
--- /dev/null
+++ b/sdk/js/src/libp2p-http-node.ts
@@ -0,0 +1,143 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// The Node side of the /libp2p-http ingress: an A2A endpoint answered by a
+// Node request listener (an Express app with the A2A SDK's handlers mounted)
+// is served by Node's own HTTP server over the libp2p stream, so the
+// listener sees a real IncomingMessage and ServerResponse. Admission is the
+// same as for a handler or url target; only who parses the request differs.
+
+import type { Connection, Stream, StreamHandler } from "@libp2p/interface";
+import http from "node:http";
+import { Duplex } from "node:stream";
+import { AUTH_HANDSHAKE_TIMEOUT_MS } from "./auth.ts";
+import {
+ HEADER_PEER_ID,
+ HEADER_SAM_AGENT,
+ HEADER_SAM_BISCUIT,
+ HEADER_SAM_NO_TRAILING_SLASH,
+ admitIngress,
+ httpIngressHandler,
+ type A2AEndpoint,
+ type NodeRequestListener,
+ type ProviderOptions,
+} from "./libp2p-http.ts";
+
+interface StreamSocket extends Duplex {
+ remotePeer: string;
+}
+
+/**
+ * Bridges a libp2p stream to a Node Duplex so Node's own HTTP parser and
+ * client can run over it.
+ */
+export function streamToNodeDuplex(stream: Stream, remotePeer: string): StreamSocket {
+ const duplex = new Duplex({
+ read() {
+ stream.resume();
+ },
+ write(chunk: Uint8Array, _encoding, callback) {
+ if (stream.send(chunk)) {
+ callback();
+ } else {
+ stream.addEventListener("drain", () => callback(), { once: true });
+ }
+ },
+ final(callback) {
+ stream.close().then(
+ () => callback(),
+ (err: Error) => callback(err),
+ );
+ },
+ destroy(err, callback) {
+ if (err !== null) {
+ stream.abort(err);
+ } else {
+ void stream.close().catch(() => {});
+ }
+ callback(err);
+ },
+ }) as StreamSocket;
+ duplex.remotePeer = remotePeer;
+ stream.addEventListener("message", (evt) => {
+ if (!duplex.push(Buffer.from(evt.data.subarray()))) {
+ stream.pause();
+ }
+ });
+ const end = () => {
+ if (!duplex.readableEnded) {
+ duplex.push(null);
+ }
+ };
+ stream.addEventListener("remoteCloseWrite", end);
+ stream.addEventListener("close", end);
+ return duplex;
+}
+
+function nodeHeaders(req: http.IncomingMessage): Headers {
+ const headers = new Headers();
+ for (const [name, value] of Object.entries(req.headers)) {
+ for (const v of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
+ headers.append(name, v);
+ }
+ }
+ return headers;
+}
+
+async function serveListener(req: http.IncomingMessage, res: http.ServerResponse, endpoint: A2AEndpoint, listener: NodeRequestListener, options: ProviderOptions): Promise<void> {
+ const remotePeer = (req.socket as unknown as StreamSocket).remotePeer;
+ const admission = await admitIngress({ target: req.url ?? "/", headers: nodeHeaders(req), remotePeer }, endpoint, options);
+ if ("status" in admission) {
+ res.writeHead(admission.status, { "content-type": "text/plain; charset=utf-8" });
+ res.end(admission.text + "\n");
+ return;
+ }
+ // The listener sees the request as a backend behind sam-node would: the
+ // path relative to the service, the verified caller, never the biscuit.
+ // X-Peer-Id is set, not added, so an inbound value cannot pose as the
+ // verified peer.
+ req.url = admission.path;
+ delete req.headers[HEADER_SAM_BISCUIT];
+ delete req.headers[HEADER_SAM_AGENT];
+ req.headers[HEADER_PEER_ID] = remotePeer;
+ if (admission.noTrailingSlash) {
+ req.headers[HEADER_SAM_NO_TRAILING_SLASH] = "true";
+ } else {
+ delete req.headers[HEADER_SAM_NO_TRAILING_SLASH];
+ }
+ listener(req, res);
+}
+
+/**
+ * Server side of /libp2p-http on Node: a listener target is served by Node's
+ * HTTP server on the stream, any other by the runtime-neutral ingress.
+ */
+export function nodeIngressHandler(endpoint: A2AEndpoint, options: ProviderOptions): StreamHandler {
+ if (!("listener" in endpoint.target)) {
+ return httpIngressHandler(endpoint, options);
+ }
+ const listener = endpoint.target.listener;
+ const server = http.createServer({ keepAlive: false }, (req, res) => {
+ void serveListener(req, res, endpoint, listener, options).catch((err: unknown) => {
+ if (!res.headersSent) {
+ res.writeHead(500, { "content-type": "text/plain" });
+ }
+ res.end(`ingress error: ${err instanceof Error ? err.message : String(err)}\n`);
+ });
+ });
+ server.headersTimeout = AUTH_HANDSHAKE_TIMEOUT_MS;
+ return (stream: Stream, connection: Connection) => {
+ server.emit("connection", streamToNodeDuplex(stream, connection.remotePeer.toString()));
+ };
+}
diff --git a/sdk/js/src/libp2p-http.test.ts b/sdk/js/src/libp2p-http.test.ts
index 3e11af9f..83350c15 100644
--- a/sdk/js/src/libp2p-http.test.ts
+++ b/sdk/js/src/libp2p-http.test.ts
@@ -37,9 +37,9 @@ import {
meshHTTPTarget,
meshURL,
splitMeshURL,
- streamToNodeDuplex,
type ProviderOptions,
} from "./libp2p-http.ts";
+import { nodeIngressHandler, streamToNodeDuplex } from "./libp2p-http-node.ts";
type Wasm = Awaited<ReturnType<typeof loadBiscuit>>;
@@ -48,6 +48,7 @@ let cpKeyPair: InstanceType<Wasm["KeyPair"]>;
let cpKey: Uint8Array;
let agent: Libp2p;
let listenerAgent: Libp2p;
+let handlerAgent: Libp2p;
let caller: Libp2p;
let callerBiscuit: Uint8Array;
let guestBiscuit: Uint8Array;
@@ -148,10 +149,36 @@ before(async () => {
};
await listenerAgent.handle(
HTTP_PROTOCOL,
- httpIngressHandler(a2aEndpoint({ name: "worker", listener }), providerOptions(mint(listenerAgent.peerId.toString(), ROLE_NODE))),
+ nodeIngressHandler(a2aEndpoint({ name: "worker", listener }), providerOptions(mint(listenerAgent.peerId.toString(), ROLE_NODE))),
{ runOnLimitedConnection: true },
);
+ // An agent answering with a fetch handler, the shape a browser member uses:
+ // echoes what it was given and, on /stream, writes three SSE events one at
+ // a time into a streaming body.
+ handlerAgent = await newHost();
+ const handler = async (request: Request): Promise<Response> => {
+ const url = new URL(request.url);
+ if (url.pathname === "/stream") {
+ const encoder = new TextEncoder();
+ let i = 0;
+ const body = new ReadableStream<Uint8Array>({
+ async pull(controller) {
+ await new Promise((r) => setTimeout(r, 10));
+ controller.enqueue(encoder.encode(`data: ${JSON.stringify({ event: i })}\n\n`));
+ if (++i === 3) {
+ controller.close();
+ }
+ },
+ });
+ return new Response(body, { headers: { "content-type": "text/event-stream" } });
+ }
+ return Response.json({ path: url.pathname + url.search, method: request.method, peer: request.headers.get("x-peer-id"), biscuit: request.headers.get("x-sam-biscuit"), echo: await request.text() });
+ };
+ await handlerAgent.handle(HTTP_PROTOCOL, httpIngressHandler(a2aEndpoint({ handler }), providerOptions(mint(handlerAgent.peerId.toString(), ROLE_NODE))), {
+ runOnLimitedConnection: true,
+ });
+
caller = await newHost();
callerBiscuit = mint(caller.peerId.toString(), ROLE_NODE);
guestBiscuit = mint(caller.peerId.toString(), "sam:role:guest");
@@ -161,6 +188,7 @@ after(async () => {
await caller.stop();
await agent.stop();
await listenerAgent.stop();
+ await handlerAgent.stop();
await new Promise<void>((resolve) => backend.close(() => resolve()));
});
@@ -209,6 +237,43 @@ test("a fetch over the stream delivers an SSE body event by event", async () =>
);
});
+test("a fetch handler sees the caller and the path, and its streaming body goes out as it is written", async () => {
+ const conn = await dial(handlerAgent);
+ const res = await httpRequestOverStream(conn, callerBiscuit, "a2a://agent", "/tasks?x=1", { method: "POST", headers: { "x-sam-biscuit": "spoof", "content-type": "text/plain" }, body: "hello" });
+ assert.equal(res.status, 200);
+ assert.deepEqual(JSON.parse(res.text()), { path: "/tasks?x=1", method: "POST", peer: caller.peerId.toString(), biscuit: null, echo: "hello" });
+
+ const response = await fetchOverStream(conn, callerBiscuit, new Request(meshURL(handlerAgent.peerId.toString(), "a2a://agent", "/stream")));
+ assert.equal(response.status, 200);
+ assert.equal(response.headers.get("content-type"), "text/event-stream");
+ const chunks: string[] = [];
+ const reader = (response.body as ReadableStream<Uint8Array>).getReader();
+ for (let next = await reader.read(); !next.done; next = await reader.read()) {
+ chunks.push(new TextDecoder().decode(next.value));
+ }
+ assert.ok(chunks.length >= 3, `want at least three chunks, got ${JSON.stringify(chunks)}`);
+ assert.deepEqual(chunks.join("").split("\n").filter((l) => l.startsWith("data:")), ['data: {"event":0}', 'data: {"event":1}', 'data: {"event":2}']);
+
+ // Node's own client reads the chunked response the ingress writes.
+ const stream = await conn.newStream(HTTP_PROTOCOL, { runOnLimitedConnection: true });
+ const socket = streamToNodeDuplex(stream, handlerAgent.peerId.toString());
+ const viaNode = await new Promise<{ status: number; body: string }>((resolve, reject) => {
+ const req = http.request(
+ { method: "GET", path: "/a2a/agent/card", headers: { host: handlerAgent.peerId.toString(), "x-sam-biscuit": Buffer.from(callerBiscuit).toString("base64") }, createConnection: () => socket },
+ (r) => {
+ let body = "";
+ r.on("data", (c: Buffer) => (body += c.toString()));
+ r.on("end", () => resolve({ status: r.statusCode ?? 0, body }));
+ },
+ );
+ req.on("error", reject);
+ req.end();
+ });
+ socket.destroy();
+ assert.equal(viaNode.status, 200);
+ assert.equal(JSON.parse(viaNode.body).path, "/card");
+});
+
test("a Node request listener sees the path relative to the agent and the verified caller", async () => {
const conn = await dial(listenerAgent);
const res = await httpRequestOverStream(conn, callerBiscuit, "a2a://worker", "/tasks/1?q=1", { method: "POST", headers: { "x-sam-biscuit": "spoof" }, body: "{}" });
diff --git a/sdk/js/src/libp2p-http.ts b/sdk/js/src/libp2p-http.ts
index 0b4871f9..f7276c7e 100644
--- a/sdk/js/src/libp2p-http.ts
+++ b/sdk/js/src/libp2p-http.ts
@@ -15,16 +15,33 @@
// The /libp2p-http protocol (go-libp2p-http): the client that calls inference
// and A2A services on the mesh, and the ingress that accepts A2A requests for
// this member's own agent, gated by the authorizer the way sam-node gates its
-// ingress (StartIngressServer in internal/node). Node's own HTTP server and
-// client run over the libp2p stream, so bodies stream in both directions and
-// an A2A message/stream (SSE) works.
+// ingress (StartIngressServer in internal/node). Requests and responses are
+// framed by the codec in http1.ts on the libp2p stream itself, so bodies
+// stream in both directions, an A2A message/stream (SSE) works, and none of
+// it needs Node: a member in a browser calls and answers the same way. A
+// Node request listener (an Express app) is served by libp2p-http-node.ts.
import type { Connection, Stream, StreamHandler } from "@libp2p/interface";
-import http from "node:http";
-import { Duplex, Readable } from "node:stream";
import { AUTH_HANDSHAKE_TIMEOUT_MS } from "./auth.ts";
import { AuthorizationError, authorizeCaller, type ProviderAuthorizerOptions } from "./authorizer.ts";
import type { VerifiedBiscuit } from "./biscuit.ts";
+import { fromBase64, toBase64 } from "./bytes.ts";
+import {
+ ByteReader,
+ HTTPParseError,
+ LAST_CHUNK,
+ bodyStream,
+ encodeChunk,
+ encodeRequestHead,
+ encodeResponseHead,
+ readBody,
+ readRequestHead,
+ readResponseHead,
+ requestBodyFraming,
+ responseBodyFraming,
+ sendAll,
+ streamSource,
+} from "./http1.ts";
import { canonicalPeerId } from "./identity.ts";
/** go-libp2p-http's protocol: plain HTTP/1.1 on a stream, one request per stream. */
@@ -50,14 +67,21 @@ export const DEFAULT_A2A_NAME = "agent";
*/
export const MESH_PATH_PREFIX = "/sam/";
-const MAX_INGRESS_BODY_BYTES = 8 * 1024 * 1024;
+/** Largest request body the ingress reads whole for a handler or url target. */
+export const MAX_INGRESS_BODY_BYTES = 8 * 1024 * 1024;
const REQUEST_TIMEOUT_MS = 60_000;
/** A fetch-style handler in this process. */
export type HTTPHandler = (request: Request, caller: VerifiedBiscuit) => Promise<Response> | Response;
-/** A Node request listener in this process, such as an Express app with the A2A SDK's handlers mounted. */
-export type NodeRequestListener = (req: http.IncomingMessage, res: http.ServerResponse) => void;
+/**
+ * A request listener of the runtime's own HTTP server, such as an Express
+ * app with the A2A SDK's handlers mounted. On Node it is
+ * (req: http.IncomingMessage, res: http.ServerResponse) => void, served by
+ * libp2p-http-node.ts; a browser has no such server and answers 501.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type NodeRequestListener = (req: any, res: any) => void;
/**
* This member's agent as other members reach it: `a2a://<name>`, answered by
@@ -97,239 +121,210 @@ export interface ProviderOptions extends ProviderAuthorizerOptions {
onAuthorized?(peerId: string, verified: VerifiedBiscuit, targetService: string): void;
}
-interface StreamSocket extends Duplex {
- remotePeer: string;
+function hasDotSegment(path: string): boolean {
+ return path.split("/").some((seg) => seg === "." || seg === "..");
}
-/**
- * Bridges a libp2p stream to a Node Duplex so Node's own HTTP parser and
- * client can run over it.
- */
-export function streamToNodeDuplex(stream: Stream, remotePeer: string): StreamSocket {
- const duplex = new Duplex({
- read() {
- stream.resume();
- },
- write(chunk: Uint8Array, _encoding, callback) {
- if (stream.send(chunk)) {
- callback();
- } else {
- stream.addEventListener("drain", () => callback(), { once: true });
- }
- },
- final(callback) {
- stream.close().then(
- () => callback(),
- (err: Error) => callback(err),
- );
- },
- destroy(err, callback) {
- if (err !== null) {
- stream.abort(err);
- } else {
- void stream.close().catch(() => {});
- }
- callback(err);
- },
- }) as StreamSocket;
- duplex.remotePeer = remotePeer;
- stream.addEventListener("message", (evt) => {
- if (!duplex.push(Buffer.from(evt.data.subarray()))) {
- stream.pause();
- }
- });
- const end = () => {
- if (!duplex.readableEnded) {
- duplex.push(null);
- }
- };
- stream.addEventListener("remoteCloseWrite", end);
- stream.addEventListener("close", end);
- return duplex;
+/** What the ingress looks at before anything reaches the agent. */
+export interface IngressRequest {
+ /** The request target as it came off the wire, path and query. */
+ target: string;
+ headers: Headers;
+ remotePeer: string;
}
-/** Reads a whole body, bounded. */
-async function readBody(readable: Readable, limit: number): Promise<Buffer> {
- const chunks: Buffer[] = [];
- let size = 0;
- for await (const chunk of readable) {
- const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array);
- size += buf.length;
- if (size > limit) {
- throw new Error(`body exceeds ${limit} bytes`);
- }
- chunks.push(buf);
- }
- return Buffer.concat(chunks);
+/** A refusal, with the text the caller gets. */
+export interface IngressRefusal {
+ status: number;
+ text: string;
}
-function hasDotSegment(path: string): boolean {
- return path.split("/").some((seg) => seg === "." || seg === "..");
+/** An authorized request for the endpoint, with what the agent may see. */
+export interface IngressAdmission {
+ verified: VerifiedBiscuit;
+ /** The path relative to the service, query included. */
+ path: string;
+ noTrailingSlash: boolean;
}
/**
- * Server side of /libp2p-http, as sam-node's StartIngressServer: the path is
- * /<type>/<name>[/<upstream>], the caller's biscuit is X-Sam-Biscuit, and the
- * request is authorized for <type>://<name> before anything is forwarded. Only
- * the agent's own endpoint is answered; anything else is 404 after
- * authorization, so an unauthorized caller learns nothing about it.
+ * Server-side admission of /libp2p-http, as sam-node's StartIngressServer:
+ * the path is /<type>/<name>[/<upstream>], the caller's biscuit is
+ * X-Sam-Biscuit, and the request is authorized for <type>://<name> before
+ * anything is forwarded. Only the agent's own endpoint is answered; anything
+ * else is 404 after authorization, so an unauthorized caller learns nothing
+ * about it.
*/
-export function httpIngressHandler(endpoint: A2AEndpoint, options: ProviderOptions): StreamHandler {
- const server = http.createServer({ keepAlive: false }, (req, res) => {
- void handleIngress(req, res, endpoint, options).catch((err: unknown) => {
- if (!res.headersSent) {
- res.writeHead(500, { "content-type": "text/plain" });
- }
- res.end(`ingress error: ${err instanceof Error ? err.message : String(err)}\n`);
- });
- });
- server.headersTimeout = AUTH_HANDSHAKE_TIMEOUT_MS;
- return (stream: Stream, connection: Connection) => {
- server.emit("connection", streamToNodeDuplex(stream, connection.remotePeer.toString()));
- };
-}
-
-async function handleIngress(req: http.IncomingMessage, res: http.ServerResponse, endpoint: A2AEndpoint, options: ProviderOptions): Promise<void> {
- const remotePeer = (req.socket as unknown as StreamSocket).remotePeer;
- const reply = (status: number, text: string) => {
- res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
- res.end(text + "\n");
- };
-
- const rawURL = req.url ?? "/";
+export async function admitIngress(req: IngressRequest, endpoint: A2AEndpoint, options: ProviderOptions): Promise<IngressRefusal | IngressAdmission> {
// Policy is decided on the /<type>/<name> prefix; a dot segment in what
// follows could resolve to a sibling path on the backend. Checked on the
// raw path, before URL parsing normalizes it away.
- if (hasDotSegment(rawURL.split("?")[0] as string)) {
- reply(400, "Invalid path");
- return;
+ if (hasDotSegment(req.target.split("?")[0] as string)) {
+ return { status: 400, text: "Invalid path" };
}
- const url = new URL(rawURL, "http://mesh.invalid");
+ const url = new URL(req.target, "http://mesh.invalid");
const parts = url.pathname.replace(/^\//, "").split("/");
if (parts.length < 2 || parts[0] === "" || parts[1] === "") {
- reply(400, "Invalid path");
- return;
+ return { status: 400, text: "Invalid path" };
}
const [serviceType, serviceName, ...rest] = parts as [string, string, ...string[]];
if (serviceType !== "inference" && serviceType !== "a2a" && serviceType !== "mcp") {
- reply(400, "Invalid service type");
- return;
+ return { status: 400, text: "Invalid service type" };
}
const upstreamPath = rest.join("/");
- const biscuitB64 = req.headers[HEADER_SAM_BISCUIT];
- if (typeof biscuitB64 !== "string" || biscuitB64 === "") {
- reply(401, "Missing X-Sam-Biscuit header");
- return;
+ const biscuitB64 = req.headers.get(HEADER_SAM_BISCUIT);
+ if (biscuitB64 === null || biscuitB64 === "") {
+ return { status: 401, text: "Missing X-Sam-Biscuit header" };
}
let biscuit: Uint8Array;
try {
- biscuit = new Uint8Array(Buffer.from(biscuitB64, "base64"));
+ biscuit = fromBase64(biscuitB64);
if (biscuit.length === 0) {
throw new Error("empty");
}
} catch {
- reply(400, "Invalid X-Sam-Biscuit encoding");
- return;
+ return { status: 400, text: "Invalid X-Sam-Biscuit encoding" };
}
const targetService = `${serviceType}://${serviceName}`;
- if (options.isBanned?.(remotePeer) === true) {
- reply(403, "Authorization failed");
- return;
+ if (options.isBanned?.(req.remotePeer) === true) {
+ return { status: 403, text: "Authorization failed" };
}
- const agentHeader = req.headers[HEADER_SAM_AGENT];
let verified: VerifiedBiscuit;
try {
verified = await authorizeCaller(
- { biscuit, peerId: remotePeer, targetService, protocol: HTTP_PROTOCOL, agent: typeof agentHeader === "string" ? agentHeader : "" },
+ { biscuit, peerId: req.remotePeer, targetService, protocol: HTTP_PROTOCOL, agent: req.headers.get(HEADER_SAM_AGENT) ?? "" },
options,
);
} catch (err) {
if (err instanceof AuthorizationError) {
- reply(403, "Authorization failed");
- return;
+ return { status: 403, text: "Authorization failed" };
}
throw err;
}
- options.onAuthorized?.(remotePeer, verified, targetService);
+ options.onAuthorized?.(req.remotePeer, verified, targetService);
// Under the type the policy was evaluated on.
if (targetService !== endpoint.service) {
- reply(404, "Service not found");
- return;
+ return { status: 404, text: "Service not found" };
}
+ return { verified, path: "/" + upstreamPath + url.search, noTrailingSlash: upstreamPath === "" && rest.length === 0 };
+}
- const path = "/" + upstreamPath + url.search;
- const noTrailingSlash = upstreamPath === "" && rest.length === 0;
-
- if ("listener" in endpoint.target) {
- // The listener sees the request as a backend behind sam-node would: the
- // path relative to the service, the verified caller, never the biscuit.
- // X-Peer-Id is set, not added, so an inbound value cannot pose as the
- // verified peer.
- req.url = path;
- delete req.headers[HEADER_SAM_BISCUIT];
- delete req.headers[HEADER_SAM_AGENT];
- req.headers[HEADER_PEER_ID] = remotePeer;
- if (noTrailingSlash) {
- req.headers[HEADER_SAM_NO_TRAILING_SLASH] = "true";
- } else {
- delete req.headers[HEADER_SAM_NO_TRAILING_SLASH];
- }
- endpoint.target.listener(req, res);
- return;
- }
+/** Headers of the mesh datapath and of the hop itself, not passed on to the agent. */
+const HOP_HEADERS = new Set([HEADER_SAM_BISCUIT, HEADER_SAM_AGENT, HEADER_SAM_NO_TRAILING_SLASH, HEADER_PEER_ID, "host", "connection", "transfer-encoding", "content-length", "keep-alive"]);
+/**
+ * The headers the agent sees: the request's own, less the datapath's, with
+ * X-Peer-Id set (not added) to the verified caller so an inbound value
+ * cannot pose as the peer.
+ */
+export function agentHeaders(inbound: Headers, remotePeer: string, noTrailingSlash: boolean): Headers {
const headers = new Headers();
- for (const [k, v] of Object.entries(req.headers)) {
- if (v === undefined || k === HEADER_SAM_BISCUIT || k === HEADER_SAM_AGENT || k === HEADER_SAM_NO_TRAILING_SLASH || k === HEADER_PEER_ID || k === "host" || k === "connection" || k === "transfer-encoding" || k === "content-length") {
- continue;
- }
- for (const value of Array.isArray(v) ? v : [v]) {
- headers.append(k, value);
+ inbound.forEach((value, name) => {
+ if (!HOP_HEADERS.has(name)) {
+ headers.append(name, value);
}
- }
+ });
headers.set(HEADER_PEER_ID, remotePeer);
if (noTrailingSlash) {
headers.set(HEADER_SAM_NO_TRAILING_SLASH, "true");
}
+ return headers;
+}
- const method = req.method ?? "GET";
- const body: Uint8Array<ArrayBuffer> | undefined =
- method === "GET" || method === "HEAD" ? undefined : new Uint8Array(await readBody(req, MAX_INGRESS_BODY_BYTES));
- const init: RequestInit = { method, headers };
- if (body !== undefined) {
- init.body = body;
- }
+/** A plain-text refusal, as sam-node's ingress writes one. */
+export function refusalResponse(refusal: IngressRefusal): Response {
+ return new Response(refusal.text + "\n", { status: refusal.status, headers: { "content-type": "text/plain; charset=utf-8" } });
+}
- let response: Response;
- if ("url" in endpoint.target) {
- const base = endpoint.target.url.replace(/\/$/, "");
- response = await fetch(base + path, { ...init, redirect: "manual" });
- } else {
- response = await endpoint.target.handler(new Request("http://" + endpoint.name + path, init), verified);
+async function writeResponse(stream: Stream, response: Response, headOnly: boolean): Promise<void> {
+ const headers = new Headers();
+ response.headers.forEach((value, name) => {
+ if (name !== "content-length" && name !== "transfer-encoding" && name !== "connection") {
+ headers.set(name, value);
+ }
+ });
+ headers.set("connection", "close");
+ const body = headOnly ? null : response.body;
+ if (body === null) {
+ headers.set("content-length", "0");
+ await sendAll(stream, encodeResponseHead(response.status, response.statusText, headers));
+ return;
+ }
+ // The length is not known up front, so each piece goes as a chunk as soon
+ // as the agent writes it; an SSE event reaches the caller before the next.
+ headers.set("transfer-encoding", "chunked");
+ await sendAll(stream, encodeResponseHead(response.status, response.statusText, headers));
+ const reader = body.getReader();
+ try {
+ for (let next = await reader.read(); !next.done; next = await reader.read()) {
+ if (next.value.length > 0) {
+ await sendAll(stream, encodeChunk(next.value));
+ }
+ }
+ } finally {
+ reader.releaseLock();
}
+ await sendAll(stream, LAST_CHUNK);
+}
- const outHeaders: Record<string, string | string[]> = {};
- response.headers.forEach((value, key) => {
- if (key === "content-length" || key === "transfer-encoding" || key === "connection") {
+async function serveIngress(stream: Stream, remotePeer: string, endpoint: A2AEndpoint, options: ProviderOptions): Promise<void> {
+ const reader = new ByteReader(streamSource(stream));
+ const headTimer = setTimeout(() => stream.abort(new Error(`no request head from ${remotePeer} within ${AUTH_HANDSHAKE_TIMEOUT_MS}ms`)), AUTH_HANDSHAKE_TIMEOUT_MS);
+ let response: Response;
+ let headOnly = false;
+ try {
+ let head;
+ try {
+ head = await readRequestHead(reader);
+ } finally {
+ clearTimeout(headTimer);
+ }
+ if (head === null) {
return;
}
- outHeaders[key] = value;
- });
- res.writeHead(response.status, outHeaders);
- if (response.body === null) {
- res.end();
- return;
+ headOnly = head.method === "HEAD";
+ const admission = await admitIngress({ target: head.target, headers: head.headers, remotePeer }, endpoint, options);
+ if ("status" in admission) {
+ response = refusalResponse(admission);
+ } else if ("listener" in endpoint.target) {
+ response = refusalResponse({ status: 501, text: "A request listener is not served in this runtime" });
+ } else {
+ const headers = agentHeaders(head.headers, remotePeer, admission.noTrailingSlash);
+ const init: RequestInit = { method: head.method, headers };
+ if (head.method !== "GET" && head.method !== "HEAD") {
+ init.body = await readBody(reader, requestBodyFraming(head), MAX_INGRESS_BODY_BYTES);
+ }
+ if ("url" in endpoint.target) {
+ const base = endpoint.target.url.replace(/\/$/, "");
+ response = await fetch(base + admission.path, { ...init, redirect: "manual" });
+ } else {
+ response = await endpoint.target.handler(new Request("http://" + endpoint.name + admission.path, init), admission.verified);
+ }
+ }
+ } catch (err) {
+ if (err instanceof HTTPParseError) {
+ response = refusalResponse({ status: 400, text: `Bad request: ${err.message}` });
+ } else {
+ response = refusalResponse({ status: 500, text: `ingress error: ${err instanceof Error ? err.message : String(err)}` });
+ }
}
- await new Promise<void>((resolve, reject) => {
- Readable.fromWeb(response.body as import("node:stream/web").ReadableStream)
- .on("error", reject)
- .pipe(res)
- .on("finish", resolve)
- .on("error", reject);
- });
+ await writeResponse(stream, response, headOnly);
+}
+
+/**
+ * Server side of /libp2p-http for an endpoint answered by a handler in this
+ * process or an A2A server at a URL. One request per stream; the stream is
+ * closed once the response has been written.
+ */
+export function httpIngressHandler(endpoint: A2AEndpoint, options: ProviderOptions): StreamHandler {
+ return (stream: Stream, connection: Connection) => {
+ void serveIngress(stream, connection.remotePeer.toString(), endpoint, options)
+ .then(() => stream.close())
+ .catch((err: unknown) => stream.abort(err instanceof Error ? err : new Error(String(err))));
+ };
}
/** The request target for a service on a peer: /<type>/<name>/<path>. */
@@ -393,50 +388,55 @@ export async function fetchOverStream(conn: Connection, biscuit: Uint8Array, req
ctl.abort(new DOMException(`no response headers from ${peerId} within ${REQUEST_TIMEOUT_MS}ms`, "TimeoutError"));
}
}, REQUEST_TIMEOUT_MS);
- timer.unref?.();
+ (timer as { unref?: () => void }).unref?.();
}
const signal = ctl.signal;
const stream = await conn.newStream(HTTP_PROTOCOL, { signal, runOnLimitedConnection: true });
- const socket = streamToNodeDuplex(stream, peerId);
- const headers: Record<string, string> = {};
- request.headers.forEach((value, key) => {
- if (key !== "host" && key !== "content-length" && key !== HEADER_SAM_BISCUIT && key !== HEADER_PEER_ID) {
- headers[key] = value;
+ const asError = (reason: unknown) => (reason instanceof Error ? reason : new Error(String(reason)));
+ const abortStream = () => stream.abort(asError(signal.reason));
+ signal.addEventListener("abort", abortStream, { once: true });
+
+ const headers = new Headers();
+ request.headers.forEach((value, name) => {
+ if (name !== "host" && name !== "content-length" && name !== "transfer-encoding" && name !== HEADER_SAM_BISCUIT && name !== HEADER_PEER_ID) {
+ headers.set(name, value);
}
});
- headers.host = peerId;
- headers[HEADER_SAM_BISCUIT] = Buffer.from(biscuit).toString("base64");
+ headers.set("host", peerId);
+ headers.set(HEADER_SAM_BISCUIT, toBase64(biscuit));
if (options.agent) {
- headers[HEADER_SAM_AGENT] = options.agent;
+ headers.set(HEADER_SAM_AGENT, options.agent);
}
- const body = request.body === null ? undefined : Buffer.from(await request.arrayBuffer());
- headers["content-length"] = String(body?.length ?? 0);
-
- return new Promise<Response>((resolve, reject) => {
- const req = http.request({ method: request.method, path: target, headers, createConnection: () => socket, signal }, (res) => {
- headersIn = true;
- const responseHeaders = new Headers();
- for (const [k, v] of Object.entries(res.headers)) {
- if (typeof v === "string") {
- responseHeaders.set(k, v);
- } else if (Array.isArray(v)) {
- responseHeaders.set(k, v.join(", "));
- }
+ const body = request.body === null ? new Uint8Array(0) : new Uint8Array(await request.arrayBuffer());
+ headers.set("content-length", String(body.length));
+
+ try {
+ await sendAll(stream, encodeRequestHead(request.method, target, headers));
+ await sendAll(stream, body);
+ const reader = new ByteReader(streamSource(stream));
+ const head = await readResponseHead(reader);
+ headersIn = true;
+ signal.throwIfAborted();
+ const framing = responseBodyFraming(request.method, head);
+ const done = (err?: Error) => {
+ signal.removeEventListener("abort", abortStream);
+ if (err !== undefined) {
+ stream.abort(err);
+ } else {
+ void stream.close().catch(() => {});
}
- res.on("close", () => socket.destroy());
- const status = res.statusCode ?? 0;
- const bodyStream = Readable.toWeb(res) as ReadableStream<Uint8Array>;
- resolve(new Response(status === 204 || status === 304 || request.method === "HEAD" ? null : bodyStream, { status, statusText: res.statusMessage ?? "", headers: responseHeaders }));
- });
- req.on("error", (err) => {
- socket.destroy();
- reject(err);
- });
- if (body !== undefined) {
- req.write(body);
+ };
+ let responseBody: ReadableStream<Uint8Array> | null = null;
+ if (framing.kind === "none") {
+ done();
+ } else {
+ responseBody = bodyStream(reader, framing, done);
}
- req.end();
- });
+ return new Response(responseBody, { status: head.status, statusText: head.statusText, headers: head.headers });
+ } catch (err) {
+ stream.abort(asError(err));
+ throw signal.aborted ? signal.reason : err;
+ }
}
export interface HTTPRequestOptions {
diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.ts
index 49db9b9a..bb09a881 100644
--- a/sdk/js/src/session.ts
+++ b/sdk/js/src/session.ts
@@ -29,7 +29,6 @@ import {
HTTP_PROTOCOL,
a2aEndpoint,
fetchOverStream,
- httpIngressHandler,
httpRequestOverStream,
meshURL,
splitMeshURL,
@@ -39,6 +38,7 @@ import {
type HTTPResponse,
type ProviderOptions,
} from "./libp2p-http.ts";
+import { nodeIngressHandler } from "./libp2p-http-node.ts";
import { BanSet, GOSSIP_EVENTS_TOPIC, MeshEvent_Type, verifyMeshEvent } from "./sync.ts";
export interface JoinOptions extends MeshHostOptions {
@@ -491,7 +491,7 @@ export class MeshSession {
isBanned: (peerId) => this.banned.has(peerId),
onAuthorized: (peerId, verified) => this.authenticatedPeers.set(peerId, verified.expiration),
};
- await this.node.handle(HTTP_PROTOCOL, httpIngressHandler(endpoint, providerOptions), HTTP_HANDLER_OPTIONS);
+ await this.node.handle(HTTP_PROTOCOL, nodeIngressHandler(endpoint, providerOptions), HTTP_HANDLER_OPTIONS);
this.#policyTimer = setInterval(() => void this.syncPolicy().catch(() => {}), this.#policySyncMs);
this.#policyTimer.unref?.();
this.endpoint = endpoint;