@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 +140 -7
- package/dist/connect-serve.d.ts +27 -1
- package/dist/connect-serve.d.ts.map +1 -1
- package/dist/duplex-over-stream.d.ts +62 -0
- package/dist/duplex-over-stream.d.ts.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +431 -98
- package/dist/message-target-over-stream.d.ts +3 -0
- package/dist/message-target-over-stream.d.ts.map +1 -1
- package/dist/port-mux.d.ts +89 -0
- package/dist/port-mux.d.ts.map +1 -0
- package/dist/stream-gate.d.ts +10 -0
- package/dist/stream-gate.d.ts.map +1 -0
- package/package.json +8 -6
- package/src/connect-serve.ts +106 -71
- package/src/duplex-over-stream.ts +239 -25
- package/src/index.ts +12 -0
- package/src/message-target-over-stream.ts +36 -31
- package/src/port-mux.ts +238 -0
- package/src/stream-gate.ts +77 -0
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
|
|
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
|
-
|
|
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
|
|
340
|
-
|
|
341
|
-
`skipHugeBody
|
|
342
|
-
|
|
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
|
|
package/dist/connect-serve.d.ts
CHANGED
|
@@ -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;
|
|
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;
|
|
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
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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"}
|