@statewalker/webrun-streams-libp2p 0.1.8 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,7 +16,7 @@ libp2p solves transport negotiation, NAT traversal, relaying and authenticated
16
16
  peer identity. What it gives an application is a `Stream`, not a request. This
17
17
  adapter binds a stream to the `Duplex` shape, so a handler written once runs
18
18
  over libp2p as it does over any other adapter. Because libp2p multiplexes
19
- natively, there is no `emulateMux`: one call is one real libp2p stream.
19
+ natively, there is no multiplexer on top: one call is one real libp2p stream.
20
20
 
21
21
  What the adapter adds on top of a raw stream:
22
22
 
@@ -55,9 +55,14 @@ runs (Node or browser).
55
55
  | `serve(params, handler)` | `Serve<ServeLibp2pParams>`. `node.handle(protocol)`; runs `handler` per inbound stream. Resolves to an idempotent teardown that calls `node.unhandle(protocol)`. |
56
56
  | `serveConnections(params, makeHandler)` | Like `serve`, but `makeHandler(context)` is called once per inbound stream with `{ remotePeer }`, and returns that stream's `Duplex`. |
57
57
  | `duplexOverStream(stream, input, options?)` | The primitive under both: runs one call over one libp2p `Stream`. Returns an `AsyncGenerator<Uint8Array>` of the peer's bytes. |
58
+ | `PeerGoneError` | What a call fails with when the stream ended before both sides finished it: the peer died, the connection dropped, or the stream was reset after the peer's side ended. `cause` is libp2p's close error, if any. |
59
+ | `messageTargetOverStream(stream, options?)` | `{ target, signal }`: one stream as a pipe of `Uint8Array` messages for `multiplexPort` / `overPipe`, and an `AbortSignal` that aborts when the stream is over. `options.maxMessageBytes` caps one message. See below. |
60
+ | `libp2pPortMux(options)` | Native MessagePorts: a `webrun-rpc` `PortMux` (by shape) whose every port is its own libp2p stream, for `overPorts`. `options`: `node`, `codec` (a value codec: `{ encode: serialize, decode: deserialize }` from `webrun-msgpack`), `peer` (to open ports), `onPort(port, { remotePeer, connection })` (to accept them), `protocol`, `maxMessageSize`, stream limits. See "MessagePorts over libp2p" below. |
61
+ | `DEFAULT_PORT_PROTOCOL`, `DEFAULT_PORT_MAX_MESSAGE_SIZE` | `"/webrun-ports/1.0.0"`, 256 KiB. |
58
62
  | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
59
63
  | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes). |
60
64
  | `DEFAULT_CLOSE_TIMEOUT_MS` | `300_000` (5 minutes), the bound on a graceful close. |
65
+ | `DEFAULT_MAX_MESSAGE_BYTES` | `67_108_864` (64 MiB), `messageTargetOverStream`'s cap on one message. |
61
66
  | `ConnectLibp2pParams`, `ServeLibp2pParams`, `ConnectionContext`, `ServeConnectionsHandler`, `DuplexOverStreamOptions` | Types, below. |
62
67
 
63
68
  `ConnectLibp2pParams`:
@@ -246,6 +251,21 @@ streams and that an unconfigured server stops at 32.
246
251
 
247
252
  - **Normal end.** Both sides finished: the stream is closed gracefully,
248
253
  bounded by the close timeout.
