@statewalker/webrun-streams-libp2p 0.2.0 → 0.4.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
 
@@ -57,10 +57,13 @@ runs (Node or browser).
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
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
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. |
60
62
  | `DEFAULT_PROTOCOL` | `"/webrun-streams/1.0.0"`. |
61
63
  | `DEFAULT_DRAIN_TIMEOUT_MS` | `300_000` (5 minutes). |
62
64
  | `DEFAULT_CLOSE_TIMEOUT_MS` | `300_000` (5 minutes), the bound on a graceful close. |
63
65
  | `DEFAULT_MAX_MESSAGE_BYTES` | `67_108_864` (64 MiB), `messageTargetOverStream`'s cap on one message. |
66
+ | `DEFAULT_MAX_FRAME_BYTES` | `67_108_864` (64 MiB), `duplexOverStream`'s default cap on one inbound frame's payload (`maxFrameBytes`). |
64
67
  | `ConnectLibp2pParams`, `ServeLibp2pParams`, `ConnectionContext`, `ServeConnectionsHandler`, `DuplexOverStreamOptions` | Types, below. |
65
68
 
66
69
  `ConnectLibp2pParams`:
@@ -71,10 +74,11 @@ runs (Node or browser).
71
74
  | `peer` | `PeerId \| Multiaddr` | required | Who to dial. |
72
75
  | `protocol` | `string` | `DEFAULT_PROTOCOL` | Protocol id. |
73
76
  | `drainTimeoutMs` | `number` | `300_000` | How long a backpressured send waits for `'drain'`. |
77
+ | `maxFrameBytes` | `number` | `DEFAULT_MAX_FRAME_BYTES` | The largest frame payload accepted from the peer. Past it, or on a malformed frame length, the call fails and the stream is aborted. |
74
78
  | `maxOutboundStreams` | `number` | libp2p's (64) | Passed to `dialProtocol`. |
75
79
  | `runOnLimitedConnection` | `boolean` | unset | Passed to `dialProtocol`. Allows relayed or otherwise limited connections. |
76
80
 
77
- `ServeLibp2pParams`: `node`, `protocol`, `drainTimeoutMs`,
81
+ `ServeLibp2pParams`: `node`, `protocol`, `drainTimeoutMs`, `maxFrameBytes`,
78
82
  `maxOutboundStreams` and `runOnLimitedConnection` as above (passed to
79
83
  `node.handle`), plus `maxInboundStreams` (libp2p default 32).
80
84
 
@@ -88,6 +92,7 @@ runs (Node or browser).
88
92
  | `onPeerInputEnd?(err?)` | Called once when the peer's side ends: closed, `ERROR` frame (passed as `err`) or torn down. `serveConnections` uses it to end the handler's input. |
89
93
  | `onSourceCompleted?()` | Called only when the peer's side ended normally. `connect` uses it to choose a graceful close over an abort. |
90
94
  | `drainTimeoutMs?` | As above. |
95
+ | `maxFrameBytes?` | As above. |
91
96
 
92
97
  ## Examples
93
98
 
@@ -173,6 +178,18 @@ from whatever chunks arrive. Normal end of input is libp2p's own
173
178
  reset carries only "stream reset"; without it, a handler that throws would
174
179
  reach the caller as an anonymous reset. Frames of other types are skipped.
175
180
 
181
+ A producer chunk larger than 64 KiB is sent as several `DATA` frames of at most
182
+ 64 KiB each. Frames are self-delimiting and a receiver yields each `DATA`
183
+ payload as it completes, so a receiver of any version reassembles the same
184
+ bytes; only the chunk boundaries the consumer sees change. The receiver keeps
185
+ unread bytes in a buffer that grows by doubling, so a large frame arriving in
186
+ many pieces is copied a bounded number of times. A frame length past
187
+ `maxFrameBytes` (default 64 MiB), or one that is not a valid varint, fails the
188
+ call with `webrun-streams-libp2p: a <n>-byte frame exceeds maxFrameBytes (<cap>)`
189
+ or `webrun-streams-libp2p: a malformed frame length`, and aborts the stream:
190
+ a peer not speaking this framing would otherwise make the receiver buffer
191
+ without bound. On the serving side the handler's input throws that error.
192
+
176
193
  ### Why identity reaches the handler by closure
177
194
 
178
195
  `Duplex` is bytes-only, so `serveConnections` passes identity to a factory
@@ -283,6 +300,54 @@ streams and that an unconfigured server stops at 32.
283
300
  A caller that sent its whole request and then stopped reading the response
284
301
  (`.return()` mid-stream) is ordinary and is not logged.
