@minip2p/core 0.7.4 → 0.7.5

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/src/sdk.ts CHANGED
@@ -14,6 +14,7 @@ import {
14
14
  PeerDisconnectedError,
15
15
  StreamClosedError,
16
16
  TimeoutError,
17
+ WriteBufferFullError,
17
18
  } from "./errors.js";
18
19
  import { P2pEvent_Tags, PathKind_Tags } from "./types.js";
19
20
  import type {
@@ -49,8 +50,29 @@ const DEFAULT_TIMEOUT_MS = 65_000;
49
50
  const EVENT_QUEUE_CAP = 4096;
50
51
  const EVENT_FLUSH_BATCH = 256;
51
52
  const CONNECT_TERMINAL_CAP = 1024;
52
- const STREAM_CHUNK_CAP = 64;
53
- const STREAM_BYTE_CAP = 1024 * 1024;
53
+ /** Default per-stream write high-water mark: one Yamux stream send cap. */
54
+ const DEFAULT_WRITE_HIGH_WATER_MARK = 256 * 1024;
55
+
56
+ /** Native events routed to one {@link Stream} after it became ready. */
57
+ const STREAM_EVENT_TAGS = [
58
+ P2pEvent_Tags.StreamData,
59
+ P2pEvent_Tags.StreamRemoteWriteClosed,
60
+ P2pEvent_Tags.StreamWriteAccepted,
61
+ P2pEvent_Tags.StreamWriteStopped,
62
+ P2pEvent_Tags.StreamClosed,
63
+ ] as const;
64
+ type StreamP2pEvent = Extract<
65
+ P2pEvent,
66
+ { readonly tag: (typeof STREAM_EVENT_TAGS)[number] }
67
+ >;
68
+ const isStreamEvent = (event: P2pEvent): event is StreamP2pEvent =>
69
+ (STREAM_EVENT_TAGS as readonly string[]).includes(event.tag);
70
+
71
+ interface PendingWrite {
72
+ readonly data: Uint8Array;
73
+ readonly resolve: () => void;
74
+ readonly reject: (error: unknown) => void;
75
+ }
54
76
 
55
77
  type EventKind = keyof Minip2pNamedEventMap;
56
78
  type AnyPayload = Minip2pNamedEventMap[EventKind];
@@ -163,6 +185,199 @@ class BoundedQueue<Item> {
163
185
  }
164
186
  }
165
187
 
