@statewalker/webrun-streams-libp2p 0.1.1 → 0.1.4

package/README.md

@@ -2,6 +2,31 @@
 
 libp2p native multi-stream `Connect` / `Serve` adapter. Each `call(input)` opens a new libp2p `Stream` via `node.dialProtocol(peer, [protocol])`; the responder registers via `node.handle(protocol, ...)`. Default protocol id: `/webrun-streams/1.0.0`. Targets libp2p 3.x.
 
+## Why it exists
+
+libp2p already solves the hard parts of peer-to-peer — transport negotiation,
+NAT traversal, circuit relaying, and an authenticated peer identity from the
+Noise handshake. What it hands an application is a `Stream`, not a request.
+
+This adapter binds that stream to the [`webrun-streams`](../webrun-streams)
+`Duplex` seam, so a handler written for a `MessagePort` or a WebSocket runs
+unchanged across a libp2p network. Because libp2p multiplexes natively, this
+adapter is one of two in the family (with
+[`webrun-streams-webrtc`](../webrun-streams-webrtc)) that needs no `emulateMux`
+— one `call` is one real libp2p stream.
+
+## Install
+
+```sh
+npm install @statewalker/webrun-streams-libp2p libp2p @libp2p/interface @multiformats/multiaddr
+```
+
+`libp2p` (`^3.0.0`), `@libp2p/interface` (`^3.0.0`) and `@multiformats/multiaddr`
+(`^13.0.0`) are **peer dependencies** — you build and own the node, including
+its transports, encryption and muxers.
+
+## Getting started
+
 ```ts
 import { connect, serve } from "@statewalker/webrun-streams-libp2p";
 
@@ -68,6 +93,45 @@ Two bounds keep a misbehaving peer from parking a long-lived server:
 
 One inbound stream failing never takes down the serving process. `duplexOverStream` rejects on the read side when a peer sends an `ERROR` frame or resets mid-request — which happens in ordinary use, a browser tab closed mid-request being enough — and `serveConnections` catches that per stream and logs it. Callers see their own errors as usual: cancelling a `call` (i.e. `.return()` on the returned generator) sends a reset, and `close()` on the connection aborts every stream it still holds open.
 
+## API
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `connect(params)` | `Connect<ConnectLibp2pParams>` | Dials `peer` and resolves `{ call, close }`. Each `call` opens one libp2p stream. |
+| `serve(params, handler)` | `Serve<ServeLibp2pParams>` | Registers `handler` on `protocol`. Returns an idempotent teardown. |
+| `serveConnections(params, makeHandler)` | function | Like `serve`, but builds a handler per inbound stream and passes it the authenticated `ConnectionContext`. |
+| `ServeConnectionsHandler` | type | `(context: ConnectionContext) => Duplex` — the factory `serveConnections` takes. |
+| `duplexOverStream(stream, options?)` | function | Wraps one libp2p `Stream` as a `Duplex`, applying the framing and flow control described above. |
+| `closeStream(stream, ...)` | function | The graceful-close-then-abort sequence, with the 5 s close timeout. |
+| `DEFAULT_PROTOCOL` | const | `"/webrun-streams/1.0.0"` — used when `protocol` is unset. |
+| `DEFAULT_DRAIN_TIMEOUT_MS` | const | `300_000` — the default drain bound (5 minutes). |
+
+### `ConnectLibp2pParams`
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `node` | `Libp2p` | — | The local node. |
+| `peer` | `PeerId \| Multiaddr` | — | Who to dial. |
+| `protocol` | `string` | `DEFAULT_PROTOCOL` | libp2p protocol id. |
+| `drainTimeoutMs` | `number` | `300_000` | Backpressure drain bound before dropping the peer. |
+| `maxOutboundStreams` | `number` | libp2p's (64) | Passed through to `dialProtocol`. |
+| `runOnLimitedConnection` | `boolean` | unset | Opt in to relayed / limited connections. |
+
+### `ServeLibp2pParams`
+
+As above minus `peer`, plus `maxInboundStreams` (libp2p default **32**).
+
+### `ConnectionContext`
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `remotePeer` | `PeerId` | The peer id proved by the Noise handshake. Unforgeable by the request payload. |
+
+### `DuplexOverStreamOptions`
+
+`onPeerInputEnd(err?)`, `onSourceCompleted()` and `drainTimeoutMs` — see
+[Flow control](#flow-control-and-what-libp2p-3x-does-not-give-you-for-free).
+
 ## Tests
 
 ```bash