285
302
 
303
+ ### MessagePorts over libp2p, and the port stack on them
304
+
305
+ `connect` / `serve` above stream each call's bytes straight onto a libp2p
306
+ stream, and so inherit libp2p's buffering: a consumer that stops reading does
307
+ not slow its producer (see Tests, L6). `webrun-rpc`'s port stack does: each
308
+ call's chunk waits for the peer's confirmation that its consumer pulled the
309
+ last one, so a producer is never more than a chunk ahead, whatever the
310
+ transport buffers underneath. Two ways to put libp2p under it:
311
+
312
+ ```ts
313
+ import { deserialize, msgpackCodec, serialize } from "@statewalker/webrun-msgpack";
314
+ import { connect, overPipe, overPorts, serve } from "@statewalker/webrun-rpc";
315
+ import { libp2pPortMux, messageTargetOverStream } from "@statewalker/webrun-streams-libp2p";
316
+
317
+ // 1. native ports: one libp2p stream per port, multiplexed by yamux
318
+ const codec = { encode: serialize, decode: deserialize };
319
+ await serve({ mux: overPorts((onPort) => libp2pPortMux({ node, codec, onPort })) }, handler);
320
+ const { call } = await connect({ mux: overPorts(() => libp2pPortMux({ node, codec, peer })) });
321
+
322
+ // 2. emulated ports: one libp2p stream, multiplexPort inventing the ports on it
323
+ const { target, signal } = messageTargetOverStream(await node.dialProtocol(peer, ["/my-mux/1.0.0"]));
324
+ const pipe = await connect({ mux: overPipe(target, { codec: msgpackCodec, side: "initiator", signal }) });
325
+ ```
326
+
327
+ Both pass the shared conformance suite, including L6 at a one-chunk bound
328
+ (`tests/port-mux.test.ts`). Which to use:
329
+
330
+ | | native (`libp2pPortMux`) | emulated (`overPipe` on one stream) |
331
+ | --- | --- | --- |
332
+ | multiplexing | yamux: per-stream windows, scheduling | `multiplexPort`'s id table |
333
+ | a call costs | a stream open (a protocol negotiation) | nothing on the wire |
334
+ | limits | a stream per concurrent call: `maxInboundStreams` / `maxOutboundStreams`, 1024 by default here (libp2p's own default, 32, would reset the 33rd call) | `maxPorts` |
335
+ | one slow call | holds its own stream only | shares the stream; `frameSize` interleaves |
336
+ | who is calling | `onPort` gets `{ remotePeer, connection }` | the stream's connection, once |
337
+ | 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 |
338
+
339
+ Each native port carries `closeSignal`, aborted when its stream ends, the peer
340
+ goes, or the port is closed here; `webrun-rpc`'s `getPortCloseSignal` reads it
341
+ from the port, so a call on a dead stream fails instead of waiting, and this
342
+ package still imports nothing from `webrun-rpc`. Ports are opened through the
343
+ same early-stream gate as `connect()`. A port `onPort` refuses (returns
344
+ `false`) is aborted: the opener's signal aborts with `PeerGoneError` and a call
345
+ on it fails. A frame the port's codec cannot decode (a peer speaking another
346
+ codec) aborts the port rather than vanish. `meta` is not sent: the
347
+ protocol says what a port is for. Messages are values (objects holding
348
+ `Uint8Array` chunks), so a port needs a value codec where `overPipe` needs a
349
+ `PortCodec`.
350
+
286
351
  ### A multiplexer over one stream closes with it
287
352
 
288
353
  `multiplexPort` (from `@statewalker/webrun-rpc`) can run many ports over one
@@ -307,7 +372,9 @@ so this also covers a peer that dies while no data is flowing.
307
372
 
308
373
  Frames are `[varint length][bytes]`. Reading starts at once, so attach the
309
374
  `message` listener in the same tick (`multiplexPort` does). `postMessage`
310
- does not wait for room, and libp2p resets a stream whose write buffer passes
375
+ takes a `Uint8Array`, an `ArrayBuffer` or another view, and throws `TypeError`
376
+ for anything else, as the other adapters' byte pipes do. It does not wait for
377
+ room, and libp2p resets a stream whose write buffer passes
311
378
  `maxWriteBufferLength`. The target reports its state instead:
312
379
  `bufferedAmount` is the stream's write buffer, and `whenDrained()` resolves
313
380
  on libp2p's `drain` (or the stream's `close`, so no sender is left waiting),
@@ -336,10 +403,76 @@ identity, burst, stream-limit and serving-resilience tests against two real
336
403
  in-process TCP nodes. `dead-peer.test.ts` kills the peer two ways, aborting
