@minip2p/core 0.7.4 → 0.7.6

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/dist/sdk.js CHANGED
@@ -1,12 +1,21 @@
1
1
  /* oxlint-disable default-case, func-style, max-classes-per-file, no-await-in-loop, no-empty-function, no-loop-func, no-use-before-define, promise/avoid-new, promise/prefer-await-to-callbacks, promise/prefer-await-to-then, typescript/no-invalid-void-type, unicorn/consistent-function-scoping, unicorn/no-new-array, unicorn/no-useless-spread, unicorn/no-useless-undefined -- Promise adapters, sequential async iterators, void event payloads, snapshot fan-out, and bounded queues are deliberate SDK internals. */
2
- import { AbortError, ClosedError, ConnectCancelledError, ConnectFailedError, ConnectResultLostError, ConnectResultUnavailableError, DriverFailedError, EventQueueOverflowError, OpenStreamError, PeerDisconnectedError, StreamClosedError, TimeoutError, } from "./errors.js";
2
+ import { AbortError, ClosedError, ConnectCancelledError, ConnectFailedError, ConnectResultLostError, ConnectResultUnavailableError, DriverFailedError, EventQueueOverflowError, OpenStreamError, PeerDisconnectedError, StreamClosedError, TimeoutError, WriteBufferFullError, } from "./errors.js";
3
3
  import { P2pEvent_Tags, PathKind_Tags } from "./types.js";
4
4
  const DEFAULT_TIMEOUT_MS = 65_000;
5
5
  const EVENT_QUEUE_CAP = 4096;
6
6
  const EVENT_FLUSH_BATCH = 256;
7
7
  const CONNECT_TERMINAL_CAP = 1024;
8
- const STREAM_CHUNK_CAP = 64;
9
- const STREAM_BYTE_CAP = 1024 * 1024;
8
+ /** Default per-stream write high-water mark: one Yamux stream send cap. */
9
+ const DEFAULT_WRITE_HIGH_WATER_MARK = 256 * 1024;
10
+ /** Native events routed to one {@link Stream} after it became ready. */
11
+ const STREAM_EVENT_TAGS = [
12
+ P2pEvent_Tags.StreamData,
13
+ P2pEvent_Tags.StreamRemoteWriteClosed,
14
+ P2pEvent_Tags.StreamWriteAccepted,
15
+ P2pEvent_Tags.StreamWriteStopped,
16
+ P2pEvent_Tags.StreamClosed,
17
+ ];
18
+ const isStreamEvent = (event) => STREAM_EVENT_TAGS.includes(event.tag);
10
19
  class BoundedQueue {
11
20
  #items;
12
21
  #head = 0;
@@ -45,6 +54,245 @@ class BoundedQueue {
45
54
  this.#size = 0;
46
55
  }
47
56
  }