254
+ - **The peer dies** (its process is killed, the network drops, the connection
255
+ is aborted). The call's output throws `PeerGoneError`, `webrun-streams-libp2p:
256
+ the stream ended before the call finished`, within milliseconds of libp2p
257
+ noticing, whether or not the caller's input is still open. It never ends
258
+ cleanly: a clean end requires the peer's own close-write
259
+ (`remoteCloseWrite`), because when a connection dies libp2p closes the
260
+ stream with no error and its iterator ends exactly as after a close-write.
261
+ Without that rule a truncated response reads as a complete one. A peer
262
+ that ended its side and then died while this side was still sending fails
263
+ the same way; the input is returned instead of waited on. A peer that
264
+ resets the stream before ending its side throws libp2p's `StreamResetError`;
265
+ one that resets it after (a tunnel whose far end gave up) throws
266
+ `PeerGoneError` with the `StreamResetError` as `cause`. Either way the
267
+ error says the call is incomplete — `PeerGoneError` does not prove the
268
+ peer died, only that the stream ended before both sides finished it.
249
269
  - **Caller cancels** (`.return()` on the call's generator). The adapter aborts
250
270
  the stream with `call cancelled` before the generator's own cleanup runs,
251
271
  because by then the stream is already marked closed and `abort` would do
@@ -262,6 +282,94 @@ streams and that an unconfigured server stops at 32.
262
282
  `[webrun-streams-libp2p] serve: inbound stream on protocol <p> failed: <message>`,
263
283
  so one failed stream never becomes an unhandled rejection that terminates
264
284
  the serving process. The handler's output is returned, so its `finally` runs.
285
+ A caller that sent its whole request and then stopped reading the response
286
+ (`.return()` mid-stream) is ordinary and is not logged.
287
+
288
+ ### MessagePorts over libp2p, and the port stack on them
289
+
290
+ `connect` / `serve` above stream each call's bytes straight onto a libp2p
291
+ stream, and so inherit libp2p's buffering: a consumer that stops reading does
292
+ not slow its producer (see Tests, L6). `webrun-rpc`'s port stack does: each
293
+ call's chunk waits for the peer's confirmation that its consumer pulled the
294
+ last one, so a producer is never more than a chunk ahead, whatever the
295
+ transport buffers underneath. Two ways to put libp2p under it:
296
+
297
+ ```ts
298
+ import { deserialize, msgpackCodec, serialize } from "@statewalker/webrun-msgpack";
299
+ import { connect, overPipe, overPorts, serve } from "@statewalker/webrun-rpc";
300
+ import { libp2pPortMux, messageTargetOverStream } from "@statewalker/webrun-streams-libp2p";
301
+
302
+ // 1. native ports: one libp2p stream per port, multiplexed by yamux
303
+ const codec = { encode: serialize, decode: deserialize };
304
+ await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, codec, onPort })) }, handler);
305
+ const { call } = await connect({ mux: overPorts(() => libp2pPortMux({ node, codec, peer })) });
306
+
307
+ // 2. emulated ports: one libp2p stream, multiplexPort inventing the ports on it
308
+ const { target, signal } = messageTargetOverStream(await node.dialProtocol(peer, ["/my-mux/1.0.0"]));
309
+ const pipe = await connect({ mux: overPipe(target, { codec: msgpackCodec, side: "initiator", signal }) });
310
+ ```
311
+
312
+ Both pass the shared conformance suite, including L6 at a one-chunk bound
313
+ (`tests/port-mux.test.ts`). Which to use:
314
+
315
+ | | native (`libp2pPortMux`) | emulated (`overPipe` on one stream) |
316
+ | --- | --- | --- |
317
+ | multiplexing | yamux: per-stream windows, scheduling | `multiplexPort`'s id table |
318
+ | a call costs | a stream open (a protocol negotiation) | nothing on the wire |
319
+ | limits | a stream per concurrent call: `maxInboundStreams` / `maxOutboundStreams`, 1024 by default here (libp2p's own default, 32, would reset the 33rd call) | `maxPorts` |
320
+ | one slow call | holds its own stream only | shares the stream; `frameSize` interleaves |
321
+ | who is calling | `onPort` gets `{ remotePeer, connection }` | the stream's connection, once |
322
+ | 4 MiB echo, in-process TCP, setup excluded (three runs) | 35–38 MiB/s (64 KiB chunks), 71–88 MiB/s (256 KiB) | 37–48 MiB/s, 79–87 MiB/s |
323
+
324
+ Each native port carries `closeSignal`, aborted when its stream ends, the peer
325
+ goes, or the port is closed here; `webrun-rpc`'s `getPortCloseSignal` reads it
326
+ from the port, so a call on a dead stream fails instead of waiting, and this
327
+ package still imports nothing from `webrun-rpc`. Ports are opened through the
328
+ same early-stream gate as `connect()`. A port `onPort` refuses (returns
329
+ `false`) is aborted: the opener's signal aborts with `PeerGoneError` and a call
330
+ on it fails. A frame the port's codec cannot decode (a peer speaking another
331
+ codec) aborts the port rather than vanish. `meta` is not sent: the
332
+ protocol says what a port is for. Messages are values (objects holding
333
+ `Uint8Array` chunks), so a port needs a value codec where `overPipe` needs a
334
+ `PortCodec`.
335
+
336
+ ### A multiplexer over one stream closes with it
337
+
338
+ `multiplexPort` (from `@statewalker/webrun-rpc`) can run many ports over one
339
+ stream. A multiplexer cannot see its pipe die, so wire the stream's life to it:
340
+
341
+ ```ts
342
+ import { msgpackCodec } from "@statewalker/webrun-msgpack";
343
+ import { multiplexPort } from "@statewalker/webrun-rpc";
344
+ import { messageTargetOverStream } from "@statewalker/webrun-streams-libp2p";
345
+
346
+ const { target, signal } = messageTargetOverStream(await node.dialProtocol(peer, ["/my-mux/1.0.0"]));
347
+ const mux = multiplexPort(target, { codec: msgpackCodec, side: "initiator", signal });
348
+ ```
349
+
350
+ `signal` aborts on the stream's `close` (with `PeerGoneError` when the
351
+ connection died) and on the peer's close-write — after the read loop has
352
+ delivered every message the peer sent before it, so a reply followed by a
353
+ close is not lost to a multiplexer that tears down on `signal`. Unwired, every port and every
354
+ call on a dead stream waits forever. Wired, 100 ports on a SIGKILLed peer all
355
+ close within the test's 1 s bound. A stream closes when its connection does,
356
+ so this also covers a peer that dies while no data is flowing.
357
+
358
+ Frames are `[varint length][bytes]`. Reading starts at once, so attach the
359
+ `message` listener in the same tick (`multiplexPort` does). `postMessage`
360
+ does not wait for room, and libp2p resets a stream whose write buffer passes
361
+ `maxWriteBufferLength`. The target reports its state instead:
362
+ `bufferedAmount` is the stream's write buffer, and `whenDrained()` resolves
363
+ on libp2p's `drain` (or the stream's `close`, so no sender is left waiting),
364
+ at once when the stream has room. A sender that must not overrun the buffer
365
+ awaits it before posting more.
366
+
367
+ A length prefix that is not a valid varint, or one past `maxMessageBytes`
368
+ (default `DEFAULT_MAX_MESSAGE_BYTES`, 64 MiB), aborts the stream and `signal`
369
+ with `webrun-streams-libp2p: a malformed message length` or `… exceeds
370
+ maxMessageBytes`: a peer not speaking this framing would otherwise make the
371
+ reader buffer without bound. Raise it with
372
+ `messageTargetOverStream(stream, { maxMessageBytes })` for larger messages.
265
373
 
266
374
  ### Constraints
267
375
 
@@ -275,10 +383,79 @@ streams and that an unconfigured server stops at 32.
275
383
 
276
384
  `pnpm test` runs the backpressure, drain and close timeout, cancellation,
277
385
  identity, burst, stream-limit and serving-resilience tests against two real
278
- in-process TCP nodes. The shared conformance suite is opt-in because it spins
386
+ in-process TCP nodes. `dead-peer.test.ts` kills the peer two ways, aborting
387
+ its connection in-process and SIGKILLing a forked server
388
+ (`tests/fixtures/greeting-server.ts`, run with `tsx`), with 100 open channels
389
+ each; every channel must fail with an error within 1 s. The shared conformance suite is opt-in because it spins
279
390
  up more nodes: `WEBRUN_STREAMS_LIBP2P=1 pnpm test`. It runs with
280
- `skipHugeBody`, and L6's small window does not apply (there is no
281
- `emulateMux`), so L6 is an integrity check.
391
+ `skipHugeBody`.
392
+
393
+ **Run-ahead is bounded for `connect` / `serve`** (spec D17, L6;
394
+ `tests/run-ahead.test.ts`, always on). L6 first found none: a consumer that
395
+ stopped reading let the producer run 22-24 MiB ahead until libp2p's 4 MiB read
396
+ buffer killed the stream. Two things buffered without limit:
397
+
398
+ - **libp2p's stream iterator** moves every message into an unbounded queue as
399
+ it arrives, and **yamux grants its peer receive window on arrival**, not on
400
+ consumption. The inbound side now reads through its own queue: past
401
+ `readHighWaterBytes` (default 64 KiB) the stream is paused, which makes yamux
402
+ withhold window updates, and it is resumed once the consumer has read half.
403
+ - **`serve` pushed every request chunk to the handler's input queue** without
404
+ waiting. Past the same 64 KiB it now waits until the handler has read the
405
+ queue back down. Once the handler's output has ended, input it never started
406
+ to read is dropped instead of waited for; input it is reading (a background
407
+ reader, say) keeps flowing at its pace. A handler that keeps its input
408
+ iterator, stops reading it and keeps producing output now makes the caller's
409
+ sends wait, and after `drainTimeoutMs` (5 minutes) abort the stream, where
410
+ the input used to be buffered without limit.
411
+
412
+ The bound is then **two receive windows plus those queues**: a resume hands
413
+ over what libp2p held while paused (up to the window granted before the
414
+ pause) as one message, and the muxer grants a new window. Measured with a
415
+ 1 MiB window: 1.06 MiB when the consumer stalls at once, 2.00 MiB when it
416
+ reads and stalls by turns; with yamux's default (16 MiB) up to 32 MiB per
417
+ stalled stream. Cap the window on nodes that serve or call with large
418
+ bodies: `yamux({ streamOptions: { maxStreamWindowSize: 1024 * 1024 } })` (the
419
+ option sits under `streamOptions`; set at the top level it is ignored, which is
420
+ why an earlier attempt to cap it "did not bound it"). yamux's default window
421
+ exceeds libp2p's default read buffer, so a paused stream raises its
422
+ `maxReadBufferLength` to the window plus the high-water mark rather than be
423
+ killed for buffering what it was allowed to receive. The pause is used only
424
+ where the muxer exposes its window (yamux's `maxStreamWindowSize`): on a
425
+ stream whose muxer does not withhold window when paused, pausing would only
426
+ move the data into libp2p's read buffer and get the stream aborted, so such a
427
+ stream is read as before, without a bound.
428
+
429
+ Review of #112 found, and tests now cover: a pause issued from inside
430
+ `resume()` (whose synchronous dispatch can refill the queue) was undone by the
431
+ muxer's own resume that follows it, leaving libp2p paused while yamux granted
432
+ window for every frame — run-ahead grew until the stream was aborted, with a
433
+ consumer that reads and stalls by turns; the message a resume dispatches (up
434
+ to a window) is now queued in high-water-sized pieces, so a frame parser
435
+ holding it does not hold a window outside the count; and a handler reading its
436
+ input after its output ended was cut off.
437
+
438
+ One-way throughput is unchanged (64 MiB over in-process TCP, 64 KiB chunks: up
439
+ 105-113, down 129-163 MiB/s before and after; 256 KiB chunks: 156-179 /
440
+ 184-219). An echo of 64 KiB chunks is slower (about 45 vs 65 MiB/s): it
441
+ profited from the server reading the whole request ahead, which is the
442
+ buffering removed. The port stack over libp2p (native or emulated ports,
443
+ above) stays bounded at one chunk.
444
+
445
+ Mutants, each killed by `tests/run-ahead.test.ts`: the reader never pauses (L6
446
+ past the bound), never resumes (the stalled transfer never completes), no
447
+ read-buffer raise (yamux's default window: the stream is aborted), `serve` not
448
+ waiting on the handler's queue (L6 request), no drop once the handler's output
449
+ ended (a handler that never reads its input hangs the call), a pause inside
450
+ `resume()` (reads and stalls by turns: aborted), the resumed message not split
451
+ (2.94 MiB past a 1 MiB window), input dropped although its reader started (a
452
+ background reader cut off). Not covered by a test: the pause skipped for a
453
+ muxer without a window (no such muxer in the test nodes).
454
+
455
+ `messageTargetOverStream` (review of the port work) now also aborts its
456
+ `signal` for a stream that ended before the target was attached: a peer that
457
+ reset the stream during protocol negotiation left its `close` event unseen and
458
+ the signal never aborted.
282
459
 
283
460
  ### Dependencies
284
461
 
@@ -287,7 +464,8 @@ up more nodes: `WEBRUN_STREAMS_LIBP2P=1 pnpm test`. It runs with
287
464
  - `@libp2p/interface`, `@multiformats/multiaddr` (peers, types only) and
288
465
  `libp2p` (optional peer). Dev dependencies `@chainsafe/libp2p-noise`,
289
466
  `@chainsafe/libp2p-yamux`, `@libp2p/tcp` and `@libp2p/utils` build the test
290
- nodes.
467
+ nodes; `@statewalker/webrun-rpc` and `@statewalker/webrun-msgpack` run the
468
+ multiplexer tests, and `tsx` runs the forked server.
291
469
 
292
470
  ## License
293
471
 
@@ -12,6 +12,11 @@ export interface ConnectLibp2pParams {
12
12
  * peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes).
13
13
  */
14
14
  drainTimeoutMs?: number;
15
+ /**
16
+ * Response bytes held while the caller is not reading before the stream is
17
+ * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
18
+ */
19
+ readHighWaterBytes?: number;
15
20
  /**
16
21
  * How many outgoing streams for this protocol libp2p allows to be open at
17
22
  * the same time on one connection; passed through to `node.dialProtocol`.
@@ -38,6 +43,11 @@ export interface ServeLibp2pParams {
38
43
  * closing, since the caller-side `.return`/abort escape does not exist here.
39
44
  */
40
45
  drainTimeoutMs?: number;
46
+ /**
47
+ * Request bytes held while the handler is not reading before the stream is
48
+ * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
49
+ */
50
+ readHighWaterBytes?: number;
41
51
  /**
42
52
  * How many incoming streams for this protocol libp2p allows to be open at
43
53
  * the same time on one connection; passed through to `node.handle`. Left
@@ -62,6 +72,10 @@ export interface ServeLibp2pParams {
62
72
  */
63
73
  runOnLimitedConnection?: boolean;
64
74
  }
75
+ /**
76
+ * Caller-side: each `call(input)` opens a new libp2p `Stream` via
77
+ * `node.dialProtocol(peer, [protocol])` and runs the call over it.
78
+ */
65
79
  export declare const connect: Connect<ConnectLibp2pParams>;
66
80
  /**
67
81
  * Server-side: registers `node.handle(protocol, ...)`. Each inbound stream is
@@ -88,5 +102,5 @@ export type ServeConnectionsHandler = (context: ConnectionContext) => Duplex;
88
102
  * Like `serve`, but the handler is built per inbound stream and is told which
89
103
  * peer libp2p proved on that connection.
90
104
  */
91
- export declare function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection, }: ServeLibp2pParams, makeHandler: ServeConnectionsHandler): Promise<() => Promise<void>>;
105
+ export declare function serveConnections({ node, protocol, drainTimeoutMs, readHighWaterBytes, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection, }: ServeLibp2pParams, makeHandler: ServeConnectionsHandler): Promise<() => Promise<void>>;
92
106
  //# sourceMappingURL=connect-serve.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,MAAM,EACN,MAAM,EAGP,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAG1E,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAsED,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,mBAAmB,CA2GhD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,iBAAiB,CACF,CAAC;AAE1C,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,CAAC;AAE7E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,EACE,IAAI,EACJ,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,EAAE,iBAAiB,EACpB,WAAW,EAAE,uBAAuB,GACnC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAiD9B"}
1
+ {"version":3,"file":"connect-serve.d.ts","sourceRoot":"","sources":["../src/connect-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,MAAM,EACN,MAAM,EAGP,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAS1E,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAqBD;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,mBAAmB,CA4FhD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,iBAAiB,CACF,CAAC;AAE1C,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,CAAC;AAE7E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,EACE,IAAI,EACJ,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,EAAE,iBAAiB,EACpB,WAAW,EAAE,uBAAuB,GACnC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA+D9B"}
@@ -45,6 +45,20 @@ export declare const DEFAULT_DRAIN_TIMEOUT_MS = 300000;
45
45
  * Exported so a deployment that knows its links can lower it deliberately.
46
46
  */
47
47
  export declare const DEFAULT_CLOSE_TIMEOUT_MS = 300000;
48
+ /**
49
+ * Default for {@link DuplexOverStreamOptions.readHighWaterBytes}: received bytes
50
+ * held for a consumer that is not reading before the stream is paused.
51
+ */
52
+ export declare const DEFAULT_READ_HIGH_WATER_BYTES: number;
53
+ /**
54
+ * The stream ended before the call finished: the peer died, the connection
55
+ * dropped, or the stream was reset or refused before both sides ended it.
56
+ * Distinct from a clean end on purpose — a response cut short must never read
57
+ * as a complete one. `cause` is the stream's close error, when libp2p gave one.
58
+ */
59
+ export declare class PeerGoneError extends Error {
60
+ constructor(cause?: unknown);
61
+ }
48
62
  /**
49
63
  * Options for {@link duplexOverStream}. The `onPeerInputEnd` hook is the seam
50
64
  * that lets the server side close its input queue as soon as the peer's source
@@ -70,6 +84,18 @@ export interface DuplexOverStreamOptions {
70
84
  * the peer. Defaults to {@link DEFAULT_DRAIN_TIMEOUT_MS}.
71
85
  */
72
86
  drainTimeoutMs?: number;
87
+ /**
88
+ * Received bytes held for a consumer that is not reading before the stream
89
+ * is paused (and resumed once half of them are read). A paused yamux stream
90
+ * stops granting its peer receive window, so the peer's `send()` reports a
91
+ * full buffer and its producer waits: run-ahead is bounded by two receive
92
+ * windows (what libp2p held while paused, and the window granted on resume)
93
+ * plus this — the receiving node's yamux `streamOptions.maxStreamWindowSize`,
94
+ * 16 MiB by default; 1 MiB bounds it at about 2.25 MiB with no loss of
95
+ * one-way throughput measured. Only where the muxer exposes its window.
96
+ * Defaults to {@link DEFAULT_READ_HIGH_WATER_BYTES}.
97
+ */
98
+ readHighWaterBytes?: number;
73
99
  }
74
100
  /**
75
101
  * Drive one `Duplex` over one libp2p `Stream` using a small in-band framing
@@ -94,4 +120,10 @@ export declare function duplexOverStream(stream: Stream, input: AsyncIterable<Ui
94
120
  * caller is never left hanging.
95
121
  */
96
122
  export declare function closeStream(stream: Stream, timeoutMs?: number): Promise<void>;
123
+ export declare function normalizeChunk(item: unknown): Uint8Array;
124
+ export declare function encodeVarint(value: number): Uint8Array;
125
+ export declare function decodeVarint(buf: Uint8Array, start: number): {
126
+ value: number;
127
+ offset: number;
128
+ };
97
129
  //# sourceMappingURL=duplex-over-stream.d.ts.map
@@ -1 +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;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"}
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;AAMlE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,wBAAwB,SAA2B,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,6BAA6B,QAAY,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,KAAK,CAAC,EAAE,OAAO,EAQ1B;CACF;AAKD;;;;;;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;IACxB;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;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,CAkL5B;AA2CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAsBf;AAgMD,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAOxD;AA8BD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAYtD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAa9F"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
1
  export { type ConnectionContext, type ConnectLibp2pParams, connect, DEFAULT_PROTOCOL, type ServeConnectionsHandler, type ServeLibp2pParams, serve, serveConnections, } from "./connect-serve.js";
2
- export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, type DuplexOverStreamOptions, duplexOverStream, } from "./duplex-over-stream.js";
2
+ export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, type DuplexOverStreamOptions, duplexOverStream, PeerGoneError, } from "./duplex-over-stream.js";
3
+ export { DEFAULT_MAX_MESSAGE_BYTES, type MessageTargetOverStreamOptions, messageTargetOverStream, type StreamMessageTarget, } from "./message-target-over-stream.js";
4
+ export { DEFAULT_PORT_MAX_MESSAGE_SIZE, DEFAULT_PORT_PROTOCOL, DEFAULT_PORT_STREAM_LIMIT, type InboundPortInfo, type Libp2pPortMux, type Libp2pPortMuxOptions, libp2pPortMux, type StreamPort, type ValueCodec, } from "./port-mux.js";
3
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +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,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,gBAAgB,GACjB,MAAM,yBAAyB,CAAC"}
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,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,gBAAgB,EAChB,aAAa,GACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,yBAAyB,EACzB,KAAK,8BAA8B,EACnC,uBAAuB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC"}