188
+ /**
189
+ * Native events that are never dropped, because stream and connection state
190
+ * depends on each one (ADR 0012), plus the driver failure that ends them.
191
+ */
192
+ const LOSSLESS_TAGS: ReadonlySet<string> = new Set<string>([
193
+ P2pEvent_Tags.StreamReady,
194
+ ...STREAM_EVENT_TAGS,
195
+ P2pEvent_Tags.ConnectionClosed,
196
+ P2pEvent_Tags.ConnectionReplaced,
197
+ P2pEvent_Tags.DriverFailed,
198
+ ]);
199
+
200
+ type StreamDataEvent = Extract<
201
+ P2pEvent,
202
+ { readonly tag: typeof P2pEvent_Tags.StreamData }
203
+ >;
204
+
205
+ /** Returns `next` appended to `last` when both are data for one stream. */
206
+ const coalesceData = (
207
+ last: QueueItem,
208
+ next: QueueItem
209
+ ): QueueItem | undefined => {
210
+ if (
211
+ last.source !== "native" ||
212
+ next.source !== "native" ||
213
+ last.event.tag !== P2pEvent_Tags.StreamData ||
214
+ next.event.tag !== P2pEvent_Tags.StreamData
215
+ ) {
216
+ return undefined;
217
+ }
218
+ const { inner } = last.event;
219
+ const { inner: added } = next.event;
220
+ if (
221
+ inner.peerId !== added.peerId ||
222
+ inner.connId !== added.connId ||
223
+ inner.streamId !== added.streamId
224
+ ) {
225
+ return undefined;
226
+ }
227
+ const data = new Uint8Array(inner.data.byteLength + added.data.byteLength);
228
+ data.set(new Uint8Array(inner.data));
229
+ data.set(new Uint8Array(added.data), inner.data.byteLength);
230
+ const event: StreamDataEvent = {
231
+ inner: { ...inner, data: data.buffer },
232
+ tag: P2pEvent_Tags.StreamData,
233
+ };
234
+ return { event, source: "native" };
235
+ };
236
+
237
+ /** The stream a native per-stream event belongs to. */
238
+ const streamEventKey = (item: QueueItem): string | undefined => {
239
+ if (
240
+ item.source !== "native" ||
241
+ (item.event.tag !== P2pEvent_Tags.StreamReady && !isStreamEvent(item.event))
242
+ ) {
243
+ return undefined;
244
+ }
245
+ const { peerId, connId, streamId } = item.event.inner;
246
+ return streamKey(peerId, connId, streamId);
247
+ };
248
+
249
+ /**
250
+ * The endpoint's shared event queue, in delivery order.
251
+ *
252
+ * Stream events and connection-end events (plus `DriverFailed`) never drop,
253
+ * and adjacent data for one stream coalesces into one event, so native
254
+ * receive budgets bound them; they do not count against the capacity. Past `capacity` other items, the oldest
255
+ * gossipsub message is dropped first, then the oldest other item.
256
+ *
257
+ * A peer-opened stream that closes without data before its `StreamReady`
258
+ * is dispatched leaves the queue whole, so a peer opening and closing
259
+ * streams cannot grow it; its events still reach `release`.
260
+ */
261
+ class EventQueue {
262
+ readonly #items = new Map<number, QueueItem>();
263
+ /** Droppable messages, then other droppable items, oldest first. */
264
+ readonly #messages = new Set<number>();
265
+ readonly #others = new Set<number>();
266
+ /**
267
+ * Peer-opened streams whose `StreamReady` is still queued, with their
268
+ * queued item ids; `undefined` once one carried data.
269
+ */
270
+ readonly #unseen = new Map<string, number[] | undefined>();
271
+ readonly #capacity: number;
272
+ readonly #release: (item: QueueItem) => void;
273
+ #next = 0;
274
+ #newest: number | undefined;
275
+
276
+ constructor(capacity: number, release: (item: QueueItem) => void) {
277
+ this.#capacity = capacity;
278
+ this.#release = release;
279
+ }
280
+
281
+ get length(): number {
282
+ return this.#items.size;
283
+ }
284
+
285
+ /** Appends `item`, returning the item dropped to make room, if any. */
286
+ push(item: QueueItem): QueueItem | undefined {
287
+ const newest =
288
+ this.#newest === undefined ? undefined : this.#items.get(this.#newest);
289
+ const merged =
290
+ newest === undefined ? undefined : coalesceData(newest, item);
291
+ if (merged !== undefined && this.#newest !== undefined) {
292
+ // A data event retires no adapter IDs, so the absorbed one needs no
293
+ // `eventHandled`.
294
+ this.#items.set(this.#newest, merged);
295
+ return undefined;
296
+ }
297
+ const id = this.#next;
298
+ this.#next += 1;
299
+ if (this.#elideUnseen(item, id)) {
300
+ return undefined;
301
+ }
302
+ this.#items.set(id, item);
303
+ this.#newest = id;
304
+ if (item.source === "native" && item.event.tag === P2pEvent_Tags.Message) {
305
+ this.#messages.add(id);
306
+ } else if (item.source !== "native" || !LOSSLESS_TAGS.has(item.event.tag)) {
307
+ this.#others.add(id);
308
+ }
309
+ if (this.#messages.size + this.#others.size <= this.#capacity) {
310
+ return undefined;
311
+ }
312
+ const [victim] = this.#messages.size > 0 ? this.#messages : this.#others;
313
+ return victim === undefined ? undefined : this.#remove(victim);
314
+ }
315
+
316
+ shift(): QueueItem | undefined {
317
+ const [oldest] = this.#items.keys();
318
+ if (oldest === undefined) {
319
+ return undefined;
320
+ }
321
+ const item = this.#remove(oldest);
322
+ if (
323
+ item?.source === "native" &&
324
+ item.event.tag === P2pEvent_Tags.StreamReady
325
+ ) {
326
+ this.#unseen.delete(streamEventKey(item) ?? "");
327
+ }
328
+ return item;
329
+ }
330
+
331
+ /**
332
+ * Records `item` (as `id`) against an unseen peer stream. Returns whether
333
+ * it closed one that carried no data, which leaves the queue whole.
334
+ */
335
+ #elideUnseen(item: QueueItem, id: number): boolean {
336
+ const key = streamEventKey(item);
337
+ if (key === undefined || item.source !== "native") {
338
+ return false;
339
+ }
340
+ const { event } = item;
341
+ if (event.tag === P2pEvent_Tags.StreamReady) {
342
+ if (!event.inner.initiatedLocally) {
343
+ this.#unseen.set(key, [id]);
344
+ }
345
+ return false;
346
+ }
347
+ if (!this.#unseen.has(key)) {
348
+ return false;
349
+ }
350
+ const ids = this.#unseen.get(key);
351
+ if (event.tag === P2pEvent_Tags.StreamData) {
352
+ this.#unseen.set(key, undefined);
353
+ } else if (ids !== undefined && event.tag === P2pEvent_Tags.StreamClosed) {
354
+ this.#unseen.delete(key);
355
+ for (const queued of ids) {
356
+ const removed = this.#remove(queued);
357
+ if (removed !== undefined) {
358
+ this.#release(removed);
359
+ }
360
+ }
361
+ this.#release(item);
362
+ return true;
363
+ } else {
364
+ ids?.push(id);
365
+ }
366
+ return false;
367
+ }
368
+
369
+ #remove(id: number): QueueItem | undefined {
370
+ const item = this.#items.get(id);
371
+ this.#items.delete(id);
372
+ this.#messages.delete(id);
373
+ this.#others.delete(id);
374
+ if (this.#newest === id) {
375
+ this.#newest = undefined;
376
+ }
377
+ return item;
378
+ }
379
+ }
380
+
166
381
  /** A negotiated custom-protocol stream with exclusive pull or flowing reads. */
