@libp2p/interface 0.0.1-6fdaa7dc

package/src/peer-store/index.ts

@@ -0,0 +1,272 @@
+import type { PeerId } from '../peer-id/index.js'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+/**
+ * A multiaddr with an optional flag that indicates if its trustworthy
+ */
+export interface Address {
+  /**
+   * Peer multiaddr
+   */
+  multiaddr: Multiaddr
+
+  /**
+   * Obtained from a signed peer record
+   */
+  isCertified: boolean
+}
+
+/**
+ * Data stored in the peer store about peers
+ */
+export interface Peer {
+  /**
+   * Peer's peer-id instance
+   */
+  id: PeerId
+
+  /**
+   * Peer's addresses containing a list of multiaddrs and a isCertified field
+   * indicating if the address was loaded from a signed peer record or not
+   */
+  addresses: Address[]
+
+  /**
+   * Peer's supported protocols
+   */
+  protocols: string[]
+
+  /**
+   * Peer's metadata map
+   */
+  metadata: Map<string, Uint8Array>
+
+  /**
+   * Tags a peer has
+   */
+  tags: Map<string, Tag>
+
+  /**
+   * The last peer record envelope received
+   */
+  peerRecordEnvelope?: Uint8Array
+}
+
+/**
+ * Peer data used to update the peer store
+ */
+export interface PeerData {
+  /**
+   * Peer's addresses containing its multiaddrs and metadata - multiaddrs
+   * passed here can be treated as certified if the `isCertifed` value is
+   * set to true.
+   *
+   * If both addresses and multiaddrs are specified they will be merged
+   * together with entries in addresses taking precedence.
+   */
+  addresses?: Address[]
+
+  /**
+   * Peer's multiaddrs - any multiaddrs passed here will be treated as
+   * uncertified.
+   *
+   * If both addresses and multiaddrs are specified they will be merged
+   * together with entries in addresses taking precedence.
+   */
+  multiaddrs?: Multiaddr[]
+
+  /**
+   * Peer's supported protocols
+   */
+  protocols?: string[]
+
+  /**
+   * Peer's metadata map. When merging pass undefined as values to remove metadata.
+   */
+  metadata?: Map<string, Uint8Array | undefined> | Record<string, Uint8Array | undefined>
+
+  /**
+   * Peer tags. When merging pass undefined as values to remove tags.
+   */
+  tags?: Map<string, TagOptions | undefined> | Record<string, TagOptions | undefined>
+
+  /**
+   * If this Peer has an RSA key, it's public key can be set with this property
+   */
+  publicKey?: Uint8Array
+
+  /**
+   * The last peer record envelope received
+   */
+  peerRecordEnvelope?: Uint8Array
+}
+
+export interface TagOptions {
+  /**
+   * An optional tag value (1-100)
+   */
+  value?: number
+
+  /**
+   * An optional duration in ms after which the tag will expire
+   */
+  ttl?: number
+}
+
+export interface Tag {
+  /**
+   * The tag value
+   */
+  value: number
+}
+
+/**
+ * A predicate by which to filter lists of peers
+ */
+export interface PeerQueryFilter { (peer: Peer): boolean }
+
+/**
+ * A predicate by which to sort lists of peers
+ */
+export interface PeerQueryOrder { (a: Peer, b: Peer): -1 | 0 | 1 }
+
+/**
+ * A query for getting lists of peers
+ */
+export interface PeerQuery {
+  filters?: PeerQueryFilter[]
+  orders?: PeerQueryOrder[]
+  limit?: number
+  offset?: number
+}
+
+export interface PeerStore {
+  /**
+   * Loop over every peer - the looping is async because we read from a
+   * datastore but the peer operation is sync, this is to prevent
+   * long-lived peer operations causing deadlocks over the datastore
+   * which can happen if they try to access the peer store during the
+   * loop
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.forEach(peer => {
+   *   // ...
+   * })
+   * ```
+   */
+  forEach: (fn: (peer: Peer) => void, query?: PeerQuery) => Promise<void>
+
+  /**
+   * Returns all peers in the peer store.
+   *
+   * @example
+   *
+   * ```js
+   * for (const peer of await peerStore.all()) {
+   *   // ...
+   * }
+   * ```
+   */
+  all: (query?: PeerQuery) => Promise<Peer[]>
+
+  /**
+   * Delete all data stored for the passed peer
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.addressBook.set(peerId, multiaddrs)
+   * await peerStore.addressBook.get(peerId)
+   * // multiaddrs[]
+   *
+   * await peerStore.delete(peerId)
+   *
+   * await peerStore.addressBook.get(peerId)
+   * // []
+   * ```
+   */
+  delete: (peerId: PeerId) => Promise<void>
+
+  /**
+   * Returns true if the passed PeerId is in the peer store
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.has(peerId)
+   * // false
+   * await peerStore.addressBook.add(peerId, multiaddrs)
+   * await peerStore.has(peerId)
+   * // true
+   * ```
+   */
+  has: (peerId: PeerId) => Promise<boolean>
+
+  /**
+   * Returns all data stored for the passed PeerId
+   *
+   * @example
+   *
+   * ```js
+   * const peer = await peerStore.get(peerId)
+   * // { .. }
+   * ```
+   */
+  get: (peerId: PeerId) => Promise<Peer>
+
+  /**
+   * Adds a peer to the peer store, overwriting any existing data
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.save(peerId, {
+   *   multiaddrs
+   * })
+   * ```
+   */
+  save: (id: PeerId, data: PeerData) => Promise<Peer>
+
+  /**
+   * Adds a peer to the peer store, overwriting only the passed fields
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.patch(peerId, {
+   *   multiaddrs
+   * })
+   * ```
+   */
+  patch: (id: PeerId, data: PeerData) => Promise<Peer>
+
+  /**
+   * Adds a peer to the peer store, deeply merging any existing data.
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.merge(peerId, {
+   *   multiaddrs
+   * })
+   * ```
+   */
+  merge: (id: PeerId, data: PeerData) => Promise<Peer>
+
+  /**
+   * Unmarshal and verify a signed peer record, extract the multiaddrs and
+   * overwrite the stored addresses for the peer.
+   *
+   * Optionally pass an expected PeerId to verify that the peer record was
+   * signed by that peer.
+   *
+   * @example
+   *
+   * ```js
+   * await peerStore.consumePeerRecord(buf, expectedPeer)
+   * ```
+   */
+  consumePeerRecord: (buf: Uint8Array, expectedPeer?: PeerId) => Promise<boolean>
+}