337
404
  its connection in-process and SIGKILLing a forked server
338
405
  (`tests/fixtures/greeting-server.ts`, run with `tsx`), with 100 open channels
339
- each; every channel must fail with an error within 1 s. The shared conformance suite is opt-in because it spins
340
- up more nodes: `WEBRUN_STREAMS_LIBP2P=1 pnpm test`. It runs with
341
- `skipHugeBody`, and L6's small window does not apply (there is no
342
- `emulateMux`), so L6 is an integrity check.
406
+ each; every channel must fail with an error within 1 s. The shared conformance
407
+ suite (`tests/conformance.test.ts`, about 7 s) runs in the same `pnpm test`, with
408
+ `skipHugeBody`.
409
+
410
+ **Run-ahead is bounded for `connect` / `serve`** (spec D17, L6;
411
+ `tests/run-ahead.test.ts`, always on). L6 first found none: a consumer that
412
+ stopped reading let the producer run 22-24 MiB ahead until libp2p's 4 MiB read
413
+ buffer killed the stream. Two things buffered without limit:
414
+
415
+ - **libp2p's stream iterator** moves every message into an unbounded queue as
416
+ it arrives, and **yamux grants its peer receive window on arrival**, not on
417
+ consumption. The inbound side now reads through its own queue: past
418
+ `readHighWaterBytes` (default 64 KiB) the stream is paused, which makes yamux
419
+ withhold window updates, and it is resumed once the consumer has read half.
420
+ - **`serve` pushed every request chunk to the handler's input queue** without
421
+ waiting. Past the same 64 KiB it now waits until the handler has read the
422
+ queue back down. Once the handler's output has ended, input it never started
423
+ to read is dropped instead of waited for; input it is reading (a background
424
+ reader, say) keeps flowing at its pace. A handler that keeps its input
425
+ iterator, stops reading it and keeps producing output now makes the caller's
426
+ sends wait, and after `drainTimeoutMs` (5 minutes) abort the stream, where
427
+ the input used to be buffered without limit.
428
+
429
+ The bound is then **two receive windows plus those queues**: a resume hands
430
+ over what libp2p held while paused (up to the window granted before the
431
+ pause) as one message, and the muxer grants a new window. Measured with a
432
+ 1 MiB window: 1.06 MiB when the consumer stalls at once, 2.00 MiB when it
433
+ reads and stalls by turns; with yamux's default (16 MiB) up to 32 MiB per
434
+ stalled stream. Cap the window on nodes that serve or call with large
435
+ bodies: `yamux({ streamOptions: { maxStreamWindowSize: 1024 * 1024 } })` (the
436
+ option sits under `streamOptions`; set at the top level it is ignored, which is
437
+ why an earlier attempt to cap it "did not bound it"). yamux's default window
438
+ exceeds libp2p's default read buffer, so a paused stream raises its
439
+ `maxReadBufferLength` to the window plus the high-water mark rather than be
440
+ killed for buffering what it was allowed to receive. The pause is used only
441
+ where the muxer exposes its window (yamux's `maxStreamWindowSize`): on a
442
+ stream whose muxer does not withhold window when paused, pausing would only
443
+ move the data into libp2p's read buffer and get the stream aborted, so such a
444
+ stream is read as before, without a bound.
445
+
446
+ Review of #112 found, and tests now cover: a pause issued from inside
447
+ `resume()` (whose synchronous dispatch can refill the queue) was undone by the
448
+ muxer's own resume that follows it, leaving libp2p paused while yamux granted
449
+ window for every frame — run-ahead grew until the stream was aborted, with a
450
+ consumer that reads and stalls by turns; the message a resume dispatches (up
451
+ to a window) is now queued in high-water-sized pieces, so a frame parser
452
+ holding it does not hold a window outside the count; and a handler reading its
453
+ input after its output ended was cut off.
454
+
455
+ One-way throughput is unchanged (64 MiB over in-process TCP, 64 KiB chunks: up
456
+ 105-113, down 129-163 MiB/s before and after; 256 KiB chunks: 156-179 /
457
+ 184-219). An echo of 64 KiB chunks is slower (about 45 vs 65 MiB/s): it
458
+ profited from the server reading the whole request ahead, which is the
459
+ buffering removed. The port stack over libp2p (native or emulated ports,
460
+ above) stays bounded at one chunk.
461
+
462
+ Mutants, each killed by `tests/run-ahead.test.ts`: the reader never pauses (L6
463
+ past the bound), never resumes (the stalled transfer never completes), no
464
+ read-buffer raise (yamux's default window: the stream is aborted), `serve` not
465
+ waiting on the handler's queue (L6 request), no drop once the handler's output
466
+ ended (a handler that never reads its input hangs the call), a pause inside
467
+ `resume()` (reads and stalls by turns: aborted), the resumed message not split
468
+ (2.94 MiB past a 1 MiB window), input dropped although its reader started (a
469
+ background reader cut off). Not covered by a test: the pause skipped for a
470
+ muxer without a window (no such muxer in the test nodes).
471
+
472
+ `messageTargetOverStream` (review of the port work) now also aborts its
473
+ `signal` for a stream that ended before the target was attached: a peer that
474
+ reset the stream during protocol negotiation left its `close` event unseen and
475
+ the signal never aborted.
343
476
 
344
477
  ### Dependencies
345
478
 
@@ -12,6 +12,17 @@ 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;
20
+ /**
21
+ * The largest frame payload accepted from the peer; past it, or on a
22
+ * malformed frame header, the call fails and the stream is aborted. See
23
+ * `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
24
+ */
25
+ maxFrameBytes?: number;
15
26
  /**
16
27
  * How many outgoing streams for this protocol libp2p allows to be open at
17
28
  * the same time on one connection; passed through to `node.dialProtocol`.
@@ -38,6 +49,17 @@ export interface ServeLibp2pParams {
38
49
  * closing, since the caller-side `.return`/abort escape does not exist here.
39
50
  */
40
51
  drainTimeoutMs?: number;
52
+ /**
53
+ * Request bytes held while the handler is not reading before the stream is
54
+ * paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
55
+ */
56
+ readHighWaterBytes?: number;
57
+ /**
58
+ * The largest frame payload accepted from the peer; past it, or on a
59
+ * malformed frame header, the call fails and the stream is aborted. See
60
+ * `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
61
+ */
62
+ maxFrameBytes?: number;
41
63
  /**
42
64
  * How many incoming streams for this protocol libp2p allows to be open at
43
65
  * the same time on one connection; passed through to `node.handle`. Left
@@ -62,6 +84,10 @@ export interface ServeLibp2pParams {
62
84
  */
63
85
  runOnLimitedConnection?: boolean;
64
86
  }
87
+ /**
88
+ * Caller-side: each `call(input)` opens a new libp2p `Stream` via
89
+ * `node.dialProtocol(peer, [protocol])` and runs the call over it.
90
+ */
65
91
  export declare const connect: Connect<ConnectLibp2pParams>;
66
92
  /**
67
93
  * Server-side: registers `node.handle(protocol, ...)`. Each inbound stream is
@@ -88,5 +114,5 @@ export type ServeConnectionsHandler = (context: ConnectionContext) => Duplex;
88
114
  * Like `serve`, but the handler is built per inbound stream and is told which
89
115
  * peer libp2p proved on that connection.
90
116
  */
91
- export declare function serveConnections({ node, protocol, drainTimeoutMs, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection, }: ServeLibp2pParams, makeHandler: ServeConnectionsHandler): Promise<() => Promise<void>>;
117
+ export declare function serveConnections({ node, protocol, drainTimeoutMs, readHighWaterBytes, maxFrameBytes, maxInboundStreams, maxOutboundStreams, runOnLimitedConnection, }: ServeLibp2pParams, makeHandler: ServeConnectionsHandler): Promise<() => Promise<void>>;
92
118
  //# 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,CAwD9B"}
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,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;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;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;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,CA8FhD,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,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,GACvB,EAAE,iBAAiB,EACpB,WAAW,EAAE,uBAAuB,GACnC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAgE9B"}
@@ -45,6 +45,22 @@ 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
+ * Default for {@link DuplexOverStreamOptions.maxFrameBytes}: the largest frame payload accepted
55
+ * from the peer. Generous, because a sender before this package's outbound chunking sent each
56
+ * producer chunk as one frame; short of letting a peer declare a 4 GiB frame.
57
+ */
58
+ export declare const DEFAULT_MAX_FRAME_BYTES: number;
59
+ /**
60
+ * The largest payload this side puts in one outbound frame: a larger producer chunk crosses as
61
+ * several frames (they are self-delimiting, so a receiver of any version reassembles the bytes).
62
+ */
63
+ export declare const OUTBOUND_FRAME_BYTES: number;
48
64
  /**
49
65
  * The stream ended before the call finished: the peer died, the connection
50
66
  * dropped, or the stream was reset or refused before both sides ended it.
@@ -79,6 +95,25 @@ export interface DuplexOverStreamOptions {
79
95
  * the peer. Defaults to {@link DEFAULT_DRAIN_TIMEOUT_MS}.
80
96
  */
81
97
  drainTimeoutMs?: number;
98
+ /**
99
+ * Received bytes held for a consumer that is not reading before the stream
100
+ * is paused (and resumed once half of them are read). A paused yamux stream
101
+ * stops granting its peer receive window, so the peer's `send()` reports a
102
+ * full buffer and its producer waits: run-ahead is bounded by two receive
103
+ * windows (what libp2p held while paused, and the window granted on resume)
104
+ * plus this — the receiving node's yamux `streamOptions.maxStreamWindowSize`,
105
+ * 16 MiB by default; 1 MiB bounds it at about 2.25 MiB with no loss of
106
+ * one-way throughput measured. Only where the muxer exposes its window.
107
+ * Defaults to {@link DEFAULT_READ_HIGH_WATER_BYTES}.
108
+ */
109
+ readHighWaterBytes?: number;
110
+ /**
111
+ * The largest frame payload accepted from the peer, in bytes. A frame header past it — or one
112
+ * whose length is not a valid varint — means the peer is not speaking this framing: the call
113
+ * fails and the stream is aborted, rather than buffering without bound. Defaults to
114
+ * {@link DEFAULT_MAX_FRAME_BYTES}.
115
+ */
116
+ maxFrameBytes?: number;
82
117
  }
