@libp2p/interface 1.7.0 → 2.0.0-18dd3cb26

package/src/errors.ts

@@ -4,91 +4,362 @@
  * AbortSignal.
  */
 export class AbortError extends Error {
-  public readonly code: string
-  public readonly type: string
+  static name = 'AbortError'
 
   constructor (message: string = 'The operation was aborted') {
     super(message)
     this.name = 'AbortError'
-    this.code = AbortError.code
-    this.type = AbortError.type
   }
+}
 
-  static readonly code = 'ABORT_ERR'
+/**
+ * Thrown when a remote Peer ID does not match the expected one
+ */
+export class UnexpectedPeerError extends Error {
+  static name = 'UnexpectedPeerError'
 
-  static readonly type = 'aborted'
+  constructor (message = 'Unexpected Peer') {
+    super(message)
+    this.name = 'UnexpectedPeerError'
+  }
 }
 
-export class CodeError<T extends Record<string, any> = Record<string, never>> extends Error {
-  public readonly props: T
+/**
+ * Thrown when a crypto exchange fails
+ */
+export class InvalidCryptoExchangeError extends Error {
+  static name = 'InvalidCryptoExchangeError'
 
-  constructor (
-    message: string,
-    public readonly code: string,
-    props?: T
-  ) {
+  constructor (message = 'Invalid crypto exchange') {
     super(message)
+    this.name = 'InvalidCryptoExchangeError'
+  }
+}
+
+/**
+ * Thrown when invalid parameters are passed to a function or method call
+ */
+export class InvalidParametersError extends Error {
+  static name = 'InvalidParametersError'
 
-    this.name = props?.name ?? 'CodeError'
-    this.props = props ?? {} as T // eslint-disable-line @typescript-eslint/consistent-type-assertions
+  constructor (message = 'Invalid parameters') {
+    super(message)
+    this.name = 'InvalidParametersError'
   }
 }
 
-export class AggregateCodeError<T extends Record<string, any> = Record<string, never>> extends AggregateError {
-  public readonly props: T
+/**
+ * Thrown when a public key is invalid
+ */
+export class InvalidPublicKeyError extends Error {
+  static name = 'InvalidPublicKeyError'
+
+  constructor (message = 'Invalid public key') {
+    super(message)
+    this.name = 'InvalidPublicKeyError'
+  }
+}
 
-  constructor (
-    errors: Error[],
-    message: string,
-    public readonly code: string,
-    props?: T
-  ) {
-    super(errors, message)
+/**
+ * Thrown when a private key is invalid
+ */
+export class InvalidPrivateKeyError extends Error {
+  static name = 'InvalidPrivateKeyError'
 
-    this.name = props?.name ?? 'AggregateCodeError'
-    this.props = props ?? {} as T // eslint-disable-line @typescript-eslint/consistent-type-assertions
+  constructor (message = 'Invalid private key') {
+    super(message)
+    this.name = 'InvalidPrivateKeyError'
   }
 }
 
-export class UnexpectedPeerError extends Error {
-  public code: string
+/**
+ * Thrown when a operation is unsupported
+ */
+export class UnsupportedOperationError extends Error {
+  static name = 'UnsupportedOperationError'
 
-  constructor (message = 'Unexpected Peer') {
+  constructor (message = 'Unsupported operation') {
     super(message)
-    this.name = 'UnexpectedPeerError'
-    this.code = UnexpectedPeerError.code
+    this.name = 'UnsupportedOperationError'
   }
+}
 
-  static readonly code = 'ERR_UNEXPECTED_PEER'
+/**
+ * Thrown when a connection is closing
+ */
+export class ConnectionClosingError extends Error {
+  static name = 'ConnectionClosingError'
+
+  constructor (message = 'The connection is closing') {
+    super(message)
+    this.name = 'ConnectionClosingError'
+  }
 }
 
-export class InvalidCryptoExchangeError extends Error {
-  public code: string
+/**
+ * Thrown when a connection is closed
+ */
+export class ConnectionClosedError extends Error {
+  static name = 'ConnectionClosedError'
 
-  constructor (message = 'Invalid crypto exchange') {
+  constructor (message = 'The connection is closed') {
     super(message)
-    this.name = 'InvalidCryptoExchangeError'
-    this.code = InvalidCryptoExchangeError.code
+    this.name = 'ConnectionClosedError'
+  }
+}
+
+/**
+ * Thrown when a connection fails
+ */
+export class ConnectionFailedError extends Error {
+  static name = 'ConnectionFailedError'
+
+  constructor (message = 'Connection failed') {
+    super(message)
+    this.name = 'ConnectionFailedError'
+  }
+}
+
+/**
+ * Thrown when the muxer is closed and an attempt to open a stream occurs
+ */
+export class MuxerClosedError extends Error {
+  static name = 'MuxerClosedError'
+
+  constructor (message = 'The muxer is closed') {
+    super(message)
+    this.name = 'MuxerClosedError'
+  }
+}
+
+/**
+ * Thrown when a protocol stream is reset by the remote muxer
+ */
+export class StreamResetError extends Error {
+  static name = 'StreamResetError'
+
+  constructor (message = 'The stream has been reset') {
+    super(message)
+    this.name = 'StreamResetError'
+  }
+}
+
+/**
+ * Thrown when a stream is in an invalid state
+ */
+export class StreamStateError extends Error {
+  static name = 'StreamStateError'
+
+  constructor (message = 'The stream is in an invalid state') {
+    super(message)
+    this.name = 'StreamStateError'
+  }
+}
+
+/**
+ * Thrown when a value could not be found
+ */
+export class NotFoundError extends Error {
+  static name = 'NotFoundError'
+
+  constructor (message = 'Not found') {
+    super(message)
+    this.name = 'NotFoundError'
+  }
+}
+
+/**
+ * Thrown when an invalid peer ID is encountered
+ */
+export class InvalidPeerIdError extends Error {
+  static name = 'InvalidPeerIdError'
+
+  constructor (message = 'Invalid PeerID') {
+    super(message)
+    this.name = 'InvalidPeerIdError'
+  }
+}
+
+/**
+ * Thrown when an invalid multiaddr is encountered
+ */
+export class InvalidMultiaddrError extends Error {
+  static name = 'InvalidMultiaddrError'
+
+  constructor (message = 'Invalid multiaddr') {
+    super(message)
+    this.name = 'InvalidMultiaddrError'
+  }
+}
+
+/**
+ * Thrown when an invalid CID is encountered
+ */
+export class InvalidCIDError extends Error {
+  static name = 'InvalidCIDError'
+
+  constructor (message = 'Invalid CID') {
+    super(message)
+    this.name = 'InvalidCIDError'
+  }
+}
+
+/**
+ * Thrown when an invalid multihash is encountered
+ */
+export class InvalidMultihashError extends Error {
+  static name = 'InvalidMultihashError'
+
+  constructor (message = 'Invalid Multihash') {
+    super(message)
+    this.name = 'InvalidMultihashError'
+  }
+}
+
+/**
+ * Thrown when a protocol is not supported
+ */
+export class UnsupportedProtocolError extends Error {
+  static name = 'UnsupportedProtocolError'
+
+  constructor (message = 'Unsupported protocol error') {
+    super(message)
+    this.name = 'UnsupportedProtocolError'
   }
+}
+
+/**
+ * An invalid or malformed message was encountered during a protocol exchange
+ */
+export class InvalidMessageError extends Error {
+  static name = 'InvalidMessageError'
 
-  static readonly code = 'ERR_INVALID_CRYPTO_EXCHANGE'
+  constructor (message = 'Invalid message') {
+    super(message)
+    this.name = 'InvalidMessageError'
+  }
 }
 
-export class InvalidCryptoTransmissionError extends Error {
-  public code: string
+/**
+ * Thrown when a remote peer sends a structurally valid message that does not
+ * comply with the protocol
+ */
+export class ProtocolError extends Error {
+  static name = 'ProtocolError'
 
-  constructor (message = 'Invalid crypto transmission') {
+  constructor (message = 'Protocol error') {
     super(message)
-    this.name = 'InvalidCryptoTransmissionError'
-    this.code = InvalidCryptoTransmissionError.code
+    this.name = 'ProtocolError'
   }
+}
+
+/**
+ * Throw when an operation times out
+ */
+export class TimeoutError extends Error {
+  static name = 'TimeoutError'
 
-  static readonly code = 'ERR_INVALID_CRYPTO_TRANSMISSION'
+  constructor (message = 'Timed out') {
+    super(message)
+    this.name = 'TimeoutError'
+  }
 }
 
-// Error codes
+/**
+ * Thrown when a startable component is interacted with but it has not been
+ * started yet
+ */
+export class NotStartedError extends Error {
+  static name = 'NotStartedError'
+
+  constructor (message = 'Not started') {
+    super(message)
+    this.name = 'NotStartedError'
+  }
+}
+
+/**
+ * Thrown when a component is started that has already been started
+ */
+export class AlreadyStartedError extends Error {
+  static name = 'AlreadyStartedError'
 
-export const ERR_TIMEOUT = 'ERR_TIMEOUT'
-export const ERR_INVALID_PARAMETERS = 'ERR_INVALID_PARAMETERS'
-export const ERR_NOT_FOUND = 'ERR_NOT_FOUND'
-export const ERR_INVALID_MESSAGE = 'ERR_INVALID_MESSAGE'
+  constructor (message = 'Already started') {
+    super(message)
+    this.name = 'AlreadyStartedError'
+  }
+}
+
+/**
+ * Thrown when dialing an address failed
+ */
+export class DialError extends Error {
+  static name = 'DialError'
+
+  constructor (message = 'Dial error') {
+    super(message)
+    this.name = 'DialError'
+  }
+}
+
+/**
+ * Thrown when listening on an address failed
+ */
+export class ListenError extends Error {
+  static name = 'ListenError'
+
+  constructor (message = 'Listen error') {
+    super(message)
+    this.name = 'ListenError'
+  }
+}
+
+/**
+ * This error is thrown when a limited connection is encountered, i.e. if the
+ * user tried to open a stream on a connection for a protocol that is not
+ * configured to run over limited connections.
+ */
+export class LimitedConnectionError extends Error {
+  static name = 'LimitedConnectionError'
+
+  constructor (message = 'Limited connection') {
+    super(message)
+    this.name = 'LimitedConnectionError'
+  }
+}
+
+/**
+ * This error is thrown where there are too many inbound protocols streams open
+ */
+export class TooManyInboundProtocolStreamsError extends Error {
+  static name = 'TooManyInboundProtocolStreamsError'
+
+  constructor (message = 'Too many inbound protocol streams') {
+    super(message)
+    this.name = 'TooManyInboundProtocolStreamsError'
+  }
+}
+
+/**
+ * This error is thrown where there are too many outbound protocols streams open
+ */
+export class TooManyOutboundProtocolStreamsError extends Error {
+  static name = 'TooManyOutboundProtocolStreamsError'
+
+  constructor (message = 'Too many outbound protocol streams') {
+    super(message)
+    this.name = 'TooManyOutboundProtocolStreamsError'
+  }
+}
+
+/**
+ * Thrown when and attempt to operate on an unsupported key was made
+ */
+export class UnsupportedKeyTypeError extends Error {
+  static name = 'UnsupportedKeyTypeError'
+
+  constructor (message = 'Unsupported key type') {
+    super(message)
+    this.name = 'UnsupportedKeyTypeError'
+  }
+}

package/src/event-target.ts

@@ -104,5 +104,3 @@ export class TypedEventEmitter<EventMap extends Record<string, any>> extends Eve
     return this.dispatchEvent(new CustomEvent<Detail>(type as string, detail))
   }
 }
-
-export const CustomEvent = globalThis.CustomEvent

package/src/index.ts

@@ -17,8 +17,9 @@
 import type { Connection, NewStreamOptions, Stream } from './connection/index.js'
 import type { ContentRouting } from './content-routing/index.js'
 import type { TypedEventTarget } from './event-target.js'
+import type { Ed25519PublicKey, PublicKey, RSAPublicKey, Secp256k1PublicKey } from './keys/index.js'
 import type { Metrics } from './metrics/index.js'
-import type { PeerId } from './peer-id/index.js'
+import type { Ed25519PeerId, PeerId, RSAPeerId, Secp256k1PeerId, URLPeerId } from './peer-id/index.js'
 import type { PeerInfo } from './peer-info/index.js'
 import type { PeerRouting } from './peer-routing/index.js'
 import type { Address, Peer, PeerStore } from './peer-store/index.js'
@@ -331,7 +332,7 @@ export interface IsDialableOptions extends AbortOptions {
    * because that protocol would not be allowed to run over a data/time limited
    * connection.
    */
-  runOnTransientConnection?: boolean
+  runOnLimitedConnection?: boolean
 }
 
 export type TransportManagerDialProgressEvents =
@@ -347,7 +348,10 @@ export type OpenConnectionProgressEvents =
   OutboundConnectionUpgradeEvents
 
 export interface DialOptions extends AbortOptions, ProgressOptions {
-
+  /**
+   * If true, open a new connection to the remote even if one already exists
+   */
+  force?: boolean
 }
 
 export interface DialProtocolOptions extends NewStreamOptions {
@@ -642,7 +646,11 @@ export interface Libp2p<T extends ServiceMap = ServiceMap> extends Startable, Ty
    * type this may mean searching the routing if the peer's key is not present
    * in the peer store.
    */
-  getPublicKey(peer: PeerId, options?: AbortOptions): Promise<Uint8Array>
+  getPublicKey(peer: Ed25519PeerId, options?: AbortOptions): Promise<Ed25519PublicKey>
+  getPublicKey(peer: Secp256k1PeerId, options?: AbortOptions): Promise<Secp256k1PublicKey>
+  getPublicKey(peer: RSAPeerId, options?: AbortOptions): Promise<RSAPublicKey>
+  getPublicKey(peer: URLPeerId, options?: AbortOptions): Promise<never>
+  getPublicKey(peer: PeerId, options?: AbortOptions): Promise<PublicKey>
 
   /**
    * Given the current node configuration, returns a promise of `true` or

package/src/keys/index.ts

@@ -1,39 +1,127 @@
+import type { CID } from 'multiformats/cid'
+import type { MultihashDigest } from 'multiformats/hashes/interface'
 import type { Uint8ArrayList } from 'uint8arraylist'
 
-export interface PublicKey<Type extends KeyType = 'Ed25519'> {
-  readonly bytes: Uint8Array
+export type KeyType = 'RSA' | 'Ed25519' | 'secp256k1'
+
+interface PublicKeyBase<KeyType extends string, DigestCode extends number = number> {
+  /**
+   * The type of this key
+   */
+  readonly type: KeyType
+
+  /**
+   * The raw public key bytes (for Ed25519 and secp256k1 keys) or PKIX in ASN1
+   * DER format (for RSA keys)
+   */
+  readonly raw: Uint8Array
+
+  /**
+   * Returns `true` if the passed object matches this key
+   */
+  equals(key?: any): boolean
+
+  /**
+   * Returns this public key as a Multihash digest.
+   *
+   * It contains either an identity hash containing the protobuf version of the
+   * public key (for Ed25519 and secp256k1 keys) or a sha256 hash of the
+   * protobuf version of the public key (RSA keys).
+   */
+  toMultihash(): MultihashDigest<DigestCode>
+
+  /**
+   * Return this public key as a CID encoded with the `libp2p-key` codec
+   *
+   * The digest contains either an identity hash containing the protobuf version
+   * of the public key (for Ed25519 and secp256k1 keys) or a sha256 hash of the
+   * protobuf version of the public key (RSA keys).
+   */
+  toCID(): CID<unknown, 0x72, DigestCode, 1>
+
+  /**
+   * Verify the passed data was signed by the private key corresponding to this
+   * public key
+   */
   verify(data: Uint8Array | Uint8ArrayList, sig: Uint8Array): boolean | Promise<boolean>
-  marshal(): Uint8Array
-  equals(key: PublicKey<Type>): boolean
-  hash(): Uint8Array | Promise<Uint8Array>
+
+  /**
+   * Returns this key as a multihash with base58btc encoding
+   */
+  toString(): string
+}
+
+export interface RSAPublicKey extends PublicKeyBase<'RSA', 0x12> {}
+export interface Ed25519PublicKey extends PublicKeyBase<'Ed25519', 0x0> {}
+export interface Secp256k1PublicKey extends PublicKeyBase<'secp256k1', 0x0> {}
+export type PublicKey = RSAPublicKey | Ed25519PublicKey | Secp256k1PublicKey
+
+/**
+ * Returns true if the passed argument has type overlap with the `PublicKey`
+ * interface. Can be used to disambiguate object types.
+ */
+export function isPublicKey (key?: any): key is PublicKey {
+  if (key == null) {
+    return false
+  }
+
+  return (key.type === 'RSA' || key.type === 'Ed25519' || key.type === 'secp256k1') &&
+    key.raw instanceof Uint8Array &&
+    typeof key.equals === 'function' &&
+    typeof key.toMultihash === 'function' &&
+    typeof key.toCID === 'function' &&
+    typeof key.verify === 'function'
 }
 
 /**
  * Generic private key interface
  */
-export interface PrivateKey<Type extends KeyType = 'Ed25519'> {
-  readonly public: PublicKey<Type>
-  readonly bytes: Uint8Array
-  sign(data: Uint8Array | Uint8ArrayList): Uint8Array | Promise<Uint8Array>
-  marshal(): Uint8Array
-  equals(key: PrivateKey<Type>): boolean
-  hash(): Uint8Array | Promise<Uint8Array>
+interface PrivateKeyBase<KeyType extends string, PublicKeyType extends PublicKeyBase<KeyType>> {
   /**
-   * Gets the ID of the key.
-   *
-   * The key id is the base58 encoding of the SHA-256 multihash of its public key.
-   * The public key is a protobuf encoding containing a type and the DER encoding
-   * of the PKCS SubjectPublicKeyInfo.
+   * The type of this key
+   */
+  readonly type: KeyType
+
+  /**
+   * The public key that corresponds to this private key
    */
-  id(): Promise<string>
+  readonly publicKey: PublicKeyType
+
   /**
-   * Exports the password protected key in the format specified.
+   * The raw public key bytes (for Ed25519 and secp256k1 keys) or PKIX in ASN1
+   * DER format (for RSA keys)
    */
-  export(password: string, format?: 'pkcs-8' | string): Promise<string>
+  readonly raw: Uint8Array
+
+  /**
+   * Returns `true` if the passed object matches this key
+   */
+  equals(key?: any): boolean
+
+  /**
+   * Sign the passed data with this private key and return the signature for
+   * later verification
+   */
+  sign(data: Uint8Array | Uint8ArrayList): Uint8Array | Promise<Uint8Array>
 }
 
-export const Ed25519 = 'Ed25519'
-export const RSA = 'RSA'
-export const secp256k1 = 'secp256k1'
+export interface RSAPrivateKey extends PrivateKeyBase<'RSA', RSAPublicKey> {}
+export interface Ed25519PrivateKey extends PrivateKeyBase<'Ed25519', Ed25519PublicKey> {}
+export interface Secp256k1PrivateKey extends PrivateKeyBase<'secp256k1', Secp256k1PublicKey> {}
+export type PrivateKey = RSAPrivateKey | Ed25519PrivateKey | Secp256k1PrivateKey
 
-export type KeyType = typeof Ed25519 | typeof RSA | typeof secp256k1
+/**
+ * Returns true if the passed argument has type overlap with the `PrivateKey`
+ * interface. Can be used to disambiguate object types.
+ */
+export function isPrivateKey (key?: any): key is PrivateKey {
+  if (key == null) {
+    return false
+  }
+
+  return (key.type === 'RSA' || key.type === 'Ed25519' || key.type === 'secp256k1') &&
+    isPublicKey(key.publicKey) &&
+    key.raw instanceof Uint8Array &&
+    typeof key.equals === 'function' &&
+    typeof key.sign === 'function'
+}

package/src/metrics/index.ts

@@ -76,23 +76,23 @@ export interface Metric {
  * A group of related metrics loosely based on the interfaces exposed by the
  * prom-client module
  */
-export interface MetricGroup {
+export interface MetricGroup<T extends string = any> {
   /**
    * Update the stored metric group to the passed value
    */
-  update(values: Record<string, number>): void
+  update(values: Partial<Record<T, number>>): void
 
   /**
    * Increment the metric group keys by the passed number or
-   * any non-numeric value to increment by 1
+   * `true` to increment by 1
    */
-  increment(values: Record<string, number | unknown>): void
+  increment(values: Partial<Record<T, number | true>>): void
 
   /**
    * Decrement the metric group keys by the passed number or
-   * any non-numeric value to decrement by 1
+   * `true` to decrement by 1
    */
-  decrement(values: Record<string, number | unknown>): void
+  decrement(values: Partial<Record<T, number | true>>): void
 
   /**
    * Reset the passed key in this metric group to its default value
@@ -128,12 +128,12 @@ export interface Counter {
  * exposed by the prom-client module - counters are metrics that only
  * go up
  */
-export interface CounterGroup {
+export interface CounterGroup<T extends string = any> {
   /**
    * Increment the metric group keys by the passed number or
    * any non-numeric value to increment by 1
    */
-  increment(values: Record<string, number | unknown>): void
+  increment(values: Partial<Record<T, number | true>>): void
 
   /**
    * Reset the passed key in this metric group to its default value