package/src/peer-store/tags.ts

@@ -0,0 +1,2 @@
+
+export const KEEP_ALIVE = 'keep-alive'

package/src/record/index.ts

@@ -0,0 +1,35 @@
+import type { PeerId } from '../peer-id/index.js'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+/**
+ * Record is the base implementation of a record that can be used as the payload of a libp2p envelope.
+ */
+export interface Record {
+  /**
+   * signature domain.
+   */
+  domain: string
+  /**
+   * identifier of the type of record
+   */
+  codec: Uint8Array
+  /**
+   * Marshal a record to be used in an envelope.
+   */
+  marshal: () => Uint8Array
+  /**
+   * Verifies if the other provided Record is identical to this one.
+   */
+  equals: (other: Record) => boolean
+}
+
+export interface Envelope {
+  peerId: PeerId
+  payloadType: Uint8Array | Uint8ArrayList
+  payload: Uint8Array
+  signature: Uint8Array | Uint8ArrayList
+
+  marshal: () => Uint8Array
+  validate: (domain: string) => Promise<boolean>
+  equals: (other: Envelope) => boolean
+}

package/src/startable.ts

@@ -0,0 +1,117 @@
+
+/**
+ * Implemented by components that have a lifecycle
+ */
+export interface Startable {
+  isStarted: () => boolean
+
+  /**
+   * If implemented, this method will be invoked before the start method.
+   *
+   * It should not assume any other components have been started.
+   */
+  beforeStart?: () => void | Promise<void>
+
+  /**
+   * This method will be invoked to start the component.
+   *
+   * It should not assume that any other components have been started.
+   */
+  start: () => void | Promise<void>
+
+  /**
+   * If implemented, this method will be invoked after the start method.
+   *
+   * All other components will have had their start method invoked before this method is called.
+   */
+  afterStart?: () => void | Promise<void>
+
+  /**
+   * If implemented, this method will be invoked before the stop method.
+   *
+   * Any other components will still be running when this method is called.
+   */
+  beforeStop?: () => void | Promise<void>
+
+  /**
+   * This method will be invoked to stop the component.
+   *
+   * It should not assume any other components are running when it is called.
+   */
+  stop: () => void | Promise<void>
+
+  /**
+   * If implemented, this method will be invoked after the stop method.
+   *
+   * All other components will have had their stop method invoked before this method is called.
+   */
+  afterStop?: () => void | Promise<void>
+}
+
+export function isStartable (obj: any): obj is Startable {
+  return obj != null && typeof obj.start === 'function' && typeof obj.stop === 'function'
+}
+
+export async function start (...objs: any[]): Promise<void> {
+  const startables: Startable[] = []
+
+  for (const obj of objs) {
+    if (isStartable(obj)) {
+      startables.push(obj)
+    }
+  }
+
+  await Promise.all(
+    startables.map(async s => {
+      if (s.beforeStart != null) {
+        await s.beforeStart()
+      }
+    })
+  )
+
+  await Promise.all(
+    startables.map(async s => {
+      await s.start()
+    })
+  )
+
+  await Promise.all(
+    startables.map(async s => {
+      if (s.afterStart != null) {
+        await s.afterStart()
+      }
+    })
+  )
+}
+
+export async function stop (...objs: any[]): Promise<void> {
+  const startables: Startable[] = []
+
+  for (const obj of objs) {
+    if (isStartable(obj)) {
+      startables.push(obj)
+    }
+  }
+
+  await Promise.all(
+    startables.map(async s => {
+      if (s.beforeStop != null) {
+        await s.beforeStop()
+      }
+    })
+  )
+
+  await Promise.all(
+    startables.map(async s => {
+      await s.stop()
+    })
+  )
+
+  await Promise.all(
+    startables.map(async s => {
+      if (s.afterStop != null) {
+        await s.afterStop()
+      }
+    })
+  )
+}