83
118
  /**
84
119
  * Drive one `Duplex` over one libp2p `Stream` using a small in-band framing
@@ -103,6 +138,33 @@ export declare function duplexOverStream(stream: Stream, input: AsyncIterable<Ui
103
138
  * caller is never left hanging.
104
139
  */
105
140
  export declare function closeStream(stream: Stream, timeoutMs?: number): Promise<void>;
141
+ /**
142
+ * Frames out of the stream's chunks, as they complete. Unread bytes sit in a {@link ByteBuffer},
143
+ * which grows by doubling, so a large frame arriving in many chunks is copied a bounded number
144
+ * of times. A header whose length is malformed or past `maxFrameBytes` throws a `FramingError`.
145
+ */
146
+ export declare function parseFrames(source: AsyncIterable<unknown>, maxFrameBytes?: number): AsyncGenerator<{
147
+ type: number;
148
+ payload: Uint8Array;
149
+ }>;
150
+ /** Unread bytes `buf[start, end)` of a buffer that grows by doubling. */
151
+ export declare class ByteBuffer {
152
+ private buf;
153
+ private start;
154
+ private end;
155
+ push(incoming: Uint8Array): void;
156
+ /** a view of the unread bytes, valid until the next `push` */
157
+ unread(): Uint8Array;
158
+ consume(n: number): void;
159
+ }
160
+ /**
161
+ * The varint length prefix at the start of `bytes`, or `undefined` while it is incomplete; throws
162
+ * a `FramingError` when it is malformed (no varint of this framing runs past 5 bytes).
163
+ */
164
+ export declare function readLength(bytes: Uint8Array, what: string): {
165
+ value: number;
166
+ offset: number;
167
+ } | undefined;
106
168
  export declare function normalizeChunk(item: unknown): Uint8Array;
