@minip2p/node 0.7.3 → 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/adapter.ts CHANGED
@@ -1,4 +1,4 @@
1
- /* oxlint-disable class-methods-use-this, func-style, max-classes-per-file, no-await-in-loop, no-use-before-define, prefer-destructuring, promise/avoid-new, unicorn/no-useless-undefined -- The adapter keeps the contract-complete native endpoint, value conversion, handle maps, and drain loop together at the binding boundary. */
1
+ /* oxlint-disable class-methods-use-this, func-style, max-classes-per-file, no-use-before-define -- The adapter keeps the contract-complete native endpoint, value conversion, and handle maps together at the binding boundary. */
2
2
 
3
3
  import { Minip2pBase, StreamClosedError } from "@minip2p/core";
4
4
  import type {
@@ -11,9 +11,12 @@ import type {
11
11
  RelayReservationInfo,
12
12
  } from "@minip2p/core";
13
13
  import {
14
+ ConnectionIdMap,
15
+ EventDrain,
14
16
  P2pEvent_Tags,
15
17
  resolveEndpointConfig,
16
18
  typedFfiError,
19
+ u64ToNumber,
17
20
  } from "@minip2p/core/backend";
18
21
  import type {
19
22
  BackendConnectTarget,
@@ -23,13 +26,22 @@ import type {
23
26
  P2pEvent,
24
27
  } from "@minip2p/core/backend";
25
28
 
29
+ import type {
30
+ NativeEvent,
31
+ NativeIdentifyInfo,
32
+ NativeKnownPeerInfo,
33
+ NativeRelayReservationInfo,
34
+ } from "./native-shape.js";
26
35
  import { nativeBinding } from "./native.js";
27
36
  import type { NativeEndpoint } from "./native.js";
28
37
 
38
+ /** Native drain batch size. */
39
+ const DRAIN_LIMIT = 256;
40
+
29
41
  class NodeBackend implements Minip2pBackend {
30
- readonly #connectionIds = new IdMap();
42
+ readonly #connectionIds = new ConnectionIdMap();
31
43
  readonly #endpoint: NativeEndpoint;
32
- readonly #events: EventDrain;
44
+ #events: EventDrain<NativeEvent> | undefined;
33
45
  readonly #streamIds = new StreamIdMap();
34
46
 
35
47
  constructor(config: Minip2pConfig) {
@@ -40,17 +52,25 @@ class NodeBackend implements Minip2pBackend {
40
52
  resolveEndpointConfig(config)
41
53
  )
42
54
  );
43
- this.#events = new EventDrain(
44
- () => this.#endpoint.drainEvents(256),
45
- (event) => normalizeEvent(event, this.#connectionIds, this.#streamIds)
46
- );
47
55
  }
48
56
 
49
57
  start(listener: (event: P2pEvent) => void): void {
50
- this.#events.start(listener);
58
+ const events = new EventDrain(
59
+ (limit) => this.#endpoint.drainEvents(limit),
60
+ (event: NativeEvent) => {
61
+ listener(normalizeEvent(event, this.#connectionIds, this.#streamIds));
62
+ },
63
+ DRAIN_LIMIT,
64
+ // One check-phase turn keeps native callbacks out of the caller's stack
65
+ // without paying the timer granularity for every bounded batch.
66
+ (task) => {
67
+ setImmediate(task);
68
+ }
69
+ );
70
+ this.#events = events;
51
71
  translateErrors(() => {
52
72
  this.#endpoint.start(() => {
53
- this.#events.ring();
73
+ events.ring();
54
74
  });
55
75
  });
56
76
  }
@@ -61,7 +81,7 @@ class NodeBackend implements Minip2pBackend {
61
81
 
62
82
  close(): void {
63
83
  this.#endpoint.close();
64
- this.#events.stop();
84
+ this.#events?.stop();
65
85
  }
66
86
 
67
87
  peerId(): string {
@@ -86,49 +106,38 @@ class NodeBackend implements Minip2pBackend {
86
106
 
87
107
  peerInfo(peerId: string): IdentifyInfo | undefined {
88
108
  const info = translateErrors(() => this.#endpoint.peerInfo(peerId));
89
- return info === null || info === undefined
90
- ? undefined
91
- : normalizeIdentifyInfo(info);
109
+ return info === null ? undefined : identifyInfo(info);
92
110
  }
93
111
 
94
112
  knownPeers(): KnownPeerInfo[] {
95
- return translateErrors(() => this.#endpoint.knownPeers()).map((peer) =>
96
- normalizeRecord<KnownPeerInfo>(peer)
97
- );
113
+ return translateErrors(() => this.#endpoint.knownPeers()).map(knownPeer);
98
114
  }
99
115
 
100
116
  discoveryNowMs(): number | undefined {
101
117
  const value = translateErrors(() => this.#endpoint.discoveryNowMs());
102
- return value === null || value === undefined
103
- ? undefined
104
- : bigintToNumber(value, "clock");
118
+ return value === null ? undefined : u64ToNumber(value, "clock");
105
119
  }
106
120
 
107
121
  activeReservation(): RelayReservationInfo | undefined {
108
- return normalizeOptional<RelayReservationInfo>(
109
- translateErrors(() => this.#endpoint.activeReservation())
122
+ const reservation = translateErrors(() =>
123
+ this.#endpoint.activeReservation()
110
124
  );
125
+ return reservation === null ? undefined : relayReservation(reservation);
111
126
  }
112
127
 
113
128
  path(peerId: string): PathKind | undefined {
114
- return normalizeOptional<PathKind>(
115
- translateErrors(() => this.#endpoint.path(peerId))
116
- );
129
+ return translateErrors(() => this.#endpoint.path(peerId)) ?? undefined;
117
130
  }
118
131
 
119
132
  connectionInfo(peerId: string): ConnectionInfo | undefined {
120
133
  const info = translateErrors(() => this.#endpoint.connectionInfo(peerId));
121
- if (info === null || info === undefined) {
134
+ if (info === null) {
122
135
  return undefined;
123
136
  }
137
+ const { connId, ...rest } = info;
124
138
  return {
125
- connId: this.#connectionIds.toPublic(info.connId),
126
- ...(typeof info.remoteAddr === "string" && {
127
- remoteAddr: info.remoteAddr,
128
- }),
129
- ...(Array.isArray(info.readyProtocols) && {
130
- readyProtocols: info.readyProtocols,
131
- }),
139
+ ...rest,
140
+ connId: this.#connectionIds.toPublic(BigInt(connId)),
132
141
  };
133
142
  }
134
143
 
@@ -137,7 +146,7 @@ class NodeBackend implements Minip2pBackend {
137
146
  }
138
147
 
139
148
  reachability(): Reachability {
140
- return translateErrors(() => this.#endpoint.reachability()) as Reachability;
149
+ return translateErrors(() => this.#endpoint.reachability());
141
150
  }
142
151
 
143
152
  setActive(active: boolean): void {
@@ -174,10 +183,10 @@ class NodeBackend implements Minip2pBackend {
174
183
  const stream = translateErrors(() =>
175
184
  this.#endpoint.openStream(peerId, protocolId)
176
185
  );
177
- const connId = this.#connectionIds.toPublic(stream.connId);
186
+ const connId = this.#connectionIds.toPublic(BigInt(stream.connId));
178
187
  return {
179
188
  connId,
180
- streamId: this.#streamIds.toPublic(connId, stream.streamId),
189
+ streamId: this.#streamIds.toPublic(connId, BigInt(stream.streamId)),
181
190
  };
182
191
  }
183
192
 
@@ -186,14 +195,14 @@ class NodeBackend implements Minip2pBackend {
186
195
  connId: number,
187
196
  streamId: number,
188
197
  data: Uint8Array
189
- ): void {
190
- translateErrors(() => {
198
+ ): boolean {
199
+ return translateErrors(() =>
191
200
  this.#endpoint.sendStream(
192
201
  peerId,
193
202
  ...this.#nativeStream(connId, streamId),
194
203
  data
195
- );
196
- });
204
+ )
205
+ );
197
206
  }
198
207
 
199
208
  closeStreamWrite(peerId: string, connId: number, streamId: number): void {
@@ -223,6 +232,15 @@ class NodeBackend implements Minip2pBackend {
223
232
  });
224
233
  }
225
234
 
235
+ streamConsumer(connId: number, streamId: number): (bytes: number) => void {
236
+ const [nativeConn, nativeStream] = this.#nativeStream(connId, streamId);
237
+ return (bytes) => {
238
+ translateErrors(() => {
239
+ this.#endpoint.streamConsumed(nativeConn, nativeStream, bytes);
240
+ });
241
+ };
242
+ }
243
+
226
244
  /**
227
245
  * Native connection and stream IDs for a public stream. Native names the
228
246
  * stream by both, so an operation for a connection that native already
@@ -240,7 +258,7 @@ class NodeBackend implements Minip2pBackend {
240
258
  // Connect IDs are not mapped because they round-trip into native calls,
241
259
  // and native allocates them well inside the safe integer range.
242
260
  connect(target: BackendConnectTarget): number {
243
- return bigintToNumber(
261
+ return u64ToNumber(
244
262
  translateErrors(() =>
245
263
  this.#endpoint.connect(
246
264
  target.kind === "peer" ? target.peerId : [...target.addresses]
@@ -326,39 +344,46 @@ function toUint8Array(value: Bytes): Uint8Array {
326
344
  : new Uint8Array(value);
327
345
  }
328
346
 
329
- function bigintToNumber(value: bigint, name: string): number {
330
- const number = Number(value);
331
- if (!Number.isSafeInteger(number) || number < 0) {
332
- throw new RangeError(`${name} exceeds JavaScript's safe integer range`);
333
- }
334
- return number;
347
+ /** Converts an Identify snapshot, copying its public key into an `ArrayBuffer`. */
348
+ function identifyInfo({
349
+ publicKey,
350
+ ...info
351
+ }: NativeIdentifyInfo): IdentifyInfo {
352
+ return {
353
+ ...info,
354
+ ...(publicKey !== undefined && { publicKey: toArrayBuffer(publicKey) }),
355
+ };
335
356
  }
336
357
 
337
- function normalizeOptional<Value>(value: unknown): Value | undefined {
338
- return value === null || value === undefined
339
- ? undefined
340
- : normalizeRecord<Value>(value);
358
+ function knownPeer({
359
+ beaconLastSeenAgeMs,
360
+ mdnsLastSeenAgeMs,
361
+ ...peer
362
+ }: NativeKnownPeerInfo): KnownPeerInfo {
363
+ return {
364
+ ...peer,
365
+ ...(beaconLastSeenAgeMs !== undefined && {
366
+ beaconLastSeenAgeMs: u64ToNumber(
367
+ beaconLastSeenAgeMs,
368
+ "beaconLastSeenAgeMs"
369
+ ),
370
+ }),
371
+ ...(mdnsLastSeenAgeMs !== undefined && {
372
+ mdnsLastSeenAgeMs: u64ToNumber(mdnsLastSeenAgeMs, "mdnsLastSeenAgeMs"),
373
+ }),
374
+ };
341
375
  }
342
376
 
343
- function normalizeRecord<Value>(value: unknown): Value {
344
- return normalizeNativeValue(value) as Value;
345
- }
346
-
347
- function normalizeIdentifyInfo(value: unknown): IdentifyInfo {
348
- const info = normalizeRecord<Record<string, unknown>>(value);
349
- const publicKey = info.publicKey;
350
- if (publicKey === undefined) {
351
- return info as unknown as IdentifyInfo;
352
- }
353
- if (Array.isArray(publicKey) || publicKey instanceof Uint8Array) {
354
- return {
355
- ...info,
356
- publicKey: nativeBytesToArrayBuffer(publicKey),
357
- } as unknown as IdentifyInfo;
358
- }
359
- throw new TypeError(
360
- "The native addon returned an invalid Identify public key"
361
- );
377
+ function relayReservation({
378
+ expiresUnixSecs,
379
+ relayPeerId,
380
+ }: NativeRelayReservationInfo): RelayReservationInfo {
381
+ return {
382
+ relayPeerId,
383
+ ...(expiresUnixSecs !== undefined && {
384
+ expiresUnixSecs: u64ToNumber(expiresUnixSecs, "expiresUnixSecs"),
385
+ }),
386
+ };
362
387
  }
363
388
 
364
389
  /** Event fields carrying a native connection ID. */
@@ -368,80 +393,82 @@ const CONNECTION_ID_KEYS: ReadonlySet<string> = new Set([
368
393
  "newConnId",
369
394
  ]);
370
395
 
396
+ /**
397
+ * Converts one value of a native event: integers to numbers, connection IDs
398
+ * through the connection map, and bytes to `ArrayBuffer`s. A stream ID is
399
+ * mapped together with the connection of the record that carries it.
400
+ */
371
401
  function normalizeNativeValue(
372
402
  value: unknown,
373
- key?: string,
374
- maps?: NativeIdMaps
403
+ maps: NativeIdMaps,
404
+ key?: string
375
405
  ): unknown {
376
- const isId = typeof value === "bigint" || typeof value === "number";
377
- if (isId && maps !== undefined && key !== undefined) {
378
- if (CONNECTION_ID_KEYS.has(key)) {
406
+ if (typeof value === "bigint" || typeof value === "number") {
407
+ if (key !== undefined && CONNECTION_ID_KEYS.has(key)) {
379
408
  return maps.connectionIds.toPublic(BigInt(value));
380
409
  }
381
- if (key === "streamId") {
382
- // Mapped with its connection once the whole record is normalized.
383
- return value;
410
+ // A QUIC stop code is a 62-bit varint the remote picks: keep it whole.
411
+ if (key === "errorCode") {
412
+ return BigInt(value);
384
413
  }
414
+ return key === "streamId" ? value : u64ToNumber(value, key ?? "native u64");
385
415
  }
386
- if (typeof value === "bigint") {
387
- return bigintToNumber(value, "native value");
416
+ if (value instanceof Uint8Array) {
417
+ return toArrayBuffer(value);
388
418
  }
389
419
  if (Array.isArray(value)) {
390
- return value.map((item) => normalizeNativeValue(item, undefined, maps));
420
+ return value.map((item) => normalizeNativeValue(item, maps));
391
421
  }
392
- if (value instanceof Uint8Array) {
422
+ if (value === null || typeof value !== "object") {
393
423
  return value;
394
424
  }
395
- if (value !== null && typeof value === "object") {
396
- const record: Record<string, unknown> = Object.fromEntries(
397
- Object.entries(value)
398
- .filter(([, item]) => item !== null)
399
- .map(([itemKey, item]) => [
400
- itemKey,
401
- normalizeNativeValue(item, itemKey, maps),
402
- ])
403
- );
404
- const { connId, streamId } = record;
405
- if (maps !== undefined && streamId !== undefined) {
406
- if (
407
- (typeof streamId !== "bigint" && typeof streamId !== "number") ||
408
- (connId !== undefined && typeof connId !== "number")
409
- ) {
410
- throw new TypeError("The native addon returned an invalid stream ID");
411
- }
412
- // Public stream IDs are allocated per connection. A record without a
413
- // connection (an endpoint error, say) cannot name a public stream.
414
- if (typeof connId === "number") {
415
- record.streamId = maps.streamIds.toPublic(connId, BigInt(streamId));
416
- } else {
417
- delete record.streamId;
418
- }
425
+ const record: Record<string, unknown> = Object.fromEntries(
426
+ Object.entries(value).map(([itemKey, item]) => [
427
+ itemKey,
428
+ normalizeNativeValue(item, maps, itemKey),
429
+ ])
430
+ );
431
+ const { connId, streamId } = record;
432
+ if (typeof streamId === "bigint" || typeof streamId === "number") {
433
+ // Public stream IDs are allocated per connection. A record without a
434
+ // connection (an endpoint error, say) cannot name a public stream.
435
+ if (typeof connId === "number") {
436
+ record.streamId = maps.streamIds.toPublic(connId, BigInt(streamId));
437
+ } else {
438
+ delete record.streamId;
419
439
  }
420
- return record;
421
440
  }
422
- return value;
441
+ return record;
423
442
  }
424
443
 
444
+ /**
445
+ * Converts one native event to its SDK backend form. Identify snapshots go
446
+ * through the typed {@link identifyInfo}; every other event shares the
447
+ * generic integer, ID and byte conversion.
448
+ */
425
449
  function normalizeEvent(
426
- value: unknown,
427
- connectionIds: IdMap,
450
+ event: NativeEvent,
451
+ connectionIds: ConnectionIdMap,
428
452
  streamIds: StreamIdMap
429
453
  ): P2pEvent {
430
- const event = normalizeNativeValue(value, undefined, {
431
- connectionIds,
432
- streamIds,
433
- }) as { tag?: unknown; inner?: unknown };
434
- if (typeof event.tag !== "string" || event.inner === undefined) {
435
- throw new TypeError("The native addon returned an invalid event");
436
- }
437
- if (
438
- event.tag === "StreamData" ||
439
- event.tag === "Message" ||
440
- event.tag === "IdentifyReceived"
441
- ) {
442
- event.inner = normalizeEventBytes(event.tag, event.inner);
443
- }
444
- const normalized = event as P2pEvent;
454
+ // Outside Identify, the addon's serde shape is the SDK shape with napi-rs
455
+ // integers and buffers (see `native-shape.ts`), which the walk converts.
456
+ const normalized: P2pEvent =
457
+ event.tag === P2pEvent_Tags.IdentifyReceived
458
+ ? {
459
+ inner: {
460
+ info: identifyInfo(event.inner.info),
461
+ peerId: event.inner.peerId,
462
+ },
463
+ tag: event.tag,
464
+ }
465
+ : ({
466
+ inner: normalizeNativeValue(event.inner, {
467
+ connectionIds,
468
+ streamIds,
469
+ }),
470
+ tag: event.tag,
471
+ } as P2pEvent);
445
472
  retireTerminalIds(normalized, connectionIds, streamIds);
446
473
  return normalized;
447
474
  }
@@ -455,12 +482,12 @@ function normalizeEvent(
455
482
  */
456
483
  function retireTerminalIds(
457
484
  event: P2pEvent,
458
- connectionIds: IdMap,
485
+ connectionIds: ConnectionIdMap,
459
486
  streamIds: StreamIdMap
460
487
  ): void {
461
488
  const connId = endedConnection(event);
462
489
  if (connId !== undefined) {
463
- connectionIds.deletePublic(connId);
490
+ connectionIds.release(connId);
464
491
  streamIds.retireConnection(connId);
465
492
  }
466
493
  if (event.tag === P2pEvent_Tags.StreamClosed) {
@@ -493,38 +520,8 @@ function endedConnection(event: P2pEvent): number | undefined {
493
520
  return undefined;
494
521
  }
495
522
 
496
- function normalizeEventBytes(tag: string, value: unknown): unknown {
497
- if (value === null || typeof value !== "object") {
498
- return value;
499
- }
500
- const inner = { ...value };
501
- if (tag === "StreamData") {
502
- const data = Reflect.get(inner, "data");
503
- if (Array.isArray(data) || data instanceof Uint8Array) {
504
- Reflect.set(inner, "data", nativeBytesToArrayBuffer(data));
505
- }
506
- }
507
- if (tag === "Message") {
508
- for (const key of ["data", "seqno"] as const) {
509
- const bytes = Reflect.get(inner, key);
510
- if (Array.isArray(bytes) || bytes instanceof Uint8Array) {
511
- Reflect.set(inner, key, nativeBytesToArrayBuffer(bytes));
512
- }
513
- }
514
- }
515
- if (tag === "IdentifyReceived") {
516
- const info = Reflect.get(inner, "info");
517
- if (info !== null && typeof info === "object") {
518
- Reflect.set(inner, "info", normalizeIdentifyInfo(info));
519
- }
520
- }
521
- return inner;
522
- }
523
-
524
- function nativeBytesToArrayBuffer(bytes: number[] | Uint8Array): ArrayBuffer {
525
- if (Array.isArray(bytes)) {
526
- return Uint8Array.from(bytes).buffer;
527
- }
523
+ /** Copies native bytes unless they already own their whole `ArrayBuffer`. */
524
+ function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
528
525
  if (
529
526
  bytes.buffer instanceof ArrayBuffer &&
530
527
  bytes.byteOffset === 0 &&
@@ -535,115 +532,11 @@ function nativeBytesToArrayBuffer(bytes: number[] | Uint8Array): ArrayBuffer {
535
532
  return Uint8Array.from(bytes).buffer;
536
533
  }
537
534
 
538
- class EventDrain {
539
- readonly #drain: () => unknown[];
540
- readonly #normalize: (event: unknown) => P2pEvent;
541
- #listener: ((event: P2pEvent) => void) | undefined;
542
- #pending = false;
543
- #running = false;
544
- #stopped = false;
545
-
546
- constructor(drain: () => unknown[], normalize: (event: unknown) => P2pEvent) {
547
- this.#drain = drain;
548
- this.#normalize = normalize;
549
- }
550
-
551
- start(listener: (event: P2pEvent) => void): void {
552
- this.#listener = listener;
553
- }
554
-
555
- ring(): void {
556
- if (this.#stopped) {
557
- return;
558
- }
559
- this.#pending = true;
560
- if (!this.#running) {
561
- this.#running = true;
562
- // One check-phase turn keeps native callbacks out of the caller's stack
563
- // without paying the timer granularity for every bounded batch.
564
- setImmediate(() => {
565
- void this.#run();
566
- });
567
- }
568
- }
569
-
570
- stop(): void {
571
- this.#stopped = true;
572
- this.#pending = false;
573
- this.#listener = undefined;
574
- }
575
-
576
- async #run(): Promise<void> {
577
- try {
578
- while (!this.#stopped && this.#pending) {
579
- this.#pending = false;
580
- let events = this.#drain();
581
- while (!this.#stopped && events.length > 0) {
582
- for (const event of events) {
583
- try {
584
- this.#listener?.(this.#normalize(event));
585
- } catch {
586
- // Application callbacks and malformed events cannot stop draining.
587
- }
588
- }
589
- await new Promise<void>((resolve) => {
590
- setImmediate(resolve);
591
- });
592
- if (this.#stopped) {
593
- break;
594
- }
595
- events = this.#drain();
596
- }
597
- }
598
- } finally {
599
- this.#running = false;
600
- if (this.#pending && !this.#stopped) {
601
- this.ring();
602
- }
603
- }
604
- }
605
- }
606
-
607
535
  interface NativeIdMaps {
608
- readonly connectionIds: IdMap;
536
+ readonly connectionIds: ConnectionIdMap;
609
537
  readonly streamIds: StreamIdMap;
610
538
  }
611
539
 
612
- class IdMap {
613
- readonly #nativeByPublic = new Map<number, bigint>();
614
- readonly #publicByNative = new Map<bigint, number>();
615
- #next = 1;
616
-
617
- toPublic(native: bigint): number {
618
- const existing = this.#publicByNative.get(native);
619
- if (existing !== undefined) {
620
- return existing;
621
- }
622
- const publicId = this.#next;
623
- this.#next += 1;
624
- this.#publicByNative.set(native, publicId);
625
- this.#nativeByPublic.set(publicId, native);
626
- return publicId;
627
- }
628
-
629
- /** The native ID of a live public connection; only stream ops ask. */
630
- toNative(publicId: number): bigint {
631
- const native = this.#nativeByPublic.get(publicId);
632
- if (native === undefined) {
633
- throw new StreamClosedError("The stream's connection ended");
634
- }
635
- return native;
636
- }
637
-
638
- deletePublic(publicId: number): void {
639
- const native = this.#nativeByPublic.get(publicId);
640
- if (native !== undefined) {
641
- this.#nativeByPublic.delete(publicId);
642
- this.#publicByNative.delete(native);
643
- }
644
- }
645
- }
646
-
647
540
  /**
648
541
  * Maps native stream IDs, which are unique only within their connection, to
649
542
  * public numbers that never repeat. Each stream remembers its public