@libp2p/interface 2.0.1 → 2.1.0-7f7ec82ae

package/src/events.ts

@@ -1,6 +1,8 @@
 import { setMaxListeners as nodeSetMaxListeners } from 'events'
 
-// create a setMaxListeners that doesn't break browser usage
+/**
+ * Create a setMaxListeners that doesn't break browser usage
+ */
 export const setMaxListeners: typeof nodeSetMaxListeners = (n, ...eventTargets) => {
   try {
     nodeSetMaxListeners(n, ...eventTargets)

package/src/keys/index.ts

@@ -4,15 +4,14 @@ import type { Uint8ArrayList } from 'uint8arraylist'
 
 export type KeyType = 'RSA' | 'Ed25519' | 'secp256k1'
 
-interface PublicKeyBase<KeyType extends string, DigestCode extends number = number> {
+export interface RSAPublicKey {
   /**
    * The type of this key
    */
-  readonly type: KeyType
+  readonly type: 'RSA'
 
   /**
-   * The raw public key bytes (for Ed25519 and secp256k1 keys) or PKIX in ASN1
-   * DER format (for RSA keys)
+   * PKIX in ASN1 DER format
    */
   readonly raw: Uint8Array
 
@@ -24,20 +23,101 @@ interface PublicKeyBase<KeyType extends string, DigestCode extends number = numb
   /**
    * 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).
+   * It contains a sha256 hash of the protobuf version of the public key.
    */
-  toMultihash(): MultihashDigest<DigestCode>
+  toMultihash(): MultihashDigest<0x12>
 
   /**
    * 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).
+   * The digest contains a sha256 hash of the protobuf version of the public
+   * key.
    */
-  toCID(): CID<unknown, 0x72, DigestCode, 1>
+  toCID(): CID<unknown, 0x72, 0x12, 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>
+
+  /**
+   * Returns this key as a multihash with base58btc encoding
+   */
+  toString(): string
+}
+
+export interface Ed25519PublicKey {
+  /**
+   * The type of this key
+   */
+  readonly type: 'Ed25519'
+
+  /**
+   * The raw public key bytes
+   */
+  readonly raw: Uint8Array
+
+  /**
+   * Returns `true` if the passed object matches this key
+   */
+  equals(key?: any): boolean
+
+  /**
+   * Returns this public key as an identity hash containing the protobuf wrapped
+   * public key
+   */
+  toMultihash(): MultihashDigest<0x0>
+
+  /**
+   * Return this public key as a CID encoded with the `libp2p-key` codec
+   *
+   * The digest contains an identity hash containing the protobuf wrapped
+   * version of the public key.
+   */
+  toCID(): CID<unknown, 0x72, 0x0, 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>
+
+  /**
+   * Returns this key as a multihash with base58btc encoding
+   */
+  toString(): string
+}
+
+export interface Secp256k1PublicKey {
+  /**
+   * The type of this key
+   */
+  readonly type: 'secp256k1'
+
+  /**
+   * The raw public key bytes
+   */
+  readonly raw: Uint8Array
+
+  /**
+   * Returns `true` if the passed object matches this key
+   */
+  equals(key?: any): boolean
+
+  /**
+   * Returns this public key as an identity hash containing the protobuf wrapped
+   * public key
+   */
+  toMultihash(): MultihashDigest<0x0>
+
+  /**
+   * Return this public key as a CID encoded with the `libp2p-key` codec
+   *
+   * The digest contains an identity hash containing the protobuf wrapped
+   * version of the public key.
+   */
+  toCID(): CID<unknown, 0x72, 0x0, 1>
 
   /**
    * Verify the passed data was signed by the private key corresponding to this
@@ -51,9 +131,6 @@ interface PublicKeyBase<KeyType extends string, DigestCode extends number = numb
   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
 
 /**
@@ -76,20 +153,75 @@ export function isPublicKey (key?: any): key is PublicKey {
 /**
  * Generic private key interface
  */
-interface PrivateKeyBase<KeyType extends string, PublicKeyType extends PublicKeyBase<KeyType>> {
+export interface RSAPrivateKey {
+  /**
+   * The type of this key
+   */
+  readonly type: 'RSA'
+
+  /**
+   * The public key that corresponds to this private key
+   */
+  readonly publicKey: RSAPublicKey
+
+  /**
+   * PKIX in ASN1 DER format
+   */
+  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 interface Ed25519PrivateKey {
+  /**
+   * The type of this key
+   */
+  readonly type: 'Ed25519'
+
+  /**
+   * The public key that corresponds to this private key
+   */
+  readonly publicKey: Ed25519PublicKey
+
+  /**
+   * The raw public key bytes
+   */
+  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 interface Secp256k1PrivateKey {
   /**
    * The type of this key
    */
-  readonly type: KeyType
+  readonly type: 'secp256k1'
 
   /**
    * The public key that corresponds to this private key
    */
-  readonly publicKey: PublicKeyType
+  readonly publicKey: Secp256k1PublicKey
 
   /**
-   * The raw public key bytes (for Ed25519 and secp256k1 keys) or PKIX in ASN1
-   * DER format (for RSA keys)
+   * The raw public key bytes
    */
   readonly raw: Uint8Array
 
@@ -105,9 +237,6 @@ interface PrivateKeyBase<KeyType extends string, PublicKeyType extends PublicKey
   sign(data: Uint8Array | Uint8ArrayList): Uint8Array | Promise<Uint8Array>
 }
 
-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
 
 /**

package/src/metrics/index.ts

@@ -142,6 +142,146 @@ export interface CounterGroup<T extends string = any> {
   reset(): void
 }
 
+export interface HistogramOptions extends MetricOptions {
+  /**
+   * Buckets for the histogram
+   */
+  buckets?: number[]
+}
+
+/**
+ * Create tracked metrics that are expensive to calculate by passing
+ * a function that is only invoked when metrics are being scraped
+ */
+export interface CalculatedHistogramOptions<T = number> extends HistogramOptions {
+  /**
+   * An optional function invoked to calculate the component metric instead of
+   * using `.observe`
+   */
+  calculate: CalculateMetric<T>
+}
+
+export interface Histogram {
+  /**
+   * Observe the passed value
+   */
+  observe(value: number): void
+
+  /**
+   * Reset this histogram to its default value
+   */
+  reset(): void
+
+  /**
+   * Start a timed metric, call the returned function to
+   * stop the timer
+   */
+  timer(): StopTimer
+}
+
+export interface HistogramGroup<T extends string = any> {
+  /**
+   * Observe the passed value for the named key in the group
+   */
+  observe(values: Partial<Record<T, number>>): void
+
+  /**
+   * Reset the passed key in this histogram group to its default value
+   * or all keys if no key is passed
+   */
+  reset(): void
+
+  /**
+   * Start a timed metric for the named key in the group, call
+   * the returned function to stop the timer
+   */
+  timer(key: string): StopTimer
+}
+
+export interface SummaryOptions extends MetricOptions {
+  /**
+   * Percentiles for the summary
+   */
+  percentiles?: number[]
+
+  /**
+   * Configure how old a bucket can be before it is reset for sliding window
+   */
+  maxAgeSeconds?: number
+
+  /**
+   * Configure how many buckets in the sliding window
+   */
+  ageBuckets?: number
+
+  /**
+   * Remove entries without any new values in the last `maxAgeSeconds`
+   */
+  pruneAgedBuckets?: boolean
+
+  /**
+   * Control compression of data in t-digest
+   */
+  compressCount?: number
+}
+
+/**
+ * Create tracked metrics that are expensive to calculate by passing
+ * a function that is only invoked when metrics are being scraped
+ */
+export interface CalculatedSummaryOptions<T = number> extends SummaryOptions {
+  /**
+   * An optional function invoked to calculate the component metric instead of
+   * using `.observe`
+   */
+  calculate: CalculateMetric<T>
+}
+
+/**
+ * A tracked summary loosely based on the Summary interface exposed
+ * by the prom-client module
+ */
+export interface Summary {
+  /**
+   * Observe the passed value
+   */
+  observe(value: number): void
+
+  /**
+   * Reset this summary to its default value
+   */
+  reset(): void
+
+  /**
+   * Start a timed metric, call the returned function to
+   * stop the timer
+   */
+  timer(): StopTimer
+}
+
+/**
+ * A group of tracked summaries loosely based on the Summary interface
+ * exposed by the prom-client module
+ */
+export interface SummaryGroup<T extends string = any> {
+  /**
+   * Observe the passed value for the named key in the group
+   */
+  observe(values: Partial<Record<T, number>>): void
+
+  /**
+   * Reset the passed key in this summary group to its default value
+   * or all keys if no key is passed
+   */
+  reset(): void
+
+  /**
+   * Start a timed metric for the named key in the group, call
+   * the returned function to stop the timer
+   */
+  timer(key: string): StopTimer
+}
+
 /**
  * The libp2p metrics tracking object. This interface is only concerned
  * with the collection of metrics, please see the individual implementations
@@ -322,4 +462,30 @@ export interface Metrics {
    * method on the returned counter group object
    */
   registerCounterGroup: ((name: string, options?: MetricOptions) => CounterGroup) & ((name: string, options: CalculatedMetricOptions<Record<string, number>>) => void)
+
+  /**
+   * Register an arbitrary histogram. Call this to set help/labels for histograms
+   * and observe them by calling methods on the returned histogram object
+   */
+  registerHistogram: ((name: string, options?: HistogramOptions) => Histogram) & ((name: string, options: CalculatedHistogramOptions) => void)
+
+  /**
+   * Register a a group of related histograms. Call this to set help/labels for
+   * groups of related histograms that will be updated with by calling the `.observe`
+   * method on the returned histogram group object
+   */
+  registerHistogramGroup: ((name: string, options?: HistogramOptions) => HistogramGroup) & ((name: string, options: CalculatedHistogramOptions<Record<string, number>>) => void)
+
+  /**
+   * Register an arbitrary summary. Call this to set help/labels for summaries
+   * and observe them by calling methods on the returned summary object
+   */
+  registerSummary: ((name: string, options?: SummaryOptions) => Summary) & ((name: string, options: CalculatedSummaryOptions) => void)
+
+  /**
+   * Register a a group of related summaries. Call this to set help/labels for
+   * groups of related summaries that will be updated with by calling the `.observe`
+   * method on the returned summary group object
+   */
+  registerSummaryGroup: ((name: string, options?: SummaryOptions) => SummaryGroup) & ((name: string, options: CalculatedSummaryOptions<Record<string, number>>) => void)
 }

package/src/pubsub/index.ts

@@ -115,7 +115,7 @@ export interface PubSubInit {
   maxOutboundStreams?: number
 }
 
-interface Subscription {
+export interface Subscription {
   topic: string
   subscribe: boolean
 }
@@ -268,3 +268,16 @@ export interface PeerStreamEvents {
   'stream:outbound': CustomEvent<never>
   'close': CustomEvent<never>
 }
+
+/**
+ * All Pubsub implementations must use this symbol as the name of a property
+ * with a boolean `true` value
+ */
+export const pubSubSymbol = Symbol.for('@libp2p/pubsub')
+
+/**
+ * Returns true if the passed argument is a PubSub implementation
+ */
+export function isPubSub (obj?: any): obj is PubSub {
+  return Boolean(obj?.[pubSubSymbol])
+}

package/src/stream-handler/index.ts

@@ -11,12 +11,16 @@ export interface StreamHandler {
 
 export interface StreamHandlerOptions {
   /**
-   * How many incoming streams can be open for this protocol at the same time on each connection (default: 32)
+   * How many incoming streams can be open for this protocol at the same time on each connection
+   *
+   * @default 32
    */
   maxInboundStreams?: number
 
   /**
-   * How many outgoing streams can be open for this protocol at the same time on each connection (default: 64)
+   * How many outgoing streams can be open for this protocol at the same time on each connection
+   *
+   * @default 64
    */
   maxOutboundStreams?: number