@@ -77,6 +141,18 @@ WEBRUN_STREAMS_LIBP2P=1 pnpm test      # + the framing/conformance suite
 
 The conformance suite is opt-in because it spins up two real libp2p TCP nodes in-process.
 
+## Dependencies
+
+| Dependency | Kind | Why |
+| --- | --- | --- |
+| [`@statewalker/webrun-streams`](../webrun-streams) | runtime | The `Duplex` seam and error serialisation. |
+| `libp2p` | **peer** (`^3.0.0`) | The node you build and own. |
+| `@libp2p/interface` | **peer** (`^3.0.0`) | `Libp2p`, `PeerId`, `Stream` types. |
+| `@multiformats/multiaddr` | **peer** (`^13.0.0`) | `Multiaddr` dial targets. |
+| `@chainsafe/libp2p-noise`, `@chainsafe/libp2p-yamux`, `@libp2p/tcp`, `@libp2p/utils` | dev | Two real in-process nodes for the test suite. |
+
+No runtime dependencies outside the workspace. ESM only (`"type": "module"`).
+
 ## License
 
-MIT
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/duplex-over-stream.d.ts

@@ -16,6 +16,35 @@ import type { Stream } from "@libp2p/interface";
  * `drainTimeoutMs` when a deployment knows better.
  */
 export declare const DEFAULT_DRAIN_TIMEOUT_MS = 300000;
+/**
+ * Default bound for {@link closeStream}'s wait for a graceful close.
+ *
+ * WHY THIS IS MINUTES AND NOT SECONDS. `stream.close()` waits for the write
+ * queue to DRAIN, and that queue is shared with every other stream on the same
+ * muxer. Draining one stream is therefore not a function of that stream alone:
+ * with many concurrent transfers it legitimately takes far longer than it would
+ * in isolation. When the bound trips, {@link closeStream} falls back to
+ * `abort()`, which resets the stream and truncates whatever was still in
+ * flight — so a bound tuned for an idle link silently corrupts healthy
+ * transfers under load.
+ *
+ * It did. This was 5000ms, matching libp2p 2.x's `DEFAULT_SEND_CLOSE_WRITE_TIMEOUT`
+ * — a number adopted for fidelity rather than reasoned about. Eighteen
+ * concurrent 3.5 MB fetches over one connection produced five complete
+ * responses out of twenty-two; the rest arrived truncated and rendered as
+ * broken images, with nothing but this module's own warning to say why.
+ *
+ * The bound's actual purpose is to catch a peer that has stopped reading and
+ * will never close, so the caller is not parked forever. Minutes serve that
+ * purpose exactly as well as seconds, and match {@link DEFAULT_DRAIN_TIMEOUT_MS},
+ * whose comment reasons about the identical hazard: *"a bound that is too tight
+ * resets a slow-but-alive peer mid-transfer — exactly what backpressure exists
+ * to avoid."* The two guard the same thing and should not disagree by a factor
+ * of sixty.
+ *
+ * Exported so a deployment that knows its links can lower it deliberately.
+ */
+export declare const DEFAULT_CLOSE_TIMEOUT_MS = 300000;
 /**
  * Options for {@link duplexOverStream}. The `onPeerInputEnd` hook is the seam
  * that lets the server side close its input queue as soon as the peer's source

package/dist/duplex-over-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplex-over-stream.d.ts","sourceRoot":"","sources":["../src/duplex-over-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAoB,MAAM,mBAAmB,CAAC;AAclE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAKhD;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,EACvD,IAAI,GAAE,uBAA4B,GACjC,cAAc,CAAC,UAAU,CAAC,CAoF5B;AA2CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAsBf"}
+{"version":3,"file":"duplex-over-stream.d.ts","sourceRoot":"","sources":["../src/duplex-over-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAoB,MAAM,mBAAmB,CAAC;AAMlE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,wBAAwB,SAA2B,CAAC;AAKjE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,EACvD,IAAI,GAAE,uBAA4B,GACjC,cAAc,CAAC,UAAU,CAAC,CAwH5B;AA2CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { type ConnectionContext, type ConnectLibp2pParams, connect, DEFAULT_PROTOCOL, type ServeConnectionsHandler, type ServeLibp2pParams, serve, serveConnections, } from "./connect-serve.js";
-export { DEFAULT_DRAIN_TIMEOUT_MS, type DuplexOverStreamOptions, duplexOverStream, } from "./duplex-over-stream.js";
+export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, type DuplexOverStreamOptions, duplexOverStream, } from "./duplex-over-stream.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,OAAO,EACP,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,EACL,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,OAAO,EACP,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,EACL,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -3,13 +3,6 @@ import { deserializeError, serializeError } from "@statewalker/webrun-streams";
 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
@@ -26,6 +19,35 @@ const DEFAULT_CLOSE_TIMEOUT_MS = 5e3;
 * `drainTimeoutMs` when a deployment knows better.
 */
 const DEFAULT_DRAIN_TIMEOUT_MS = 3e5;
