feat: allow registering custom protocol codecs (#425)

Exposes the internal registry to allow adding/removing protocol
codecs.

Author: achingbrain

README.md

@@ -114,6 +114,37 @@ console.info(resolved)
 // [Multiaddr('/ip4/147.75...'), Multiaddr('/ip4/147.75...'), Multiaddr('/ip4/147.75...')...]
 ```
 
+## Example - Adding custom protocols
+
+To add application-specific or experimental protocols, add a protocol codec
+to the protocol registry:
+
+```ts
+import { registry, V, multiaddr } from '@multiformats/multiaddr'
+import type { ProtocolCodec } from '@multiformats/multiaddr'
+
+const maWithCustomTuple = '/custom-protocol/hello'
+
+// throws UnknownProtocolError
+multiaddr(maWithCustomTuple)
+
+const protocol: ProtocolCodec = {
+  code: 2059,
+  name: 'custom-protocol',
+  size: V
+  // V means variable length, can also be 0, a positive integer (e.g. a fixed
+  // length or omitted
+}
+
+registry.addProtocol(protocol)
+
+// does not throw UnknownProtocolError
+multiaddr(maWithCustomTuple)
+
+// protocols can also be removed
+registry.removeProtocol(protocol.code)
+```
+
 # Install
 
 ```console

src/components.ts

@@ -13,7 +13,7 @@ export function bytesToComponents (bytes: Uint8Array): Component[] {
   let i = 0
   while (i < bytes.length) {
     const code = varint.decode(bytes, i)
-    const codec = registry.getCodec(code)
+    const codec = registry.getProtocol(code)
     const codeLength = varint.encodingLength(code)
     const size = sizeForAddr(codec, bytes, i + codeLength)
     let sizeLength = 0
@@ -51,7 +51,7 @@ export function componentsToBytes (components: Component[]): Uint8Array {
 
   for (const component of components) {
     if (component.bytes == null) {
-      const codec = registry.getCodec(component.code)
+      const codec = registry.getProtocol(component.code)
       const codecLength = varint.encodingLength(component.code)
       let valueBytes: Uint8Array | undefined
       let valueLength = 0
@@ -119,7 +119,7 @@ export function stringToComponents (string: string): Component[] {
     const ended = i === string.length - 1
 
     if (char === '/' || ended) {
-      const codec = registry.getCodec(protocol)
+      const codec = registry.getProtocol(protocol)
 
       if (collecting === 'protocol') {
         if (codec.size == null || codec.size === 0) {
@@ -176,7 +176,7 @@ export function componentsToString (components: Component[]): string {
         return component.name
       }
 
-      const codec = registry.getCodec(component.code)
+      const codec = registry.getProtocol(component.code)
 
       if (codec == null) {
         throw new InvalidMultiaddrError(`Unknown protocol code ${component.code}`)

src/convert.ts

@@ -45,7 +45,7 @@ export function convert (proto: string, a: string | Uint8Array): Uint8Array | st
  * @deprecated Will be removed in a future release
  */
 export function convertToString (proto: number | string, buf: Uint8Array): string {
-  const protocol = registry.getCodec(proto)
+  const protocol = registry.getProtocol(proto)
 
   return protocol.bytesToValue?.(buf) ?? uint8ArrayToString(buf, 'base16')  // no clue. convert to hex
 }
@@ -56,7 +56,7 @@ export function convertToString (proto: number | string, buf: Uint8Array): strin
  * @deprecated Will be removed in a future release
  */
 export function convertToBytes (proto: string | number, str: string): Uint8Array {
-  const protocol = registry.getCodec(proto)
+  const protocol = registry.getProtocol(proto)
 
   return protocol.valueToBytes?.(str) ?? uint8ArrayFromString(str, 'base16') // no clue. convert from hex
 }

src/errors.ts

@@ -16,7 +16,7 @@ export class InvalidParametersError extends Error {
   name = 'InvalidParametersError'
 }
 
-export class InvalidProtocolError extends Error {
-  static name = 'InvalidProtocolError'
-  name = 'InvalidProtocolError'
+export class UnknownProtocolError extends Error {
+  static name = 'UnknownProtocolError'
+  name = 'UnknownProtocolError'
 }

src/index.ts

@@ -91,12 +91,44 @@
  * console.info(resolved)
  * // [Multiaddr('/ip4/147.75...'), Multiaddr('/ip4/147.75...'), Multiaddr('/ip4/147.75...')...]
  * ```
+ *
+ * @example Adding custom protocols
+ *
+ * To add application-specific or experimental protocols, add a protocol codec
+ * to the protocol registry:
+ *
+ * ```ts
+ * import { registry, V, multiaddr } from '@multiformats/multiaddr'
+ * import type { ProtocolCodec } from '@multiformats/multiaddr'
+ *
+ * const maWithCustomTuple = '/custom-protocol/hello'
+ *
+ * // throws UnknownProtocolError
+ * multiaddr(maWithCustomTuple)
+ *
+ * const protocol: ProtocolCodec = {
+ *   code: 2059,
+ *   name: 'custom-protocol',
+ *   size: V
+ *   // V means variable length, can also be 0, a positive integer (e.g. a fixed
+ *   // length or omitted
+ * }
+ *
+ * registry.addProtocol(protocol)
+ *
+ * // does not throw UnknownProtocolError
+ * multiaddr(maWithCustomTuple)
+ *
+ * // protocols can also be removed
+ * registry.removeProtocol(protocol.code)
+ * ```
  */
 
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
 import { InvalidParametersError } from './errors.ts'
 import { Multiaddr as MultiaddrClass, symbol } from './multiaddr.js'
-import { registry } from './registry.ts'
+import { registry, V } from './registry.ts'
+import type { ProtocolCodec } from './registry.ts'
 import type { Resolver } from './resolvers/index.js'
 import type { DNS } from '@multiformats/dns'
 import type { AbortOptions } from 'abort-error'
@@ -124,6 +156,28 @@ export interface MultiaddrObject {
   port: number
 }
 
+/**
+ * The protocol registry stores protocol codecs that allow transformation of
+ * multiaddr tuples from bytes to string and back again, and also validation of
+ * the address values.
+ */
+export interface Registry {
+  /**
+   * Retrieve a protocol definition by it's code or name
+   */
+  getProtocol (key: string | number): ProtocolCodec
+
+  /**
+   * Add a new protocol definition
+   */
+  addProtocol (codec: ProtocolCodec): void
+
+  /**
+   * Remove a protocol definition by it's code
+   */
+  removeProtocol (code: number): void
+}
+
 /**
  * A NodeAddress is an IPv4/IPv6 address/TCP port combination
  */
@@ -621,7 +675,7 @@ export function fromNodeAddress (addr: NodeAddress, transport: string): Multiadd
  */
 export function fromTuples (tuples: Tuple[]): Multiaddr {
   return multiaddr(tuples.map(([code, value]) => {
-    const codec = registry.getCodec(code)
+    const codec = registry.getProtocol(code)
 
     const component: Component = {
       code,
@@ -655,7 +709,7 @@ export function fromTuples (tuples: Tuple[]): Multiaddr {
  */
 export function fromStringTuples (tuples: StringTuple[]): Multiaddr {
   return multiaddr(tuples.map(([code, value]) => {
-    const codec = registry.getCodec(code)
+    const codec = registry.getProtocol(code)
 
     const component: Component = {
       code,
@@ -743,7 +797,7 @@ export function multiaddr (addr?: MultiaddrInput): Multiaddr {
  * @deprecated This will be removed in a future version
  */
 export function protocols (proto: number | string): Protocol {
-  const codec = registry.getCodec(proto)
+  const codec = registry.getProtocol(proto)
 
   return {
     code: codec.code,
@@ -759,3 +813,5 @@ export function protocols (proto: number | string): Protocol {
  * out by bundlers.
  */
 export * from './constants.ts'
+export { registry, V }
+export type { ProtocolCodec }

src/multiaddr.ts

@@ -157,7 +157,7 @@ export class Multiaddr implements MultiaddrInterface {
 
   protos (): Protocol[] {
     return this.#components.map(({ code, value }) => {
-      const codec = registry.getCodec(code)
+      const codec = registry.getProtocol(code)
 
       return {
         code,
@@ -183,7 +183,7 @@ export class Multiaddr implements MultiaddrInterface {
         return [code]
       }
 
-      const codec = registry.getCodec(code)
+      const codec = registry.getProtocol(code)
       const output: Tuple = [code]
 
       if (value != null) {
@@ -283,7 +283,7 @@ export class Multiaddr implements MultiaddrInterface {
 
   getPath (): string | null {
     for (const component of this.#components) {
-      const codec = registry.getCodec(component.code)
+      const codec = registry.getProtocol(component.code)
 
       if (!codec.path) {
         continue
@@ -371,7 +371,7 @@ export class Multiaddr implements MultiaddrInterface {
 export function validate (addr: Multiaddr): void {
   addr.getComponents()
     .forEach(component => {
-      const codec = registry.getCodec(component.code)
+      const codec = registry.getProtocol(component.code)
 
       if (component.value == null) {
         return

src/registry.ts

@@ -2,18 +2,50 @@ import { isIPv4, isIPv6 } from '@chainsafe/is-ip'
 import { CID } from 'multiformats'
 import { base64url } from 'multiformats/bases/base64'
 import { CODE_CERTHASH, CODE_DCCP, CODE_DNS, CODE_DNS4, CODE_DNS6, CODE_DNSADDR, CODE_GARLIC32, CODE_GARLIC64, CODE_HTTP, CODE_HTTP_PATH, CODE_HTTPS, CODE_IP4, CODE_IP6, CODE_IP6ZONE, CODE_IPCIDR, CODE_MEMORY, CODE_NOISE, CODE_ONION, CODE_ONION3, CODE_P2P, CODE_P2P_CIRCUIT, CODE_P2P_STARDUST, CODE_P2P_WEBRTC_DIRECT, CODE_P2P_WEBRTC_STAR, CODE_P2P_WEBSOCKET_STAR, CODE_QUIC, CODE_QUIC_V1, CODE_SCTP, CODE_SNI, CODE_TCP, CODE_TLS, CODE_UDP, CODE_UDT, CODE_UNIX, CODE_UTP, CODE_WEBRTC, CODE_WEBRTC_DIRECT, CODE_WEBTRANSPORT, CODE_WS, CODE_WSS } from './constants.ts'
-import { InvalidProtocolError, ValidationError } from './errors.ts'
+import { UnknownProtocolError, ValidationError } from './errors.ts'
 import { bytes2mb, bytes2onion, bytes2port, bytesToString, ip4ToBytes, ip4ToString, ip6StringToValue, ip6ToBytes, ip6ToString, mb2bytes, onion2bytes, onion32bytes, port2bytes, stringToBytes } from './utils.ts'
 import { validatePort } from './validation.ts'
+import type { Registry as RegistryInterface } from './index.ts'
 
 export const V = -1
 
 export interface ProtocolCodec {
+  /**
+   * A numeric code that will be used in the binary representation of the tuple.
+   */
   code: number
+
+  /**
+   * A string name that will be used in the string representation of the addr.
+   */
   name: string
+
+  /**
+   * Size defines the expected length of the address part of the tuple - valid
+   * values are `-1` (or the `V` constant) for variable length (this will be
+   * varint encoded in the binary representation), `0` for no address part or a
+   * number that represents a fixed-length address.
+   */
   size?: number
+
+  /**
+   * If this protocol is a path protocol.
+   *
+   * @deprecated This will be removed in a future release
+   */
   path?: boolean
+
+  /**
+   * If this protocol can be resolved using configured resolvers.
+   *
+   * @deprecated This will be removed in a future release
+   */
   resolvable?: boolean
+
+  /**
+   * If specified this protocol codec will also be used to decode tuples with
+   * these names from string multiaddrs.
+   */
   aliases?: string[]
 
   /**
@@ -43,11 +75,11 @@ export interface ProtocolCodec {
   validate?(value: string): void
 }
 
-class Registry {
+class Registry implements RegistryInterface {
   private protocolsByCode = new Map<number, ProtocolCodec>()
   private protocolsByName = new Map<string, ProtocolCodec>()
 
-  getCodec (key: string | number): ProtocolCodec {
+  getProtocol (key: string | number): ProtocolCodec {
     let codec: ProtocolCodec | undefined
 
     if (typeof key === 'string') {
@@ -57,23 +89,23 @@ class Registry {
     }
 
     if (codec == null) {
-      throw new InvalidProtocolError(`Protocol ${key} was unknown`)
+      throw new UnknownProtocolError(`Protocol ${key} was unknown`)
     }
 
     return codec
   }
 
-  addCodec (key: number, codec: ProtocolCodec, aliases?: string[]): void {
-    this.protocolsByCode.set(key, codec)
+  addProtocol (codec: ProtocolCodec): void {
+    this.protocolsByCode.set(codec.code, codec)
     this.protocolsByName.set(codec.name, codec)
 
-    aliases?.forEach(alias => {
+    codec.aliases?.forEach(alias => {
       this.protocolsByName.set(alias, codec)
     })
   }
 
-  deleteCodec (key: number): void {
-    const codec = this.getCodec(key)
+  removeProtocol (code: number): void {
+    const codec = this.protocolsByCode.get(code)
 
     if (codec == null) {
       return
@@ -288,5 +320,5 @@ const codecs: ProtocolCodec[] = [{
 }]
 
 codecs.forEach(codec => {
-  registry.addCodec(codec.code, codec, codec.aliases)
+  registry.addProtocol(codec)
 })

test/codec.spec.ts

@@ -78,7 +78,7 @@ describe('codec', () => {
           value: 'non-existant'
         }])
       ).to.throw()
-        .with.property('name', 'InvalidProtocolError')
+        .with.property('name', 'UnknownProtocolError')
     })
   })
 })

test/index.spec.ts

@@ -672,14 +672,14 @@ describe('helpers', () => {
       expect(
         () => multiaddr('/ip5/127.0.0.1/udp/5000')
       ).to.throw()
-        .with.property('name', 'InvalidProtocolError')
+        .with.property('name', 'UnknownProtocolError')
     })
 
     it('throws on an invalid protocol name when the transport protocol is not valid', () => {
       expect(
         () => multiaddr('/ip4/127.0.0.1/utp/5000')
       ).to.throw()
-        .with.property('name', 'InvalidProtocolError')
+        .with.property('name', 'UnknownProtocolError')
     })
   })
 
@@ -892,6 +892,6 @@ describe('unknown protocols', () => {
   it('throws an error', () => {
     const str = '/ip4/127.0.0.1/unknown'
     expect(() => multiaddr(str)).to.throw()
-      .with.property('name', 'InvalidProtocolError')
+      .with.property('name', 'UnknownProtocolError')
   })
 })