@statewalker/webrun-streams-libp2p 0.1.1

package/dist/index.js

@@ -0,0 +1,405 @@
+import { deserializeError, serializeError } from "@statewalker/webrun-streams";
+//#region src/duplex-over-stream.ts
+const TYPE_DATA = 0;
+const TYPE_ERROR = 2;
+/**
+* Default bound for {@link closeStream}'s wait for a graceful close. Matches
+* 2.x's own default (`DEFAULT_SEND_CLOSE_WRITE_TIMEOUT`,
+* `@libp2p/utils@6.7.2/dist/src/abstract-stream.js:7`) — this restores that
+* bound rather than inventing a new number.
+*/
+const DEFAULT_CLOSE_TIMEOUT_MS = 5e3;
+/**
+* Default bound for {@link waitForDrain}'s wait for the peer to make room in
+* its receive window. Without a bound, a peer that requests something and then
+* simply stops reading — alive, so no `close` event ever fires — parks the
+* serving side's outbound pump forever, holding the stream, the handler and
+* whatever the handler buffered. On the serving side there is no escape hatch:
+* `connect`'s `.return`/abort override is a *caller*-side affordance.
+*
+* The number is deliberately generous, because a bound that is too tight
+* resets a slow-but-alive peer mid-transfer — exactly what backpressure exists
+* to avoid. Five minutes covers a peer draining a full yamux receive window
+* (256 KiB by default) at under 1 KiB/s, i.e. slower than any link on which
+* the transfer would complete anyway; a peer slower than that is
+* indistinguishable from one that has stopped reading altogether. Override via
+* `drainTimeoutMs` when a deployment knows better.
+*/
+const DEFAULT_DRAIN_TIMEOUT_MS = 3e5;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+* Drive one `Duplex` over one libp2p `Stream` using a small in-band framing
+* protocol:
+*
+*     [1-byte type][varint length][payload bytes]
+*
+* Types are `DATA` (0x00, body bytes) and `ERROR` (0x02, followed by a
+* JSON-serialised `Error`). Normal end-of-input is signalled by libp2p's
+* `close()`. The frame layer exists so we can preserve `Error` fidelity
+* across the wire (yamux's native stream reset only carries "stream reset").
+*/
+async function* duplexOverStream(stream, input, opts = {}) {
+	let peerEndedCalled = false;
+	const firePeerInputEnd = (err) => {
+		if (peerEndedCalled) return;
+		peerEndedCalled = true;
+		opts.onPeerInputEnd?.(err);
+	};
+	const outboundSource = framedOutbound(input);
+	const outbound = (async () => {
+		try {
+			for await (const chunk of outboundSource) if (!stream.send(chunk)) await waitForDrain(stream, opts.drainTimeoutMs ?? 3e5);
+			await closeStream(stream);
+		} catch (err) {
+			const e = err instanceof Error ? err : new Error(String(err));
+			try {
+				stream.abort(e);
+			} catch {}
+		} finally {
+			try {
+				await outboundSource.return?.(void 0);
+			} catch {}
+		}
+	})();
+	let sourceCompleted = false;
+	try {
+		for await (const frame of parseFrames(stream)) if (frame.type === TYPE_DATA) yield frame.payload;
+		else if (frame.type === TYPE_ERROR) {
+			const err = decodeError(frame.payload);
+			firePeerInputEnd(err);
+			throw err;
+		}
+		sourceCompleted = true;
+		firePeerInputEnd();
+		opts.onSourceCompleted?.();
+	} finally {
+		firePeerInputEnd();
+		if (!sourceCompleted) try {
+			await outboundSource.return?.(void 0);
+		} catch {}
+		await outbound;
+	}
+}
+/**
+* Wait for `stream` to signal it can accept more data, per the real
+* `'drain'` event rather than the broken {@link Stream.onDrain}. Rejects if
+* the stream closes first (including a remote reset) so a peer that goes
+* away while we're backpressured unwinds into the caller's existing
+* `catch` instead of hanging forever — and rejects after `timeoutMs` for the
+* peer that neither reads nor closes, which produces no event at all. The
+* expiry is loud (a `console.warn` naming the protocol and the bound) rather
+* than a silent stall, per this project's "silent failures deserve loud
+* guards" rule; the rejection itself reaches the outbound pump's `catch`,
+* which aborts the stream so the peer learns it was dropped.
+*/
+function waitForDrain(stream, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			clearTimeout(timer);
+			stream.removeEventListener("drain", onDrain);
+			stream.removeEventListener("close", onClose);
+		};
+		const onDrain = () => {
+			cleanup();
+			resolve();
+		};
+		const onClose = (evt) => {
+			cleanup();
+			reject(evt.error ?? /* @__PURE__ */ new Error("stream closed"));
+		};
+		const timer = setTimeout(() => {
+			cleanup();
+			const message = `[webrun-streams-libp2p] waitForDrain: peer on protocol ${stream.protocol} did not accept more data within ${timeoutMs}ms and never closed the stream; dropping it so this side's pump is not parked forever`;
+			console.warn(message);
+			reject(new Error(message));
+		}, timeoutMs);
+		stream.addEventListener("drain", onDrain);
+		stream.addEventListener("close", onClose);
+	});
+}
+/**
+* Close a `Stream`'s writable end, bounded by `timeoutMs`. Plain
+* `stream.close()` awaits the write queue draining and the peer
+* acknowledging with no bound of its own — a peer that stops reading
+* without resetting (a suspended tab, a paused container, `SIGSTOP`) means
+* it never settles, which would otherwise hang every caller waiting on it
+* (the outbound pump here, and `connect`/`serve`'s teardown in
+* `connect-serve.ts`). On timeout we fall back to a hard `abort()` so the
+* caller is never left hanging.
+*/
+async function closeStream(stream, timeoutMs = DEFAULT_CLOSE_TIMEOUT_MS) {
+	try {
+		await stream.close({ signal: AbortSignal.timeout(timeoutMs) });
+	} catch (err) {
+		const e = err instanceof Error ? err : new Error(String(err));
+		console.warn(`[webrun-streams-libp2p] closeStream: graceful close of protocol ${stream.protocol} failed (bound ${timeoutMs}ms), aborting instead (peer may see truncated data): ${e.message}`);
+		try {
+			stream.abort(e);
+		} catch {}
+	}
+}
+async function* framedOutbound(input) {
+	try {
+		for await (const chunk of toAsyncIterable(input)) yield frameData(chunk);
+	} catch (err) {
+		yield frameError(err instanceof Error ? err : new Error(String(err)));
+	}
+}
+async function* parseFrames(source) {
+	let buf = /* @__PURE__ */ new Uint8Array(0);
+	for await (const item of source) {
+		const incoming = normalizeChunk(item);
+		if (incoming.byteLength === 0) continue;
+		if (buf.byteLength === 0) buf = new Uint8Array(incoming);
+		else {
+			const merged = new Uint8Array(buf.byteLength + incoming.byteLength);
+			merged.set(buf, 0);
+			merged.set(incoming, buf.byteLength);
+			buf = merged;
+		}
+		while (buf.byteLength > 0) {
+			if (buf.byteLength < 2) break;
+			const type = buf[0];
+			let lenInfo;
+			try {
+				lenInfo = decodeVarint(buf, 1);
+			} catch {
+				break;
+			}
+			const total = lenInfo.offset + lenInfo.value;
+			if (buf.byteLength < total) break;
+			yield {
+				type,
+				payload: new Uint8Array(buf.subarray(lenInfo.offset, total))
+			};
+			buf = buf.byteLength === total ? /* @__PURE__ */ new Uint8Array(0) : new Uint8Array(buf.subarray(total));
+		}
+	}
+}
+function normalizeChunk(item) {
+	if (item instanceof Uint8Array) return item;
+	const asList = item;
+	if (typeof asList.subarray === "function") return new Uint8Array(asList.subarray());
+	return /* @__PURE__ */ new Uint8Array(0);
+}
+function frameData(payload) {
+	const lenEnc = encodeVarint(payload.byteLength);
+	const out = new Uint8Array(1 + lenEnc.byteLength + payload.byteLength);
+	out[0] = TYPE_DATA;
+	out.set(lenEnc, 1);
+	out.set(payload, 1 + lenEnc.byteLength);
+	return out;
+}
+function frameError(err) {
+	const payload = textEncoder.encode(JSON.stringify(serializeError(err)));
+	const lenEnc = encodeVarint(payload.byteLength);
+	const out = new Uint8Array(1 + lenEnc.byteLength + payload.byteLength);
+	out[0] = TYPE_ERROR;
+	out.set(lenEnc, 1);
+	out.set(payload, 1 + lenEnc.byteLength);
+	return out;
+}
+function decodeError(payload) {
+	if (payload.byteLength === 0) return /* @__PURE__ */ new Error("unknown stream error");
+	try {
+		return deserializeError(JSON.parse(textDecoder.decode(payload)));
+	} catch {
+		return new Error(textDecoder.decode(payload));
+	}
+}
+function encodeVarint(value) {
+	if (!Number.isInteger(value) || value < 0) throw new RangeError(`encodeVarint: ${value} is not a non-negative integer`);
+	const out = [];
+	let v = value;
+	while (v >= 128) {
+		out.push(v & 127 | 128);
+		v >>>= 7;
+	}
+	out.push(v & 127);
+	return new Uint8Array(out);
+}
+function decodeVarint(buf, start) {
+	let value = 0;
+	let shift = 0;
+	let i = start;
+	while (i < buf.length) {
+		const b = buf[i++];
+		value |= (b & 127) << shift;
+		if ((b & 128) === 0) return {
+			value: value >>> 0,
+			offset: i
+		};
+		shift += 7;
+		if (shift > 28) throw new Error("decodeVarint: too long");
+	}
+	throw new Error("decodeVarint: truncated");
+}
+function toAsyncIterable(input) {
+	if (input[Symbol.asyncIterator]) return input;
+	const it = input[Symbol.iterator]();
+	return { [Symbol.asyncIterator]() {
+		return { next: () => Promise.resolve(it.next()) };
+	} };
+}
+//#endregion
+//#region src/connect-serve.ts
+const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
+/**
+* Builds the options object passed to `node.dialProtocol`/`node.handle`,
+* omitting any field the caller didn't supply rather than setting it to
+* `undefined` — so an unset field falls back to libp2p's own default instead
+* of an explicit `undefined` overriding it.
+*/
+function definedOptions(fields) {
+	const options = {};
+	let any = false;
+	for (const key of Object.keys(fields)) {
+		const value = fields[key];
+		if (value !== void 0) {
+			options[key] = value;
+			any = true;
+		}
+	}
+	return any ? options : void 0;
+}
+/**
+* Caller-side: each `call(input)` opens a new libp2p `Stream` via
+* `node.dialProtocol(peer, [protocol])` and runs the call over it.
+*/
+const connect = async ({ node, peer, protocol, drainTimeoutMs, maxOutboundStreams, runOnLimitedConnection }) => {
+	const proto = protocol ?? "/webrun-streams/1.0.0";
+	const dialOptions = definedOptions({
+		maxOutboundStreams,
+		runOnLimitedConnection
+	});
+	const open = /* @__PURE__ */ new Set();
+	const call = (input) => {
+		let streamRef = null;
+		const gen = (async function* () {
+			const stream = await node.dialProtocol(peer, [proto], dialOptions);
+			streamRef = stream;
+			open.add(stream);
+			let sourceCompleted = false;
+			try {
+				yield* duplexOverStream(stream, input, {
+					drainTimeoutMs,
+					onSourceCompleted: () => {
+						sourceCompleted = true;
+					}
+				});
+			} finally {
+				open.delete(stream);
+				if (sourceCompleted) await closeStream(stream);
+			}
+		})();
+		const origReturn = gen.return.bind(gen);
+		gen.return = async (value) => {
+			if (streamRef) try {
+				streamRef.abort(/* @__PURE__ */ new Error("call cancelled"));
+			} catch {}
+			return origReturn(value);
+		};
+		return gen;
+	};
+	return {
+		call,
+		async close() {
+			for (const s of open) try {
+				s.abort(/* @__PURE__ */ new Error("connection close"));
+			} catch {}
+		}
+	};
+};
+/**
+* Server-side: registers `node.handle(protocol, ...)`. Each inbound stream is
+* wrapped as a `Duplex` and handed to `handler`. Identity-unaware; use
+* `serveConnections` when the handler needs to know who is calling.
+*/
+const serve = async (params, handler) => serveConnections(params, () => handler);
+/**
+* Like `serve`, but the handler is built per inbound stream and is told which
+* peer libp2p proved on that connection.
+*/
+async function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection }, makeHandler) {
+	const proto = protocol ?? "/webrun-streams/1.0.0";
+	const handleOptions = definedOptions({
+		maxInboundStreams,
+		maxOutboundStreams,
+		runOnLimitedConnection
+	});
+	const onStream = (stream, connection) => {
+		(async () => {
+			const handler = makeHandler({ remotePeer: connection.remotePeer });
+			const inputQueue = makeInputQueue();
+			const output = handler(inputQueue.iter());
+			try {
+				for await (const chunk of duplexOverStream(stream, output, {
+					drainTimeoutMs,
+					onPeerInputEnd: (err) => inputQueue.done(err)
+				})) inputQueue.push(chunk);
+			} finally {
+				inputQueue.done();
+				await closeStream(stream);
+			}
+		})().catch((err) => {
+			const e = err instanceof Error ? err : new Error(String(err));
+			console.warn(`[webrun-streams-libp2p] serve: inbound stream on protocol ${proto} failed: ${e.message}`, e);
+		});
+	};
+	await node.handle(proto, onStream, handleOptions);
+	let torn = false;
+	return async () => {
+		if (torn) return;
+		torn = true;
+		await node.unhandle(proto);
+	};
+}
+function makeInputQueue() {
+	const slots = [];
+	let wake = null;
+	let closed = false;
+	return {
+		iter() {
+			return (async function* () {
+				try {
+					while (true) {
+						if (slots.length === 0) {
+							await new Promise((r) => {
+								wake = r;
+							});
+							wake = null;
+							continue;
+						}
+						const s = slots.shift();
+						if (s.type === "done") {
+							if (s.err) throw s.err;
+							return;
+						}
+						yield s.value;
+					}
+				} finally {
+					closed = true;
+				}
+			})();
+		},
+		push(chunk) {
+			if (closed) return;
+			slots.push({
+				type: "value",
+				value: chunk
+			});
+			wake?.();
+		},
+		done(err) {
+			if (closed) return;
+			slots.push({
+				type: "done",
+				err
+			});
+			wake?.();
+		}
+	};
+}
+//#endregion
+export { DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_PROTOCOL, connect, duplexOverStream, serve, serveConnections };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@statewalker/webrun-streams-libp2p",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "libp2p native multi-stream Connect/Serve adapter in the webrun-streams-* family",
+  "homepage": "https://github.com/statewalker/webrun-wire",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-wire.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-streams": "0.1.1"
+  },
+  "peerDependencies": {
+    "@libp2p/interface": "^3.0.0",
+    "@multiformats/multiaddr": "^13.0.0",
+    "libp2p": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "libp2p": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@chainsafe/libp2p-noise": "17.0.0",
+    "@chainsafe/libp2p-yamux": "8.0.1",
+    "@libp2p/interface": "3.2.5",
+    "@libp2p/tcp": "11.0.26",
+    "@libp2p/utils": "7.3.2",
+    "@multiformats/multiaddr": "13.0.3",
+    "@types/node": "^26.2.0",
+    "libp2p": "3.3.8",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-streams-conformance": "0.1.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check src tests"
+  }
+}