+/**
+* Default bound for {@link closeStream}'s wait for a graceful close.
+*
+* WHY THIS IS MINUTES AND NOT SECONDS. `stream.close()` waits for the write
+* queue to DRAIN, and that queue is shared with every other stream on the same
+* muxer. Draining one stream is therefore not a function of that stream alone:
+* with many concurrent transfers it legitimately takes far longer than it would
+* in isolation. When the bound trips, {@link closeStream} falls back to
+* `abort()`, which resets the stream and truncates whatever was still in
+* flight — so a bound tuned for an idle link silently corrupts healthy
+* transfers under load.
+*
+* It did. This was 5000ms, matching libp2p 2.x's `DEFAULT_SEND_CLOSE_WRITE_TIMEOUT`
+* — a number adopted for fidelity rather than reasoned about. Eighteen
+* concurrent 3.5 MB fetches over one connection produced five complete
+* responses out of twenty-two; the rest arrived truncated and rendered as
+* broken images, with nothing but this module's own warning to say why.
+*
+* The bound's actual purpose is to catch a peer that has stopped reading and
+* will never close, so the caller is not parked forever. Minutes serve that
+* purpose exactly as well as seconds, and match {@link DEFAULT_DRAIN_TIMEOUT_MS},
+* whose comment reasons about the identical hazard: *"a bound that is too tight
+* resets a slow-but-alive peer mid-transfer — exactly what backpressure exists
+* to avoid."* The two guard the same thing and should not disagree by a factor
+* of sixty.
+*
+* Exported so a deployment that knows its links can lower it deliberately.
+*/
+const DEFAULT_CLOSE_TIMEOUT_MS = DEFAULT_DRAIN_TIMEOUT_MS;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 /**
@@ -46,7 +68,11 @@ async function* duplexOverStream(stream, input, opts = {}) {
 		peerEndedCalled = true;
 		opts.onPeerInputEnd?.(err);
 	};
-	const outboundSource = framedOutbound(input);
+	const inputIterator = input[Symbol.asyncIterator]?.() ?? input[Symbol.iterator]();
+	const cancelInput = () => {
+		Promise.resolve(inputIterator.return?.(void 0)).catch(() => void 0);
+	};
+	const outboundSource = framedOutbound(inputIterator);
 	const outbound = (async () => {
 		try {
 			for await (const chunk of outboundSource) if (!stream.send(chunk)) await waitForDrain(stream, opts.drainTimeoutMs ?? 3e5);
@@ -75,10 +101,14 @@ async function* duplexOverStream(stream, input, opts = {}) {
 		opts.onSourceCompleted?.();
 	} finally {
 		firePeerInputEnd();
-		if (!sourceCompleted) try {
-			await outboundSource.return?.(void 0);
-		} catch {}
-		await outbound;
+		if (!sourceCompleted) {
+			cancelInput();
+			Promise.resolve(outboundSource.return?.(void 0)).catch(() => void 0);
+			try {
+				stream.abort(/* @__PURE__ */ new Error("duplexOverStream: consumer cancelled"));
+			} catch {}
+			outbound.catch(() => void 0);
+		} else await outbound;
 	}
 }
 /**
@@ -139,11 +169,28 @@ async function closeStream(stream, timeoutMs = DEFAULT_CLOSE_TIMEOUT_MS) {
 		} catch {}
 	}
 }
-async function* framedOutbound(input) {
+/**
+* Frame the caller's outbound chunks.
+*
+* TAKES AN ITERATOR, NOT AN ITERABLE, so the caller can cancel the PRODUCER
+* directly. Returning this wrapper generator is not enough: while it is
+* parked awaiting the producer's `next()`, a `.return()` on the wrapper is
+* queued behind that pending call and reaches the producer only once the
+* producer yields — which a long-lived session never does. Teardown therefore
+* needs a handle on the producer itself, and acquiring the iterator once (in
+* `duplexOverStream`) is what provides it.
+*/
+async function* framedOutbound(iterator) {
 	try {
-		for await (const chunk of toAsyncIterable(input)) yield frameData(chunk);
+		for (;;) {
+			const next = await iterator.next();
+			if (next.done === true) return;
+			yield frameData(normalizeChunk(next.value));
+		}
 	} catch (err) {
 		yield frameError(err instanceof Error ? err : new Error(String(err)));
+	} finally {
+		Promise.resolve(iterator.return?.(void 0)).catch(() => void 0);
 	}
 }
 async function* parseFrames(source) {
@@ -235,13 +282,6 @@ function decodeVarint(buf, start) {
 	}
 	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";
@@ -402,4 +442,4 @@ function makeInputQueue() {
 	};
 }
 //#endregion
