multiaddr 0.0.11__py3-none-any.whl

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.
multiaddr/protocols.py ADDED
@@ -0,0 +1,491 @@
1
+ """
2
+ Multiaddr Protocol Codes and Registry
3
+
4
+ This module defines all supported multiaddr protocol codes, their names, and their encodings.
5
+
6
+ Key features:
7
+ - Protocol code constants (e.g., P_IP4, P_TCP, P_DNSADDR)
8
+ - Protocol class for protocol metadata
9
+ - ProtocolRegistry for fast lookup and aliasing
10
+ - Reference to the multicodec table for protocol codes
11
+
12
+ Common protocol codes:
13
+ P_IP4 = 0x04 # IPv4
14
+ P_IP6 = 0x29 # IPv6
15
+ P_TCP = 0x06 # TCP
16
+ P_UDP = 0x0111 # UDP
17
+ P_DNS = 0x35 # DNS (any)
18
+ P_DNS4 = 0x36 # DNS (IPv4)
19
+ P_DNS6 = 0x37 # DNS (IPv6)
20
+ P_DNSADDR = 0x38 # DNSADDR (libp2p)
21
+ P_P2P = 0x01A5 # Peer ID
22
+ P_TLS = 0x01C0 # TLS
23
+ P_HTTP = 0x01E0 # HTTP
24
+ P_HTTPS = 0x01BB # HTTPS
25
+ ...
26
+
27
+ For a full list, see the PROTOCOLS list and the multicodec table:
28
+ https://github.com/multiformats/multicodec/blob/master/table.csv
29
+
30
+ Example usage:
31
+ from multiaddr.protocols import P_TCP, protocol_with_code
32
+ print(P_TCP) # 6
33
+ proto = protocol_with_code(P_TCP)
34
+ print(proto.name) # 'tcp'
35
+ """
36
+
37
+ from typing import Any
38
+
39
+ import varint
40
+
41
+ from . import exceptions
42
+ from .codecs import codec_by_name
43
+
44
+ __all__ = ("PROTOCOLS", "REGISTRY", "Protocol")
45
+
46
+
47
+ # source of protocols https://github.com/multiformats/multicodec/blob/master/table.csv#L382
48
+
49
+ P_IP4 = 0x04
50
+ P_IP6 = 0x29
51
+ P_IP6ZONE = 0x2A
52
+ P_TCP = 0x06
53
+ P_UDP = 0x0111
54
+ P_DCCP = 0x21
55
+ P_SCTP = 0x84
56
+ P_UDT = 0x012D
57
+ P_UTP = 0x012E
58
+ P_P2P = 0x01A5
59
+ P_HTTP = 0x01E0
60
+ P_HTTPS = 0x01BB
61
+ P_TLS = 0x01C0
62
+ P_QUIC = 0x01CC
63
+ P_QUIC1 = 0x01CD
64
+ P_WS = 0x01DD
65
+ P_WSS = 0x01DE
66
+ P_ONION = 0x01BC
67
+ P_ONION3 = 0x01BD
68
+ P_P2P_CIRCUIT = 0x0122
69
+ P_DNS = 0x35
70
+ P_DNS4 = 0x36
71
+ P_DNS6 = 0x37
72
+ P_DNSADDR = 0x38
73
+ P_P2P_WEBSOCKET_STAR = 0x01DF
74
+ P_P2P_WEBRTC_STAR = 0x0113
75
+ P_P2P_WEBRTC_DIRECT = 0x0114
76
+ P_UNIX = 0x0190
77
+ P_HTTP_PATH = 0x01E1
78
+ P_SNI = 0x01C1
79
+ P_NOISE = 0x01C6
80
+ P_WEBTRANSPORT = 0x01D1
81
+ P_MEMORY = 0x309
82
+
83
+
84
+ class Protocol:
85
+ __slots__ = [
86
+ "code", # int
87
+ "codec", # string
88
+ "name", # string
89
+ ]
90
+
91
+ def __init__(self, code: int, name: str, codec: str | None) -> None:
92
+ if not isinstance(code, int):
93
+ raise TypeError("code must be an integer")
94
+ if not isinstance(name, str):
95
+ raise TypeError("name must be a string")
96
+ if not isinstance(codec, str) and codec is not None:
97
+ raise TypeError("codec must be a string or None")
98
+
99
+ self.code = code
100
+ self.name = name
101
+ self.codec = codec
102
+
103
+ @property
104
+ def size(self) -> int:
105
+ return codec_by_name(self.codec).SIZE
106
+
107
+ @property
108
+ def path(self) -> bool:
109
+ return codec_by_name(self.codec).IS_PATH
110
+
111
+ @property
112
+ def vcode(self) -> bytes:
113
+ return varint.encode(self.code)
114
+
115
+ def __eq__(self, other: Any) -> bool:
116
+ if not isinstance(other, Protocol):
117
+ return NotImplemented
118
+
119
+ return all(
120
+ (
121
+ self.code == other.code,
122
+ self.name == other.name,
123
+ self.codec == other.codec,
124
+ self.path == other.path,
125
+ )
126
+ )
127
+
128
+ def __hash__(self) -> int:
129
+ return hash((self.code, self.name))
130
+
131
+ def __repr__(self) -> str:
132
+ return "Protocol(code={code!r}, name={name!r}, codec={codec!r})".format(
133
+ code=self.code,
134
+ name=self.name,
135
+ codec=self.codec,
136
+ )
137
+
138
+
139
+ # List of multiaddr protocols supported by this module by default
140
+ PROTOCOLS = [
141
+ Protocol(P_IP4, "ip4", "ip4"),
142
+ Protocol(P_TCP, "tcp", "uint16be"),
143
+ Protocol(P_UDP, "udp", "uint16be"),
144
+ Protocol(P_DCCP, "dccp", "uint16be"),
145
+ Protocol(P_IP6, "ip6", "ip6"),
146
+ Protocol(P_IP6ZONE, "ip6zone", "utf8"),
147
+ Protocol(P_DNS, "dns", "domain"),
148
+ Protocol(P_DNS4, "dns4", "domain"),
149
+ Protocol(P_DNS6, "dns6", "domain"),
150
+ Protocol(P_DNSADDR, "dnsaddr", "domain"),
151
+ Protocol(P_SCTP, "sctp", "uint16be"),
152
+ Protocol(P_UDT, "udt", None),
153
+ Protocol(P_UTP, "utp", None),
154
+ Protocol(P_P2P, "p2p", "cid"),
155
+ Protocol(P_ONION, "onion", "onion"),
156
+ Protocol(P_ONION3, "onion3", "onion3"),
157
+ Protocol(P_QUIC, "quic", None),
158
+ Protocol(P_QUIC1, "quic-v1", None),
159
+ Protocol(P_HTTP, "http", None),
160
+ Protocol(P_HTTPS, "https", None),
161
+ Protocol(P_TLS, "tls", None),
162
+ Protocol(P_WS, "ws", None),
163
+ Protocol(P_WSS, "wss", None),
164
+ Protocol(P_P2P_WEBSOCKET_STAR, "p2p-websocket-star", None),
165
+ Protocol(P_P2P_WEBRTC_STAR, "p2p-webrtc-star", None),
166
+ Protocol(P_P2P_WEBRTC_DIRECT, "p2p-webrtc-direct", None),
167
+ Protocol(P_P2P_CIRCUIT, "p2p-circuit", None),
168
+ Protocol(P_WEBTRANSPORT, "webtransport", None),
169
+ Protocol(P_UNIX, "unix", "fspath"),
170
+ Protocol(P_MEMORY, "memory", "memory"),
171
+ ]
172
+
173
+
174
+ class ProtocolRegistry:
175
+ """A collection of individual Multiaddr protocols indexed for fast lookup"""
176
+
177
+ __slots__ = ("_codes_to_protocols", "_locked", "_names_to_protocols")
178
+
179
+ def __init__(self, protocols: list[Protocol] | tuple[Protocol, ...] = ()) -> None:
180
+ self._locked = False
181
+ protocols_tuple = tuple(protocols) if isinstance(protocols, list) else protocols
182
+ self._codes_to_protocols: dict[int, Protocol] = {
183
+ proto.code: proto for proto in protocols_tuple
184
+ }
185
+ self._names_to_protocols: dict[str, Protocol] = {
186
+ proto.name: proto for proto in protocols_tuple
187
+ }
188
+
189
+ def add(self, proto: Protocol) -> Protocol:
190
+ """Add the given protocol description to this registry
191
+
192
+ Raises
193
+ ------
194
+ ~multiaddr.exceptions.ProtocolRegistryLocked
195
+ Protocol registry is locked and does not accept any new entries.
196
+
197
+ You can use `.copy(unlock=True)` to copy an existing locked registry
198
+ and unlock it.
199
+ ~multiaddr.exceptions.ProtocolExistsError
200
+ A protocol with the given name or code already exists.
201
+ """
202
+ if self._locked:
203
+ raise exceptions.ProtocolRegistryLocked()
204
+
205
+ if proto.name in self._names_to_protocols:
206
+ raise exceptions.ProtocolExistsError(proto, "name")
207
+
208
+ if proto.code in self._codes_to_protocols:
209
+ raise exceptions.ProtocolExistsError(proto, "code")
210
+
211
+ self._names_to_protocols[proto.name] = proto
212
+ self._codes_to_protocols[proto.code] = proto
213
+ return proto
214
+
215
+ def add_alias_name(self, proto: Protocol | str, alias_name: str) -> None:
216
+ """Add an alternate name for an existing protocol description to the registry
217
+
218
+ Raises
219
+ ------
220
+ ~multiaddr.exceptions.ProtocolRegistryLocked
221
+ Protocol registry is locked and does not accept any new entries.
222
+
223
+ You can use `.copy(unlock=True)` to copy an existing locked registry
224
+ and unlock it.
225
+ ~multiaddr.exceptions.ProtocolExistsError
226
+ A protocol with the given name already exists.
227
+ ~multiaddr.exceptions.ProtocolNotFoundError
228
+ No protocol matching *proto* could be found.
229
+ """
230
+ if self._locked:
231
+ raise exceptions.ProtocolRegistryLocked()
232
+
233
+ proto = self.find(proto)
234
+ assert self._names_to_protocols.get(proto.name) is proto, (
235
+ "Protocol to alias must have already been added to the registry"
236
+ )
237
+
238
+ if alias_name in self._names_to_protocols:
239
+ raise exceptions.ProtocolExistsError(self._names_to_protocols[alias_name], "name")
240
+
241
+ self._names_to_protocols[alias_name] = proto
242
+
243
+ def add_alias_code(self, proto: Protocol | int, alias_code: int) -> None:
244
+ """Add an alternate code for an existing protocol description to the registry
245
+
246
+ Raises
247
+ ------
248
+ ~multiaddr.exceptions.ProtocolRegistryLocked
249
+ Protocol registry is locked and does not accept any new entries.
250
+
251
+ You can use `.copy(unlock=True)` to copy an existing locked registry
252
+ and unlock it.
253
+ ~multiaddr.exceptions.ProtocolExistsError
254
+ A protocol with the given code already exists.
255
+ ~multiaddr.exceptions.ProtocolNotFoundError
256
+ No protocol matching *proto* could be found.
257
+ """
258
+ if self._locked:
259
+ raise exceptions.ProtocolRegistryLocked()
260
+
261
+ proto = self.find(proto)
262
+ assert self._codes_to_protocols.get(proto.code) is proto, (
263
+ "Protocol to alias must have already been added to the registry"
264
+ )
265
+
266
+ if alias_code in self._codes_to_protocols:
267
+ raise exceptions.ProtocolExistsError(self._codes_to_protocols[alias_code], "name")
268
+
269
+ self._codes_to_protocols[alias_code] = proto
270
+
271
+ def lock(self) -> None:
272
+ """Lock this registry instance to deny any further changes"""
273
+ self._locked = True
274
+
275
+ @property
276
+ def locked(self) -> bool:
277
+ return self._locked
278
+
279
+ def copy(self, *, unlock: bool = False) -> "ProtocolRegistry":
280
+ """Create a copy of this protocol registry
281
+
282
+ Arguments
283
+ ---------
284
+ unlock
285
+ Create the copied registry unlocked even if the current one is locked?
286
+ """
287
+ registry = ProtocolRegistry()
288
+ registry._locked = self._locked and not unlock
289
+ registry._codes_to_protocols = self._codes_to_protocols.copy()
290
+ registry._names_to_protocols = self._names_to_protocols.copy()
291
+ return registry
292
+
293
+ __copy__ = copy
294
+
295
+ def find_by_name(self, name: str) -> Protocol:
296
+ """Find a protocol by its name
297
+
298
+ Raises
299
+ ------
300
+ ~multiaddr.exceptions.ProtocolNotFoundError
301
+ No protocol matching *name* could be found.
302
+ """
303
+ try:
304
+ return self._names_to_protocols[name]
305
+ except KeyError:
306
+ raise exceptions.ProtocolNotFoundError(name)
307
+
308
+ def find_by_code(self, code: int) -> Protocol:
309
+ """Find a protocol by its code
310
+
311
+ Raises
312
+ ------
313
+ ~multiaddr.exceptions.ProtocolNotFoundError
314
+ No protocol matching *code* could be found.
315
+ """
316
+ try:
317
+ return self._codes_to_protocols[code]
318
+ except KeyError:
319
+ raise exceptions.ProtocolNotFoundError(code)
320
+
321
+ def find(self, proto: Protocol | str | int) -> Protocol:
322
+ """Find a protocol by its name, code, or Protocol instance
323
+
324
+ Raises
325
+ ------
326
+ ~multiaddr.exceptions.ProtocolNotFoundError
327
+ No protocol matching *proto* could be found.
328
+ """
329
+ if isinstance(proto, Protocol):
330
+ return proto
331
+ elif isinstance(proto, str):
332
+ return self.find_by_name(proto)
333
+ elif isinstance(proto, int):
334
+ return self.find_by_code(proto)
335
+ else:
336
+ raise TypeError("Protocol must be a string, integer, or Protocol instance")
337
+
338
+
339
+ # Create a registry with all the default protocols
340
+ REGISTRY = ProtocolRegistry(PROTOCOLS)
341
+ REGISTRY.lock()
342
+
343
+
344
+ def protocol_with_name(name: str) -> Protocol:
345
+ """Find a protocol by its name
346
+
347
+ Raises
348
+ ------
349
+ ~multiaddr.exceptions.ProtocolNotFoundError
350
+ No protocol matching *name* could be found.
351
+ """
352
+ return REGISTRY.find_by_name(name)
353
+
354
+
355
+ def protocol_with_code(code: int) -> Protocol:
356
+ """Find a protocol by its code
357
+
358
+ Raises
359
+ ------
360
+ ~multiaddr.exceptions.ProtocolNotFoundError
361
+ No protocol matching *code* could be found.
362
+ """
363
+ return REGISTRY.find_by_code(code)
364
+
365
+
366
+ def protocol_with_any(proto: Protocol | str | int) -> Protocol:
367
+ """Find a protocol by its name, code, or Protocol instance
368
+
369
+ Raises
370
+ ------
371
+ ~multiaddr.exceptions.ProtocolNotFoundError
372
+ No protocol matching *proto* could be found.
373
+ """
374
+ return REGISTRY.find(proto)
375
+
376
+
377
+ def protocols_with_string(string: str) -> list[Protocol]:
378
+ """Find all protocols that are part of the given string
379
+
380
+ Raises
381
+ ------
382
+ ~multiaddr.exceptions.StringParseError
383
+ The given string is not a valid multiaddr string.
384
+ ~multiaddr.exceptions.ProtocolNotFoundError
385
+ If a protocol in the string is not found.
386
+ """
387
+ if not string:
388
+ return []
389
+ if not string.startswith("/"):
390
+ string = "/" + string
391
+ # consume trailing slashes
392
+ string = string.rstrip("/")
393
+ sp = string.split("/")
394
+
395
+ # skip the first element, since it starts with /
396
+ sp.pop(0)
397
+ protocols = []
398
+ while sp:
399
+ element = sp.pop(0)
400
+ if not element: # Skip empty elements from multiple slashes
401
+ continue
402
+ try:
403
+ proto = protocol_with_name(element)
404
+ protocols.append(proto)
405
+ if proto.codec is not None:
406
+ codec = codec_by_name(proto.codec)
407
+ if proto.name == "unix":
408
+ # For unix, consume all remaining elements as part of the path
409
+ if sp:
410
+ path_value = "/".join(sp)
411
+ try:
412
+ codec.to_bytes(proto, path_value)
413
+ sp.clear()
414
+ continue
415
+ except Exception as exc:
416
+ raise exceptions.StringParseError(
417
+ f"Invalid path value for protocol {proto.name}",
418
+ string,
419
+ proto.name,
420
+ exc,
421
+ ) from exc
422
+ else:
423
+ raise exceptions.StringParseError(
424
+ f"Protocol {proto.name} requires a path value",
425
+ string,
426
+ proto.name,
427
+ ValueError("Missing required path value"),
428
+ )
429
+ elif sp:
430
+ # Find next non-empty element
431
+ next_elem = None
432
+ while sp and not next_elem:
433
+ next_elem = sp[0]
434
+ if not next_elem: # Skip empty elements
435
+ sp.pop(0)
436
+ continue
437
+
438
+ if next_elem: # Only proceed if we found a non-empty element
439
+ # First try to validate as value for current protocol
440
+ try:
441
+ codec.to_bytes(proto, next_elem)
442
+ sp.pop(0)
443
+ continue
444
+ except Exception as exc:
445
+ # If value validation fails, check if it's a protocol name
446
+ if next_elem.isalnum():
447
+ try:
448
+ protocol_with_name(next_elem)
449
+ if proto.name in ["ip6zone"]:
450
+ if not any(codec.to_bytes(proto, val) for val in sp if val):
451
+ raise exceptions.StringParseError(
452
+ f"Protocol {proto.name} requires a value",
453
+ string,
454
+ proto.name,
455
+ ValueError("Missing required value"),
456
+ )
457
+ continue
458
+ except exceptions.ProtocolNotFoundError:
459
+ raise exceptions.StringParseError(
460
+ f"Invalid value for protocol {proto.name}",
461
+ string,
462
+ proto.name,
463
+ exc,
464
+ ) from exc
465
+ else:
466
+ raise exceptions.StringParseError(
467
+ f"Invalid value for protocol {proto.name}",
468
+ string,
469
+ proto.name,
470
+ exc,
471
+ ) from exc
472
+ else:
473
+ if proto.name in ["ip6zone"]:
474
+ raise exceptions.StringParseError(
475
+ f"Protocol {proto.name} requires a value",
476
+ string,
477
+ proto.name,
478
+ ValueError("Missing required value"),
479
+ )
480
+ else:
481
+ if proto.name in ["ip6zone"]:
482
+ raise exceptions.StringParseError(
483
+ f"Protocol {proto.name} requires a value",
484
+ string,
485
+ proto.name,
486
+ ValueError("Missing required value"),
487
+ )
488
+ except exceptions.ProtocolNotFoundError as exc:
489
+ raise exc
490
+
491
+ return protocols
@@ -0,0 +1,6 @@
1
+ """DNS resolution support for multiaddr."""
2
+
3
+ from .base import Resolver
4
+ from .dns import DNSResolver
5
+
6
+ __all__ = ["DNSResolver", "Resolver"]
@@ -0,0 +1,29 @@
1
+ """Base resolver interface for multiaddr."""
2
+
3
+ from typing import Protocol as TypeProtocol
4
+
5
+ from ..multiaddr import Multiaddr
6
+
7
+
8
+ class Resolver(TypeProtocol):
9
+ """Protocol for multiaddr resolvers."""
10
+
11
+ async def resolve(self, maddr: Multiaddr) -> list[Multiaddr]:
12
+ """Resolve a multiaddr to its final form.
13
+
14
+ Parameters
15
+ ----------
16
+ maddr : ~multiaddr.multiaddr.Multiaddr
17
+ The multiaddr to resolve.
18
+
19
+ Returns
20
+ -------
21
+ list[~multiaddr.multiaddr.Multiaddr]
22
+ The resolved multiaddrs.
23
+
24
+ Raises
25
+ ------
26
+ ~multiaddr.exceptions.ResolveError
27
+ If the multiaddr cannot be resolved.
28
+ """
29
+ ...