57
+ /** An unbounded queue whose `shift` is O(1), unlike `Array#shift`. */
58
+ class Fifo {
59
+ #items = [];
60
+ #head = 0;
61
+ get length() {
62
+ return this.#items.length - this.#head;
63
+ }
64
+ push(item) {
65
+ this.#items.push(item);
66
+ }
67
+ shift() {
68
+ if (this.#head === this.#items.length) {
69
+ return undefined;
70
+ }
71
+ const item = this.#items[this.#head];
72
+ this.#items[this.#head] = undefined;
73
+ this.#head += 1;
74
+ // Drop the consumed prefix once it is at least half the array.
75
+ if (this.#head * 2 >= this.#items.length) {
76
+ this.#items = this.#items.slice(this.#head);
77
+ this.#head = 0;
78
+ }
79
+ return item;
80
+ }
81
+ clear() {
82
+ this.#items = [];
83
+ this.#head = 0;
84
+ }
85
+ }
86
+ /**
87
+ * Native events that are never dropped, because stream and connection state
88
+ * depends on each one (ADR 0012), plus the driver failure that ends them.
89
+ */
90
+ const LOSSLESS_TAGS = new Set([
91
+ P2pEvent_Tags.StreamReady,
92
+ ...STREAM_EVENT_TAGS,
93
+ P2pEvent_Tags.ConnectionClosed,
94
+ P2pEvent_Tags.ConnectionReplaced,
95
+ P2pEvent_Tags.DriverFailed,
96
+ ]);
97
+ /** Returns `next` appended to `last` when both are data for one stream. */
98
+ const coalesceData = (last, next) => {
99
+ if (last.source !== "native" ||
100
+ next.source !== "native" ||
101
+ last.event.tag !== P2pEvent_Tags.StreamData ||
102
+ next.event.tag !== P2pEvent_Tags.StreamData) {
103
+ return undefined;
104
+ }
105
+ const { inner } = last.event;
106
+ const { inner: added } = next.event;
107
+ if (inner.peerId !== added.peerId ||
108
+ inner.connId !== added.connId ||
109
+ inner.streamId !== added.streamId) {
110
+ return undefined;
111
+ }
112
+ const data = new Uint8Array(inner.data.byteLength + added.data.byteLength);
113
+ data.set(new Uint8Array(inner.data));
114
+ data.set(new Uint8Array(added.data), inner.data.byteLength);
115
+ const event = {
116
+ inner: { ...inner, data: data.buffer },
117
+ tag: P2pEvent_Tags.StreamData,
118
+ };
119
+ return { event, source: "native" };
120
+ };
121
+ /**
122
+ * Values keyed by a stream's public connection and stream IDs, without
123
+ * building a key per lookup. Public connection IDs never repeat and each
124
+ * names one peer's connection, so the pair names the stream.
125
+ */
126
+ class StreamTable {
127
+ #byConnection = new Map();
128
+ get(connId, streamId) {
129
+ return this.#byConnection.get(connId)?.get(streamId);
130
+ }
131
+ has(connId, streamId) {
132
+ return this.#byConnection.get(connId)?.has(streamId) ?? false;
133
+ }
134
+ set(connId, streamId, value) {
135
+ let streams = this.#byConnection.get(connId);
136
+ if (streams === undefined) {
137
+ streams = new Map();
138
+ this.#byConnection.set(connId, streams);
139
+ }
140
+ streams.set(streamId, value);
141
+ }
142
+ delete(connId, streamId) {
143
+ const streams = this.#byConnection.get(connId);
144
+ if (streams?.delete(streamId) === true && streams.size === 0) {
145
+ this.#byConnection.delete(connId);
146
+ }
147
+ }
148
+ /** Removes and returns every value on `connId`. */
149
+ takeConnection(connId) {
150
+ const streams = this.#byConnection.get(connId);
151
+ this.#byConnection.delete(connId);
152
+ return streams === undefined ? [] : [...streams.values()];
153
+ }
154
+ /** A snapshot of every value. */
155
+ values() {
156
+ return [...this.#byConnection.values()].flatMap((streams) => [
157
+ ...streams.values(),
158
+ ]);
159
+ }
160
+ /** Removes and returns every value. */
161
+ takeAll() {
162
+ const values = this.values();
163
+ this.#byConnection.clear();
164
+ return values;
165
+ }
166
+ }
167
+ /** The native per-stream event an item carries, if any. */
168
+ const streamEventOf = (item) => item.source === "native" &&
169
+ (item.event.tag === P2pEvent_Tags.StreamReady || isStreamEvent(item.event))
170
+ ? item.event
171
+ : undefined;
172
+ /**
173
+ * The endpoint's shared event queue, in delivery order.
174
+ *
175
+ * Stream events and connection-end events (plus `DriverFailed`) never drop,
176
+ * and adjacent data for one stream coalesces into one event, so native
177
+ * receive budgets bound them; they do not count against the capacity. Past `capacity` other items, the oldest
178
+ * gossipsub message is dropped first, then the oldest other item.
179
+ *
180
+ * A peer-opened stream that closes without data before its `StreamReady`
181
+ * is dispatched leaves the queue whole, so a peer opening and closing
182
+ * streams cannot grow it; its events still reach `release`.
183
+ */
184
+ class EventQueue {
185
+ #items = new Map();
186
+ /** Droppable messages, then other droppable items, oldest first. */
187
+ #messages = new Set();
188
+ #others = new Set();
189
+ /**
190
+ * Peer-opened streams whose `StreamReady` is still queued, with their
191
+ * queued item ids; `undefined` once one carried data.
192
+ */
193
+ #unseen = new StreamTable();
194
+ #capacity;
195
+ #release;
196
+ #next = 0;
197
+ #newest;
198
+ constructor(capacity, release) {
199
+ this.#capacity = capacity;
200
+ this.#release = release;
201
+ }
202
+ get length() {
203
+ return this.#items.size;
204
+ }
205
+ /** Appends `item`, returning the item dropped to make room, if any. */
206
+ push(item) {
207
+ const newest = this.#newest === undefined ? undefined : this.#items.get(this.#newest);
208
+ const merged = newest === undefined ? undefined : coalesceData(newest, item);
209
+ if (merged !== undefined && this.#newest !== undefined) {
210
+ // A data event retires no adapter IDs, so the absorbed one needs no
211
+ // `eventHandled`.
212
+ this.#items.set(this.#newest, merged);
213
+ return undefined;
214
+ }
215
+ const id = this.#next;
216
+ this.#next += 1;
217
+ if (this.#elideUnseen(item, id)) {
218
+ return undefined;
219
+ }
220
+ this.#items.set(id, item);
221
+ this.#newest = id;
222
+ if (item.source === "native" && item.event.tag === P2pEvent_Tags.Message) {
223
+ this.#messages.add(id);
224
+ }
225
+ else if (item.source !== "native" || !LOSSLESS_TAGS.has(item.event.tag)) {
226
+ this.#others.add(id);
227
+ }
228
+ if (this.#messages.size + this.#others.size <= this.#capacity) {
229
+ return undefined;
230
+ }
231
+ const [victim] = this.#messages.size > 0 ? this.#messages : this.#others;
232
+ return victim === undefined ? undefined : this.#remove(victim);
233
+ }
234
+ shift() {
235
+ const [oldest] = this.#items.keys();
236
+ if (oldest === undefined) {
237
+ return undefined;
238
+ }
239
+ const item = this.#remove(oldest);
240
+ if (item?.source === "native" &&
241
+ item.event.tag === P2pEvent_Tags.StreamReady) {
242
+ this.#unseen.delete(item.event.inner.connId, item.event.inner.streamId);
243
+ }
244
+ return item;
245
+ }
246
+ /**
247
+ * Records `item` (as `id`) against an unseen peer stream. Returns whether
248
+ * it closed one that carried no data, which leaves the queue whole.
249
+ */
250
+ #elideUnseen(item, id) {
251
+ const event = streamEventOf(item);
252
+ if (event === undefined) {
253
+ return false;
254
+ }
255
+ const { connId, streamId } = event.inner;
256
+ if (event.tag === P2pEvent_Tags.StreamReady) {
257
+ if (!event.inner.initiatedLocally) {
258
+ this.#unseen.set(connId, streamId, [id]);
259
+ }
260
+ return false;
261
+ }
262
+ if (!this.#unseen.has(connId, streamId)) {
263
+ return false;
264
+ }
265
+ const ids = this.#unseen.get(connId, streamId);
266
+ if (event.tag === P2pEvent_Tags.StreamData) {
267
+ this.#unseen.set(connId, streamId, undefined);
268
+ }
269
+ else if (ids !== undefined && event.tag === P2pEvent_Tags.StreamClosed) {
270
+ this.#unseen.delete(connId, streamId);
271
+ for (const queued of ids) {
272
+ const removed = this.#remove(queued);
273
+ if (removed !== undefined) {
274
+ this.#release(removed);
275
+ }
276
+ }
277
+ this.#release(item);
278
+ return true;
279
+ }
280
+ else {
281
+ ids?.push(id);
282
+ }
283
+ return false;
284
+ }
285
+ #remove(id) {
286
+ const item = this.#items.get(id);
287
+ this.#items.delete(id);
288
+ this.#messages.delete(id);
289
+ this.#others.delete(id);
290
+ if (this.#newest === id) {
291
+ this.#newest = undefined;
292
+ }
293
+ return item;
294
+ }
295
+ }
48
296
  /** A negotiated custom-protocol stream with exclusive pull or flowing reads. */