-export { DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_PROTOCOL, connect, duplexOverStream, serve, serveConnections };
+export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_PROTOCOL, connect, duplexOverStream, serve, serveConnections };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-streams-libp2p",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "libp2p native multi-stream Connect/Serve adapter in the webrun-streams-* family",
@@ -15,14 +15,18 @@
     "url": "git@github.com:statewalker/webrun-wire.git"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-streams": "0.1.1"
+    "@statewalker/webrun-streams": "^0.2.1"
   },
   "peerDependencies": {
     "@libp2p/interface": "^3.0.0",
@@ -35,24 +39,26 @@
     }
   },
   "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",
+    "@biomejs/biome": "^2.5.15",
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/interface": "^3.3.0",
+    "@libp2p/tcp": "^11.0.28",
+    "@libp2p/utils": "^7.4.1",
+    "@multiformats/multiaddr": "^13.0.3",
+    "@types/node": "^26.6.4",
+    "libp2p": "^3.3.11",
     "rimraf": "^6.1.3",
-    "rolldown": "^1.2.4",
+    "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10",
-    "@statewalker/webrun-streams-conformance": "0.1.1"
+    "vitest": "^5.0.3",
+    "@statewalker/webrun-streams-conformance": "^0.3.1"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "test": "vitest run",

package/src/duplex-over-stream.ts

@@ -4,14 +4,6 @@ import { deserializeError, serializeError } from "@statewalker/webrun-streams";
 const TYPE_DATA = 0x00;
 const TYPE_ERROR = 0x02;
 
-/**
- * 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 = 5000;
-
 /**
  * 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
@@ -30,6 +22,36 @@ const DEFAULT_CLOSE_TIMEOUT_MS = 5000;
  */
 export const DEFAULT_DRAIN_TIMEOUT_MS = 300_000;
 