package/src/stream-handler/index.ts

@@ -0,0 +1,27 @@
+import type { Connection, Stream } from '../connection/index.js'
+
+export interface IncomingStreamData {
+  stream: Stream
+  connection: Connection
+}
+
+export interface StreamHandler {
+  (data: IncomingStreamData): void
+}
+
+export interface StreamHandlerOptions {
+  /**
+   * 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)
+   */
+  maxOutboundStreams?: number
+}
+
+export interface StreamHandlerRecord {
+  handler: StreamHandler
+  options: StreamHandlerOptions
+}

package/src/stream-muxer/index.ts

@@ -0,0 +1,58 @@
+import type { Direction, Stream } from '../connection/index.js'
+import type { AbortOptions } from '../index.js'
+import type { Duplex, Source } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
+
+export interface StreamMuxerFactory {
+  /**
+   * The protocol used to select this muxer during connection opening
+   */
+  protocol: string
+
+  /**
+   * Creates a new stream muxer to be used with a new connection
+   */
+  createStreamMuxer: (init?: StreamMuxerInit) => StreamMuxer
+}
+
+/**
+ * A libp2p stream muxer
+ */
+export interface StreamMuxer extends Duplex<AsyncGenerator<Uint8Array>, Source<Uint8ArrayList | Uint8Array>, Promise<void>> {
+  /**
+   * The protocol used to select this muxer during connection opening
+   */
+  protocol: string
+
+  /**
+   * A list of streams that are currently open. Closed streams will not be returned.
+   */
+  readonly streams: Stream[]
+  /**
+   * Initiate a new stream with the given name. If no name is
+   * provided, the id of the stream will be used.
+   */
+  newStream: (name?: string) => Stream | Promise<Stream>
+
+  /**
+   * Close or abort all tracked streams and stop the muxer
+   */
+  close: (err?: Error) => void
+}
+
+export interface StreamMuxerInit extends AbortOptions {
+  /**
+   * A callback function invoked every time an incoming stream is opened
+   */
+  onIncomingStream?: (stream: Stream) => void
+
+  /**
+   * A callback function invoke every time a stream ends
+   */
+  onStreamEnd?: (stream: Stream) => void
+
+  /**
+   * Outbound stream muxers are opened by the local node, inbound stream muxers are opened by the remote
+   */
+  direction?: Direction
+}