@libp2p/memory 0.0.0-91687998d

package/src/listener.ts

@@ -0,0 +1,135 @@
+/**
+ * @packageDocumentation
+ *
+ * A [libp2p transport](https://docs.libp2p.io/concepts/transports/overview/)
+ * that operates in-memory only.
+ *
+ * This is intended for testing and can only be used to connect two libp2p nodes
+ * that are running in the same process.
+ *
+ * @example
+ *
+ * ```TypeScript
+ * import { createLibp2p } from 'libp2p'
+ * import { memory } from '@libp2p/memory'
+ * import { multiaddr } from '@multiformats/multiaddr'
+ *
+ * const listener = await createLibp2p({
+ *   addresses: {
+ *     listen: [
+ *       '/memory/node-a'
+ *     ]
+ *   },
+ *   transports: [
+ *     memory()
+ *   ]
+ * })
+ *
+ * const dialer = await createLibp2p({
+ *   transports: [
+ *     memory()
+ *   ]
+ * })
+ *
+ * const ma = multiaddr('/memory/node-a')
+ *
+ * // dial the listener, timing out after 10s
+ * const connection = await dialer.dial(ma, {
+ *   signal: AbortSignal.timeout(10_000)
+ * })
+ *
+ * // use connection...
+ * ```
+ */
+
+import { ListenError, TypedEventEmitter } from '@libp2p/interface'
+import { multiaddr } from '@multiformats/multiaddr'
+import { nanoid } from 'nanoid'
+import { MemoryConnection, connections } from './connections.js'
+import type { MemoryTransportComponents, MemoryTransportInit } from './index.js'
+import type { Listener, CreateListenerOptions, ListenerEvents, MultiaddrConnection, UpgraderOptions } from '@libp2p/interface'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export interface MemoryTransportListenerInit extends CreateListenerOptions, MemoryTransportInit {
+  upgraderOptions?: UpgraderOptions
+}
+
+export class MemoryTransportListener extends TypedEventEmitter<ListenerEvents> implements Listener {
+  private listenAddr?: Multiaddr
+  private connection?: MemoryConnection
+  private readonly components: MemoryTransportComponents
+  private readonly init: MemoryTransportListenerInit
+
+  constructor (components: MemoryTransportComponents, init: MemoryTransportListenerInit) {
+    super()
+
+    this.components = components
+    this.init = init
+  }
+
+  async listen (ma: Multiaddr): Promise<void> {
+    const [[, value]] = ma.stringTuples()
+
+    const address = `/memory/${value ?? nanoid()}`
+
+    if (value != null && connections.has(address)) {
+      throw new ListenError(`Memory address ${address} already in use`)
+    }
+
+    this.connection = new MemoryConnection(this.components, {
+      onConnection: this.onConnection.bind(this),
+      address
+    })
+    this.listenAddr = multiaddr(address)
+
+    connections.set(address, this.connection)
+
+    queueMicrotask(() => {
+      this.safeDispatchEvent('listening')
+    })
+  }
+
+  onConnection (maConn: MultiaddrConnection): void {
+    let signal: AbortSignal | undefined
+
+    if (this.init.inboundUpgradeTimeout != null) {
+      signal = AbortSignal.timeout(this.init.inboundUpgradeTimeout)
+    }
+
+    this.init.upgrader.upgradeInbound(maConn, {
+      ...this.init.upgraderOptions,
+      signal
+    })
+      .then(connection => {
+        this.init.handler?.(connection)
+        this.safeDispatchEvent('connection', {
+          detail: connection
+        })
+      })
+      .catch(err => {
+        maConn.abort(err)
+      })
+  }
+
+  getAddrs (): Multiaddr[] {
+    if (this.listenAddr == null) {
+      return []
+    }
+
+    return [
+      this.listenAddr
+    ]
+  }
+
+  async close (): Promise<void> {
+    this.connection?.close()
+
+    if (this.listenAddr != null) {
+      connections.delete(this.listenAddr.toString())
+    }
+
+    queueMicrotask(() => {
+      this.safeDispatchEvent('close')
+    })
+  }
+}