167
382
  export class Stream {
168
383
  /** Remote peer that owns the other end of this stream. */
@@ -177,6 +392,7 @@ export class Stream {
177
392
  readonly initiatedLocally: boolean;
178
393
  readonly #backend: Minip2pBackend;
179
394
  readonly #onTerminal: () => void;
395
+ readonly #consume: (bytes: number) => void;
180
396
  readonly #listeners = new Map<
181
397
  keyof StreamEventMap,
182
398
  Set<(payload: StreamEventMap[keyof StreamEventMap]) => void>
@@ -187,6 +403,21 @@ export class Stream {
187
403
  #mode: "pull" | "flowing" | undefined;
188
404
  #receiveState: StreamReceiveState = { kind: "receiving" };
189
405
  #closed = false;
406
+ /** Writes not yet accepted by native, oldest (possibly in flight) first. */
407
+ readonly #writes: PendingWrite[] = [];
408
+ #writeBytes = 0;
409
+ /** Native holds the head write's tail until `StreamWriteAccepted`. */
410
+ #writeInFlight = false;
411
+ /** Why later writes fail: `closeWrite`, a remote stop, or a terminal. */
412
+ #writeEnded: Error | undefined;
413
+ #closeWriteQueued = false;
414
+
415
+ /**
416
+ * Most bytes the stream buffers before {@link write} rejects with
417
+ * {@link WriteBufferFullError}, counting the write native is still taking.
418
+ * A write into an empty buffer is always admitted, whatever its size.
419
+ */
420
+ writeHighWaterMark = DEFAULT_WRITE_HIGH_WATER_MARK;
190
421
 
191
422
  constructor(
192
423
  backend: Minip2pBackend,
@@ -195,6 +426,7 @@ export class Stream {
195
426
  ) {
196
427
  this.#backend = backend;
197
428
  this.#onTerminal = onTerminal;
429
+ this.#consume = streamConsumer(backend, meta);
198
430
  this.peerId = meta.peerId;
199
431
  this.protocolId = meta.protocolId;
200
432
  this.streamId = meta.streamId;
@@ -202,7 +434,16 @@ export class Stream {
202
434
  this.initiatedLocally = meta.initiatedLocally;
203
435
  }
204
436
 
205
- /** Subscribes to stream lifecycle or data events. */
437
+ /**
438
+ * Subscribes to stream lifecycle or data events.
439
+ *
440
+ * A chunk counts as consumed once every `data` handler has returned, and
441
+ * only consumed bytes let the sender continue: a stream delivers at most
442
+ * one receive window that has not been consumed. An `async` handler is
443
+ * consumed when it returns its Promise, not when that Promise settles; to
444
+ * hold the sender back while asynchronous work runs, use {@link read}
445
+ * instead.
446
+ */
206
447
  on<Kind extends keyof StreamEventMap>(
207
448
  type: Kind,
208
449
  handler: (payload: StreamEventMap[Kind]) => void
@@ -239,6 +480,11 @@ export class Stream {
239
480
  /**
240
481
  * Reads the next buffered chunk, or `undefined` after the remote write side
241
482
  * closes. Pull reads and flowing `data` handlers are mutually exclusive.
483
+ *
484
+ * Returning a chunk consumes it, which lets the sender continue: the
485
+ * stream delivers at most one receive window that has not been read, so a
486
+ * reader that stops calling `read()` stalls its sender rather than
487
+ * buffering without bound.
242
488
  */
243
489
  read(): Promise<Uint8Array | undefined> {
244
490
  if (this.#mode === "flowing") {
@@ -250,56 +496,110 @@ export class Stream {
250
496
  if (this.#receiveState.kind === "failed") {
251
497
  return Promise.reject(this.#receiveState.error);
252
498
  }
253
- const buffered = this.#shift();
254
- if (buffered !== undefined) {
499
+ const buffered = this.#take();
500
+ if (buffered !== undefined || this.#receiveState.kind === "eof") {
255
501
  return Promise.resolve(buffered);
256
502
  }
257
- if (this.#receiveState.kind === "eof") {
258
- return Promise.resolve(this.#shift());
259
- }
260
503
  return new Promise((resolve, reject) => {
261
504
  this.#reads.push({ reject, resolve });
262
505
  });
263
506
  }
264
507
 
265
- /** Writes UTF-8 text or bytes to the stream. */
266
- write(data: string | Bytes): void {
508
+ /**
509
+ * Writes UTF-8 text or bytes to the stream, resolving once native has
510
+ * accepted every byte. Writes are delivered in call order.
511
+ *
512
+ * Rejects with {@link WriteBufferFullError} when the stream already
513
+ * buffers {@link writeHighWaterMark} bytes (a first write is always
514
+ * admitted, so a payload larger than the mark can still be sent), and with
515
+ * a closed error after `closeWrite()`, a remote stop, or the stream
516
+ * closing.
517
+ *
518
+ * A write queued behind a pending one keeps a reference to `data`, and
519
+ * native reads it only when the write reaches the head of the queue: leave
520
+ * the buffer untouched until the Promise settles.
521
+ */
522
+ write(data: string | Bytes): Promise<void> {
267
523
  if (this.#closed) {
268
- throw new ClosedError();
524
+ return Promise.reject(new ClosedError());
269
525
  }
270
- this.#backend.sendStream(
271
- this.peerId,
272
- this.connId,
273
- this.streamId,
274
- toUint8Array(data)
275
- );
526
+ if (this.#writeEnded !== undefined) {
527
+ return Promise.reject(this.#writeEnded);
528
+ }
529
+ const bytes = toUint8Array(data);
530
+ if (
531
+ this.#writeBytes > 0 &&
532
+ this.#writeBytes + bytes.byteLength > this.writeHighWaterMark
533
+ ) {
534
+ return Promise.reject(
535
+ new WriteBufferFullError(this.#writeBytes, this.writeHighWaterMark)
536
+ );
537
+ }
538
+ return new Promise((resolve, reject) => {
539
+ this.#writes.push({ data: bytes, reject, resolve });
540
+ this.#writeBytes += bytes.byteLength;
541
+ this.#pumpWrites();
542
+ });
276
543
  }
277
544
 
278
- /** Half-closes the local write side while keeping reads available. */
545
+ /**
546
+ * Half-closes the local write side once every earlier write has been
547
+ * accepted, keeping reads available. Later writes reject.
548
+ *
549
+ * With no write pending the close goes to native now and throws if native
550
+ * refuses it. Behind pending writes it is queued, and a close native then
551
+ * refuses is reported by the stream's terminal event instead.
552
+ */
279
553
  closeWrite(): void {
280
- if (!this.#closed) {
554
+ if (this.#closed || this.#writeEnded !== undefined) {
555
+ return;
556
+ }
557
+ this.#writeEnded = new StreamClosedError("The stream write side closed");
558
+ if (this.#writes.length === 0) {
281
559
  this.#backend.closeStreamWrite(this.peerId, this.connId, this.streamId);
560
+ return;
282
561
  }
562
+ this.#closeWriteQueued = true;
283
563
  }
284
564
 
285
- /** Abruptly resets the stream and emits `closed`. */
565
+ /**
566
+ * Abruptly resets the stream and emits `closed`. On a stream that already
567
+ * closed, discards unread bytes instead.
568
+ */
286
569
  reset(): void {
287
- if (!this.#closed) {
288
- this.#backend.resetStream(this.peerId, this.connId, this.streamId);
289
- this.terminal();
570
+ if (this.#closed) {
571
+ this.#discardUnread();
572
+ return;
290
573
  }
574
+ this.#backend.resetStream(this.peerId, this.connId, this.streamId);
575
+ this.terminal();
291
576
  }
292
577
 
293
- /** Relinquishes the stream and requests a reset while it remains active. */
578
+ /**
579
+ * Relinquishes the stream and requests a reset while it remains active.
580
+ * On a stream that already closed, discards unread bytes instead.
581
+ */
294
582
  abandon(): void {
295
- if (!this.#closed) {
296
- try {
297
- this.#backend.abandonStream(this.peerId, this.connId, this.streamId);
298
- } catch {
299
- // A native close can overtake its queued terminal event.
300
- }
301
- this.terminal();
583
+ if (this.#closed) {
584
+ this.#discardUnread();
585
+ return;
586
+ }
587
+ try {
588
+ this.#backend.abandonStream(this.peerId, this.connId, this.streamId);
589
+ } catch {
590
+ // A native close can overtake its queued terminal event.
302
591
  }
592
+ this.terminal();
593
+ }
594
+
595
+ /**
596
+ * A cleanly closed stream keeps unread bytes for later reads, and they
597
+ * hold its native stream slot until consumed; discarding them releases it.
598
+ */
599
+ #discardUnread(): void {
600
+ this.#consumed(this.#fifoBytes);
601
+ this.#fifo.length = 0;
602
+ this.#fifoBytes = 0;
303
603
  }
304
604
 
305
605
  [Symbol.dispose](): void {
@@ -330,26 +630,49 @@ export class Stream {
330
630
  const read = this.#reads.shift();
331
631
  if (read !== undefined) {
332
632
  read.resolve(chunk);
633
+ this.#consumed(chunk.byteLength);
333
634
  return;
334
635
  }
335
636
  if (this.#mode === "flowing") {
336
- this.#emit("data", chunk);
337
- return;
338
- }
339
- if (
340
- this.#fifo.length >= STREAM_CHUNK_CAP ||
341
- this.#fifoBytes + chunk.byteLength > STREAM_BYTE_CAP
342
- ) {
343
- this.#emit("dataOverflow", {
344
- droppedBytes: chunk.byteLength,
345
- droppedChunks: 1,
346
- });
637
+ this.#emitData(chunk);
347
638
  return;
348
639
  }
640
+ // Unbounded here, because native delivers at most one receive window
641
+ // that has not been consumed.
349
642
  this.#fifo.push(chunk);
350
643
  this.#fifoBytes += chunk.byteLength;
351
644
  }
352
645
 
646
+ /**
647
+ * Native accepted the whole in-flight write.
648
+ * @internal
649
+ */
650
+ writeAccepted(): void {
651
+ if (!this.#writeInFlight) {
652
+ return;
653
+ }
654
+ this.#writeInFlight = false;
655
+ this.#settleHead();
656
+ this.#pumpWrites();
657
+ }
658
+
659
+ /**
660
+ * The remote asked this side to stop writing.
661
+ * @internal
662
+ */
663
+ writeStopped(errorCode: bigint): void {
664
+ if (this.#closed) {
665
+ return;
666
+ }
667
+ const error = new StreamClosedError(
668
+ `The remote stopped reading this stream (code ${errorCode})`
669
+ );
670
+ this.#writeEnded ??= error;
671
+ this.#closeWriteQueued = false;
672
+ this.#failWrites(error);
673
+ this.#emit("writeStopped", { errorCode });
674
+ }
675
+
353
676
  /** @internal */
354
677
  remoteWriteClosed(): void {
355
678
  if (this.#closed || this.#receiveState.kind !== "receiving") {
@@ -373,18 +696,18 @@ export class Stream {
373
696
  return;
374
697
  }
375
698
  this.#closed = true;
699
+ this.#failWrites(error);
376
700
  // StreamClosed carries no cause. Once the remote FIN establishes EOF,
377
701
  // later full closure cannot reinterpret that receive-side outcome.
378
702
  const hasRemoteEof =
379
703
  options.preserveRemoteEof === true && this.#receiveState.kind === "eof";
380
704
  if (!hasRemoteEof) {
381
705
  this.#receiveState = { error, kind: "failed" };
382
- this.#fifo.length = 0;
383
- this.#fifoBytes = 0;
706
+ this.#discardUnread();
384
707
  }
385
708
  for (const read of this.#reads.splice(0)) {
386
709
  if (hasRemoteEof) {
387
- read.resolve(this.#shift());
710
+ read.resolve(this.#take());
388
711
  } else {
389
712
  read.reject(error);
390
713
  }
@@ -394,23 +717,111 @@ export class Stream {
394
717
  this.#onTerminal();
395
718
  }
396
719
 
720
+ /**
721
+ * Hands queued writes to native one at a time. A write native accepts only
722
+ * in part stays at the head until `StreamWriteAccepted`, which keeps
723
+ * writes, and the queued close, in order.
724
+ */
725
+ #pumpWrites(): void {
726
+ while (!this.#writeInFlight && !this.#closed) {
727
+ const [head] = this.#writes;
728
+ if (head === undefined) {
729
+ if (this.#closeWriteQueued) {
730
+ this.#closeWriteQueued = false;
731
+ try {
732
+ this.#backend.closeStreamWrite(
733
+ this.peerId,
734
+ this.connId,
735
+ this.streamId
736
+ );
737
+ } catch {
738
+ // A deferred close has no caller left to throw to; the stream
739
+ // already ended, and its terminal event reports that.
740
+ }
741
+ }
742
+ return;
743
+ }
744
+ let accepted: boolean;
745
+ try {
746
+ accepted = this.#backend.sendStream(
747
+ this.peerId,
748
+ this.connId,
749
+ this.streamId,
750
+ head.data
751
+ );
752
+ } catch (error) {
753
+ this.#failWrites(error);
754
+ return;
755
+ }
756
+ if (!accepted) {
757
+ this.#writeInFlight = true;
758
+ return;
759
+ }
760
+ this.#settleHead();
761
+ }
762
+ }
763
+
764
+ #settleHead(): void {
765
+ const head = this.#writes.shift();
766
+ if (head !== undefined) {
767
+ this.#writeBytes -= head.data.byteLength;
768
+ head.resolve();
769
+ }
770
+ }
771
+
772
+ #failWrites(error: unknown): void {
773
+ this.#writeInFlight = false;
774
+ this.#writeBytes = 0;
775
+ for (const write of this.#writes.splice(0)) {
776
+ write.reject(error);
777
+ }
778
+ }
779
+
780
+ /**
781
+ * Hands buffered chunks to `data` handlers. After a clean close the
782
+ * buffer still holds the bytes that arrived before EOF (a failed stream
783
+ * has already discarded them), so a late handler drains it too.
784
+ */
397
785
  #flushFlowing(): void {
398
- while (this.#fifo.length > 0 && !this.#closed) {
399
- const chunk = this.#shift();
786
+ while (this.#fifo.length > 0) {
787
+ const chunk = this.#fifo.shift();
400
788
  if (chunk !== undefined) {
401
- this.#emit("data", chunk);
789
+ this.#fifoBytes -= chunk.byteLength;
790
+ this.#emitData(chunk);
402
791
  }
403
792
  }
404
793
  }
405
794
 
406
- #shift(): Uint8Array | undefined {
795
+ /** Hands `chunk` to every `data` handler; it is consumed once they return. */
796
+ #emitData(chunk: Uint8Array): void {
797
+ // Counted first: a handler may transfer the buffer, detaching it.
798
+ const bytes = chunk.byteLength;
799
+ this.#emit("data", chunk);
800
+ this.#consumed(bytes);
801
+ }
802
+
803
+ /** Takes the oldest buffered chunk for a reader, consuming it. */
804
+ #take(): Uint8Array | undefined {
407
805
  const chunk = this.#fifo.shift();
408
806
  if (chunk !== undefined) {
409
807
  this.#fifoBytes -= chunk.byteLength;
808
+ this.#consumed(chunk.byteLength);
410
809
  }
411
810
  return chunk;
412
811
  }
413
812
 
813
+ /** Acknowledges consumed bytes to native, letting the sender continue. */
814
+ #consumed(bytes: number): void {
815
+ if (bytes === 0) {
816
+ return;
817
+ }
818
+ try {
819
+ this.#consume(bytes);
820
+ } catch {
821
+ // The stream or its connection is already gone natively.
822
+ }
823
+ }
824
+
414
825
  #emit<Kind extends keyof StreamEventMap>(
415
826
  type: Kind,
416
827
  payload?: StreamEventMap[Kind]
@@ -425,6 +836,33 @@ export class Stream {
425
836
  }
426
837
  }
427
838
 
839
+ /**
840
+ * The backend's acknowledgement function for a stream. A connection whose
841
+ * end the adapter already saw has nothing left to settle.
842
+ */
843
+ const streamConsumer = (
844
+ backend: Minip2pBackend,
845
+ meta: InboundStreamMeta
846
+ ): ((bytes: number) => void) => {
847
+ try {
848
+ return backend.streamConsumer(meta.connId, meta.streamId);
849
+ } catch {
850
+ return () => {};
851
+ }
852
+ };
853
+
854
+ /** Acknowledges data that arrived for a stream the SDK no longer tracks. */
855
+ const consumeUntracked = (
856
+ backend: Minip2pBackend,
857
+ inner: StreamDataEvent["inner"]
858
+ ): void => {
859
+ try {
860
+ backend.streamConsumer(inner.connId, inner.streamId)(inner.data.byteLength);
861
+ } catch {
862
+ // Settled already, or its connection is gone: nothing to release.
863
+ }
864
+ };
865
+
428
866
  /** Events emitted by a negotiated {@link Stream}. */
429
867
  export interface StreamEventMap {
430
868
  /** A received binary chunk. */
@@ -433,11 +871,8 @@ export interface StreamEventMap {
433
871
  remoteWriteClosed: void;
434
872
  /** The stream reached a terminal state. */
435
873
  closed: void;
436
- /** Incoming data exceeded the bounded pull-read buffer. */
437
- dataOverflow: {
438
- readonly droppedChunks: number;
439
- readonly droppedBytes: number;
440
- };
874
+ /** The remote asked this side to stop writing; pending writes rejected. */
875
+ writeStopped: { readonly errorCode: bigint };
441
876
  }
442
877
 
443
878
  /**
@@ -452,7 +887,9 @@ export class Minip2pBase {
452
887
  readonly #catchAll = new Set<CatchAllHandler>();
453
888
  readonly #closeHandlers = new Set<(reason: CloseReason) => void>();
454
889
  readonly #waiters = new Set<EventWaiter>();
455
- readonly #queue = new BoundedQueue<QueueItem>(EVENT_QUEUE_CAP);
890
+ readonly #queue = new EventQueue(EVENT_QUEUE_CAP, (item) => {
891
+ this.#releaseQueueItem(item);
892
+ });
456
893
  readonly #connects = new Map<number, ConnectAttempt>();
457
894
  readonly #terminalConnects = new Set<number>();
458
895
  readonly #streams = new Map<string, Stream>();
@@ -1204,11 +1641,7 @@ export class Minip2pBase {
1204
1641
  this.#streamReady(event.inner);
1205
1642
  return;
1206
1643
  }
1207
- if (
1208
- event.tag === P2pEvent_Tags.StreamData ||
1209
- event.tag === P2pEvent_Tags.StreamRemoteWriteClosed ||
1210
- event.tag === P2pEvent_Tags.StreamClosed
1211
- ) {
1644
+ if (isStreamEvent(event)) {
1212
1645
  this.#streamEvent(event);
1213
1646
  return;
1214
1647
  }
@@ -1366,17 +1799,7 @@ export class Minip2pBase {
1366
1799
  }
1367
1800
  }
1368
1801
 
1369
- #streamEvent(
1370
- event: Extract<
1371
- P2pEvent,
1372
- {
1373
- readonly tag:
1374
- | typeof P2pEvent_Tags.StreamData
1375
- | typeof P2pEvent_Tags.StreamRemoteWriteClosed
1376
- | typeof P2pEvent_Tags.StreamClosed;
1377
- }
1378
- >
1379
- ): void {
1802
+ #streamEvent(event: StreamP2pEvent): void {
1380
1803
  const { peerId, connId, streamId } = event.inner;
1381
1804
  const stream = this.#streams.get(streamKey(peerId, connId, streamId));
1382
1805
  if (event.tag === P2pEvent_Tags.StreamClosed) {
@@ -1391,7 +1814,18 @@ export class Minip2pBase {
1391
1814
  preserveRemoteEof: true,
1392
1815
  });
1393
1816
  } else if (event.tag === P2pEvent_Tags.StreamData) {
1394
- stream?.receive(event.inner.data);
1817
+ if (stream === undefined) {
1818
+ // Nothing will read it, so it is consumed now: an abandon that
1819
+ // native refused (the stream had already closed there) leaves the
1820
+ // bytes holding the native stream slot otherwise.
1821
+ consumeUntracked(this.#backend, event.inner);
1822
+ } else {
1823
+ stream.receive(event.inner.data);
1824
+ }
1825
+ } else if (event.tag === P2pEvent_Tags.StreamWriteAccepted) {
1826
+ stream?.writeAccepted();
1827
+ } else if (event.tag === P2pEvent_Tags.StreamWriteStopped) {
1828
+ stream?.writeStopped(event.inner.errorCode);
1395
1829
  } else {
1396
1830
  stream?.remoteWriteClosed();
1397
1831
  }
@@ -1677,14 +2111,12 @@ function toBackendTarget(target: ConnectTarget): BackendConnectTarget {
1677
2111
  function normalizeEvent(
1678
2112
  event: Exclude<
1679
2113
  P2pEvent,
1680
- {
1681
- readonly tag:
1682
- | typeof P2pEvent_Tags.DriverFailed
1683
- | typeof P2pEvent_Tags.StreamReady
1684
- | typeof P2pEvent_Tags.StreamData
1685
- | typeof P2pEvent_Tags.StreamRemoteWriteClosed
1686
- | typeof P2pEvent_Tags.StreamClosed;
1687
- }
2114
+ | StreamP2pEvent
2115
+ | {
2116
+ readonly tag:
2117
+ | typeof P2pEvent_Tags.DriverFailed
2118
+ | typeof P2pEvent_Tags.StreamReady;
2119
+ }
1688
2120
  >
1689
2121
  ):
1690
2122
  | {