@minip2p/core 0.9.1 → 0.10.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/src/types.ts CHANGED
@@ -186,12 +186,29 @@ export interface RelayReservationInfo {
186
186
  readonly expiresUnixSecs?: number;
187
187
  }
188
188
 
189
- /** A usable NAT-orchestrated connection path. */
189
+ /**
190
+ * How an established connection was made: `direct` (dialed or accepted),
191
+ * `punched` (by a DCUtR hole punch), or `relayed` through a relay. A
192
+ * replacement connection has its own path.
193
+ */
190
194
  export type Path =
191
- | { readonly kind: "directDialed" }
192
- | { readonly kind: "directPunched" }
195
+ | { readonly kind: "direct" }
196
+ | { readonly kind: "punched" }
193
197
  | { readonly kind: "relayed"; readonly relayPeerId: string };
194
198
 
199
+ /**
200
+ * Why one connection ended. `remote` carries the peer's close code: its QUIC
201
+ * CONNECTION_CLOSE code, or its Yamux GoAway code over TCP and relay
202
+ * circuits. `timedOut` means the peer went silent, `stalled` that it stopped
203
+ * reading.
204
+ */
205
+ export type ConnectionCloseReason =
206
+ | { readonly kind: "local" }
207
+ | { readonly kind: "remote"; readonly code: bigint }
208
+ | { readonly kind: "timedOut" }
209
+ | { readonly kind: "stalled" }
210
+ | { readonly kind: "error"; readonly message: string };
211
+
195
212
  /** Serializable metadata for an inbound stream catch-all event. */
