@libp2p/multistream-select 0.0.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@libp2p/multistream-select",
+  "version": "0.0.0",
+  "leadMaintainer": "Jacob Heun <jacobheun@gmail.com>",
+  "description": "JavaScript implementation of multistream-select",
+  "type": "module",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check dist/src/**/*.js dist/test/**/*.js",
+    "build": "tsc",
+    "pretest": "npm run build",
+    "test": "aegir test -f ./dist/test/*.js -f ./dist/test/**/*.js",
+    "test:chrome": "npm run test -- -t browser",
+    "test:chrome-webworker": "npm run test -- -t webworker",
+    "test:firefox": "npm run test -- -t browser -- --browser firefox",
+    "test:firefox-webworker": "npm run test -- -t webworker -- --browser firefox",
+    "test:node": "npm run test -- -t node --cov",
+    "test:electron-main": "npm run test -- -t electron-main"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/multiformats/js-multistream-select.git"
+  },
+  "pre-push": [
+    "lint"
+  ],
+  "keywords": [
+    "stream",
+    "multistream",
+    "protocol",
+    "ipfs",
+    "libp2p"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/multiformats/js-multistream-select/issues"
+  },
+  "homepage": "https://github.com/multiformats/js-multistream-select#readme",
+  "dependencies": {
+    "@libp2p/interfaces": "^1.3.6",
+    "it-stream-types": "^1.0.4",
+    "abortable-iterator": "^4.0.2",
+    "@libp2p/logger": "^1.0.3",
+    "err-code": "^3.0.1",
+    "it-first": "^1.0.6",
+    "it-handshake": "^3.0.0",
+    "it-length-prefixed": "^7.0.0",
+    "it-pipe": "^2.0.3",
+    "it-reader": "^5.0.0",
+    "p-defer": "^4.0.0",
+    "uint8arrays": "^3.0.0",
+    "uint8arraylist": "^1.2.0"
+  },
+  "devDependencies": {
+    "aegir": "^36.1.1",
+    "it-pair": "^2.0.2",
+    "p-timeout": "^5.0.2",
+    "timeout-abort-controller": "^3.0.0",
+    "util": "^0.12.4",
+    "varint": "^6.0.0"
+  },
+  "contributors": [
+    "David Dias <daviddias.p@gmail.com>",
+    "Jacob Heun <jacobheun@gmail.com>",
+    "Alex Potsides <alex@achingbrain.net>",
+    "dignifiedquire <dignifiedquire@gmail.com>",
+    "Victor Bjelkholm <victorbjelkholm@gmail.com>",
+    "Richard Littauer <richard.littauer@gmail.com>",
+    "Vasco Santos <vasco.santos@moxy.studio>",
+    "Alan Shaw <alan.shaw@protocol.ai>",
+    "Hugo Dias <mail@hugodias.me>",
+    "Didrik Nordström <didrik.nordstrom@gmail.com>",
+    "Projjol Banerji <probaner23@gmail.com>"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+
+export const PROTOCOL_ID = '/multistream/1.0.0'

package/src/handle.ts

@@ -0,0 +1,43 @@
+import { logger } from '@libp2p/logger'
+import * as multistream from './multistream.js'
+import { handshake } from 'it-handshake'
+import { PROTOCOL_ID } from './constants.js'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import { Uint8ArrayList } from 'uint8arraylist'
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { Duplex } from 'it-stream-types'
+
+const log = logger('libp2p:mss:handle')
+
+export async function handle (stream: Duplex<Uint8Array>, protocols: string | string[], options?: AbortOptions) {
+  protocols = Array.isArray(protocols) ? protocols : [protocols]
+  const { writer, reader, rest, stream: shakeStream } = handshake(stream)
+
+  while (true) {
+    const protocol = await multistream.readString(reader, options)
+    log('read "%s"', protocol)
+
+    if (protocol === PROTOCOL_ID) {
+      log('respond with "%s" for "%s"', PROTOCOL_ID, protocol)
+      multistream.write(writer, uint8ArrayFromString(PROTOCOL_ID))
+      continue
+    }
+
+    if (protocols.includes(protocol)) {
+      multistream.write(writer, uint8ArrayFromString(protocol))
+      log('respond with "%s" for "%s"', protocol, protocol)
+      rest()
+      return { stream: shakeStream, protocol }
+    }
+
+    if (protocol === 'ls') {
+      // <varint-msg-len><varint-proto-name-len><proto-name>\n<varint-proto-name-len><proto-name>\n\n
+      multistream.write(writer, new Uint8ArrayList(...protocols.map(p => multistream.encode(uint8ArrayFromString(p)))))
+      log('respond with "%s" for %s', protocols, protocol)
+      continue
+    }
+
+    multistream.write(writer, uint8ArrayFromString('na'))
+    log('respond with "na" for "%s"', protocol)
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { select } from './select.js'
+import { handle } from './handle.js'
+import { ls } from './ls.js'
+import { PROTOCOL_ID } from './constants.js'
+import type { Duplex } from 'it-stream-types'
+import type { AbortOptions } from '@libp2p/interfaces'
+
+export { PROTOCOL_ID }
+
+export interface ProtocolStream {
+  stream: Duplex<Uint8Array>
+  protocol: string
+}
+
+class MultistreamSelect {
+  protected stream: Duplex<Uint8Array>
+  protected shaken: boolean
+
+  constructor (stream: Duplex<Uint8Array>) {
+    this.stream = stream
+    this.shaken = false
+  }
+
+  /**
+   * Perform the multistream-select handshake
+   *
+   * @param {AbortOptions} [options]
+   */
+  async _handshake (options?: AbortOptions): Promise<void> {
+    if (this.shaken) {
+      return
+    }
+
+    const { stream } = await select(this.stream, PROTOCOL_ID, undefined, options)
+    this.stream = stream
+    this.shaken = true
+  }
+}
+
+export class Dialer extends MultistreamSelect {
+  async select (protocols: string | string[], options?: AbortOptions): Promise<ProtocolStream> {
+    return await select(this.stream, protocols, this.shaken ? undefined : PROTOCOL_ID, options)
+  }
+
+  async ls (options?: AbortOptions): Promise<string[]> {
+    await this._handshake(options)
+    const res = await ls(this.stream, options)
+    const { stream, protocols } = res
+    this.stream = stream
+    return protocols
+  }
+}
+
+export class Listener extends MultistreamSelect {
+  async handle (protocols: string | string[], options?: AbortOptions): Promise<ProtocolStream> {
+    return await handle(this.stream, protocols, options)
+  }
+}

package/src/ls.ts

@@ -0,0 +1,45 @@
+import { reader as createReader } from 'it-reader'
+import { logger } from '@libp2p/logger'
+import * as multistream from './multistream.js'
+import { handshake } from 'it-handshake'
+import * as lp from 'it-length-prefixed'
+import { pipe } from 'it-pipe'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import type { Duplex } from 'it-stream-types'
+import type { AbortOptions } from '@libp2p/interfaces'
+
+const log = logger('libp2p:mss:ls')
+
+export async function ls (stream: Duplex<Uint8Array>, options?: AbortOptions): Promise<{ stream: Duplex<Uint8Array>, protocols: string[] }> {
+  const { reader, writer, rest, stream: shakeStream } = handshake(stream)
+
+  log('write "ls"')
+  multistream.write(writer, uint8ArrayFromString('ls'))
+  rest()
+
+  // Next message from remote will be (e.g. for 2 protocols):
+  // <varint-msg-len><varint-proto-name-len><proto-name>\n<varint-proto-name-len><proto-name>\n
+  const res = await multistream.read(reader, options)
+
+  // After reading response we have:
+  // <varint-proto-name-len><proto-name>\n<varint-proto-name-len><proto-name>\n
+  const protocolsReader = createReader([res])
+  const protocols: string[] = []
+
+  // Decode each of the protocols from the reader
+  await pipe(
+    protocolsReader,
+    lp.decode(),
+    async (source) => {
+      for await (const protocol of source) {
+        // Remove the newline
+        protocols.push(uint8ArrayToString(protocol.slice(0, -1)))
+      }
+    }
+  )
+
+  const output = { stream: shakeStream, protocols }
+
+  return output
+}

package/src/multistream.ts

@@ -0,0 +1,82 @@
+
+import { Uint8ArrayList } from 'uint8arraylist'
+import * as lp from 'it-length-prefixed'
+import { pipe } from 'it-pipe'
+import errCode from 'err-code'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import first from 'it-first'
+import { abortableSource } from 'abortable-iterator'
+import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
+import type { Pushable } from 'it-pushable'
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { Source } from 'it-stream-types'
+import type { Reader } from 'it-reader'
+
+const NewLine = uint8ArrayFromString('\n')
+
+export function encode (buffer: Uint8Array | Uint8ArrayList): Uint8Array {
+  const list = new Uint8ArrayList(buffer, NewLine)
+
+  return lp.encode.single(list).slice()
+}
+
+/**
+ * `write` encodes and writes a single buffer
+ */
+export function write (writer: Pushable<Uint8Array>, buffer: Uint8Array | Uint8ArrayList) {
+  writer.push(encode(buffer).slice())
+}
+
+/**
+ * `writeAll` behaves like `write`, except it encodes an array of items as a single write
+ */
+export function writeAll (writer: Pushable<Uint8Array>, buffers: Uint8Array[]) {
+  const list = new Uint8ArrayList()
+
+  for (const buf of buffers) {
+    list.append(encode(buf))
+  }
+
+  writer.push(list.slice())
+}
+
+export async function read (reader: Reader, options?: AbortOptions) {
+  let byteLength = 1 // Read single byte chunks until the length is known
+  const varByteSource = { // No return impl - we want the reader to remain readable
+    [Symbol.asyncIterator]: () => varByteSource,
+    next: async () => await reader.next(byteLength)
+  }
+
+  let input: Source<Uint8ArrayList> = varByteSource
+
+  // If we have been passed an abort signal, wrap the input source in an abortable
+  // iterator that will throw if the operation is aborted
+  if (options?.signal != null) {
+    input = abortableSource(varByteSource, options.signal)
+  }
+
+  // Once the length has been parsed, read chunk for that length
+  const onLength = (l: number) => { byteLength = l }
+
+  const buf = await pipe(
+    input,
+    lp.decode({ onLength }),
+    async (source) => await first(source)
+  )
+
+  if (buf == null) {
+    throw errCode(new Error('no buffer returned'), 'ERR_INVALID_MULTISTREAM_SELECT_MESSAGE')
+  }
+
+  if (buf[buf.length - 1] !== NewLine[0]) {
+    throw errCode(new Error('missing newline'), 'ERR_INVALID_MULTISTREAM_SELECT_MESSAGE')
+  }
+
+  return buf.slice(0, -1) // Remove newline
+}
+
+export async function readString (reader: Reader, options?: AbortOptions) {
+  const buf = await read(reader, options)
+
+  return uint8ArrayToString(buf)
+}

package/src/select.ts

@@ -0,0 +1,59 @@
+import { logger } from '@libp2p/logger'
+import errCode from 'err-code'
+import * as multistream from './multistream.js'
+import { handshake } from 'it-handshake'
+import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { Duplex } from 'it-stream-types'
+
+const log = logger('libp2p:mss:select')
+
+export async function select (stream: Duplex<Uint8Array>, protocols: string | string[], protocolId?: string, options?: AbortOptions) {
+  protocols = Array.isArray(protocols) ? [...protocols] : [protocols]
+  const { reader, writer, rest, stream: shakeStream } = handshake(stream)
+
+  const protocol = protocols.shift()
+
+  if (protocol == null) {
+    throw new Error('At least one protocol must be specified')
+  }
+
+  if (protocolId != null) {
+    log('select: write ["%s", "%s"]', protocolId, protocol)
+    multistream.writeAll(writer, [uint8ArrayFromString(protocolId), uint8ArrayFromString(protocol)])
+  } else {
+    log('select: write "%s"', protocol)
+    multistream.write(writer, uint8ArrayFromString(protocol))
+  }
+
+  let response = await multistream.readString(reader, options)
+  log('select: read "%s"', response)
+
+  // Read the protocol response if we got the protocolId in return
+  if (response === protocolId) {
+    response = await multistream.readString(reader, options)
+    log('select: read "%s"', response)
+  }
+
+  // We're done
+  if (response === protocol) {
+    rest()
+    return { stream: shakeStream, protocol }
+  }
+
+  // We haven't gotten a valid ack, try the other protocols
+  for (const protocol of protocols) {
+    log('select: write "%s"', protocol)
+    multistream.write(writer, uint8ArrayFromString(protocol))
+    const response = await multistream.readString(reader, options)
+    log('select: read "%s" for "%s"', response, protocol)
+
+    if (response === protocol) {
+      rest() // End our writer so others can start writing to stream
+      return { stream: shakeStream, protocol }
+    }
+  }
+
+  rest()
+  throw errCode(new Error('protocol selection failed'), 'ERR_UNSUPPORTED_PROTOCOL')
+}