@minip2p/core 0.1.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 ADDED
@@ -0,0 +1,336 @@
1
+ /** Bytes accepted by the platform-neutral SDK. */
2
+ export type Bytes = ArrayBuffer | Uint8Array;
3
+
4
+ /** Signed-discovery settings. */
5
+ export interface MiniP2pDiscoveryOptions {
6
+ /** Pubsub topic carrying signed discovery beacons. */
7
+ readonly topic: string;
8
+ /** Milliseconds between local beacon announcements. */
9
+ readonly beaconIntervalMs: number;
10
+ /** Milliseconds before a signed peer observation expires. */
11
+ readonly peerTtlMs: number;
12
+ /** Whether accepted observations may trigger automatic dials. */
13
+ readonly autoDial: boolean;
14
+ }
15
+
16
+ /** Local-link mDNS discovery settings. Omitted fields use Rust defaults. */
17
+ export interface MiniP2pMdnsOptions {
18
+ readonly enableIpv6?: boolean;
19
+ readonly ttlMs?: number;
20
+ readonly queryIntervalMs?: number;
21
+ readonly maxPacketBytes?: number;
22
+ readonly maxAnnouncedAddrs?: number;
23
+ readonly interfaceRefreshMs?: number;
24
+ readonly socketPollIntervalMs?: number;
25
+ readonly autoDial?: boolean;
26
+ }
27
+
28
+ /** Pubsub routing engine. */
29
+ export enum PubsubRouter {
30
+ Gossipsub = 0,
31
+ Floodsub = 1,
32
+ }
33
+
34
+ /** Configuration accepted by a platform minip2p endpoint. */
35
+ export interface MiniP2pConfig {
36
+ /** Raw 32-byte Ed25519 secret key material. */
37
+ readonly secretKey: Bytes;
38
+ /** Identify agent version, or the native default when absent. */
39
+ readonly agentVersion?: string;
40
+ /** Direct QUIC relay peer addresses. */
41
+ readonly relays?: readonly string[];
42
+ /** Direct QUIC peers used as AutoNAT reachability servers. */
43
+ readonly autonatServers?: readonly string[];
44
+ /** QUIC listen multiaddress, or dual-stack wildcard binding when absent. */
45
+ readonly listenAddr?: string;
46
+ /** Whether connection attempts must remain relayed. */
47
+ readonly forceRelay?: boolean;
48
+ /** Whether unsigned pubsub messages are accepted. */
49
+ readonly allowUnsigned?: boolean;
50
+ /** Pubsub router; defaults to gossipsub. */
51
+ readonly pubsubRouter?: PubsubRouter;
52
+ /** Custom application protocols registered before startup. */
53
+ readonly protocols?: readonly string[];
54
+ /** Signed-discovery settings, or no discovery when absent. */
55
+ readonly discovery?: MiniP2pDiscoveryOptions;
56
+ /** Enables mDNS with defaults (`true`) or explicit settings. */
57
+ readonly mdns?: boolean | MiniP2pMdnsOptions;
58
+ }
59
+
60
+ /** Coarse local reachability state. */
61
+ export enum Reachability {
62
+ Unknown = 0,
63
+ Public = 1,
64
+ Private = 2,
65
+ }
66
+
67
+ /** Source that contributed a discovery observation. */
68
+ export enum DiscoverySource {
69
+ SignedBeacon = 0,
70
+ Mdns = 1,
71
+ }
72
+
73
+ /** Category of a fatal background-driver failure. */
74
+ export enum DriverFailureKind {
75
+ Transport = 0,
76
+ Swarm = 1,
77
+ Invariant = 2,
78
+ Panic = 3,
79
+ }
80
+
81
+ /** Category of a non-fatal endpoint runtime error. */
82
+ export enum EndpointErrorKind {
83
+ Transport = 0,
84
+ Multistream = 1,
85
+ Identify = 2,
86
+ Ping = 3,
87
+ IdentifyStreamRejected = 4,
88
+ OpenStreamFailed = 5,
89
+ UnsupportedProtocol = 6,
90
+ Driver = 7,
91
+ }
92
+
93
+ /** Category of a failed NAT connection attempt. */
94
+ export enum NatErrorKind {
95
+ NoPathAvailable = 0,
96
+ Timeout = 1,
97
+ DialFailed = 2,
98
+ Protocol = 3,
99
+ RelayRefused = 4,
100
+ }
101
+
102
+ /** Tags for a usable connection path. */
103
+ export enum PathKind_Tags {
104
+ DirectDialed = "DirectDialed",
105
+ DirectPunched = "DirectPunched",
106
+ Relayed = "Relayed",
107
+ }
108
+
109
+ /** Kind of usable connection path. */
110
+ export type PathKind =
111
+ | { readonly tag: PathKind_Tags.DirectDialed }
112
+ | { readonly tag: PathKind_Tags.DirectPunched }
113
+ | {
114
+ readonly tag: PathKind_Tags.Relayed;
115
+ readonly inner: { readonly relayPeerId: string };
116
+ };
117
+
118
+ /** Tags for events delivered by a minip2p endpoint. */
119
+ export enum P2pEvent_Tags {
120
+ EventsDropped = "EventsDropped",
121
+ DriverFailed = "DriverFailed",
122
+ ConnectionEstablished = "ConnectionEstablished",
123
+ ConnectionClosed = "ConnectionClosed",
124
+ PeerReady = "PeerReady",
125
+ IdentifyReceived = "IdentifyReceived",
126
+ PingRttMeasured = "PingRttMeasured",
127
+ PingTimeout = "PingTimeout",
128
+ StreamReady = "StreamReady",
129
+ StreamData = "StreamData",
130
+ StreamRemoteWriteClosed = "StreamRemoteWriteClosed",
131
+ StreamClosed = "StreamClosed",
132
+ EndpointError = "EndpointError",
133
+ ReachabilityChanged = "ReachabilityChanged",
134
+ PublicAddressesChanged = "PublicAddressesChanged",
135
+ RelayReserved = "RelayReserved",
136
+ RelayReservationLost = "RelayReservationLost",
137
+ PathEstablished = "PathEstablished",
138
+ PathUpgraded = "PathUpgraded",
139
+ HolePunchFailed = "HolePunchFailed",
140
+ FellBackToRelay = "FellBackToRelay",
141
+ ConnectFailed = "ConnectFailed",
142
+ InboundDirectUpgrade = "InboundDirectUpgrade",
143
+ Message = "Message",
144
+ PeerSubscribed = "PeerSubscribed",
145
+ PeerUnsubscribed = "PeerUnsubscribed",
146
+ PubsubOutboundFailure = "PubsubOutboundFailure",
147
+ PubsubProtocolViolation = "PubsubProtocolViolation",
148
+ PeerDiscovered = "PeerDiscovered",
149
+ PeerUpdated = "PeerUpdated",
150
+ PeerExpired = "PeerExpired",
151
+ DiscoveryDialFailed = "DiscoveryDialFailed",
152
+ DiscoveryProtocolViolation = "DiscoveryProtocolViolation",
153
+ }
154
+
155
+ interface Event<Tag extends P2pEvent_Tags, Inner> {
156
+ readonly tag: Tag;
157
+ readonly inner: Readonly<Inner>;
158
+ }
159
+
160
+ /** Latest Identify information advertised by a remote peer. */
161
+ export interface IdentifyInfo {
162
+ readonly publicKey?: ArrayBuffer;
163
+ readonly listenAddrs: readonly string[];
164
+ readonly protocols: readonly string[];
165
+ readonly observedAddr?: string;
166
+ readonly protocolVersion?: string;
167
+ readonly agentVersion?: string;
168
+ }
169
+
170
+ /** A platform-independent event emitted by the minip2p driver. */
171
+ export type P2pEvent =
172
+ | Event<
173
+ P2pEvent_Tags.EventsDropped,
174
+ { dropped: number; totalDropped: number }
175
+ >
176
+ | Event<
177
+ P2pEvent_Tags.DriverFailed,
178
+ { kind: DriverFailureKind; detail: string }
179
+ >
180
+ | Event<
181
+ P2pEvent_Tags.ConnectionEstablished,
182
+ { peerId: string; connId: number }
183
+ >
184
+ | Event<P2pEvent_Tags.ConnectionClosed, { peerId: string; connId: number }>
185
+ | Event<
186
+ P2pEvent_Tags.PeerReady,
187
+ { peerId: string; protocols: readonly string[] }
188
+ >
189
+ | Event<
190
+ P2pEvent_Tags.IdentifyReceived,
191
+ { peerId: string; info: IdentifyInfo }
192
+ >
193
+ | Event<P2pEvent_Tags.PingRttMeasured, { peerId: string; rttMs: number }>
194
+ | Event<P2pEvent_Tags.PingTimeout, { peerId: string }>
195
+ | Event<
196
+ P2pEvent_Tags.StreamReady,
197
+ {
198
+ peerId: string;
199
+ connId: number;
200
+ streamId: number;
201
+ protocolId: string;
202
+ initiatedLocally: boolean;
203
+ }
204
+ >
205
+ | Event<
206
+ P2pEvent_Tags.StreamData,
207
+ { peerId: string; connId: number; streamId: number; data: ArrayBuffer }
208
+ >
209
+ | Event<
210
+ P2pEvent_Tags.StreamRemoteWriteClosed,
211
+ { peerId: string; connId: number; streamId: number }
212
+ >
213
+ | Event<
214
+ P2pEvent_Tags.StreamClosed,
215
+ { peerId: string; connId: number; streamId: number }
216
+ >
217
+ | Event<
218
+ P2pEvent_Tags.EndpointError,
219
+ {
220
+ kind: EndpointErrorKind;
221
+ peerId?: string;
222
+ connId?: number;
223
+ detail: string;
224
+ }
225
+ >
226
+ | Event<
227
+ P2pEvent_Tags.ReachabilityChanged,
228
+ {
229
+ previous: Reachability;
230
+ current: Reachability;
231
+ confirmedAddrs: readonly string[];
232
+ }
233
+ >
234
+ | Event<P2pEvent_Tags.PublicAddressesChanged, { addrs: readonly string[] }>
235
+ | Event<
236
+ P2pEvent_Tags.RelayReserved,
237
+ { relayPeerId: string; expiresUnixSecs?: number }
238
+ >
239
+ | Event<P2pEvent_Tags.RelayReservationLost, { relayPeerId: string }>
240
+ | Event<
241
+ P2pEvent_Tags.PathEstablished,
242
+ { connectId: number; peerId: string; path: PathKind }
243
+ >
244
+ | Event<
245
+ P2pEvent_Tags.PathUpgraded,
246
+ { connectId: number; peerId: string; from: PathKind; to: PathKind }
247
+ >
248
+ | Event<
249
+ P2pEvent_Tags.HolePunchFailed,
250
+ { connectId: number; attempt: number; reason: string }
251
+ >
252
+ | Event<P2pEvent_Tags.FellBackToRelay, { connectId: number; peerId: string }>
253
+ | Event<
254
+ P2pEvent_Tags.ConnectFailed,
255
+ {
256
+ connectId: number;
257
+ peerId: string;
258
+ kind: NatErrorKind;
259
+ detail: string;
260
+ }
261
+ >
262
+ | Event<P2pEvent_Tags.InboundDirectUpgrade, { peerId: string }>
263
+ | Event<
264
+ P2pEvent_Tags.Message,
265
+ {
266
+ fromPeerId: string;
267
+ topics: readonly string[];
268
+ data: ArrayBuffer;
269
+ seqno: ArrayBuffer;
270
+ signed: boolean;
271
+ }
272
+ >
273
+ | Event<P2pEvent_Tags.PeerSubscribed, { peerId: string; topic: string }>
274
+ | Event<P2pEvent_Tags.PeerUnsubscribed, { peerId: string; topic: string }>
275
+ | Event<
276
+ P2pEvent_Tags.PubsubOutboundFailure,
277
+ { peerId: string; reason: string }
278
+ >
279
+ | Event<
280
+ P2pEvent_Tags.PubsubProtocolViolation,
281
+ { peerId: string; reason: string }
282
+ >
283
+ | Event<
284
+ P2pEvent_Tags.PeerDiscovered,
285
+ { peerId: string; addrs: readonly string[]; source: DiscoverySource }
286
+ >
287
+ | Event<
288
+ P2pEvent_Tags.PeerUpdated,
289
+ { peerId: string; addrs: readonly string[]; source: DiscoverySource }
290
+ >
291
+ | Event<P2pEvent_Tags.PeerExpired, { peerId: string }>
292
+ | Event<P2pEvent_Tags.DiscoveryDialFailed, { peerId: string; reason: string }>
293
+ | Event<
294
+ P2pEvent_Tags.DiscoveryProtocolViolation,
295
+ {
296
+ peerId?: string;
297
+ source: DiscoverySource;
298
+ reason: string;
299
+ suppressed: number;
300
+ }
301
+ >;
302
+
303
+ /** Extracts one native event variant by its tag. */
304
+ export type P2pEventByTag<Tag extends P2pEvent_Tags> = Extract<
305
+ P2pEvent,
306
+ { tag: Tag }
307
+ >;
308
+
309
+ /** One peer in the shared discovery address book. */
310
+ export interface KnownPeerInfo {
311
+ readonly peerId: string;
312
+ readonly addrs: readonly string[];
313
+ readonly beaconAddrs: readonly string[];
314
+ readonly mdnsAddrs: readonly string[];
315
+ readonly beaconLastSeenAgeMs?: number;
316
+ readonly mdnsLastSeenAgeMs?: number;
317
+ readonly connected: boolean;
318
+ }
319
+
320
+ /** Snapshot of the active inbound relay reservation. */
321
+ export interface RelayReservationInfo {
322
+ readonly relayPeerId: string;
323
+ readonly expiresUnixSecs?: number;
324
+ }
325
+
326
+ /** Host-side notification that the TypeScript event queue discarded events. */
327
+ export interface QueueOverflowEvent {
328
+ readonly type: "queueOverflow";
329
+ readonly dropped: number;
330
+ }
331
+
332
+ /** An event emitted by the high-level SDK. */
333
+ export type MiniP2pEvent = P2pEvent | QueueOverflowEvent;
334
+
335
+ /** Removes an event subscription. */
336
+ export type Unsubscribe = () => void;