@minip2p/node 0.7.3 → 0.7.4

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
 
@@ -240,7 +249,7 @@ class NodeBackend implements Minip2pBackend {
240
249
  // Connect IDs are not mapped because they round-trip into native calls,
241
250
  // and native allocates them well inside the safe integer range.
242
251
  connect(target: BackendConnectTarget): number {
243
- return bigintToNumber(
252
+ return u64ToNumber(
244
253
  translateErrors(() =>
245
254
  this.#endpoint.connect(
246
255
  target.kind === "peer" ? target.peerId : [...target.addresses]
@@ -326,39 +335,46 @@ function toUint8Array(value: Bytes): Uint8Array {
326
335
  : new Uint8Array(value);
327
336
  }
328
337
 
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;
335
- }
336
-
337
- function normalizeOptional<Value>(value: unknown): Value | undefined {
338
- return value === null || value === undefined
339
- ? undefined
340
- : normalizeRecord<Value>(value);
338
+ /** Converts an Identify snapshot, copying its public key into an `ArrayBuffer`. */
339
+ function identifyInfo({
340
+ publicKey,
341
+ ...info
342
+ }: NativeIdentifyInfo): IdentifyInfo {
343
+ return {
344
+ ...info,
345
+ ...(publicKey !== undefined && { publicKey: toArrayBuffer(publicKey) }),
346
+ };
341
347
  }
342
348
 
343
- function normalizeRecord<Value>(value: unknown): Value {
344
- return normalizeNativeValue(value) as Value;
349
+ function knownPeer({
350
+ beaconLastSeenAgeMs,
351
+ mdnsLastSeenAgeMs,
352
+ ...peer
353
+ }: NativeKnownPeerInfo): KnownPeerInfo {
354
+ return {
355
+ ...peer,
356
+ ...(beaconLastSeenAgeMs !== undefined && {
357
+ beaconLastSeenAgeMs: u64ToNumber(
358
+ beaconLastSeenAgeMs,
359
+ "beaconLastSeenAgeMs"
360
+ ),
361
+ }),
362
+ ...(mdnsLastSeenAgeMs !== undefined && {
363
+ mdnsLastSeenAgeMs: u64ToNumber(mdnsLastSeenAgeMs, "mdnsLastSeenAgeMs"),
364
+ }),
365
+ };
345
366
  }
346
367
 
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
- );
368
+ function relayReservation({
369
+ expiresUnixSecs,
370
+ relayPeerId,
371
+ }: NativeRelayReservationInfo): RelayReservationInfo {
372
+ return {
373
+ relayPeerId,
374
+ ...(expiresUnixSecs !== undefined && {
375
+ expiresUnixSecs: u64ToNumber(expiresUnixSecs, "expiresUnixSecs"),
376
+ }),
377
+ };
362
378
  }
363
379
 
364
380
  /** Event fields carrying a native connection ID. */
@@ -368,80 +384,78 @@ const CONNECTION_ID_KEYS: ReadonlySet<string> = new Set([
368
384
  "newConnId",
369
385
  ]);
370
386
 
387
+ /**
388
+ * Converts one value of a native event: integers to numbers, connection IDs
389
+ * through the connection map, and bytes to `ArrayBuffer`s. A stream ID is
390
+ * mapped together with the connection of the record that carries it.
391
+ */
371
392
  function normalizeNativeValue(
372
393
  value: unknown,
373
- key?: string,
374
- maps?: NativeIdMaps
394
+ maps: NativeIdMaps,
395
+ key?: string
375
396
  ): unknown {
376
- const isId = typeof value === "bigint" || typeof value === "number";
377
- if (isId && maps !== undefined && key !== undefined) {
378
- if (CONNECTION_ID_KEYS.has(key)) {
397
+ if (typeof value === "bigint" || typeof value === "number") {
398
+ if (key !== undefined && CONNECTION_ID_KEYS.has(key)) {
379
399
  return maps.connectionIds.toPublic(BigInt(value));
380
400
  }
381
- if (key === "streamId") {
382
- // Mapped with its connection once the whole record is normalized.
383
- return value;
384
- }
401
+ return key === "streamId" ? value : u64ToNumber(value, key ?? "native u64");
385
402
  }
386
- if (typeof value === "bigint") {
387
- return bigintToNumber(value, "native value");
403
+ if (value instanceof Uint8Array) {
404
+ return toArrayBuffer(value);
388
405
  }
389
406
  if (Array.isArray(value)) {
390
- return value.map((item) => normalizeNativeValue(item, undefined, maps));
407
+ return value.map((item) => normalizeNativeValue(item, maps));
391
408
  }
392
- if (value instanceof Uint8Array) {
409
+ if (value === null || typeof value !== "object") {
393
410
  return value;
394
411
  }
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
- }
412
+ const record: Record<string, unknown> = Object.fromEntries(
413
+ Object.entries(value).map(([itemKey, item]) => [
414
+ itemKey,
415
+ normalizeNativeValue(item, maps, itemKey),
416
+ ])
417
+ );
418
+ const { connId, streamId } = record;
419
+ if (typeof streamId === "bigint" || typeof streamId === "number") {
420
+ // Public stream IDs are allocated per connection. A record without a
421
+ // connection (an endpoint error, say) cannot name a public stream.
422
+ if (typeof connId === "number") {
423
+ record.streamId = maps.streamIds.toPublic(connId, BigInt(streamId));
424
+ } else {
425
+ delete record.streamId;
419
426
  }
420
- return record;
421
427
  }
422
- return value;
428
+ return record;
423
429
  }
424
430
 
431
+ /**
432
+ * Converts one native event to its SDK backend form. Identify snapshots go
433
+ * through the typed {@link identifyInfo}; every other event shares the
434
+ * generic integer, ID and byte conversion.
435
+ */
425
436
  function normalizeEvent(
426
- value: unknown,
427
- connectionIds: IdMap,
437
+ event: NativeEvent,
438
+ connectionIds: ConnectionIdMap,
428
439
  streamIds: StreamIdMap
429
440
  ): 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;
441
+ // Outside Identify, the addon's serde shape is the SDK shape with napi-rs
442
+ // integers and buffers (see `native-shape.ts`), which the walk converts.
443
+ const normalized: P2pEvent =
444
+ event.tag === P2pEvent_Tags.IdentifyReceived
445
+ ? {
446
+ inner: {
447
+ info: identifyInfo(event.inner.info),
448
+ peerId: event.inner.peerId,
449
+ },
450
+ tag: event.tag,
451
+ }
452
+ : ({
453
+ inner: normalizeNativeValue(event.inner, {
454
+ connectionIds,
455
+ streamIds,
456
+ }),
457
+ tag: event.tag,
458
+ } as P2pEvent);
445
459
  retireTerminalIds(normalized, connectionIds, streamIds);
446
460
  return normalized;
447
461
  }
@@ -455,12 +469,12 @@ function normalizeEvent(
455
469
  */
456
470
  function retireTerminalIds(
457
471
  event: P2pEvent,
458
- connectionIds: IdMap,
472
+ connectionIds: ConnectionIdMap,
459
473
  streamIds: StreamIdMap
460
474
  ): void {
461
475
  const connId = endedConnection(event);
462
476
  if (connId !== undefined) {
463
- connectionIds.deletePublic(connId);
477
+ connectionIds.release(connId);
464
478
  streamIds.retireConnection(connId);
465
479
  }
466
480
  if (event.tag === P2pEvent_Tags.StreamClosed) {
@@ -493,38 +507,8 @@ function endedConnection(event: P2pEvent): number | undefined {
493
507
  return undefined;
494
508
  }
495
509
 
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
- }
510
+ /** Copies native bytes unless they already own their whole `ArrayBuffer`. */
511
+ function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
528
512
  if (
529
513
  bytes.buffer instanceof ArrayBuffer &&
530
514
  bytes.byteOffset === 0 &&
@@ -535,115 +519,11 @@ function nativeBytesToArrayBuffer(bytes: number[] | Uint8Array): ArrayBuffer {
535
519
  return Uint8Array.from(bytes).buffer;
536
520
  }
537
521
 
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
522
  interface NativeIdMaps {
608
- readonly connectionIds: IdMap;
523
+ readonly connectionIds: ConnectionIdMap;
609
524
  readonly streamIds: StreamIdMap;
610
525
  }
611
526
 
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
527
  /**
648
528
  * Maps native stream IDs, which are unique only within their connection, to
649
529
  * public numbers that never repeat. Each stream remembers its public