@minip2p/core 0.9.1 → 0.10.0

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
@@ -416,15 +441,20 @@ export interface ConnectOptions extends OpOptions {
416
441
  readonly cancelOnTimeout?: boolean;
417
442
  }
418
443
 
419
- /** The transport connection currently selected for a peer. */
444
+ /** A snapshot of a peer's established connection. */
420
445
  export interface ConnectionInfo {
446
+ /** The peer on the other end. */
447
+ readonly peerId: string;
421
448
  /** Endpoint-local connection identifier, as carried by connection events. */
422
449
  readonly connId: number;
423
- /** Remote transport address, when known. */
424
- readonly remoteAddr?: string;
450
+ /** Remote transport address; a circuit reports `/p2p/<relay>/p2p-circuit`. */
451
+ readonly remoteAddr: string;
452
+ /** How the connection was made. */
453
+ readonly path: Path;
425
454
  /**
426
- * Protocols this connection advertised, once it is ready; absent until
427
- * then. Readiness, `connId` and protocols come from one native snapshot.
455
+ * Protocols this connection advertised through Identify, once it is ready;
456
+ * absent until then, which is distinct from an empty list. Readiness,
457
+ * `connId` and protocols come from one native snapshot.
428
458
  */
429
459
  readonly readyProtocols?: readonly string[];
430
460
  }
@@ -453,12 +483,38 @@ export interface ConnectResult {
453
483
  readonly path: Path;
454
484
  }
455
485
 
456
- /** Reason reported to endpoint close observers. */
457
- export type CloseReason =
458
- | { readonly reason: "close" }
486
+ /** How the native close drain ended. */
487
+ export const CloseOutcome = {
488
+ /** The close deadline passed with connections still tracked. */
489
+ DeadlineExpired: "DeadlineExpired",
490
+ /** Every tracked connection finished its teardown in time. */
491
+ Drained: "Drained",
492
+ /** Driving the transports failed and ended the drain early. */
493
+ Failed: "Failed",
494
+ } as const;
495
+ export type CloseOutcome = (typeof CloseOutcome)[keyof typeof CloseOutcome];
496
+
497
+ /** Why the endpoint stopped: the application closed it, or its driver failed. */
498
+ export type EndpointCloseReason = EndpointCloseReport["reason"];
499
+
500
+ /**
501
+ * What endpoint close observers receive once the native drain finished.
502
+ * `unfinished` lists the peers whose connections were still tracked when it
503
+ * ended (an inbound handshake that had not identified its peer is not
504
+ * listed); empty means no tracked teardown remains, not that peers
505
+ * acknowledged it. A failed driver tears down at once, so its report has no
506
+ * `outcome`.
507
+ */
508
+ export type EndpointCloseReport =
509
+ | {
510
+ readonly reason: "close";
511
+ readonly outcome: CloseOutcome;
512
+ readonly unfinished: readonly string[];
513
+ }
459
514
  | {
460
515
  readonly reason: "driverFailed";
461
516
  readonly error: DriverFailedError;
517
+ readonly unfinished: readonly string[];
462
518
  };
463
519
 
464
520
  /** Idempotent callback that removes a subscription. */
@@ -466,19 +522,40 @@ export type Unsubscribe = () => void;
466
522
 
467
523
  /** Raw backend-only path tags. */
468
524
  export const PathKind_Tags = {
469
- DirectDialed: "DirectDialed",
470
- DirectPunched: "DirectPunched",
525
+ Direct: "Direct",
526
+ Punched: "Punched",
471
527
  Relayed: "Relayed",
472
528
  } as const;
473
529
  export type PathKindTag = (typeof PathKind_Tags)[keyof typeof PathKind_Tags];
474
530
  export type PathKind =
475
- | { readonly tag: typeof PathKind_Tags.DirectDialed }
476
- | { readonly tag: typeof PathKind_Tags.DirectPunched }
531
+ | { readonly tag: typeof PathKind_Tags.Direct }
532
+ | { readonly tag: typeof PathKind_Tags.Punched }
477
533
  | {
478
534
  readonly tag: typeof PathKind_Tags.Relayed;
479
535
  readonly inner: { readonly relayPeerId: string };
480
536
  };
481
537
 
538
+ /** Raw backend-only connection close reason tags. */
539
+ export const ConnectionCloseReason_Tags = {
540
+ Error: "Error",
541
+ Local: "Local",
542
+ Remote: "Remote",
543
+ Stalled: "Stalled",
544
+ TimedOut: "TimedOut",
545
+ } as const;
546
+ export type RawConnectionCloseReason =
547
+ | { readonly tag: typeof ConnectionCloseReason_Tags.Local }
548
+ | {
549
+ readonly tag: typeof ConnectionCloseReason_Tags.Remote;
550
+ readonly inner: { readonly code: bigint };
551
+ }
552
+ | { readonly tag: typeof ConnectionCloseReason_Tags.TimedOut }
553
+ | { readonly tag: typeof ConnectionCloseReason_Tags.Stalled }
554
+ | {
555
+ readonly tag: typeof ConnectionCloseReason_Tags.Error;
556
+ readonly inner: { readonly message: string };
557
+ };
558
+
482
559
  /** Raw backend-only event tags. */
483
560
  export const P2pEvent_Tags = {
484
561
  ConnectCancelled: "ConnectCancelled",
@@ -489,6 +566,7 @@ export const P2pEvent_Tags = {
489
566
  DiscoveryDialFailed: "DiscoveryDialFailed",
490
567
  DiscoveryProtocolViolation: "DiscoveryProtocolViolation",
491
568
  DriverFailed: "DriverFailed",
569
+ EndpointClosed: "EndpointClosed",
492
570
  EndpointError: "EndpointError",
493
571
  EventsDropped: "EventsDropped",
494
572
  GossipsubOutboundFailure: "GossipsubOutboundFailure",
@@ -541,13 +619,20 @@ export type P2pEvent =
541
619
  typeof P2pEvent_Tags.DriverFailed,
542
620
  { kind: DriverFailureKind; detail: string }
543
621
  >
622
+ | RawEvent<
623
+ typeof P2pEvent_Tags.EndpointClosed,
624
+ {
625
+ outcome: CloseOutcome;
626
+ unfinished: { connId: number; peerId?: string }[];
627
+ }
628
+ >
544
629
  | RawEvent<
545
630
  typeof P2pEvent_Tags.ConnectionEstablished,
546
631
  { peerId: string; connId: number }
547
632
  >
548
633
  | RawEvent<
549
634
  typeof P2pEvent_Tags.ConnectionClosed,
550
- { peerId: string; connId: number }
635
+ { peerId: string; connId: number; reason: RawConnectionCloseReason }
551
636
  >
552
637
  | RawEvent<
553
638
  typeof P2pEvent_Tags.ConnectionReplaced,