+/**
+ * Default bound for {@link closeStream}'s wait for a graceful close.
+ *
+ * WHY THIS IS MINUTES AND NOT SECONDS. `stream.close()` waits for the write
+ * queue to DRAIN, and that queue is shared with every other stream on the same
+ * muxer. Draining one stream is therefore not a function of that stream alone:
+ * with many concurrent transfers it legitimately takes far longer than it would
+ * in isolation. When the bound trips, {@link closeStream} falls back to
+ * `abort()`, which resets the stream and truncates whatever was still in
+ * flight — so a bound tuned for an idle link silently corrupts healthy
+ * transfers under load.
+ *
+ * It did. This was 5000ms, matching libp2p 2.x's `DEFAULT_SEND_CLOSE_WRITE_TIMEOUT`
+ * — a number adopted for fidelity rather than reasoned about. Eighteen
+ * concurrent 3.5 MB fetches over one connection produced five complete
+ * responses out of twenty-two; the rest arrived truncated and rendered as
+ * broken images, with nothing but this module's own warning to say why.
+ *
+ * The bound's actual purpose is to catch a peer that has stopped reading and
+ * will never close, so the caller is not parked forever. Minutes serve that
+ * purpose exactly as well as seconds, and match {@link DEFAULT_DRAIN_TIMEOUT_MS},
+ * whose comment reasons about the identical hazard: *"a bound that is too tight
+ * resets a slow-but-alive peer mid-transfer — exactly what backpressure exists
+ * to avoid."* The two guard the same thing and should not disagree by a factor
+ * of sixty.
+ *
+ * Exported so a deployment that knows its links can lower it deliberately.
+ */
+export const DEFAULT_CLOSE_TIMEOUT_MS = DEFAULT_DRAIN_TIMEOUT_MS;
+
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
 
@@ -83,7 +105,18 @@ export async function* duplexOverStream(
     opts.onPeerInputEnd?.(err);
   };
 