package/src/memory.ts

@@ -0,0 +1,113 @@
+/**
+ * @packageDocumentation
+ *
+ * A [libp2p transport](https://docs.libp2p.io/concepts/transports/overview/)
+ * that operates in-memory only.
+ *
+ * This is intended for testing and can only be used to connect two libp2p nodes
+ * that are running in the same process.
+ *
+ * @example
+ *
+ * ```TypeScript
+ * import { createLibp2p } from 'libp2p'
+ * import { memory } from '@libp2p/memory'
+ * import { multiaddr } from '@multiformats/multiaddr'
+ *
+ * const listener = await createLibp2p({
+ *   addresses: {
+ *     listen: [
+ *       '/memory/node-a'
+ *     ]
+ *   },
+ *   transports: [
+ *     memory()
+ *   ]
+ * })
+ *
+ * const dialer = await createLibp2p({
+ *   transports: [
+ *     memory()
+ *   ]
+ * })
+ *
+ * const ma = multiaddr('/memory/node-a')
+ *
+ * // dial the listener, timing out after 10s
+ * const connection = await dialer.dial(ma, {
+ *   signal: AbortSignal.timeout(10_000)
+ * })
+ *
+ * // use connection...
+ * ```
+ */
+
+import { ConnectionFailedError, serviceCapabilities, transportSymbol } from '@libp2p/interface'
+import { Memory } from '@multiformats/multiaddr-matcher'
+import { connections } from './connections.js'
+import { MemoryTransportListener } from './listener.js'
+import type { MemoryTransportComponents, MemoryTransportInit } from './index.js'
+import type { Connection, Transport, Listener, CreateListenerOptions, DialTransportOptions } from '@libp2p/interface'
+import type { Multiaddr } from '@multiformats/multiaddr'
+
+export class MemoryTransport implements Transport {
+  private readonly components: MemoryTransportComponents
+  private readonly init: MemoryTransportInit
+
+  constructor (components: MemoryTransportComponents, init: MemoryTransportInit = {}) {
+    this.components = components
+    this.init = init
+  }
+
+  readonly [transportSymbol] = true
+
+  readonly [Symbol.toStringTag] = '@libp2p/memory'
+
+  readonly [serviceCapabilities]: string[] = [
+    '@libp2p/transport'
+  ]
+
+  async dial (ma: Multiaddr, options: DialTransportOptions): Promise<Connection> {
+    options.signal?.throwIfAborted()
+
+    const memoryConnection = connections.get(`${ma.getPeerId() == null ? ma : ma.decapsulate('/p2p')}`)
+
+    if (memoryConnection == null) {
+      throw new ConnectionFailedError(`No memory listener found at ${ma}`)
+    }
+
+    const maConn = await memoryConnection.dial(this.components.peerId)
+
+    try {
+      options.signal?.throwIfAborted()
+
+      return await options.upgrader.upgradeOutbound(maConn, {
+        ...options,
+        ...this.init.upgraderOptions
+      })
+    } catch (err: any) {
+      maConn.abort(err)
+      throw err
+    }
+  }
+
+  /**
+   * Creates a TCP listener. The provided `handler` function will be called
+   * anytime a new incoming Connection has been successfully upgraded via
+   * `upgrader.upgradeInbound`.
+   */
+  createListener (options: CreateListenerOptions): Listener {
+    return new MemoryTransportListener(this.components, {
+      ...options,
+      ...this.init
+    })
+  }
+
+  listenFilter (multiaddrs: Multiaddr[]): Multiaddr[] {
+    return multiaddrs.filter(ma => Memory.exactMatch(ma))
+  }
+
+  dialFilter (multiaddrs: Multiaddr[]): Multiaddr[] {
+    return this.listenFilter(multiaddrs)
+  }
+}