107
169
  export declare function encodeVarint(value: number): Uint8Array;
108
170
  export declare function decodeVarint(buf: Uint8Array, start: number): {
@@ -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;AAEjE;;;;;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;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,CAgL5B;AA2CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAsBf;AA8ED,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"}
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;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,QAAY,CAAC;AAK9C;;;;;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;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;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,CAwL5B;AA2CD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAsBf;AAkKD;;;;GAIG;AACH,wBAAuB,WAAW,CAChC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,aAAa,GAAE,MAAgC,GAC9C,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC,CAyBvD;AAED,yEAAyE;AACzE,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAqB;IAChC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAK;IAEhB,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAW/B;IAED,8DAA8D;IAC9D,MAAM,IAAI,UAAU,CAEnB;IAED,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAGvB;CACF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAO/C;AAED,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,4 +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, PeerGoneError, } from "./duplex-over-stream.js";
2
+ export { DEFAULT_CLOSE_TIMEOUT_MS, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_MAX_FRAME_BYTES, type DuplexOverStreamOptions, duplexOverStream, PeerGoneError, } from "./duplex-over-stream.js";
3
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";
4
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,EAChB,aAAa,GACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,yBAAyB,EACzB,KAAK,8BAA8B,EACnC,uBAAuB,EACvB,KAAK,mBAAmB,GACzB,MAAM,iCAAiC,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,uBAAuB,EACvB,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"}