@minip2p/core 0.8.3 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minip2p/core",
3
- "version": "0.8.3",
3
+ "version": "0.9.1",
4
4
  "description": "Platform-neutral TypeScript SDK for minip2p",
5
5
  "keywords": [
6
6
  "libp2p",
package/src/backend.ts CHANGED
@@ -1,8 +1,10 @@
1
1
  import {
2
2
  BackpressureError,
3
+ InvalidConfigError,
3
4
  MessageTooLargeError,
4
5
  NotPermittedError,
5
6
  } from "./errors.js";
7
+ import { ConfigCapability } from "./types.js";
6
8
  import type {
7
9
  Bytes,
8
10
  ConnectionInfo,
@@ -40,7 +42,10 @@ export type BackendConnectTarget =
40
42
  export interface Minip2pBackend {
41
43
  /** Starts native event delivery exactly once. */
42
44
  start: (listener: (event: P2pEvent) => void) => void;
43
- /** Releases adapter state retained until an event has been dispatched. */
45
+ /**
46
+ * Releases adapter state retained until an event has been dispatched,
47
+ * elided, dropped, or coalesced into an earlier one.
48
+ */
44
49
  eventHandled?: (event: P2pEvent) => void;
45
50
  /** Idempotently releases the native endpoint. */
46
51
  close: () => void;
@@ -101,8 +106,10 @@ export interface Minip2pBackend {
101
106
  *
102
107
  * Called once, when the stream becomes ready; the returned function keeps
103
108
  * naming that stream after its terminal event retires the public IDs. It
104
- * throws on an over-acknowledgement and is a no-op once the stream or its
105
- * connection is gone.
109
+ * throws on an over-acknowledgement and is a no-op once the stream is
110
+ * settled. Unacknowledged bytes hold their ended connection's native slot,
111
+ * so this, and `abandonStream`, must still reach native for a stream whose
112
+ * connection ended while its events were in flight (see `SettleHandles`).
106
113
  */
107
114
  streamConsumer: (connId: number, streamId: number) => (bytes: number) => void;
108
115
  /** Half-closes the local stream write side, after any pending write. */
@@ -122,6 +129,7 @@ export interface Minip2pBackend {
122
129
  export { resolveEndpointConfig, type BackendEndpointConfig } from "./config.js";
123
130
  export { EventDrain } from "./event-drain.js";
124
131
  export { ConnectionIdMap, u64ToNumber } from "./native-ids.js";
132
+ export { SettleHandles, eventStream } from "./settle-handles.js";
125
133
  export {
126
134
  P2pEvent_Tags,
127
135
  PathKind_Tags,
@@ -131,14 +139,31 @@ export {
131
139
  } from "./types.js";
132
140
 
133
141
  /**
134
- * Returns the typed SDK error for a native `FfiError` variant name, or
135
- * `undefined` for variants that adapters rethrow unchanged. `detail` is the
136
- * variant's detail field, when it has one.
142
+ * The parts of a native `FfiError` an adapter reads off its toolchain's error
143
+ * value: the variant name, its detail field, and an `InvalidConfig`'s
144
+ * capability as its Rust variant name.
145
+ */
146
+ export interface NativeErrorFields {
147
+ readonly tag?: string | undefined;
148
+ readonly detail?: string | undefined;
149
+ readonly capability?: string | undefined;
150
+ }
151
+
152
+ // Each capability's name is its value, so an own key is a capability.
153
+ const isConfigCapability = (name: string): name is ConfigCapability =>
154
+ Object.hasOwn(ConfigCapability, name);
155
+
156
+ /**
157
+ * Returns the typed SDK error for a native `FfiError`, or `undefined` for
158
+ * variants that adapters rethrow unchanged. An `InvalidConfig` whose
159
+ * capability is missing or unknown (native and SDK versions out of step)
160
+ * is rethrown unchanged too, rather than given a capability it did not name.
137
161
  */
138
- export const typedFfiError = (
139
- tag: string | undefined,
140
- detail: string | undefined
141
- ): Error | undefined => {
162
+ export const typedFfiError = ({
163
+ capability,
164
+ detail,
165
+ tag,
166
+ }: NativeErrorFields): Error | undefined => {
142
167
  switch (tag) {
143
168
  case "Backpressure": {
144
169
  return new BackpressureError();
@@ -149,6 +174,11 @@ export const typedFfiError = (
149
174
  case "NotPermitted": {
150
175
  return new NotPermittedError(detail);
151
176
  }
177
+ case "InvalidConfig": {
178
+ return capability !== undefined && isConfigCapability(capability)
179
+ ? new InvalidConfigError(capability, detail ?? "")
180
+ : undefined;
181
+ }
152
182
  default: {
153
183
  return undefined;
154
184
  }
package/src/errors.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  /* oxlint-disable max-classes-per-file -- Public error types are intentionally colocated. */
2
2
 
3
3
  import type {
4
+ ConfigCapability,
4
5
  DriverFailureKind,
5
6
  EndpointErrorKind,
6
7
  NatErrorKind,
@@ -30,6 +31,25 @@ export class NotPermittedError extends Error {
30
31
  }
31
32
  }
32
33
 
34
+ /**
35
+ * The endpoint configuration was invalid. `capability` names the part of the
36
+ * configuration to change; a socket the platform refused is a transport
37
+ * failure instead, and a malformed listen address an invalid-address one.
38
+ */
39
+ export class InvalidConfigError extends Error {
40
+ /** The part of the configuration that was invalid. */
41
+ readonly capability: ConfigCapability;
42
+ /** Human-readable native diagnostic. */
43
+ readonly detail: string;
44
+
45
+ constructor(capability: ConfigCapability, detail: string) {
46
+ super(detail.length > 0 ? detail : `Invalid ${capability} configuration`);
47
+ this.name = "InvalidConfigError";
48
+ this.capability = capability;
49
+ this.detail = detail;
50
+ }
51
+ }
52
+
33
53
  /** Platform-neutral operation cancellation error. */
34
54
  export class AbortError extends Error {
35
55
  constructor(message = "The operation was aborted") {
package/src/index.ts CHANGED
@@ -8,6 +8,7 @@ export {
8
8
  ConnectResultUnavailableError,
9
9
  DriverFailedError,
10
10
  EventQueueOverflowError,
11
+ InvalidConfigError,
11
12
  MessageTooLargeError,
12
13
  NotPermittedError,
13
14
  OpenStreamError,
@@ -18,9 +19,11 @@ export {
18
19
  } from "./errors.js";
19
20
  export { Minip2pBase, Stream, type StreamEventMap } from "./sdk.js";
20
21
  export {
22
+ ConfigCapability,
21
23
  DiscoverySource,
22
24
  DriverFailureKind,
23
25
  EndpointErrorKind,
26
+ MdnsFailureKind,
24
27
  NatErrorKind,
25
28
  Reachability,
26
29
  type Bytes,
package/src/sdk.ts CHANGED
@@ -328,6 +328,33 @@ class StreamTable<Value> {
328
328
  }
329
329
  }
330
330
 
331
+ /** Every connection a native event names. */
332
+ const connectionsOf = (event: P2pEvent): number[] => {
333
+ if (!("inner" in event)) {
334
+ return [];
335
+ }
336
+ const { inner } = event;
337
+ return [
338
+ "connId" in inner ? inner.connId : undefined,
339
+ "oldConnId" in inner ? inner.oldConnId : undefined,
340
+ "newConnId" in inner ? inner.newConnId : undefined,
341
+ ].filter((id): id is number => typeof id === "number");
342
+ };
343
+
344
+ /**
345
+ * Native events that leave a connection unseen. Anything else naming it is
346
+ * something the application acts on or must hear about, so it keeps the
347
+ * connection's events.
348
+ */
349
+ const UNSEEN_CONNECTION_TAGS: ReadonlySet<string> = new Set<P2pEvent["tag"]>([
350
+ P2pEvent_Tags.PeerReady,
351
+ P2pEvent_Tags.IdentifyReceived,
352
+ P2pEvent_Tags.EndpointError,
353
+ P2pEvent_Tags.StreamRemoteWriteClosed,
354
+ P2pEvent_Tags.StreamWriteStopped,
355
+ P2pEvent_Tags.StreamClosed,
356
+ ]);
357
+
331
358
  /** The native per-stream event an item carries, if any. */
332
359
  const streamEventOf = (
333
360
  item: QueueItem
@@ -348,6 +375,15 @@ const streamEventOf = (
348
375
  * A peer-opened stream that closes without data before its `StreamReady`
349
376
  * is dispatched leaves the queue whole, so a peer opening and closing
350
377
  * streams cannot grow it; its events still reach `release`.
378
+ *
379
+ * Connections follow the same rule (ADR 0012): one that ends without data
380
+ * before any of its events was dispatched, whichever side dialed it, leaves
381
+ * with every event naming it. One replaced instead folds into its
382
+ * successor: its queued `ConnectionEstablished` is renamed to the successor
383
+ * and the `ConnectionReplaced` goes (as it does when the capacity already
384
+ * dropped that `ConnectionEstablished`). A connection the application knows
385
+ * otherwise -- a stream it opened, a ping result, an attempt or path event
386
+ * naming it -- is kept.
351
387
  */
352
388
  class EventQueue {
353
389
  readonly #items = new Map<number, QueueItem>();
@@ -359,6 +395,14 @@ class EventQueue {
359
395
  * queued item ids; `undefined` once one carried data.
360
396
  */
361
397
  readonly #unseen = new StreamTable<number[] | undefined>();
398
+ /** Connections whose `ConnectionEstablished` is queued and unseen. */
399
+ readonly #unseenConnections = new Set<number>();
400
+ /**
401
+ * Live connections the application learned of outside the queue, so a
402
+ * later replacement fold must not make them unseen; each leaves with its
403
+ * end.
404
+ */
405
+ readonly #knownConnections = new Set<number>();
362
406
  readonly #capacity: number;
363
407
  readonly #release: (item: QueueItem) => void;
364
408
  #next = 0;
@@ -380,14 +424,14 @@ class EventQueue {
380
424
  const merged =
381
425
  newest === undefined ? undefined : coalesceData(newest, item);
382
426
  if (merged !== undefined && this.#newest !== undefined) {
383
- // A data event retires no adapter IDs, so the absorbed one needs no
384
- // `eventHandled`.
385
427
  this.#items.set(this.#newest, merged);
428
+ // The absorbed event is handled: its adapter state goes now.
429
+ this.#release(item);
386
430
  return undefined;
387
431
  }
388
432
  const id = this.#next;
389
433
  this.#next += 1;
390
- if (this.#elideUnseen(item, id)) {
434
+ if (this.#elideUnseen(item, id) || this.#elideConnection(item)) {
391
435
  return undefined;
392
436
  }
393
437
  this.#items.set(id, item);
@@ -410,15 +454,114 @@ class EventQueue {
410
454
  return undefined;
411
455
  }
412
456
  const item = this.#remove(oldest);
413
- if (
414
- item?.source === "native" &&
415
- item.event.tag === P2pEvent_Tags.StreamReady
416
- ) {
417
- this.#unseen.delete(item.event.inner.connId, item.event.inner.streamId);
457
+ if (item?.source === "native") {
458
+ if (item.event.tag === P2pEvent_Tags.StreamReady) {
459
+ this.#unseen.delete(item.event.inner.connId, item.event.inner.streamId);
460
+ }
461
+ for (const connId of connectionsOf(item.event)) {
462
+ this.#unseenConnections.delete(connId);
463
+ }
418
464
  }
419
465
  return item;
420
466
  }
421
467
 
468
+ /** The application learned of `connId` outside the queue. */
469
+ markConnectionSeen(connId: number): void {
470
+ this.#unseenConnections.delete(connId);
471
+ this.#knownConnections.add(connId);
472
+ }
473
+
474
+ /**
475
+ * Records `item` against the unseen connections it names. Returns whether
476
+ * it ended or replaced one that carried no data, which leaves the queue
477
+ * with that connection's items instead.
478
+ */
479
+ #elideConnection(item: QueueItem): boolean {
480
+ if (item.source !== "native") {
481
+ return false;
482
+ }
483
+ const { event } = item;
484
+ switch (event.tag) {
485
+ case P2pEvent_Tags.ConnectionEstablished: {
486
+ if (!this.#knownConnections.has(event.inner.connId)) {
487
+ this.#unseenConnections.add(event.inner.connId);
488
+ }
489
+ return false;
490
+ }
491
+ case P2pEvent_Tags.ConnectionClosed: {
492
+ this.#knownConnections.delete(event.inner.connId);
493
+ if (!this.#unseenConnections.delete(event.inner.connId)) {
494
+ return false;
495
+ }
496
+ this.#removeConnection(event.inner.connId);
497
+ this.#release(item);
498
+ return true;
499
+ }
500
+ case P2pEvent_Tags.ConnectionReplaced: {
501
+ const { newConnId, oldConnId } = event.inner;
502
+ this.#knownConnections.delete(oldConnId);
503
+ if (!this.#unseenConnections.delete(oldConnId)) {
504
+ return false;
505
+ }
506
+ this.#renameOpening(oldConnId, newConnId);
507
+ this.#removeConnection(oldConnId);
508
+ if (!this.#knownConnections.has(newConnId)) {
509
+ this.#unseenConnections.add(newConnId);
510
+ }
511
+ this.#release(item);
512
+ return true;
513
+ }
514
+ case P2pEvent_Tags.StreamReady: {
515
+ if (event.inner.initiatedLocally) {
516
+ this.#unseenConnections.delete(event.inner.connId);
517
+ }
518
+ return false;
519
+ }
520
+ default: {
521
+ if (!UNSEEN_CONNECTION_TAGS.has(event.tag)) {
522
+ for (const connId of connectionsOf(event)) {
523
+ this.#unseenConnections.delete(connId);
524
+ }
525
+ }
526
+ return false;
527
+ }
528
+ }
529
+ }
530
+
531
+ /** Renames the queued `ConnectionEstablished` of `from` to `to`. */
532
+ #renameOpening(from: number, to: number): void {
533
+ for (const [id, queued] of this.#items) {
534
+ if (
535
+ queued.source === "native" &&
536
+ queued.event.tag === P2pEvent_Tags.ConnectionEstablished &&
537
+ queued.event.inner.connId === from
538
+ ) {
539
+ this.#items.set(id, {
540
+ event: {
541
+ ...queued.event,
542
+ inner: { ...queued.event.inner, connId: to },
543
+ },
544
+ source: "native",
545
+ });
546
+ return;
547
+ }
548
+ }
549
+ }
550
+
551
+ /** Removes every queued item naming `connId`, releasing each. */
552
+ #removeConnection(connId: number): void {
553
+ for (const [id, queued] of [...this.#items]) {
554
+ if (
555
+ queued.source === "native" &&
556
+ connectionsOf(queued.event).includes(connId)
557
+ ) {
558
+ this.#remove(id);
559
+ this.#release(queued);
560
+ }
561
+ }
562
+ this.#unseen.takeConnection(connId);
563
+ }
564
+
422
565
  /**
423
566
  * Records `item` (as `id`) against an unseen peer stream. Returns whether
424
567
  * it closed one that carried no data, which leaves the queue whole.
@@ -1376,6 +1519,8 @@ export class Minip2pBase {
1376
1519
  let identity: { readonly connId: number; readonly streamId: number };
1377
1520
  try {
1378
1521
  identity = this.#backend.openStream(peerId, protocolId);
1522
+ // The application now knows the connection: its end must reach it.
1523
+ this.#queue.markConnectionSeen(identity.connId);
1379
1524
  } catch (error) {
1380
1525
  return Promise.reject(
1381
1526
  new OpenStreamError({
@@ -2209,6 +2354,8 @@ const SDK_EVENT_NAMES: {
2209
2354
  [P2pEvent_Tags.PeerUpdated]: "peerUpdated",
2210
2355
  [P2pEvent_Tags.PeerExpired]: "peerExpired",
2211
2356
  [P2pEvent_Tags.DiscoveryDialFailed]: "discoveryDialFailed",
2357
+ [P2pEvent_Tags.MdnsFailed]: "mdnsFailed",
2358
+ [P2pEvent_Tags.MdnsRecovered]: "mdnsRecovered",
2212
2359
  [P2pEvent_Tags.DiscoveryProtocolViolation]: "discoveryProtocolViolation",
2213
2360
  };
2214
2361
 
@@ -2230,7 +2377,8 @@ function normalizeEvent(
2230
2377
  payload: AnyPayload;
2231
2378
  } {
2232
2379
  const type = SDK_EVENT_NAMES[event.tag];
2233
- let payload: unknown = event.inner;
2380
+ // A native variant without fields arrives without `inner`.
2381
+ let payload: unknown = "inner" in event ? event.inner : {};
2234
2382
  if (event.tag === P2pEvent_Tags.PathEstablished) {
2235
2383
  payload = { ...event.inner, path: normalizePath(event.inner.path) };
2236
2384
  } else if (event.tag === P2pEvent_Tags.InboundPathEstablished) {
@@ -0,0 +1,78 @@
1
+ import { P2pEvent_Tags } from "./types.js";
2
+ import type { P2pEvent } from "./types.js";
3
+
4
+ /** The public stream a backend event names, when it names one. */
5
+ export const eventStream = (
6
+ event: P2pEvent
7
+ ): { readonly connId: number; readonly streamId: number } | undefined => {
8
+ switch (event.tag) {
9
+ case P2pEvent_Tags.StreamReady:
10
+ case P2pEvent_Tags.StreamData:
11
+ case P2pEvent_Tags.StreamWriteAccepted:
12
+ case P2pEvent_Tags.StreamWriteStopped:
13
+ case P2pEvent_Tags.StreamRemoteWriteClosed:
14
+ case P2pEvent_Tags.StreamClosed: {
15
+ return event.inner;
16
+ }
17
+ default: {
18
+ return undefined;
19
+ }
20
+ }
21
+ };
22
+
23
+ /**
24
+ * Native identities of streams whose events the SDK has not finished
25
+ * handling: the acknowledgement-only handle that outlives a stream's
26
+ * connection (ADR 0012).
27
+ *
28
+ * An adapter releases a connection's public ID as soon as it normalizes the
29
+ * event that ends it, so stream operations behind that event fail. Bytes the
30
+ * stream already delivered still hold the ended connection's native slot
31
+ * until they are acknowledged or abandoned, though, and the SDK may only get
32
+ * to them afterwards: dispatching a late `StreamReady`, discarding data for
33
+ * a stream it no longer tracks, or reading bytes kept after a FIN. Each
34
+ * normalized stream event holds its stream's handle until `eventHandled`, so
35
+ * those paths still reach native; a stream consumer captured while it was
36
+ * held keeps working after. With no event left in flight, the handle goes.
37
+ */
38
+ export class SettleHandles<Native> {
39
+ readonly #handles = new Map<
40
+ number,
41
+ Map<number, { native: Native; held: number }>
42
+ >();
43
+
44
+ /** Holds `native` for the stream of one normalized event. */
45
+ hold(connId: number, streamId: number, native: Native): void {
46
+ let streams = this.#handles.get(connId);
47
+ if (streams === undefined) {
48
+ streams = new Map();
49
+ this.#handles.set(connId, streams);
50
+ }
51
+ const handle = streams.get(streamId);
52
+ if (handle === undefined) {
53
+ streams.set(streamId, { held: 1, native });
54
+ } else {
55
+ handle.held += 1;
56
+ }
57
+ }
58
+
59
+ /** Releases one event's hold, once the SDK handled it. */
60
+ release(connId: number, streamId: number): void {
61
+ const streams = this.#handles.get(connId);
62
+ const handle = streams?.get(streamId);
63
+ if (streams === undefined || handle === undefined) {
64
+ return;
65
+ }
66
+ handle.held -= 1;
67
+ if (handle.held === 0) {
68
+ streams.delete(streamId);
69
+ if (streams.size === 0) {
70
+ this.#handles.delete(connId);
71
+ }
72
+ }
73
+ }
74
+
75
+ get(connId: number, streamId: number): Native | undefined {
76
+ return this.#handles.get(connId)?.get(streamId)?.native;
77
+ }
78
+ }
package/src/types.ts CHANGED
@@ -52,6 +52,45 @@ export const DiscoverySource = {
52
52
  export type DiscoverySource =
53
53
  (typeof DiscoverySource)[keyof typeof DiscoverySource];
54
54
 
55
+ /** Categories of an mDNS failure reported by `mdnsFailed`. */
56
+ export const MdnsFailureKind = {
57
+ /** A goodbye could not be sent before shutdown gave up on a full send buffer. */
58
+ Congested: "Congested",
59
+ /** The interface id space is exhausted. */
60
+ InterfaceIdsExhausted: "InterfaceIdsExhausted",
61
+ /** Platform I/O failed. */
62
+ Io: "Io",
63
+ /** An interface has no usable address. */
64
+ NoInterfaceAddress: "NoInterfaceAddress",
65
+ /** A datagram is larger than the carrier can ever send. */
66
+ Oversized: "Oversized",
67
+ /** A send named an interface that has gone away. */
68
+ UnknownInterface: "UnknownInterface",
69
+ /** The platform cannot provide mDNS sockets. */
70
+ Unsupported: "Unsupported",
71
+ } as const;
72
+ export type MdnsFailureKind =
73
+ (typeof MdnsFailureKind)[keyof typeof MdnsFailureKind];
74
+
75
+ /** The part of an endpoint's configuration an `InvalidConfigError` names. */
76
+ export const ConfigCapability = {
77
+ /** Signed discovery or peer-book settings. */
78
+ Discovery: "Discovery",
79
+ /** Gossipsub settings. */
80
+ Gossipsub: "Gossipsub",
81
+ /** mDNS settings. */
82
+ Mdns: "Mdns",
83
+ /**
84
+ * The endpoint's own options: listen addresses, protocols, NAT and relay
85
+ * policy, auto-dial.
86
+ */
87
+ Options: "Options",
88
+ /** QUIC or TCP transport settings. */
89
+ Transport: "Transport",
90
+ } as const;
91
+ export type ConfigCapability =
92
+ (typeof ConfigCapability)[keyof typeof ConfigCapability];
93
+
55
94
  /** Fatal native-driver failure categories. */
56
95
  export const DriverFailureKind = {
57
96
  Invariant: "Invariant",
@@ -304,6 +343,14 @@ export interface Minip2pNamedEventMap {
304
343
  };
305
344
  peerExpired: { readonly peerId: string };
306
345
  discoveryDialFailed: { readonly peerId: string; readonly reason: string };
346
+ /**
347
+ * mDNS hit a hard failure. It keeps running and retries; this fires once
348
+ * per change in failure state, and `mdnsRecovered` follows once a retry
349
+ * succeeds. A goodbye that failed during shutdown is final.
350
+ */
351
+ mdnsFailed: { readonly kind: MdnsFailureKind; readonly detail: string };
352
+ /** mDNS recovered from its last `mdnsFailed`. Carries no fields. */
353
+ mdnsRecovered: Readonly<Record<never, never>>;
307
354
  discoveryProtocolViolation: {
308
355
  readonly peerId?: string;
309
356
  readonly source: DiscoverySource;
@@ -450,6 +497,8 @@ export const P2pEvent_Tags = {
450
497
  IdentifyReceived: "IdentifyReceived",
451
498
  InboundDirectUpgrade: "InboundDirectUpgrade",
452
499
  InboundPathEstablished: "InboundPathEstablished",
500
+ MdnsFailed: "MdnsFailed",
501
+ MdnsRecovered: "MdnsRecovered",
453
502
  Message: "Message",
454
503
  PathEstablished: "PathEstablished",
455
504
  PathUpgraded: "PathUpgraded",
@@ -626,6 +675,12 @@ export type P2pEvent =
626
675
  typeof P2pEvent_Tags.DiscoveryDialFailed,
627
676
  Minip2pNamedEventMap["discoveryDialFailed"]
628
677
  >
678
+ | RawEvent<
679
+ typeof P2pEvent_Tags.MdnsFailed,
680
+ Minip2pNamedEventMap["mdnsFailed"]
681
+ >
682
+ // A variant without fields has no `inner`, as both runtimes deliver it.
683
+ | { readonly tag: typeof P2pEvent_Tags.MdnsRecovered }
629
684
  | RawEvent<
630
685
  typeof P2pEvent_Tags.DiscoveryProtocolViolation,
631
686
  Minip2pNamedEventMap["discoveryProtocolViolation"]