-  const outboundSource = framedOutbound(input);
+  // Acquire the producer's iterator ONCE, so teardown can cancel the producer
+  // itself rather than the wrapper around it — see `framedOutbound`.
+  const inputIterator: AsyncIterator<Uint8Array> | Iterator<Uint8Array> =
+    (input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator]?.() ??
+    (input as Iterable<Uint8Array>)[Symbol.iterator]();
+  const cancelInput = (): void => {
+    void Promise.resolve((inputIterator as AsyncIterator<Uint8Array>).return?.(undefined)).catch(
+      () => undefined,
+    );
+  };
+
+  const outboundSource = framedOutbound(inputIterator);
   const outbound = (async () => {
     try {
       // libp2p 3.x streams are push-based (`send()` + drain) rather than
@@ -146,18 +179,43 @@ export async function* duplexOverStream(
     opts.onSourceCompleted?.();
   } finally {
     firePeerInputEnd();
-    // If the consumer aborted before the source completed, force the outbound
-    // generator to return so `await outbound` doesn't hang on a still-pumping
-    // handler. On natural source completion we DO NOT cut outbound short —
-    // peer closing write doesn't entitle us to silence our own writes.
+    // If the consumer aborted before the source completed, cut the outbound
+    // generator short. On natural source completion we DO NOT: the peer
+    // closing its write half does not entitle us to silence our own writes.
+    //
+    // NEITHER CALL IS AWAITED, AND THAT IS THE FIX.
+    //
+    // `.return()` on an async generator that is PARKED AWAITING ITS OWN
+    // SOURCE is queued behind that pending `next()` — it is not preemptive.
+    // For a long-lived session, waiting inside `next()` is where the pump
+    // spends its entire life, so the old `await outboundSource.return()`
+    // never settled, and the `await outbound` behind it never settled either:
+    // tearing down a duplex whose input was still open hung for ever. Two
+    // consumers of this package hit it and both worked around it with
+    // `close()`, which is a defect report, not a usage pattern.
+    //
+    // Cancelling without waiting keeps the contract a consumer is entitled to
+    // — `.return()` settles promptly, and a well-behaved producer still sees
+    // its `finally` — while a producer that cannot be woken is simply
+    // abandoned rather than allowed to hold the caller hostage. The stream is
+    // aborted below, so the peer is told rather than left guessing.
     if (!sourceCompleted) {
+      // The producer first — this is the call that actually runs its
+      // `finally` — then the wrapper, which may be parked behind it.
+      cancelInput();
+      void Promise.resolve(outboundSource.return?.(undefined)).catch(() => undefined);
+      // The pump may be parked in `next()` or in `waitForDrain`; aborting the
+      // stream is what unblocks the latter and tells the peer this call is
+      // over. `closeStream`'s graceful path belongs to a completed call.
       try {
-        await outboundSource.return?.(undefined);
+        stream.abort(new Error("duplexOverStream: consumer cancelled"));
       } catch {
-        /* ignore */
+        /* already gone */
       }
+      void outbound.catch(() => undefined);
+    } else {
+      await outbound;
     }
-    await outbound;
   }
 }
 
@@ -239,16 +297,45 @@ export async function closeStream(
   }
 }
 
+/**
+ * Frame the caller's outbound chunks.
+ *
+ * TAKES AN ITERATOR, NOT AN ITERABLE, so the caller can cancel the PRODUCER
+ * directly. Returning this wrapper generator is not enough: while it is
+ * parked awaiting the producer's `next()`, a `.return()` on the wrapper is
+ * queued behind that pending call and reaches the producer only once the
+ * producer yields — which a long-lived session never does. Teardown therefore
+ * needs a handle on the producer itself, and acquiring the iterator once (in
+ * `duplexOverStream`) is what provides it.
+ */
 async function* framedOutbound(
-  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  iterator: AsyncIterator<Uint8Array> | Iterator<Uint8Array>,
 ): AsyncGenerator<Uint8Array> {
   try {
-    for await (const chunk of toAsyncIterable(input)) {
-      yield frameData(chunk);
+    for (;;) {
+      const next = await iterator.next();
+      if (next.done === true) return;
+      yield frameData(normalizeChunk(next.value));
     }
   } catch (err) {
     const e = err instanceof Error ? err : new Error(String(err));
     yield frameError(e);
+  } finally {
+    // PROPAGATE CANCELLATION TO THE PRODUCER, and do not wait for it.
+    //
+    // `for await (… of input)` used to do this implicitly: returning this
+    // generator ran the loop's cleanup, which returned the producer. Driving
+    // the iterator by hand (needed so teardown can hold a handle on the
+    // producer) removes that, and removing it silently stopped a server-side
+    // handler from ever being told its caller had gone — a regression caught
+    // by `cancel-server-handler.test.ts`.
+    //
+    // Not awaited: `.return()` on a producer parked at an `await` is queued
+    // behind it, so awaiting here would reintroduce the very hang this file's
+    // teardown was fixed to avoid.
+    void Promise.resolve((iterator as AsyncIterator<Uint8Array>).return?.(undefined)).catch(
+      () => undefined,
+    );
   }
 }
 
@@ -269,7 +356,8 @@ async function* parseFrames(
     }
     while (buf.byteLength > 0) {
       if (buf.byteLength < 2) break; // need at least type + 1 varint byte
-      const type = buf[0]!; // buf.byteLength >= 2, checked above, so index 0 exists
+      // biome-ignore lint/style/noNonNullAssertion: buf.byteLength >= 2, checked above, so index 0 exists.
+      const type = buf[0]!;
       let lenInfo: { value: number; offset: number };
       try {
         lenInfo = decodeVarint(buf, 1);
@@ -341,7 +429,8 @@ function decodeVarint(buf: Uint8Array, start: number): { value: number; offset:
   let shift = 0;
   let i = start;
   while (i < buf.length) {
-    const b = buf[i++]!; // i < buf.length, checked by the while condition, so this index exists
+    // biome-ignore lint/style/noNonNullAssertion: i < buf.length, checked by the while condition, so this index exists.
+    const b = buf[i++]!;
     value |= (b & 0x7f) << shift;
     if ((b & 0x80) === 0) return { value: value >>> 0, offset: i };
     shift += 7;
@@ -349,19 +438,3 @@ function decodeVarint(buf: Uint8Array, start: number): { value: number; offset:
   }
   throw new Error("decodeVarint: truncated");
 }
-
-function toAsyncIterable(
-  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
-): AsyncIterable<Uint8Array> {
-  if ((input as AsyncIterable<Uint8Array>)[Symbol.asyncIterator]) {
-    return input as AsyncIterable<Uint8Array>;
-  }
-  const it = (input as Iterable<Uint8Array>)[Symbol.iterator]();
-  return {
-    [Symbol.asyncIterator]() {
-      return {
-        next: () => Promise.resolve(it.next()),
-      };
-    },
-  };
-}

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   serveConnections,
 } from "./connect-serve.js";
 export {
+  DEFAULT_CLOSE_TIMEOUT_MS,
   DEFAULT_DRAIN_TIMEOUT_MS,
   type DuplexOverStreamOptions,
   duplexOverStream,