@statewalker/webrun-streams-libp2p 0.6.0 → 0.7.1
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 +205 -82
- package/dist/connect-serve.d.ts +130 -67
- package/dist/connect-serve.d.ts.map +1 -1
- package/dist/duplex-over-stream.d.ts +13 -0
- package/dist/duplex-over-stream.d.ts.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +289 -22
- package/dist/legacy-connect-serve.d.ts +116 -0
- package/dist/legacy-connect-serve.d.ts.map +1 -0
- package/dist/message-target-over-stream.d.ts +10 -2
- package/dist/message-target-over-stream.d.ts.map +1 -1
- package/dist/port-mux.d.ts +21 -1
- package/dist/port-mux.d.ts.map +1 -1
- package/dist/shared.d.ts +26 -0
- package/dist/shared.d.ts.map +1 -0
- package/package.json +6 -5
- package/src/connect-serve.ts +355 -342
- package/src/duplex-over-stream.ts +13 -0
- package/src/index.ts +2 -0
- package/src/legacy-connect-serve.ts +425 -0
- package/src/message-target-over-stream.ts +13 -2
- package/src/port-mux.ts +37 -5
- package/src/shared.ts +28 -0
|
@@ -19,6 +19,10 @@ const TYPE_ERROR = 0x02;
|
|
|
19
19
|
* the transfer would complete anyway; a peer slower than that is
|
|
20
20
|
* indistinguishable from one that has stopped reading altogether. Override via
|
|
21
21
|
* `drainTimeoutMs` when a deployment knows better.
|
|
22
|
+
*
|
|
23
|
+
* Also the default stall bound of the port protocol (`connect`, `serve`,
|
|
24
|
+
* `serveConnections`, `libp2pPortMux`): a write on a call's stream that has
|
|
25
|
+
* waited for drain this long resets the stream (statewalker/webrun-wire#195).
|
|
22
26
|
*/
|
|
23
27
|
export const DEFAULT_DRAIN_TIMEOUT_MS = 300_000;
|
|
24
28
|
|
|
@@ -49,6 +53,9 @@ export const DEFAULT_DRAIN_TIMEOUT_MS = 300_000;
|
|
|
49
53
|
* of sixty.
|
|
50
54
|
*
|
|
51
55
|
* Exported so a deployment that knows its links can lower it deliberately.
|
|
56
|
+
*
|
|
57
|
+
* @deprecated The deprecated protocol's (statewalker/webrun-wire#153): kept for
|
|
58
|
+
* one release, as the shim `connect`/`serve` run for older peers, then removed.
|
|
52
59
|
*/
|
|
53
60
|
export const DEFAULT_CLOSE_TIMEOUT_MS = DEFAULT_DRAIN_TIMEOUT_MS;
|
|
54
61
|
|
|
@@ -101,6 +108,9 @@ const textDecoder = new TextDecoder();
|
|
|
101
108
|
* exhausts — without it, the server-side `serve` would deadlock waiting for the
|
|
102
109
|
* outbound pump to finish, which itself waits for the handler, which waits for
|
|
103
110
|
* inputQueue.done.
|
|
111
|
+
*
|
|
112
|
+
* @deprecated The deprecated protocol's (statewalker/webrun-wire#153): kept for
|
|
113
|
+
* one release, as the shim `connect`/`serve` run for older peers, then removed.
|
|
104
114
|
*/
|
|
105
115
|
export interface DuplexOverStreamOptions {
|
|
106
116
|
/**
|
|
@@ -151,6 +161,9 @@ export interface DuplexOverStreamOptions {
|
|
|
151
161
|
* JSON-serialised `Error`). Normal end-of-input is signalled by libp2p's
|
|
152
162
|
* `close()`. The frame layer exists so we can preserve `Error` fidelity
|
|
153
163
|
* across the wire (yamux's native stream reset only carries "stream reset").
|
|
164
|
+
*
|
|
165
|
+
* @deprecated The deprecated protocol's (statewalker/webrun-wire#153): kept for
|
|
166
|
+
* one release, as the shim `connect`/`serve` run for older peers, then removed.
|
|
154
167
|
*/
|
|
155
168
|
export async function* duplexOverStream(
|
|
156
169
|
stream: Stream,
|
package/src/index.ts
CHANGED
|
@@ -0,0 +1,425 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The deprecated protocol of `connect`/`serve` (statewalker/webrun-wire#153):
|
|
3
|
+
* one call per libp2p stream on `protocol` itself, framed by
|
|
4
|
+
* `duplexOverStream`, with its own flow control (yamux pause/resume and a
|
|
5
|
+
* paced reader). Releases up to 0.6.0 spoke only this.
|
|
6
|
+
*
|
|
7
|
+
* Kept for one release as a compatibility shim on both ends: `serve` still
|
|
8
|
+
* answers old callers on it, and `connect` falls back to it against an old
|
|
9
|
+
* server. Removed in the release after the one that introduced the port
|
|
10
|
+
* protocol, together with `duplexOverStream`.
|
|
11
|
+
*
|
|
12
|
+
* @deprecated Use `connect`/`serve`, which run over the windowed native port mux.
|
|
13
|
+
*/
|
|
14
|
+
import type {
|
|
15
|
+
Connection,
|
|
16
|
+
DialProtocolOptions,
|
|
17
|
+
Libp2p,
|
|
18
|
+
PeerId,
|
|
19
|
+
Stream,
|
|
20
|
+
StreamHandlerOptions,
|
|
21
|
+
} from "@libp2p/interface";
|
|
22
|
+
import type { Multiaddr } from "@multiformats/multiaddr";
|
|
23
|
+
import type { Connect, Duplex } from "@statewalker/webrun-streams";
|
|
24
|
+
import {
|
|
25
|
+
closeStream,
|
|
26
|
+
DEFAULT_READ_HIGH_WATER_BYTES,
|
|
27
|
+
duplexOverStream,
|
|
28
|
+
PeerGoneError,
|
|
29
|
+
} from "./duplex-over-stream.js";
|
|
30
|
+
import { DEFAULT_PROTOCOL, type ServeConnectionsHandler } from "./shared.js";
|
|
31
|
+
import { openGatedStream } from "./stream-gate.js";
|
|
32
|
+
|
|
33
|
+
/** @deprecated See the module comment. */
|
|
34
|
+
export interface LegacyConnectParams {
|
|
35
|
+
node: Libp2p;
|
|
36
|
+
peer: PeerId | Multiaddr;
|
|
37
|
+
/** libp2p protocol id; defaults to `/webrun-streams/1.0.0`. */
|
|
38
|
+
protocol?: string;
|
|
39
|
+
/**
|
|
40
|
+
* How long to wait for a backpressured stream to drain before dropping the
|
|
41
|
+
* peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes).
|
|
42
|
+
*/
|
|
43
|
+
drainTimeoutMs?: number;
|
|
44
|
+
/**
|
|
45
|
+
* Response bytes held while the caller is not reading before the stream is
|
|
46
|
+
* paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
|
|
47
|
+
*/
|
|
48
|
+
readHighWaterBytes?: number;
|
|
49
|
+
/**
|
|
50
|
+
* The largest frame payload accepted from the peer; past it, or on a
|
|
51
|
+
* malformed frame header, the call fails and the stream is aborted. See
|
|
52
|
+
* `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
|
|
53
|
+
*/
|
|
54
|
+
maxFrameBytes?: number;
|
|
55
|
+
/**
|
|
56
|
+
* How many outgoing streams for this protocol libp2p allows to be open at
|
|
57
|
+
* the same time on one connection; passed through to `node.dialProtocol`.
|
|
58
|
+
* Left unset, libp2p's own default (64) applies.
|
|
59
|
+
*/
|
|
60
|
+
maxOutboundStreams?: number;
|
|
61
|
+
/**
|
|
62
|
+
* Opt-in to dialing over a connection with limits on how much data can be
|
|
63
|
+
* transferred or how long it can be open for (e.g. a relayed circuit);
|
|
64
|
+
* passed through to `node.dialProtocol`. Left unset, libp2p refuses to open
|
|
65
|
+
* this protocol's stream on such a connection — this package does not
|
|
66
|
+
* decide that trade-off for the caller, it only exposes the knob.
|
|
67
|
+
*/
|
|
68
|
+
runOnLimitedConnection?: boolean;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** @deprecated See the module comment. */
|
|
72
|
+
export interface LegacyServeParams {
|
|
73
|
+
node: Libp2p;
|
|
74
|
+
/** libp2p protocol id; defaults to `/webrun-streams/1.0.0`. */
|
|
75
|
+
protocol?: string;
|
|
76
|
+
/**
|
|
77
|
+
* How long to wait for a backpressured stream to drain before dropping the
|
|
78
|
+
* peer; defaults to `DEFAULT_DRAIN_TIMEOUT_MS` (5 minutes). This is the only
|
|
79
|
+
* bound on a peer that requests something and then stops reading without
|
|
80
|
+
* closing, since the caller-side `.return`/abort escape does not exist here.
|
|
81
|
+
*/
|
|
82
|
+
drainTimeoutMs?: number;
|
|
83
|
+
/**
|
|
84
|
+
* Request bytes held while the handler is not reading before the stream is
|
|
85
|
+
* paused; see `DuplexOverStreamOptions.readHighWaterBytes` (default 64 KiB).
|
|
86
|
+
*/
|
|
87
|
+
readHighWaterBytes?: number;
|
|
88
|
+
/**
|
|
89
|
+
* The largest frame payload accepted from the peer; past it, or on a
|
|
90
|
+
* malformed frame header, the call fails and the stream is aborted. See
|
|
91
|
+
* `DuplexOverStreamOptions.maxFrameBytes` (default 64 MiB).
|
|
92
|
+
*/
|
|
93
|
+
maxFrameBytes?: number;
|
|
94
|
+
/**
|
|
95
|
+
* How many incoming streams for this protocol libp2p allows to be open at
|
|
96
|
+
* the same time on one connection; passed through to `node.handle`. Left
|
|
97
|
+
* unset, libp2p's own default (32) applies — past it, a new inbound stream
|
|
98
|
+
* is reset rather than queued, so a caller that opens one stream per
|
|
99
|
+
* in-flight request will start seeing rejected calls above that count.
|
|
100
|
+
*/
|
|
101
|
+
maxInboundStreams?: number;
|
|
102
|
+
/**
|
|
103
|
+
* How many outgoing streams for this protocol libp2p allows to be open at
|
|
104
|
+
* the same time on one connection; passed through to `node.handle`. Left
|
|
105
|
+
* unset, libp2p's own default (64) applies.
|
|
106
|
+
*/
|
|
107
|
+
maxOutboundStreams?: number;
|
|
108
|
+
/**
|
|
109
|
+
* Opt-in to accepting streams for this protocol over a connection with
|
|
110
|
+
* limits on how much data can be transferred or how long it can be open
|
|
111
|
+
* for (e.g. a relayed circuit); passed through to `node.handle`. Left
|
|
112
|
+
* unset, libp2p refuses to open this protocol's stream on such a
|
|
113
|
+
* connection — this package does not decide that trade-off for the
|
|
114
|
+
* consumer, it only exposes the knob.
|
|
115
|
+
*/
|
|
116
|
+
runOnLimitedConnection?: boolean;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Builds the options object passed to `node.dialProtocol`/`node.handle`,
|
|
121
|
+
* omitting any field the caller didn't supply rather than setting it to
|
|
122
|
+
* `undefined` — so an unset field falls back to libp2p's own default instead
|
|
123
|
+
* of an explicit `undefined` overriding it.
|
|
124
|
+
*/
|
|
125
|
+
function definedOptions<T extends Record<string, unknown>>(fields: T): Partial<T> | undefined {
|
|
126
|
+
const options: Partial<T> = {};
|
|
127
|
+
let any = false;
|
|
128
|
+
for (const key of Object.keys(fields) as (keyof T)[]) {
|
|
129
|
+
const value = fields[key];
|
|
130
|
+
if (value !== undefined) {
|
|
131
|
+
options[key] = value;
|
|
132
|
+
any = true;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
return any ? options : undefined;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Caller-side: each `call(input)` opens a new libp2p `Stream` via
|
|
140
|
+
* `node.dialProtocol(peer, [protocol])` and runs the call over it.
|
|
141
|
+
*
|
|
142
|
+
* @deprecated See the module comment.
|
|
143
|
+
*/
|
|
144
|
+
export const legacyConnect: Connect<LegacyConnectParams> = async ({
|
|
145
|
+
node,
|
|
146
|
+
peer,
|
|
147
|
+
protocol,
|
|
148
|
+
drainTimeoutMs,
|
|
149
|
+
readHighWaterBytes,
|
|
150
|
+
maxFrameBytes,
|
|
151
|
+
maxOutboundStreams,
|
|
152
|
+
runOnLimitedConnection,
|
|
153
|
+
}) => {
|
|
154
|
+
const proto = protocol ?? DEFAULT_PROTOCOL;
|
|
155
|
+
const dialOptions: DialProtocolOptions | undefined = definedOptions({
|
|
156
|
+
maxOutboundStreams,
|
|
157
|
+
runOnLimitedConnection,
|
|
158
|
+
});
|
|
159
|
+
const open = new Set<Stream>();
|
|
160
|
+
|
|
161
|
+
// A burst of calls must not reach the remote before its muxer is ready.
|
|
162
|
+
//
|
|
163
|
+
// When there is no connection to the peer yet, every call dials it and they
|
|
164
|
+
// all share the one connection libp2p establishes. Their streams can arrive
|
|
165
|
+
// while the REMOTE side is still upgrading that connection, and yamux counts
|
|
166
|
+
// those "early streams": past `maxEarlyStreams` (10 by default) it aborts the
|
|
167
|
+
// whole muxer, so every stream on the connection dies — the remote sees EOF
|
|
168
|
+
// during protocol negotiation, this side sees `StreamResetError`. Raising the
|
|
169
|
+
// limit on our own nodes would not help against any other libp2p peer.
|
|
170
|
+
//
|
|
171
|
+
// So until one stream has negotiated its protocol on an open connection, the
|
|
172
|
+
// calls open their streams one at a time: a completed negotiation means the
|
|
173
|
+
// remote has finished its upgrade, and from then on streams are not early and
|
|
174
|
+
// open concurrently. If that connection closes, the next burst is gated again.
|
|
175
|
+
// The state is shared by every connect() to the same peer from the same node
|
|
176
|
+
// (callers often connect() per request), since they all share its connection.
|
|
177
|
+
const openStream = (): Promise<Stream> => openGatedStream(node, peer, proto, dialOptions);
|
|
178
|
+
|
|
179
|
+
const call: Duplex = (input) => {
|
|
180
|
+
let streamRef: Stream | null = null;
|
|
181
|
+
const gen = (async function* () {
|
|
182
|
+
const stream = await openStream();
|
|
183
|
+
streamRef = stream;
|
|
184
|
+
open.add(stream);
|
|
185
|
+
let sourceCompleted = false;
|
|
186
|
+
try {
|
|
187
|
+
yield* duplexOverStream(stream, input, {
|
|
188
|
+
drainTimeoutMs,
|
|
189
|
+
readHighWaterBytes,
|
|
190
|
+
maxFrameBytes,
|
|
191
|
+
onSourceCompleted: () => {
|
|
192
|
+
sourceCompleted = true;
|
|
193
|
+
},
|
|
194
|
+
});
|
|
195
|
+
} finally {
|
|
196
|
+
open.delete(stream);
|
|
197
|
+
if (sourceCompleted) {
|
|
198
|
+
// Natural end on both sides. Graceful close, bounded so a peer
|
|
199
|
+
// that stops reading without resetting can't hang this forever.
|
|
200
|
+
await closeStream(stream);
|
|
201
|
+
}
|
|
202
|
+
// Else: consumer cancelled. The .return override below has already
|
|
203
|
+
// called stream.abort to send RST; nothing more to do here.
|
|
204
|
+
}
|
|
205
|
+
})();
|
|
206
|
+
|
|
207
|
+
// Send a yamux RST to peer when the consumer cancels (i.e., calls .return
|
|
208
|
+
// on this generator). Doing it here is essential because by the time the
|
|
209
|
+
// generator's own finally runs, the for-await teardown chain has already
|
|
210
|
+
// marked the stream's status as `closed` — and AbstractStream.abort is a
|
|
211
|
+
// no-op on closed streams.
|
|
212
|
+
const origReturn = gen.return.bind(gen);
|
|
213
|
+
gen.return = async (value: unknown) => {
|
|
214
|
+
if (streamRef) {
|
|
215
|
+
try {
|
|
216
|
+
streamRef.abort(new Error("call cancelled"));
|
|
217
|
+
} catch {
|
|
218
|
+
/* ignore */
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
return origReturn(value as undefined);
|
|
222
|
+
};
|
|
223
|
+
|
|
224
|
+
return gen;
|
|
225
|
+
};
|
|
226
|
+
return {
|
|
227
|
+
call,
|
|
228
|
+
async close() {
|
|
229
|
+
for (const s of open) {
|
|
230
|
+
try {
|
|
231
|
+
s.abort(new Error("connection close"));
|
|
232
|
+
} catch {
|
|
233
|
+
/* ignore */
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
},
|
|
237
|
+
};
|
|
238
|
+
};
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Server-side: registers `node.handle(protocol, ...)`. The handler is built per
|
|
242
|
+
* inbound stream and is told which peer libp2p proved on that connection.
|
|
243
|
+
*
|
|
244
|
+
* @deprecated See the module comment.
|
|
245
|
+
*/
|
|
246
|
+
export async function legacyServeConnections(
|
|
247
|
+
{
|
|
248
|
+
node,
|
|
249
|
+
protocol,
|
|
250
|
+
drainTimeoutMs,
|
|
251
|
+
readHighWaterBytes,
|
|
252
|
+
maxFrameBytes,
|
|
253
|
+
maxInboundStreams,
|
|
254
|
+
maxOutboundStreams,
|
|
255
|
+
runOnLimitedConnection,
|
|
256
|
+
}: LegacyServeParams,
|
|
257
|
+
makeHandler: ServeConnectionsHandler,
|
|
258
|
+
): Promise<() => Promise<void>> {
|
|
259
|
+
const proto = protocol ?? DEFAULT_PROTOCOL;
|
|
260
|
+
const handleOptions: StreamHandlerOptions | undefined = definedOptions({
|
|
261
|
+
maxInboundStreams,
|
|
262
|
+
maxOutboundStreams,
|
|
263
|
+
runOnLimitedConnection,
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
const onStream = (stream: Stream, connection: Connection): void => {
|
|
267
|
+
// The caller sent its whole request; a stream that dies after that is a
|
|
268
|
+
// caller that stopped reading the response — ordinary, not a fault.
|
|
269
|
+
let requestComplete = false;
|
|
270
|
+
void (async () => {
|
|
271
|
+
const handler = makeHandler({ remotePeer: connection.remotePeer });
|
|
272
|
+
const inputQueue = makeInputQueue(readHighWaterBytes ?? DEFAULT_READ_HIGH_WATER_BYTES);
|
|
273
|
+
// once the handler's output has ended, input it never started to read is
|
|
274
|
+
// dropped instead of waited for (input it is reading, perhaps in the
|
|
275
|
+
// background, keeps flowing at its pace)
|
|
276
|
+
const output = endsWith(handler(inputQueue.iter()), () => inputQueue.abandon());
|
|
277
|
+
try {
|
|
278
|
+
for await (const chunk of duplexOverStream(stream, output, {
|
|
279
|
+
drainTimeoutMs,
|
|
280
|
+
readHighWaterBytes,
|
|
281
|
+
maxFrameBytes,
|
|
282
|
+
onPeerInputEnd: (err) => {
|
|
283
|
+
if (err === undefined) requestComplete = true;
|
|
284
|
+
inputQueue.done(err);
|
|
285
|
+
},
|
|
286
|
+
})) {
|
|
287
|
+
// past readHighWaterBytes queued for the handler, the next chunk is
|
|
288
|
+
// read only once it took this one: a handler that stops reading
|
|
289
|
+
// pauses the stream (see readHighWaterBytes)
|
|
290
|
+
await inputQueue.push(chunk);
|
|
291
|
+
}
|
|
292
|
+
} finally {
|
|
293
|
+
inputQueue.done();
|
|
294
|
+
await closeStream(stream);
|
|
295
|
+
}
|
|
296
|
+
})().catch((err: unknown) => {
|
|
297
|
+
// One inbound stream failing must not take down the process serving
|
|
298
|
+
// every other peer. `duplexOverStream` rejects on the read side
|
|
299
|
+
// whenever the peer sends an ERROR frame or resets mid-request — which
|
|
300
|
+
// happens in ordinary use, not just under attack (a browser tab closed
|
|
301
|
+
// mid-request resets its streams). Without this catch that rejection is
|
|
302
|
+
// unhandled, and Node's default for `unhandledRejection` is to
|
|
303
|
+
// terminate. Logged rather than rethrown, and never rethrown from here:
|
|
304
|
+
// there is no caller left to receive it.
|
|
305
|
+
if (requestComplete && err instanceof PeerGoneError) return;
|
|
306
|
+
const e = err instanceof Error ? err : new Error(String(err));
|
|
307
|
+
console.warn(
|
|
308
|
+
`[webrun-streams-libp2p] serve: inbound stream on protocol ${proto} failed: ${e.message}`,
|
|
309
|
+
e,
|
|
310
|
+
);
|
|
311
|
+
});
|
|
312
|
+
};
|
|
313
|
+
|
|
314
|
+
await node.handle(proto, onStream, handleOptions);
|
|
315
|
+
|
|
316
|
+
let torn = false;
|
|
317
|
+
return async () => {
|
|
318
|
+
if (torn) return;
|
|
319
|
+
torn = true;
|
|
320
|
+
await node.unhandle(proto);
|
|
321
|
+
};
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/** `source`, calling `onEnd` once when it ends, fails or is returned. */
|
|
325
|
+
function endsWith(
|
|
326
|
+
source: AsyncIterable<Uint8Array>,
|
|
327
|
+
onEnd: () => void,
|
|
328
|
+
): AsyncGenerator<Uint8Array> {
|
|
329
|
+
return (async function* () {
|
|
330
|
+
try {
|
|
331
|
+
yield* source;
|
|
332
|
+
} finally {
|
|
333
|
+
onEnd();
|
|
334
|
+
}
|
|
335
|
+
})();
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
interface InputQueue {
|
|
339
|
+
iter(): AsyncGenerator<Uint8Array>;
|
|
340
|
+
/**
|
|
341
|
+
* resolves at once while the bytes queued for the handler stay within the
|
|
342
|
+
* limit, else once the handler has read them back down to it (or will never
|
|
343
|
+
* read on)
|
|
344
|
+
*/
|
|
345
|
+
push(chunk: Uint8Array): Promise<void>;
|
|
346
|
+
done(err?: Error): void;
|
|
347
|
+
/**
|
|
348
|
+
* the handler's output ended: if it never started reading its input, pending
|
|
349
|
+
* and later chunks are dropped (an iterator started already is left to its
|
|
350
|
+
* reader, which may go on reading after the output ended)
|
|
351
|
+
*/
|
|
352
|
+
abandon(): void;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
function makeInputQueue(limit: number): InputQueue {
|
|
356
|
+
type Slot = { type: "value"; value: Uint8Array } | { type: "done"; err?: Error };
|
|
357
|
+
const slots: Slot[] = [];
|
|
358
|
+
let wake: (() => void) | null = null;
|
|
359
|
+
let closed = false;
|
|
360
|
+
let pulled = false;
|
|
361
|
+
let queued = 0;
|
|
362
|
+
// the one push waiting for room (the serving loop awaits each push)
|
|
363
|
+
let room: (() => void) | null = null;
|
|
364
|
+
const makeRoom = (): void => {
|
|
365
|
+
const r = room;
|
|
366
|
+
room = null;
|
|
367
|
+
r?.();
|
|
368
|
+
};
|
|
369
|
+
const release = (): void => {
|
|
370
|
+
slots.length = 0;
|
|
371
|
+
queued = 0;
|
|
372
|
+
makeRoom();
|
|
373
|
+
};
|
|
374
|
+
return {
|
|
375
|
+
iter(): AsyncGenerator<Uint8Array> {
|
|
376
|
+
return (async function* () {
|
|
377
|
+
if (closed) return; // abandoned before anyone read: the input was dropped
|
|
378
|
+
pulled = true;
|
|
379
|
+
try {
|
|
380
|
+
while (true) {
|
|
381
|
+
if (slots.length === 0) {
|
|
382
|
+
await new Promise<void>((r) => {
|
|
383
|
+
wake = r;
|
|
384
|
+
});
|
|
385
|
+
wake = null;
|
|
386
|
+
continue;
|
|
387
|
+
}
|
|
388
|
+
const s = slots.shift() as Slot;
|
|
389
|
+
if (s.type === "done") {
|
|
390
|
+
if (s.err) throw s.err;
|
|
391
|
+
return;
|
|
392
|
+
}
|
|
393
|
+
queued -= s.value.byteLength;
|
|
394
|
+
if (queued <= limit) makeRoom();
|
|
395
|
+
yield s.value;
|
|
396
|
+
}
|
|
397
|
+
} finally {
|
|
398
|
+
closed = true;
|
|
399
|
+
release();
|
|
400
|
+
}
|
|
401
|
+
})();
|
|
402
|
+
},
|
|
403
|
+
push(chunk: Uint8Array): Promise<void> {
|
|
404
|
+
if (closed) return Promise.resolve();
|
|
405
|
+
slots.push({ type: "value", value: chunk });
|
|
406
|
+
queued += chunk.byteLength;
|
|
407
|
+
wake?.();
|
|
408
|
+
if (queued <= limit) return Promise.resolve();
|
|
409
|
+
return new Promise<void>((resolve) => {
|
|
410
|
+
room = resolve;
|
|
411
|
+
});
|
|
412
|
+
},
|
|
413
|
+
done(err?: Error): void {
|
|
414
|
+
if (closed) return;
|
|
415
|
+
slots.push({ type: "done", err });
|
|
416
|
+
wake?.();
|
|
417
|
+
},
|
|
418
|
+
abandon(): void {
|
|
419
|
+
if (pulled) return;
|
|
420
|
+
closed = true;
|
|
421
|
+
release();
|
|
422
|
+
wake?.();
|
|
423
|
+
},
|
|
424
|
+
};
|
|
425
|
+
}
|
|
@@ -29,6 +29,13 @@ export interface StreamMessageTarget {
|
|
|
29
29
|
* closed; at once when it can now.
|
|
30
30
|
*/
|
|
31
31
|
whenDrained(): Promise<void>;
|
|
32
|
+
/**
|
|
33
|
+
* Whether the stream needs to drain before it takes more (libp2p's
|
|
34
|
+
* `writableNeedsDrain`: the muxer's send window is spent and bytes are
|
|
35
|
+
* piling up in the write buffer). A windowed native port sends nothing
|
|
36
|
+
* while it is `true` (statewalker/webrun-wire#195).
|
|
37
|
+
*/
|
|
38
|
+
readonly needsDrain: boolean;
|
|
32
39
|
/** `signal` again, on the target: `webrun-rpc`'s `getPortCloseSignal` reads it from a port. */
|
|
33
40
|
readonly closeSignal: AbortSignal;
|
|
34
41
|
};
|
|
@@ -70,8 +77,9 @@ export const DEFAULT_MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
|
|
|
70
77
|
* as on a `MessagePort`. Every message the peer sent before closing is
|
|
71
78
|
* delivered before `signal` aborts. `postMessage` hands the frame to
|
|
72
79
|
* `stream.send()` and does not wait for room; libp2p buffers up to the
|
|
73
|
-
* stream's `maxWriteBufferLength
|
|
74
|
-
* that must wait
|
|
80
|
+
* stream's `maxWriteBufferLength` (unbounded with yamux), past which it
|
|
81
|
+
* resets the stream. A sender that must wait checks `needsDrain` and awaits
|
|
82
|
+
* `whenDrained()`, as a windowed native port does.
|
|
75
83
|
*/
|
|
76
84
|
export function messageTargetOverStream(
|
|
77
85
|
stream: Stream,
|
|
@@ -177,6 +185,9 @@ export function messageTargetOverStream(
|
|
|
177
185
|
get bufferedAmount() {
|
|
178
186
|
return stream.writeBufferLength;
|
|
179
187
|
},
|
|
188
|
+
get needsDrain() {
|
|
189
|
+
return stream.writableNeedsDrain === true && !life.signal.aborted;
|
|
190
|
+
},
|
|
180
191
|
whenDrained() {
|
|
181
192
|
if (!stream.writableNeedsDrain || life.signal.aborted) return Promise.resolve();
|
|
182
193
|
return new Promise<void>((resolve) => {
|
package/src/port-mux.ts
CHANGED
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
newNativePortMux,
|
|
14
14
|
type ValueCodec,
|
|
15
15
|
} from "@statewalker/webrun-streams";
|
|
16
|
+
import { DEFAULT_DRAIN_TIMEOUT_MS } from "./duplex-over-stream.js";
|
|
16
17
|
import { messageTargetOverStream } from "./message-target-over-stream.js";
|
|
17
18
|
import { openGatedStream } from "./stream-gate.js";
|
|
18
19
|
|
|
@@ -89,11 +90,25 @@ export interface Libp2pPortMuxOptions {
|
|
|
89
90
|
* negotiates `protocol` and runs as before. 1-4 MiB is a reasonable range:
|
|
90
91
|
* the most one call moves per round trip, and the most a producer runs
|
|
91
92
|
* ahead of a consumer that stopped reading.
|
|
93
|
+
*
|
|
94
|
+
* A windowed port never runs further ahead than min(the peer's window,
|
|
95
|
+
* this window), and sends nothing while its stream needs to drain
|
|
96
|
+
* (statewalker/webrun-wire#195).
|
|
92
97
|
*/
|
|
93
98
|
window?: number;
|
|
99
|
+
/**
|
|
100
|
+
* How long, in ms, a write on a windowed port may wait for its stream to
|
|
101
|
+
* drain (a peer that stopped reading at the transport) before the stream
|
|
102
|
+
* is reset and the port fails. Only a write blocked on drain counts: a
|
|
103
|
+
* quiet call (an event stream between events) is never timed out. Credit
|
|
104
|
+
* for the peer is held back while the stream needs to drain, and counts
|
|
105
|
+
* too. Default {@link DEFAULT_DRAIN_TIMEOUT_MS} (5 minutes); 0 or `Infinity`:
|
|
106
|
+
* no bound.
|
|
107
|
+
*/
|
|
108
|
+
drainTimeoutMs?: number;
|
|
94
109
|
}
|
|
95
110
|
|
|
96
|
-
/** A `webrun-rpc` `PortMux` by shape;
|
|
111
|
+
/** A `webrun-rpc` `PortMux` by shape; the port mux imports nothing from it. */
|
|
97
112
|
export interface Libp2pPortMux {
|
|
98
113
|
openPort(meta?: unknown, options?: { signal?: AbortSignal }): Promise<StreamPort>;
|
|
99
114
|
close(reason?: unknown): Promise<void>;
|
|
@@ -119,13 +134,26 @@ export interface Libp2pPortMux {
|
|
|
119
134
|
* `connect()`. `meta` is not sent: the protocol says what a port is for.
|
|
120
135
|
*/
|
|
121
136
|
export async function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp2pPortMux> {
|
|
137
|
+
return openLibp2pPortMux(options, DEFAULT_PORT_STREAM_LIMIT);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* {@link libp2pPortMux}, with `streamLimit` as the default of both stream
|
|
142
|
+
* limits; `undefined` leaves libp2p's own defaults (what `connect`/`serve`
|
|
143
|
+
* have always passed through). Internal.
|
|
144
|
+
*/
|
|
145
|
+
export async function openLibp2pPortMux(
|
|
146
|
+
options: Libp2pPortMuxOptions,
|
|
147
|
+
streamLimit: number | undefined,
|
|
148
|
+
): Promise<Libp2pPortMux> {
|
|
122
149
|
const { node, peer, codec, onPort, maxMessageBytes, runOnLimitedConnection } = options;
|
|
123
|
-
const maxInboundStreams = options.maxInboundStreams ??
|
|
124
|
-
const maxOutboundStreams = options.maxOutboundStreams ??
|
|
150
|
+
const maxInboundStreams = options.maxInboundStreams ?? streamLimit;
|
|
151
|
+
const maxOutboundStreams = options.maxOutboundStreams ?? streamLimit;
|
|
125
152
|
const protocol = options.protocol ?? DEFAULT_PORT_PROTOCOL;
|
|
126
153
|
const maxMessageSize = options.maxMessageSize ?? DEFAULT_PORT_MAX_MESSAGE_SIZE;
|
|
127
154
|
// Checked by the shared lifecycle, before the protocols are handled.
|
|
128
155
|
const { window } = options;
|
|
156
|
+
const drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
|
|
129
157
|
const windowProtocol = windowProtocolOf(protocol);
|
|
130
158
|
|
|
131
159
|
/**
|
|
@@ -140,7 +168,8 @@ export async function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp
|
|
|
140
168
|
: {}),
|
|
141
169
|
});
|
|
142
170
|
|
|
143
|
-
const dialOptions: DialProtocolOptions = {
|
|
171
|
+
const dialOptions: DialProtocolOptions = {};
|
|
172
|
+
if (maxOutboundStreams !== undefined) dialOptions.maxOutboundStreams = maxOutboundStreams;
|
|
144
173
|
if (runOnLimitedConnection !== undefined)
|
|
145
174
|
dialOptions.runOnLimitedConnection = runOnLimitedConnection;
|
|
146
175
|
|
|
@@ -151,6 +180,7 @@ export async function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp
|
|
|
151
180
|
maxMessageSize,
|
|
152
181
|
onPort,
|
|
153
182
|
window,
|
|
183
|
+
drainTimeoutMs,
|
|
154
184
|
async open(signal) {
|
|
155
185
|
if (!peer) throw new Error("webrun-streams-libp2p: openPort needs `peer`");
|
|
156
186
|
const protocols = window !== undefined ? [windowProtocol, protocol] : protocol;
|
|
@@ -165,7 +195,9 @@ export async function libp2pPortMux(options: Libp2pPortMuxOptions): Promise<Libp
|
|
|
165
195
|
});
|
|
166
196
|
|
|
167
197
|
if (onPort) {
|
|
168
|
-
const handleOptions: StreamHandlerOptions = {
|
|
198
|
+
const handleOptions: StreamHandlerOptions = {};
|
|
199
|
+
if (maxInboundStreams !== undefined) handleOptions.maxInboundStreams = maxInboundStreams;
|
|
200
|
+
if (maxOutboundStreams !== undefined) handleOptions.maxOutboundStreams = maxOutboundStreams;
|
|
169
201
|
if (runOnLimitedConnection !== undefined)
|
|
170
202
|
handleOptions.runOnLimitedConnection = runOnLimitedConnection;
|
|
171
203
|
const served = window !== undefined ? [protocol, windowProtocol] : [protocol];
|
package/src/shared.ts
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { PeerId } from "@libp2p/interface";
|
|
2
|
+
import type { Duplex } from "@statewalker/webrun-streams";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The protocol id `connect`/`serve` are configured with unless told otherwise.
|
|
6
|
+
* Their calls negotiate `portProtocolOf(protocol)` (with `/window`); the id
|
|
7
|
+
* itself is the deprecated protocol, still served and dialled as a fallback
|
|
8
|
+
* for one release (statewalker/webrun-wire#153).
|
|
9
|
+
*/
|
|
10
|
+
export const DEFAULT_PROTOCOL = "/webrun-streams/1.0.0";
|
|
11
|
+
|
|
12
|
+
/** What the serving side knows about the connection a call arrived on. */
|
|
13
|
+
export interface ConnectionContext {
|
|
14
|
+
/**
|
|
15
|
+
* The peer id libp2p's Noise handshake proved for this connection. This is
|
|
16
|
+
* the only identity claim on the serving side that cannot be forged by the
|
|
17
|
+
* request payload.
|
|
18
|
+
*/
|
|
19
|
+
remotePeer: PeerId;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Builds a handler for one inbound call. Called once per call (one port, or one
|
|
24
|
+
* stream of the deprecated protocol), so the connection stays reachable in the
|
|
25
|
+
* returned Duplex's closure — `Duplex` is bytes-only (ADR-0004) and gains no
|
|
26
|
+
* new parameter.
|
|
27
|
+
*/
|
|
28
|
+
export type ServeConnectionsHandler = (context: ConnectionContext) => Duplex;
|