49
297
  export class Stream {
50
298
  /** Remote peer that owns the other end of this stream. */
@@ -59,23 +307,48 @@ export class Stream {
59
307
  initiatedLocally;
60
308
  #backend;
61
309
  #onTerminal;
310
+ #consume;
62
311
  #listeners = new Map();
63
- #fifo = [];
312
+ #fifo = new Fifo();
64
313
  #reads = [];
65
314
  #fifoBytes = 0;
66
315
  #mode;
67
316
  #receiveState = { kind: "receiving" };
68
317
  #closed = false;
318
+ /** Writes not yet accepted by native, oldest (possibly in flight) first. */
319
+ #writes = [];
320
+ #writeBytes = 0;
321
+ /** Native holds the head write's tail until `StreamWriteAccepted`. */
322
+ #writeInFlight = false;
323
+ /** Why later writes fail: `closeWrite`, a remote stop, or a terminal. */
324
+ #writeEnded;
325
+ #closeWriteQueued = false;
326
+ /**
327
+ * Most bytes the stream buffers before {@link write} rejects with
328
+ * {@link WriteBufferFullError}, counting the write native is still taking.
329
+ * A write into an empty buffer is always admitted, whatever its size.
330
+ */
331
+ writeHighWaterMark = DEFAULT_WRITE_HIGH_WATER_MARK;
69
332
  constructor(backend, meta, onTerminal) {
70
333
  this.#backend = backend;
71
334
  this.#onTerminal = onTerminal;
335
+ this.#consume = streamConsumer(backend, meta);
72
336
  this.peerId = meta.peerId;
73
337
  this.protocolId = meta.protocolId;
74
338
  this.streamId = meta.streamId;
75
339
  this.connId = meta.connId;
76
340
  this.initiatedLocally = meta.initiatedLocally;
77
341
  }
78
- /** Subscribes to stream lifecycle or data events. */
342
+ /**
343
+ * Subscribes to stream lifecycle or data events.
344
+ *
345
+ * A chunk counts as consumed once every `data` handler has returned, and
346
+ * only consumed bytes let the sender continue: a stream delivers at most
347
+ * one receive window that has not been consumed. An `async` handler is
348
+ * consumed when it returns its Promise, not when that Promise settles; to
349
+ * hold the sender back while asynchronous work runs, use {@link read}
350
+ * instead.
351
+ */
79
352
  on(type, handler) {
80
353
  if (type === "data") {
81
354
  if (this.#mode === "pull") {
@@ -104,6 +377,11 @@ export class Stream {
104
377
  /**
105
378
  * Reads the next buffered chunk, or `undefined` after the remote write side
106
379
  * closes. Pull reads and flowing `data` handlers are mutually exclusive.
380
+ *
381
+ * Returning a chunk consumes it, which lets the sender continue: the
382
+ * stream delivers at most one receive window that has not been read, so a
383
+ * reader that stops calling `read()` stalls its sender rather than
384
+ * buffering without bound.
107
385
  */
108
386
  read() {
109
387
  if (this.#mode === "flowing") {
@@ -113,48 +391,102 @@ export class Stream {
113
391
  if (this.#receiveState.kind === "failed") {
114
392
  return Promise.reject(this.#receiveState.error);
115
393
  }
116
- const buffered = this.#shift();
117
- if (buffered !== undefined) {
394
+ const buffered = this.#take();
395
+ if (buffered !== undefined || this.#receiveState.kind === "eof") {
118
396
  return Promise.resolve(buffered);
119
397
  }
120
- if (this.#receiveState.kind === "eof") {
121
- return Promise.resolve(this.#shift());
122
- }
123
398
  return new Promise((resolve, reject) => {
124
399
  this.#reads.push({ reject, resolve });
125
400
  });
126
401
  }
127
- /** Writes UTF-8 text or bytes to the stream. */
402
+ /**
403
+ * Writes UTF-8 text or bytes to the stream, resolving once native has
404
+ * accepted every byte. Writes are delivered in call order.
405
+ *
406
+ * Rejects with {@link WriteBufferFullError} when the stream already
407
+ * buffers {@link writeHighWaterMark} bytes (a first write is always
408
+ * admitted, so a payload larger than the mark can still be sent), and with
409
+ * a closed error after `closeWrite()`, a remote stop, or the stream
410
+ * closing.
411
+ *
412
+ * A write queued behind a pending one keeps a reference to `data`, and
413
+ * native reads it only when the write reaches the head of the queue: leave
414
+ * the buffer untouched until the Promise settles.
415
+ */
128
416
  write(data) {
129
417
  if (this.#closed) {
130
- throw new ClosedError();
418
+ return Promise.reject(new ClosedError());
131
419
  }
132
- this.#backend.sendStream(this.peerId, this.connId, this.streamId, toUint8Array(data));
420
+ if (this.#writeEnded !== undefined) {
421
+ return Promise.reject(this.#writeEnded);
422
+ }
423
+ const bytes = toUint8Array(data);
424
+ if (this.#writeBytes > 0 &&
425
+ this.#writeBytes + bytes.byteLength > this.writeHighWaterMark) {
426
+ return Promise.reject(new WriteBufferFullError(this.#writeBytes, this.writeHighWaterMark));
427
+ }
428
+ return new Promise((resolve, reject) => {
429
+ this.#writes.push({ data: bytes, reject, resolve });
430
+ this.#writeBytes += bytes.byteLength;
431
+ this.#pumpWrites();
432
+ });
133
433
  }
134
- /** Half-closes the local write side while keeping reads available. */
434
+ /**
435
+ * Half-closes the local write side once every earlier write has been
436
+ * accepted, keeping reads available. Later writes reject.
437
+ *
438
+ * With no write pending the close goes to native now and throws if native
439
+ * refuses it. Behind pending writes it is queued, and a close native then
440
+ * refuses is reported by the stream's terminal event instead.
441
+ */
135
442
  closeWrite() {
136
- if (!this.#closed) {
443
+ if (this.#closed || this.#writeEnded !== undefined) {
444
+ return;
445
+ }
446
+ this.#writeEnded = new StreamClosedError("The stream write side closed");
447
+ if (this.#writes.length === 0) {
137
448
  this.#backend.closeStreamWrite(this.peerId, this.connId, this.streamId);
449
+ return;
138
450
  }
451
+ this.#closeWriteQueued = true;
139
452
  }
140
- /** Abruptly resets the stream and emits `closed`. */
453
+ /**
454
+ * Abruptly resets the stream and emits `closed`. On a stream that already
455
+ * closed, discards unread bytes instead.
456
+ */
141
457
  reset() {
142
- if (!this.#closed) {
143
- this.#backend.resetStream(this.peerId, this.connId, this.streamId);
144
- this.terminal();
458
+ if (this.#closed) {
459
+ this.#discardUnread();
460
+ return;
145
461
  }
462
+ this.#backend.resetStream(this.peerId, this.connId, this.streamId);
463
+ this.terminal();
146
464
  }
147
- /** Relinquishes the stream and requests a reset while it remains active. */
465
+ /**
466
+ * Relinquishes the stream and requests a reset while it remains active.
467
+ * On a stream that already closed, discards unread bytes instead.
468
+ */
148
469
  abandon() {
149
- if (!this.#closed) {
150
- try {
151
- this.#backend.abandonStream(this.peerId, this.connId, this.streamId);
152
- }
153
- catch {
154
- // A native close can overtake its queued terminal event.
155
- }
156
- this.terminal();
470
+ if (this.#closed) {
471
+ this.#discardUnread();
472
+ return;
473
+ }
474
+ try {
475
+ this.#backend.abandonStream(this.peerId, this.connId, this.streamId);
476
+ }
477
+ catch {
478
+ // A native close can overtake its queued terminal event.
157
479
  }
480
+ this.terminal();
481
+ }
482
+ /**
483
+ * A cleanly closed stream keeps unread bytes for later reads, and they
484
+ * hold its native stream slot until consumed; discarding them releases it.
485
+ */
486
+ #discardUnread() {
487
+ this.#consumed(this.#fifoBytes);
488
+ this.#fifo.clear();
489
+ this.#fifoBytes = 0;
158
490
  }
159
491
  [Symbol.dispose]() {
160
492
  this.abandon();
@@ -182,23 +514,44 @@ export class Stream {
182
514
  const read = this.#reads.shift();
183
515
  if (read !== undefined) {
184
516
  read.resolve(chunk);
517
+ this.#consumed(chunk.byteLength);
185
518
  return;
186
519
  }
187
520
  if (this.#mode === "flowing") {
188
- this.#emit("data", chunk);
189
- return;
190
- }
191
- if (this.#fifo.length >= STREAM_CHUNK_CAP ||
192
- this.#fifoBytes + chunk.byteLength > STREAM_BYTE_CAP) {
193
- this.#emit("dataOverflow", {
194
- droppedBytes: chunk.byteLength,
195
- droppedChunks: 1,
196
- });
521
+ this.#emitData(chunk);
197
522
  return;
198
523
  }
524
+ // Unbounded here, because native delivers at most one receive window
525
+ // that has not been consumed.
199
526
  this.#fifo.push(chunk);
200
527
  this.#fifoBytes += chunk.byteLength;
201
528
  }
529
+ /**
530
+ * Native accepted the whole in-flight write.
531
+ * @internal
532
+ */
533
+ writeAccepted() {
534
+ if (!this.#writeInFlight) {
535
+ return;
536
+ }
537
+ this.#writeInFlight = false;
538
+ this.#settleHead();
539
+ this.#pumpWrites();
540
+ }
541
+ /**
542
+ * The remote asked this side to stop writing.
543
+ * @internal
544
+ */
545
+ writeStopped(errorCode) {
546
+ if (this.#closed) {
547
+ return;
548
+ }
549
+ const error = new StreamClosedError(`The remote stopped reading this stream (code ${errorCode})`);
550
+ this.#writeEnded ??= error;
551
+ this.#closeWriteQueued = false;
552
+ this.#failWrites(error);
553
+ this.#emit("writeStopped", { errorCode });
554
+ }
202
555
  /** @internal */
203
556
  remoteWriteClosed() {
204
557
  if (this.#closed || this.#receiveState.kind !== "receiving") {
@@ -218,17 +571,17 @@ export class Stream {
218
571
  return;
219
572
  }
220
573
  this.#closed = true;
574
+ this.#failWrites(error);
221
575
  // StreamClosed carries no cause. Once the remote FIN establishes EOF,
222
576
  // later full closure cannot reinterpret that receive-side outcome.
223
577
  const hasRemoteEof = options.preserveRemoteEof === true && this.#receiveState.kind === "eof";
224
578
  if (!hasRemoteEof) {
225
579
  this.#receiveState = { error, kind: "failed" };
226
- this.#fifo.length = 0;
227
- this.#fifoBytes = 0;
580
+ this.#discardUnread();
228
581
  }
229
582
  for (const read of this.#reads.splice(0)) {
230
583
  if (hasRemoteEof) {
231
- read.resolve(this.#shift());
584
+ read.resolve(this.#take());
232
585
  }
233
586
  else {
234
587
  read.reject(error);
@@ -238,21 +591,98 @@ export class Stream {
238
591
  this.#listeners.clear();
239
592
  this.#onTerminal();
240
593
  }
594
+ /**
595
+ * Hands queued writes to native one at a time. A write native accepts only
596
+ * in part stays at the head until `StreamWriteAccepted`, which keeps
597
+ * writes, and the queued close, in order.
598
+ */
599
+ #pumpWrites() {
600
+ while (!this.#writeInFlight && !this.#closed) {
601
+ const [head] = this.#writes;
602
+ if (head === undefined) {
603
+ if (this.#closeWriteQueued) {
604
+ this.#closeWriteQueued = false;
605
+ try {
606
+ this.#backend.closeStreamWrite(this.peerId, this.connId, this.streamId);
607
+ }
608
+ catch {
609
+ // A deferred close has no caller left to throw to; the stream
610
+ // already ended, and its terminal event reports that.
611
+ }
612
+ }
613
+ return;
614
+ }
615
+ let accepted;
616
+ try {
617
+ accepted = this.#backend.sendStream(this.peerId, this.connId, this.streamId, head.data);
618
+ }
619
+ catch (error) {
620
+ this.#failWrites(error);
621
+ return;
622
+ }
623
+ if (!accepted) {
624
+ this.#writeInFlight = true;
625
+ return;
626
+ }
627
+ this.#settleHead();
628
+ }
629
+ }
630
+ #settleHead() {
631
+ const head = this.#writes.shift();
632
+ if (head !== undefined) {
633
+ this.#writeBytes -= head.data.byteLength;
634
+ head.resolve();
635
+ }
636
+ }
637
+ #failWrites(error) {
638
+ this.#writeInFlight = false;
639
+ this.#writeBytes = 0;
640
+ for (const write of this.#writes.splice(0)) {
641
+ write.reject(error);
642
+ }
643
+ }
644
+ /**
645
+ * Hands buffered chunks to `data` handlers. After a clean close the
646
+ * buffer still holds the bytes that arrived before EOF (a failed stream
647
+ * has already discarded them), so a late handler drains it too.
648
+ */
241
649
  #flushFlowing() {
242
- while (this.#fifo.length > 0 && !this.#closed) {
243
- const chunk = this.#shift();
650
+ while (this.#fifo.length > 0) {
651
+ const chunk = this.#fifo.shift();
244
652
  if (chunk !== undefined) {
245
- this.#emit("data", chunk);
653
+ this.#fifoBytes -= chunk.byteLength;
654
+ this.#emitData(chunk);
246
655
  }
247
656
  }
248
657
  }
249
- #shift() {
658
+ /** Hands `chunk` to every `data` handler; it is consumed once they return. */
659
+ #emitData(chunk) {
660
+ // Counted first: a handler may transfer the buffer, detaching it.
661
+ const bytes = chunk.byteLength;
662
+ this.#emit("data", chunk);
663
+ this.#consumed(bytes);
664
+ }
665
+ /** Takes the oldest buffered chunk for a reader, consuming it. */
666
+ #take() {
250
667
  const chunk = this.#fifo.shift();
251
668
  if (chunk !== undefined) {
252
669
  this.#fifoBytes -= chunk.byteLength;
670
+ this.#consumed(chunk.byteLength);
253
671
  }
254
672
  return chunk;
255
673
  }
674
+ /** Acknowledges consumed bytes to native, letting the sender continue. */
675
+ #consumed(bytes) {
676
+ if (bytes === 0) {
677
+ return;
678
+ }
679
+ try {
680
+ this.#consume(bytes);
681
+ }
682
+ catch {
683
+ // The stream or its connection is already gone natively.
684
+ }
685
+ }
256
686
  #emit(type, payload) {
257
687
  for (const handler of [...(this.#listeners.get(type) ?? [])]) {
258
688
  try {
@@ -264,6 +694,27 @@ export class Stream {
264
694
  }
265
695
  }
266
696
  }
697
+ /**
698
+ * The backend's acknowledgement function for a stream. A connection whose
699
+ * end the adapter already saw has nothing left to settle.
700
+ */
701
+ const streamConsumer = (backend, meta) => {
702
+ try {
703
+ return backend.streamConsumer(meta.connId, meta.streamId);
704
+ }
705
+ catch {
706
+ return () => { };
707
+ }
708
+ };
709
+ /** Acknowledges data that arrived for a stream the SDK no longer tracks. */
710
+ const consumeUntracked = (backend, inner) => {
711
+ try {
712
+ backend.streamConsumer(inner.connId, inner.streamId)(inner.data.byteLength);
713
+ }
714
+ catch {
715
+ // Settled already, or its connection is gone: nothing to release.
716
+ }
717
+ };
267
718
  /**
268
719
  * Promise-first, platform-neutral owner for one native minip2p endpoint.
269
720
  *
@@ -276,11 +727,13 @@ export class Minip2pBase {
276
727
  #catchAll = new Set();
277
728
  #closeHandlers = new Set();
278
729
  #waiters = new Set();
279
- #queue = new BoundedQueue(EVENT_QUEUE_CAP);
730
+ #queue = new EventQueue(EVENT_QUEUE_CAP, (item) => {
731
+ this.#releaseQueueItem(item);
732
+ });
280
733
  #connects = new Map();
281
734
  #terminalConnects = new Set();
282
- #streams = new Map();
283
- #pendingOpens = new Map();
735
+ #streams = new StreamTable();
736
+ #pendingOpens = new StreamTable();
284
737
  #pings = new Map();
285
738
  #dropped = 0;
286
739
  #flushScheduled = false;
@@ -627,8 +1080,7 @@ export class Minip2pBase {
627
1080
  pending.removeAbort = listenAbort(options.signal, () => {
628
1081
  this.#expireOpen(pending, new AbortError());
629
1082
  });
630
- const key = pendingOpenKey(peerId, identity.connId, identity.streamId);
631
- const overwritten = this.#pendingOpens.get(key);
1083
+ const overwritten = this.#pendingOpens.get(identity.connId, identity.streamId);
632
1084
  if (overwritten !== undefined) {
633
1085
  clearPendingOpen(overwritten);
634
1086
  overwritten.reject(new OpenStreamError({
@@ -639,7 +1091,7 @@ export class Minip2pBase {
639
1091
  streamId: overwritten.streamId,
640
1092
  }));
641
1093
  }
642
- this.#pendingOpens.set(key, pending);
1094
+ this.#pendingOpens.set(identity.connId, identity.streamId, pending);
643
1095
  });
644
1096
  }
645
1097
  /**
@@ -827,7 +1279,7 @@ export class Minip2pBase {
827
1279
  this.#connectResultsLost(event.inner.terminalConnectIds);
828
1280
  }
829
1281
  }
830
- for (const pending of this.#pendingOpens.values()) {
1282
+ for (const pending of this.#pendingOpens.takeAll()) {
831
1283
  clearPendingOpen(pending);
832
1284
  pending.reject(error);
833
1285
  try {
@@ -837,7 +1289,6 @@ export class Minip2pBase {
837
1289
  // The operation is already failed; native cleanup is best effort.
838
1290
  }
839
1291
  }
840
- this.#pendingOpens.clear();
841
1292
  }
842
1293
  #enqueueNative(event) {
843
1294
  if (this.#closed) {
@@ -923,9 +1374,7 @@ export class Minip2pBase {
923
1374
  this.#streamReady(event.inner);
924
1375
  return;
925
1376
  }
926
- if (event.tag === P2pEvent_Tags.StreamData ||
927
- event.tag === P2pEvent_Tags.StreamRemoteWriteClosed ||
928
- event.tag === P2pEvent_Tags.StreamClosed) {
1377
+ if (isStreamEvent(event)) {
929
1378
  this.#streamEvent(event);
930
1379
  return;
931
1380
  }
@@ -933,12 +1382,12 @@ export class Minip2pBase {
933
1382
  this.#correlateOpenError(event.inner);
934
1383
  }
935
1384
  if (event.tag === P2pEvent_Tags.ConnectionClosed) {
936
- this.#connectionEnded(event.inner.peerId, event.inner.connId, new PeerDisconnectedError(event.inner.peerId, "stream"), new PeerDisconnectedError(event.inner.peerId, "openStream"));
1385
+ this.#connectionEnded(event.inner.connId, new PeerDisconnectedError(event.inner.peerId, "stream"), new PeerDisconnectedError(event.inner.peerId, "openStream"));
937
1386
  }
938
1387
  if (event.tag === P2pEvent_Tags.ConnectionReplaced) {
939
1388
  // Native ends the replaced connection's streams without per-stream
940
1389
  // terminal events, so they end here.
941
- this.#connectionEnded(event.inner.peerId, event.inner.oldConnId, new StreamClosedError("The stream's connection was replaced"), new StreamClosedError("The stream's connection was replaced before it became ready"));
1390
+ this.#connectionEnded(event.inner.oldConnId, new StreamClosedError("The stream's connection was replaced"), new StreamClosedError("The stream's connection was replaced before it became ready"));
942
1391
  }
943
1392
  if (isConnectTerminal(event)) {
944
1393
  this.#connectTerminal(event);
@@ -947,17 +1396,17 @@ export class Minip2pBase {
947
1396
  this.#connectResultsLost(event.inner.terminalConnectIds);
948
1397
  }
949
1398
  const normalized = normalizeEvent(event);
950
- if (normalized !== undefined) {
951
- this.#dispatch(normalized.type, normalized.payload, normalized.payload);
952
- }
1399
+ this.#dispatch(normalized.type, normalized.payload, normalized.payload);
953
1400
  }
954
1401
  #dispatch(type, payload, catchPayload) {
955
1402
  let claimed = false;
956
- const result = eventResult(type, payload);
957
- for (const waiter of [...this.#waiters]) {
1403
+ // Built only once a waiter of this type is found.
1404
+ let result;
1405
+ for (const waiter of this.#waiters.size > 0 ? [...this.#waiters] : []) {
958
1406
  if (waiter.type !== type) {
959
1407
  continue;
960
1408
  }
1409
+ result ??= eventResult(type, payload);
961
1410
  let matched = false;
962
1411
  try {
963
1412
  matched = waiter.predicate(result);
@@ -986,7 +1435,8 @@ export class Minip2pBase {
986
1435
  this.#handlerFailed(type, payload, error);
987
1436
  }
988
1437
  }
989
- if (type !== "stream") {
1438
+ if (type !== "stream" && this.#catchAll.size > 0) {
1439
+ // Its own object: a waiter's resolved event is never a catch-all's.
990
1440
  const catchEvent = eventResult(type, catchPayload);
991
1441
  for (const handler of [...this.#catchAll]) {
992
1442
  try {
@@ -1012,15 +1462,13 @@ export class Minip2pBase {
1012
1462
  });
1013
1463
  }
1014
1464
  #streamReady(meta) {
1015
- const key = streamKey(meta.peerId, meta.connId, meta.streamId);
1016
1465
  const stream = new Stream(this.#backend, meta, () => {
1017
- this.#streams.delete(key);
1466
+ this.#streams.delete(meta.connId, meta.streamId);
1018
1467
  });
1019
- this.#streams.set(key, stream);
1020
- const pendingKey = pendingOpenKey(meta.peerId, meta.connId, meta.streamId);
1021
- const pending = this.#pendingOpens.get(pendingKey);
1468
+ this.#streams.set(meta.connId, meta.streamId, stream);
1469
+ const pending = this.#pendingOpens.get(meta.connId, meta.streamId);
1022
1470
  if (pending !== undefined && meta.initiatedLocally) {
1023
- this.#pendingOpens.delete(pendingKey);
1471
+ this.#pendingOpens.delete(meta.connId, meta.streamId);
1024
1472
  clearPendingOpen(pending);
1025
1473
  pending.resolve(stream);
1026
1474
  return;
@@ -1052,13 +1500,12 @@ export class Minip2pBase {
1052
1500
  }
1053
1501
  }
1054
1502
  #streamEvent(event) {
1055
- const { peerId, connId, streamId } = event.inner;
1056
- const stream = this.#streams.get(streamKey(peerId, connId, streamId));
1503
+ const { connId, streamId } = event.inner;
1504
+ const stream = this.#streams.get(connId, streamId);
1057
1505
  if (event.tag === P2pEvent_Tags.StreamClosed) {
1058
- const pendingKey = pendingOpenKey(peerId, connId, streamId);
1059
- const pending = this.#pendingOpens.get(pendingKey);
1506
+ const pending = this.#pendingOpens.get(connId, streamId);
1060
1507
  if (pending !== undefined) {
1061
- this.#pendingOpens.delete(pendingKey);
1508
+ this.#pendingOpens.delete(connId, streamId);
1062
1509
  clearPendingOpen(pending);
1063
1510
  pending.reject(new StreamClosedError());
1064
1511
  }
@@ -1067,7 +1514,21 @@ export class Minip2pBase {
1067
1514
  });
1068
1515
  }
1069
1516
  else if (event.tag === P2pEvent_Tags.StreamData) {
1070
- stream?.receive(event.inner.data);
1517
+ if (stream === undefined) {
1518
+ // Nothing will read it, so it is consumed now: an abandon that
1519
+ // native refused (the stream had already closed there) leaves the
1520
+ // bytes holding the native stream slot otherwise.
1521
+ consumeUntracked(this.#backend, event.inner);
1522
+ }
1523
+ else {
1524
+ stream.receive(event.inner.data);
1525
+ }
1526
+ }
1527
+ else if (event.tag === P2pEvent_Tags.StreamWriteAccepted) {
1528
+ stream?.writeAccepted();
1529
+ }
1530
+ else if (event.tag === P2pEvent_Tags.StreamWriteStopped) {
1531
+ stream?.writeStopped(event.inner.errorCode);
1071
1532
  }
1072
1533
  else {
1073
1534
  stream?.remoteWriteClosed();
@@ -1077,7 +1538,9 @@ export class Minip2pBase {
1077
1538
  if (error.streamId === undefined) {
1078
1539
  return;
1079
1540
  }
1080
- const candidates = [...this.#pendingOpens.values()].filter((pending) => pending.streamId === error.streamId &&
1541
+ const candidates = this.#pendingOpens
1542
+ .values()
1543
+ .filter((pending) => pending.streamId === error.streamId &&
1081
1544
  (error.peerId === undefined || error.peerId === pending.peerId) &&
1082
1545
  (error.connId === undefined || error.connId === pending.connId));
1083
1546
  if (candidates.length !== 1) {
@@ -1087,7 +1550,7 @@ export class Minip2pBase {
1087
1550
  if (pending === undefined) {
1088
1551
  return;
1089
1552
  }
1090
- this.#pendingOpens.delete(pendingOpenKey(pending.peerId, pending.connId, pending.streamId));
1553
+ this.#pendingOpens.delete(pending.connId, pending.streamId);
1091
1554
  clearPendingOpen(pending);
1092
1555
  pending.reject(new OpenStreamError({
1093
1556
  connId: error.connId,
@@ -1098,19 +1561,13 @@ export class Minip2pBase {
1098
1561
  }));
1099
1562
  }
1100
1563
  /** Ends every stream and pending open on a closed or replaced connection. */
1101
- #connectionEnded(peerId, connId, streamError, openError) {
1102
- for (const [key, stream] of [...this.#streams]) {
1103
- if (stream.peerId === peerId && stream.connId === connId) {
1104
- stream.terminal(streamError);
1105
- this.#streams.delete(key);
1106
- }
1564
+ #connectionEnded(connId, streamError, openError) {
1565
+ for (const stream of this.#streams.takeConnection(connId)) {
1566
+ stream.terminal(streamError);
1107
1567
  }
1108
- for (const pending of [...this.#pendingOpens.values()]) {
1109
- if (pending.peerId === peerId && pending.connId === connId) {
1110
- this.#pendingOpens.delete(pendingOpenKey(pending.peerId, pending.connId, pending.streamId));
1111
- clearPendingOpen(pending);
1112
- pending.reject(openError);
1113
- }
1568
+ for (const pending of this.#pendingOpens.takeConnection(connId)) {
1569
+ clearPendingOpen(pending);
1570
+ pending.reject(openError);
1114
1571
  }
1115
1572
  }
1116
1573
  #connectTerminal(event) {
@@ -1188,11 +1645,10 @@ export class Minip2pBase {
1188
1645
  this.#terminalConnects.delete(connectId);
1189
1646
  }
1190
1647
  #expireOpen(pending, error) {
1191
- const key = pendingOpenKey(pending.peerId, pending.connId, pending.streamId);
1192
- if (this.#pendingOpens.get(key) !== pending) {
1648
+ if (this.#pendingOpens.get(pending.connId, pending.streamId) !== pending) {
1193
1649
  return;
1194
1650
  }
1195
- this.#pendingOpens.delete(key);
1651
+ this.#pendingOpens.delete(pending.connId, pending.streamId);
1196
1652
  clearPendingOpen(pending);
1197
1653
  pending.reject(error);
1198
1654
  try {
@@ -1239,15 +1695,13 @@ export class Minip2pBase {
1239
1695
  }
1240
1696
  this.#connects.clear();
1241
1697
  this.#terminalConnects.clear();
1242
- for (const pending of this.#pendingOpens.values()) {
1698
+ for (const pending of this.#pendingOpens.takeAll()) {
1243
1699
  clearPendingOpen(pending);
1244
1700
  pending.reject(error);
1245
1701
  }
1246
- this.#pendingOpens.clear();
1247
- for (const stream of this.#streams.values()) {
1702
+ for (const stream of this.#streams.takeAll()) {
1248
1703
  stream.terminal(error);
1249
1704
  }
1250
- this.#streams.clear();
1251
1705
  for (const ping of this.#pings.values()) {
1252
1706
  ping.cancel(error);
1253
1707
  }
@@ -1286,43 +1740,44 @@ function toBackendTarget(target) {
1286
1740
  ? { addresses: [target], kind: "addresses" }
1287
1741
  : { kind: "peer", peerId: target };
1288
1742
  }
1743
+ /**
1744
+ * SDK event names for every native event that dispatches by name. Each name
1745
+ * is its tag uncapitalized, so a wrong mapping fails to compile.
1746
+ */
1747
+ const SDK_EVENT_NAMES = {
1748
+ [P2pEvent_Tags.EventsDropped]: "eventsDropped",
1749
+ [P2pEvent_Tags.ConnectionEstablished]: "connectionEstablished",
1750
+ [P2pEvent_Tags.ConnectionClosed]: "connectionClosed",
1751
+ [P2pEvent_Tags.ConnectionReplaced]: "connectionReplaced",
1752
+ [P2pEvent_Tags.PeerReady]: "peerReady",
1753
+ [P2pEvent_Tags.IdentifyReceived]: "identifyReceived",
1754
+ [P2pEvent_Tags.PingRttMeasured]: "pingRttMeasured",
1755
+ [P2pEvent_Tags.PingTimeout]: "pingTimeout",
1756
+ [P2pEvent_Tags.EndpointError]: "endpointError",
1757
+ [P2pEvent_Tags.ReachabilityChanged]: "reachabilityChanged",
1758
+ [P2pEvent_Tags.PublicAddressesChanged]: "publicAddressesChanged",
1759
+ [P2pEvent_Tags.RelayReserved]: "relayReserved",
1760
+ [P2pEvent_Tags.RelayReservationLost]: "relayReservationLost",
1761
+ [P2pEvent_Tags.PathEstablished]: "pathEstablished",
1762
+ [P2pEvent_Tags.InboundPathEstablished]: "inboundPathEstablished",
1763
+ [P2pEvent_Tags.PathUpgraded]: "pathUpgraded",
1764
+ [P2pEvent_Tags.HolePunchFailed]: "holePunchFailed",
1765
+ [P2pEvent_Tags.ConnectFailed]: "connectFailed",
1766
+ [P2pEvent_Tags.ConnectCancelled]: "connectCancelled",
1767
+ [P2pEvent_Tags.InboundDirectUpgrade]: "inboundDirectUpgrade",
1768
+ [P2pEvent_Tags.Message]: "message",
1769
+ [P2pEvent_Tags.PeerSubscribed]: "peerSubscribed",
1770
+ [P2pEvent_Tags.PeerUnsubscribed]: "peerUnsubscribed",
1771
+ [P2pEvent_Tags.GossipsubOutboundFailure]: "gossipsubOutboundFailure",
1772
+ [P2pEvent_Tags.GossipsubProtocolViolation]: "gossipsubProtocolViolation",
1773
+ [P2pEvent_Tags.PeerDiscovered]: "peerDiscovered",
1774
+ [P2pEvent_Tags.PeerUpdated]: "peerUpdated",
1775
+ [P2pEvent_Tags.PeerExpired]: "peerExpired",
1776
+ [P2pEvent_Tags.DiscoveryDialFailed]: "discoveryDialFailed",
1777
+ [P2pEvent_Tags.DiscoveryProtocolViolation]: "discoveryProtocolViolation",
1778
+ };
1289
1779
  function normalizeEvent(event) {
1290
- const names = {
1291
- [P2pEvent_Tags.EventsDropped]: "eventsDropped",
1292
- [P2pEvent_Tags.ConnectionEstablished]: "connectionEstablished",
1293
- [P2pEvent_Tags.ConnectionClosed]: "connectionClosed",
1294
- [P2pEvent_Tags.ConnectionReplaced]: "connectionReplaced",
1295
- [P2pEvent_Tags.PeerReady]: "peerReady",
1296
- [P2pEvent_Tags.IdentifyReceived]: "identifyReceived",
1297
- [P2pEvent_Tags.PingRttMeasured]: "pingRttMeasured",
1298
- [P2pEvent_Tags.PingTimeout]: "pingTimeout",
1299
- [P2pEvent_Tags.EndpointError]: "endpointError",
1300
- [P2pEvent_Tags.ReachabilityChanged]: "reachabilityChanged",
1301
- [P2pEvent_Tags.PublicAddressesChanged]: "publicAddressesChanged",
1302
- [P2pEvent_Tags.RelayReserved]: "relayReserved",
1303
- [P2pEvent_Tags.RelayReservationLost]: "relayReservationLost",
1304
- [P2pEvent_Tags.PathEstablished]: "pathEstablished",
1305
- [P2pEvent_Tags.InboundPathEstablished]: "inboundPathEstablished",
1306
- [P2pEvent_Tags.PathUpgraded]: "pathUpgraded",
1307
- [P2pEvent_Tags.HolePunchFailed]: "holePunchFailed",
1308
- [P2pEvent_Tags.ConnectFailed]: "connectFailed",
1309
- [P2pEvent_Tags.ConnectCancelled]: "connectCancelled",
1310
- [P2pEvent_Tags.InboundDirectUpgrade]: "inboundDirectUpgrade",
1311
- [P2pEvent_Tags.Message]: "message",
1312
- [P2pEvent_Tags.PeerSubscribed]: "peerSubscribed",
1313
- [P2pEvent_Tags.PeerUnsubscribed]: "peerUnsubscribed",
1314
- [P2pEvent_Tags.GossipsubOutboundFailure]: "gossipsubOutboundFailure",
1315
- [P2pEvent_Tags.GossipsubProtocolViolation]: "gossipsubProtocolViolation",
1316
- [P2pEvent_Tags.PeerDiscovered]: "peerDiscovered",
1317
- [P2pEvent_Tags.PeerUpdated]: "peerUpdated",
1318
- [P2pEvent_Tags.PeerExpired]: "peerExpired",
1319
- [P2pEvent_Tags.DiscoveryDialFailed]: "discoveryDialFailed",
1320
- [P2pEvent_Tags.DiscoveryProtocolViolation]: "discoveryProtocolViolation",
1321
- };
1322
- const type = names[event.tag];
1323
- if (type === undefined) {
1324
- return undefined;
1325
- }
1780
+ const type = SDK_EVENT_NAMES[event.tag];
1326
1781
  let payload = event.inner;
1327
1782
  if (event.tag === P2pEvent_Tags.PathEstablished) {
1328
1783
  payload = { ...event.inner, path: normalizePath(event.inner.path) };
@@ -1337,7 +1792,7 @@ function normalizeEvent(event) {
1337
1792
  to: normalizePath(event.inner.to),
1338
1793
  };
1339
1794
  }
1340
- return { payload: payload, type: type };
1795
+ return { payload: payload, type };
1341
1796
  }
1342
1797
  function normalizePath(path) {
1343
1798
  switch (path.tag) {
@@ -1352,12 +1807,6 @@ function normalizePath(path) {
1352
1807
  }
1353
1808
  }
1354
1809
  }
1355
- function streamKey(peerId, connId, streamId) {
1356
- return `${peerId}\u0000${connId}\u0000${streamId}`;
1357
- }
1358
- function pendingOpenKey(peerId, connId, streamId) {
1359
- return streamKey(peerId, connId, streamId);
1360
- }
1361
1810
  function streamMeta(stream) {
1362
1811
  return {
1363
1812
  connId: stream.connId,