196
213
  export interface InboundStreamMeta {
197
214
  readonly peerId: string;
@@ -214,8 +231,16 @@ export interface Minip2pNamedEventMap {
214
231
  };
215
232
  /** A peer went from disconnected to connected on `connId`. */
216
233
  connectionEstablished: { readonly peerId: string; readonly connId: number };
217
- /** The peer's last connection closed; the peer is now disconnected. */
218
- connectionClosed: { readonly peerId: string; readonly connId: number };
234
+ /**
235
+ * The peer's last connection closed, for `reason`; the peer is now
236
+ * disconnected. A failure that ended it is its `reason`, never also an
237
+ * `endpointError`.
238
+ */
239
+ connectionClosed: {
240
+ readonly peerId: string;
241
+ readonly connId: number;
242
+ readonly reason: ConnectionCloseReason;
243
+ };
219
244
  /**
220
245
  * A newer connection took the peer's single connection slot from
221
246
  * `oldConnId`. The peer stays connected: this stands in for both a
@@ -264,6 +289,12 @@ export interface Minip2pNamedEventMap {
264
289
  readonly current: Reachability;
265
290
  readonly confirmedAddrs: readonly string[];
266
291
  };
292
+ /**
293
+ * The listen set changed without a `listen` call, as when a WebTransport
294
+ * listener's certificate rotates: `addrs` is the whole new set (what
295
+ * `listenAddrs()` now returns), for the app to republish.
296
+ */
297
+ listenAddressesChanged: { readonly addrs: readonly string[] };
267
298
  publicAddressesChanged: { readonly addrs: readonly string[] };
268
299
  relayReserved: {
269
300
  readonly relayPeerId: string;
@@ -416,15 +447,20 @@ export interface ConnectOptions extends OpOptions {
416
447
  readonly cancelOnTimeout?: boolean;
417
448
  }
418
449
 
419
- /** The transport connection currently selected for a peer. */
450
+ /** A snapshot of a peer's established connection. */
420
451
  export interface ConnectionInfo {
452
+ /** The peer on the other end. */
453
+ readonly peerId: string;
421
454
  /** Endpoint-local connection identifier, as carried by connection events. */
422
455
  readonly connId: number;
423
- /** Remote transport address, when known. */
424
- readonly remoteAddr?: string;
456
+ /** Remote transport address; a circuit reports `/p2p/<relay>/p2p-circuit`. */
457
+ readonly remoteAddr: string;
458
+ /** How the connection was made. */
459
+ readonly path: Path;
425
460
  /**
426
- * Protocols this connection advertised, once it is ready; absent until
427
- * then. Readiness, `connId` and protocols come from one native snapshot.
461
+ * Protocols this connection advertised through Identify, once it is ready;
462
+ * absent until then, which is distinct from an empty list. Readiness,
463
+ * `connId` and protocols come from one native snapshot.
428
464
  */
429
465
  readonly readyProtocols?: readonly string[];
430
466
  }
@@ -453,12 +489,38 @@ export interface ConnectResult {
453
489
  readonly path: Path;
454
490
  }
455
491
 
456
- /** Reason reported to endpoint close observers. */
457
- export type CloseReason =
458
- | { readonly reason: "close" }
492
+ /** How the native close drain ended. */
493
+ export const CloseOutcome = {
494
+ /** The close deadline passed with connections still tracked. */
495
+ DeadlineExpired: "DeadlineExpired",
496
+ /** Every tracked connection finished its teardown in time. */
497
+ Drained: "Drained",
498
+ /** Driving the transports failed and ended the drain early. */
499
+ Failed: "Failed",
500
+ } as const;
501
+ export type CloseOutcome = (typeof CloseOutcome)[keyof typeof CloseOutcome];
502
+
503
+ /** Why the endpoint stopped: the application closed it, or its driver failed. */
504
+ export type EndpointCloseReason = EndpointCloseReport["reason"];
505
+
506
+ /**
507
+ * What endpoint close observers receive once the native drain finished.
508
+ * `unfinished` lists the peers whose connections were still tracked when it
509
+ * ended (an inbound handshake that had not identified its peer is not
510
+ * listed); empty means no tracked teardown remains, not that peers
511
+ * acknowledged it. A failed driver tears down at once, so its report has no
512
+ * `outcome`.
513
+ */
514
+ export type EndpointCloseReport =
515
+ | {
516
+ readonly reason: "close";
517
+ readonly outcome: CloseOutcome;
518
+ readonly unfinished: readonly string[];
519
+ }
459
520
  | {
460
521
  readonly reason: "driverFailed";
461
522
  readonly error: DriverFailedError;
523
+ readonly unfinished: readonly string[];
462
524
  };
463
525
 
464
526
  /** Idempotent callback that removes a subscription. */
@@ -466,19 +528,40 @@ export type Unsubscribe = () => void;
466
528
 
467
529
  /** Raw backend-only path tags. */
468
530
  export const PathKind_Tags = {
469
- DirectDialed: "DirectDialed",
470
- DirectPunched: "DirectPunched",
531
+ Direct: "Direct",
532
+ Punched: "Punched",
471
533
  Relayed: "Relayed",
472
534
  } as const;
473
535
  export type PathKindTag = (typeof PathKind_Tags)[keyof typeof PathKind_Tags];
474
536
  export type PathKind =
475
- | { readonly tag: typeof PathKind_Tags.DirectDialed }
476
- | { readonly tag: typeof PathKind_Tags.DirectPunched }
537
+ | { readonly tag: typeof PathKind_Tags.Direct }
538
+ | { readonly tag: typeof PathKind_Tags.Punched }
477
539
  | {
478
540
  readonly tag: typeof PathKind_Tags.Relayed;
479
541
  readonly inner: { readonly relayPeerId: string };
480
542
  };
481
543
 
544
+ /** Raw backend-only connection close reason tags. */
545
+ export const ConnectionCloseReason_Tags = {
546
+ Error: "Error",
547
+ Local: "Local",
548
+ Remote: "Remote",
549
+ Stalled: "Stalled",
550
+ TimedOut: "TimedOut",
551
+ } as const;
552
+ export type RawConnectionCloseReason =
553
+ | { readonly tag: typeof ConnectionCloseReason_Tags.Local }
554
+ | {
555
+ readonly tag: typeof ConnectionCloseReason_Tags.Remote;
556
+ readonly inner: { readonly code: bigint };
557
+ }
558
+ | { readonly tag: typeof ConnectionCloseReason_Tags.TimedOut }
559
+ | { readonly tag: typeof ConnectionCloseReason_Tags.Stalled }
560
+ | {
561
+ readonly tag: typeof ConnectionCloseReason_Tags.Error;
562
+ readonly inner: { readonly message: string };
563
+ };
564
+
482
565
  /** Raw backend-only event tags. */
483
566
  export const P2pEvent_Tags = {
484
567
  ConnectCancelled: "ConnectCancelled",
@@ -489,6 +572,7 @@ export const P2pEvent_Tags = {
489
572
  DiscoveryDialFailed: "DiscoveryDialFailed",
490
573
  DiscoveryProtocolViolation: "DiscoveryProtocolViolation",
491
574
  DriverFailed: "DriverFailed",
575
+ EndpointClosed: "EndpointClosed",
492
576
  EndpointError: "EndpointError",
493
577
  EventsDropped: "EventsDropped",
494
578
  GossipsubOutboundFailure: "GossipsubOutboundFailure",
@@ -497,6 +581,7 @@ export const P2pEvent_Tags = {
497
581
  IdentifyReceived: "IdentifyReceived",
498
582
  InboundDirectUpgrade: "InboundDirectUpgrade",
499
583
  InboundPathEstablished: "InboundPathEstablished",
584
+ ListenAddressesChanged: "ListenAddressesChanged",
500
585
  MdnsFailed: "MdnsFailed",
501
586
  MdnsRecovered: "MdnsRecovered",
502
587
  Message: "Message",
@@ -541,13 +626,20 @@ export type P2pEvent =
541
626
  typeof P2pEvent_Tags.DriverFailed,
542
627
  { kind: DriverFailureKind; detail: string }
543
628
  >
629
+ | RawEvent<
630
+ typeof P2pEvent_Tags.EndpointClosed,
631
+ {
632
+ outcome: CloseOutcome;
633
+ unfinished: { connId: number; peerId?: string }[];
634
+ }
635
+ >
544
636
  | RawEvent<
545
637
  typeof P2pEvent_Tags.ConnectionEstablished,
546
638
  { peerId: string; connId: number }
547
639
  >
548
640
  | RawEvent<
549
641
  typeof P2pEvent_Tags.ConnectionClosed,
550
- { peerId: string; connId: number }
642
+ { peerId: string; connId: number; reason: RawConnectionCloseReason }
551
643
  >
552
644
  | RawEvent<
553
645
  typeof P2pEvent_Tags.ConnectionReplaced,
@@ -595,6 +687,10 @@ export type P2pEvent =
595
687
  typeof P2pEvent_Tags.ReachabilityChanged,
596
688
  Minip2pNamedEventMap["reachabilityChanged"]
597
689
  >
690
+ | RawEvent<
691
+ typeof P2pEvent_Tags.ListenAddressesChanged,
692
+ Minip2pNamedEventMap["listenAddressesChanged"]
693
+ >
598
694
  | RawEvent<
599
695
  typeof P2pEvent_Tags.PublicAddressesChanged,
600
696
  Minip2pNamedEventMap["publicAddressesChanged"]