@minip2p/core 0.8.3 → 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/README.md +10 -4
- package/dist/backend.d.ts +72 -13
- package/dist/backend.d.ts.map +1 -1
- package/dist/backend.js +69 -6
- package/dist/backend.js.map +1 -1
- package/dist/errors.d.ts +13 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +17 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/sdk.d.ts +30 -7
- package/dist/sdk.d.ts.map +1 -1
- package/dist/sdk.js +273 -46
- package/dist/sdk.js.map +1 -1
- package/dist/settle-handles.d.ts +30 -0
- package/dist/settle-handles.d.ts.map +1 -0
- package/dist/settle-handles.js +69 -0
- package/dist/settle-handles.js.map +1 -0
- package/dist/types.d.ts +154 -16
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +55 -2
- package/dist/types.js.map +1 -1
- package/package.json +1 -1
- package/src/backend.ts +136 -15
- package/src/errors.ts +20 -0
- package/src/index.ts +7 -1
- package/src/sdk.ts +307 -50
- package/src/settle-handles.ts +78 -0
- package/src/types.ts +158 -18
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",
|
|
@@ -147,12 +186,29 @@ export interface RelayReservationInfo {
|
|
|
147
186
|
readonly expiresUnixSecs?: number;
|
|
148
187
|
}
|
|
149
188
|
|
|
150
|
-
/**
|
|
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
|
+
*/
|
|
151
194
|
export type Path =
|
|
152
|
-
| { readonly kind: "
|
|
153
|
-
| { readonly kind: "
|
|
195
|
+
| { readonly kind: "direct" }
|
|
196
|
+
| { readonly kind: "punched" }
|
|
154
197
|
| { readonly kind: "relayed"; readonly relayPeerId: string };
|
|
155
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
|
+
|
|
156
212
|
/** Serializable metadata for an inbound stream catch-all event. */
|
|
157
213
|
export interface InboundStreamMeta {
|
|
158
214
|
readonly peerId: string;
|
|
@@ -175,8 +231,16 @@ export interface Minip2pNamedEventMap {
|
|
|
175
231
|
};
|
|
176
232
|
/** A peer went from disconnected to connected on `connId`. */
|
|
177
233
|
connectionEstablished: { readonly peerId: string; readonly connId: number };
|
|
178
|
-
/**
|
|
179
|
-
|
|
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
|
+
};
|
|
180
244
|
/**
|
|
181
245
|
* A newer connection took the peer's single connection slot from
|
|
182
246
|
* `oldConnId`. The peer stays connected: this stands in for both a
|
|
@@ -304,6 +368,14 @@ export interface Minip2pNamedEventMap {
|
|
|
304
368
|
};
|
|
305
369
|
peerExpired: { readonly peerId: string };
|
|
306
370
|
discoveryDialFailed: { readonly peerId: string; readonly reason: string };
|
|
371
|
+
/**
|
|
372
|
+
* mDNS hit a hard failure. It keeps running and retries; this fires once
|
|
373
|
+
* per change in failure state, and `mdnsRecovered` follows once a retry
|
|
374
|
+
* succeeds. A goodbye that failed during shutdown is final.
|
|
375
|
+
*/
|
|
376
|
+
mdnsFailed: { readonly kind: MdnsFailureKind; readonly detail: string };
|
|
377
|
+
/** mDNS recovered from its last `mdnsFailed`. Carries no fields. */
|
|
378
|
+
mdnsRecovered: Readonly<Record<never, never>>;
|
|
307
379
|
discoveryProtocolViolation: {
|
|
308
380
|
readonly peerId?: string;
|
|
309
381
|
readonly source: DiscoverySource;
|
|
@@ -369,15 +441,20 @@ export interface ConnectOptions extends OpOptions {
|
|
|
369
441
|
readonly cancelOnTimeout?: boolean;
|
|
370
442
|
}
|
|
371
443
|
|
|
372
|
-
/**
|
|
444
|
+
/** A snapshot of a peer's established connection. */
|
|
373
445
|
export interface ConnectionInfo {
|
|
446
|
+
/** The peer on the other end. */
|
|
447
|
+
readonly peerId: string;
|
|
374
448
|
/** Endpoint-local connection identifier, as carried by connection events. */
|
|
375
449
|
readonly connId: number;
|
|
376
|
-
/** Remote transport address
|
|
377
|
-
readonly remoteAddr
|
|
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;
|
|
378
454
|
/**
|
|
379
|
-
* Protocols this connection advertised, once it is ready;
|
|
380
|
-
* then
|
|
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.
|
|
381
458
|
*/
|
|
382
459
|
readonly readyProtocols?: readonly string[];
|
|
383
460
|
}
|
|
@@ -406,12 +483,38 @@ export interface ConnectResult {
|
|
|
406
483
|
readonly path: Path;
|
|
407
484
|
}
|
|
408
485
|
|
|
409
|
-
/**
|
|
410
|
-
export
|
|
411
|
-
|
|
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
|
+
}
|
|
412
514
|
| {
|
|
413
515
|
readonly reason: "driverFailed";
|
|
414
516
|
readonly error: DriverFailedError;
|
|
517
|
+
readonly unfinished: readonly string[];
|
|
415
518
|
};
|
|
416
519
|
|
|
417
520
|
/** Idempotent callback that removes a subscription. */
|
|
@@ -419,19 +522,40 @@ export type Unsubscribe = () => void;
|
|
|
419
522
|
|
|
420
523
|
/** Raw backend-only path tags. */
|
|
421
524
|
export const PathKind_Tags = {
|
|
422
|
-
|
|
423
|
-
|
|
525
|
+
Direct: "Direct",
|
|
526
|
+
Punched: "Punched",
|
|
424
527
|
Relayed: "Relayed",
|
|
425
528
|
} as const;
|
|
426
529
|
export type PathKindTag = (typeof PathKind_Tags)[keyof typeof PathKind_Tags];
|
|
427
530
|
export type PathKind =
|
|
428
|
-
| { readonly tag: typeof PathKind_Tags.
|
|
429
|
-
| { readonly tag: typeof PathKind_Tags.
|
|
531
|
+
| { readonly tag: typeof PathKind_Tags.Direct }
|
|
532
|
+
| { readonly tag: typeof PathKind_Tags.Punched }
|
|
430
533
|
| {
|
|
431
534
|
readonly tag: typeof PathKind_Tags.Relayed;
|
|
432
535
|
readonly inner: { readonly relayPeerId: string };
|
|
433
536
|
};
|
|
434
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
|
+
|
|
435
559
|
/** Raw backend-only event tags. */
|
|
436
560
|
export const P2pEvent_Tags = {
|
|
437
561
|
ConnectCancelled: "ConnectCancelled",
|
|
@@ -442,6 +566,7 @@ export const P2pEvent_Tags = {
|
|
|
442
566
|
DiscoveryDialFailed: "DiscoveryDialFailed",
|
|
443
567
|
DiscoveryProtocolViolation: "DiscoveryProtocolViolation",
|
|
444
568
|
DriverFailed: "DriverFailed",
|
|
569
|
+
EndpointClosed: "EndpointClosed",
|
|
445
570
|
EndpointError: "EndpointError",
|
|
446
571
|
EventsDropped: "EventsDropped",
|
|
447
572
|
GossipsubOutboundFailure: "GossipsubOutboundFailure",
|
|
@@ -450,6 +575,8 @@ export const P2pEvent_Tags = {
|
|
|
450
575
|
IdentifyReceived: "IdentifyReceived",
|
|
451
576
|
InboundDirectUpgrade: "InboundDirectUpgrade",
|
|
452
577
|
InboundPathEstablished: "InboundPathEstablished",
|
|
578
|
+
MdnsFailed: "MdnsFailed",
|
|
579
|
+
MdnsRecovered: "MdnsRecovered",
|
|
453
580
|
Message: "Message",
|
|
454
581
|
PathEstablished: "PathEstablished",
|
|
455
582
|
PathUpgraded: "PathUpgraded",
|
|
@@ -492,13 +619,20 @@ export type P2pEvent =
|
|
|
492
619
|
typeof P2pEvent_Tags.DriverFailed,
|
|
493
620
|
{ kind: DriverFailureKind; detail: string }
|
|
494
621
|
>
|
|
622
|
+
| RawEvent<
|
|
623
|
+
typeof P2pEvent_Tags.EndpointClosed,
|
|
624
|
+
{
|
|
625
|
+
outcome: CloseOutcome;
|
|
626
|
+
unfinished: { connId: number; peerId?: string }[];
|
|
627
|
+
}
|
|
628
|
+
>
|
|
495
629
|
| RawEvent<
|
|
496
630
|
typeof P2pEvent_Tags.ConnectionEstablished,
|
|
497
631
|
{ peerId: string; connId: number }
|
|
498
632
|
>
|
|
499
633
|
| RawEvent<
|
|
500
634
|
typeof P2pEvent_Tags.ConnectionClosed,
|
|
501
|
-
{ peerId: string; connId: number }
|
|
635
|
+
{ peerId: string; connId: number; reason: RawConnectionCloseReason }
|
|
502
636
|
>
|
|
503
637
|
| RawEvent<
|
|
504
638
|
typeof P2pEvent_Tags.ConnectionReplaced,
|
|
@@ -626,6 +760,12 @@ export type P2pEvent =
|
|
|
626
760
|
typeof P2pEvent_Tags.DiscoveryDialFailed,
|
|
627
761
|
Minip2pNamedEventMap["discoveryDialFailed"]
|
|
628
762
|
>
|
|
763
|
+
| RawEvent<
|
|
764
|
+
typeof P2pEvent_Tags.MdnsFailed,
|
|
765
|
+
Minip2pNamedEventMap["mdnsFailed"]
|
|
766
|
+
>
|
|
767
|
+
// A variant without fields has no `inner`, as both runtimes deliver it.
|
|
768
|
+
| { readonly tag: typeof P2pEvent_Tags.MdnsRecovered }
|
|
629
769
|
| RawEvent<
|
|
630
770
|
typeof P2pEvent_Tags.DiscoveryProtocolViolation,
|
|
631
771
|
Minip2pNamedEventMap["discoveryProtocolViolation"]
|