@libp2p/multistream-select 6.0.29-8484de8a2 → 6.0.29-87bc8d4fb

package/src/handle.ts

@@ -1,11 +1,11 @@
-import { lpStream } from '@libp2p/utils'
 import { encode } from 'it-length-prefixed'
+import { lpStream } from 'it-length-prefixed-stream'
 import { Uint8ArrayList } from 'uint8arraylist'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { MAX_PROTOCOL_LENGTH, PROTOCOL_ID } from './constants.js'
-import { readString } from './multistream.js'
-import type { MultistreamSelectInit } from './index.js'
-import type { MultiaddrConnection, MessageStream } from '@libp2p/interface'
+import * as multistream from './multistream.js'
+import type { MultistreamSelectInit, ProtocolStream } from './index.js'
+import type { Duplex } from 'it-stream-types'
 
 /**
  * Handle multistream protocol selections for the given list of protocols.
@@ -53,38 +53,34 @@ import type { MultiaddrConnection, MessageStream } from '@libp2p/interface'
  * })
  * ```
  */
-export async function handle <Stream extends MessageStream = MultiaddrConnection> (stream: Stream, protocols: string | string[], options: MultistreamSelectInit = {}): Promise<string> {
+export async function handle <Stream extends Duplex<any, any, any>> (stream: Stream, protocols: string | string[], options: MultistreamSelectInit): Promise<ProtocolStream<Stream>> {
   protocols = Array.isArray(protocols) ? protocols : [protocols]
-
-  const log = stream.log.newScope('mss:handle')
+  options.log.trace('handle: available protocols %s', protocols)
 
   const lp = lpStream(stream, {
     ...options,
     maxDataLength: MAX_PROTOCOL_LENGTH,
-    maxLengthLength: 2, // 2 bytes is enough to length-prefix MAX_PROTOCOL_LENGTH
-    stopPropagation: true
+    maxLengthLength: 2 // 2 bytes is enough to length-prefix MAX_PROTOCOL_LENGTH
   })
 
   while (true) {
-    log.trace('reading incoming string')
-    const protocol = await readString(lp, options)
-    log.trace('read "%s"', protocol)
+    options.log.trace('handle: reading incoming string')
+    const protocol = await multistream.readString(lp, options)
+    options.log.trace('handle: read "%s"', protocol)
 
     if (protocol === PROTOCOL_ID) {
-      log.trace('respond with "%s" for "%s"', PROTOCOL_ID, protocol)
-      await lp.write(uint8ArrayFromString(`${PROTOCOL_ID}\n`), options)
-      log.trace('responded with "%s" for "%s"', PROTOCOL_ID, protocol)
+      options.log.trace('handle: respond with "%s" for "%s"', PROTOCOL_ID, protocol)
+      await multistream.write(lp, uint8ArrayFromString(`${PROTOCOL_ID}\n`), options)
+      options.log.trace('handle: responded with "%s" for "%s"', PROTOCOL_ID, protocol)
       continue
     }
 
     if (protocols.includes(protocol)) {
-      log.trace('respond with "%s" for "%s"', protocol, protocol)
-      await lp.write(uint8ArrayFromString(`${protocol}\n`), options)
-      log.trace('responded with "%s" for "%s"', protocol, protocol)
-
-      lp.unwrap()
+      options.log.trace('handle: respond with "%s" for "%s"', protocol, protocol)
+      await multistream.write(lp, uint8ArrayFromString(`${protocol}\n`), options)
+      options.log.trace('handle: responded with "%s" for "%s"', protocol, protocol)
 
-      return protocol
+      return { stream: lp.unwrap(), protocol }
     }
 
     if (protocol === 'ls') {
@@ -94,14 +90,14 @@ export async function handle <Stream extends MessageStream = MultiaddrConnection
         uint8ArrayFromString('\n')
       )
 
-      log.trace('respond with "%s" for %s', protocols, protocol)
-      await lp.write(protos, options)
-      log.trace('responded with "%s" for %s', protocols, protocol)
+      options.log.trace('handle: respond with "%s" for %s', protocols, protocol)
+      await multistream.write(lp, protos, options)
+      options.log.trace('handle: responded with "%s" for %s', protocols, protocol)
       continue
     }
 
-    log.trace('respond with "na" for "%s"', protocol)
-    await lp.write(uint8ArrayFromString('na\n'), options)
-    log('responded with "na" for "%s"', protocol)
+    options.log.trace('handle: respond with "na" for "%s"', protocol)
+    await multistream.write(lp, uint8ArrayFromString('na\n'), options)
+    options.log('handle: responded with "na" for "%s"', protocol)
   }
 }

package/src/index.ts

@@ -21,12 +21,17 @@
  */
 
 import { PROTOCOL_ID } from './constants.js'
-import type { AbortOptions } from '@libp2p/interface'
-import type { LengthPrefixedStreamOpts } from '@libp2p/utils'
+import type { AbortOptions, LoggerOptions } from '@libp2p/interface'
+import type { LengthPrefixedStreamOpts } from 'it-length-prefixed-stream'
 
 export { PROTOCOL_ID }
 
-export interface MultistreamSelectInit extends AbortOptions, Partial<LengthPrefixedStreamOpts> {
+export interface ProtocolStream<Stream> {
+  stream: Stream
+  protocol: string
+}
+
+export interface MultistreamSelectInit extends AbortOptions, LoggerOptions, Partial<LengthPrefixedStreamOpts> {
   /**
    * When false, and only a single protocol is being negotiated, use optimistic
    * select to send both the protocol name and the first data buffer in the
@@ -38,4 +43,5 @@ export interface MultistreamSelectInit extends AbortOptions, Partial<LengthPrefi
 }
 
 export { select } from './select.js'
+export type { SelectStream } from './select.js'
 export { handle } from './handle.js'

package/src/multistream.ts

@@ -1,21 +1,46 @@
 import { InvalidMessageError } from '@libp2p/interface'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { toString as uint8ArrayToString } from 'uint8arrays/to-string'
-import type { AbortOptions } from '@libp2p/interface'
-import type { LengthPrefixedStream } from '@libp2p/utils'
+import type { AbortOptions, LoggerOptions } from '@libp2p/interface'
+import type { LengthPrefixedStream } from 'it-length-prefixed-stream'
+import type { Duplex, Source } from 'it-stream-types'
+import type { Uint8ArrayList } from 'uint8arraylist'
 
 const NewLine = uint8ArrayFromString('\n')
 
 /**
- * Read a length-prefixed string from the passed stream, stripping the final newline character
+ * `write` encodes and writes a single buffer
+ */
+export async function write (writer: LengthPrefixedStream<Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>, Source<Uint8Array>>>, buffer: Uint8Array | Uint8ArrayList, options?: AbortOptions): Promise<void> {
+  await writer.write(buffer, options)
+}
+
+/**
+ * `writeAll` behaves like `write`, except it encodes an array of items as a single write
  */
-export async function readString (reader: LengthPrefixedStream<any>, options?: AbortOptions): Promise<string> {
+export async function writeAll (writer: LengthPrefixedStream<Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>, Source<Uint8Array>>>, buffers: Uint8Array[], options?: AbortOptions): Promise<void> {
+  await writer.writeV(buffers, options)
+}
+
+/**
+ * Read a length-prefixed buffer from the passed stream, stripping the final newline character
+ */
+export async function read (reader: LengthPrefixedStream<Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>, Source<Uint8Array>>>, options: AbortOptions & LoggerOptions): Promise<Uint8ArrayList> {
   const buf = await reader.read(options)
-  const arr = buf.subarray()
 
-  if (arr.byteLength === 0 || arr[arr.length - 1] !== NewLine[0]) {
+  if (buf.byteLength === 0 || buf.get(buf.byteLength - 1) !== NewLine[0]) {
+    options.log.error('Invalid mss message - missing newline', buf)
     throw new InvalidMessageError('Missing newline')
   }
 
-  return uint8ArrayToString(arr).trimEnd()
+  return buf.sublist(0, -1) // Remove newline
+}
+
+/**
+ * Read a length-prefixed string from the passed stream, stripping the final newline character
+ */
+export async function readString (reader: LengthPrefixedStream<Duplex<AsyncGenerator<Uint8Array | Uint8ArrayList>, Source<Uint8Array>>>, options: AbortOptions & LoggerOptions): Promise<string> {
+  const buf = await read(reader, options)
+
+  return uint8ArrayToString(buf.subarray())
 }

package/src/select.ts

@@ -1,11 +1,23 @@
 import { UnsupportedProtocolError } from '@libp2p/interface'
-import { lpStream } from '@libp2p/utils'
+import { lpStream } from 'it-length-prefixed-stream'
+import pDefer from 'p-defer'
+import { raceSignal } from 'race-signal'
+import * as varint from 'uint8-varint'
+import { Uint8ArrayList } from 'uint8arraylist'
 import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string'
 import { MAX_PROTOCOL_LENGTH } from './constants.js'
-import { readString } from './multistream.js'
+import * as multistream from './multistream.js'
 import { PROTOCOL_ID } from './index.js'
-import type { MultistreamSelectInit } from './index.js'
-import type { MessageStream } from '@libp2p/interface'
+import type { MultistreamSelectInit, ProtocolStream } from './index.js'
+import type { AbortOptions } from '@libp2p/interface'
+import type { Duplex } from 'it-stream-types'
+
+export interface SelectStream extends Duplex<any, any, any> {
+  readStatus?: string
+  closeWrite?(options?: AbortOptions): Promise<void>
+  closeRead?(options?: AbortOptions): Promise<void>
+  close?(options?: AbortOptions): Promise<void>
+}
 
 /**
  * Negotiate a protocol to use from a list of protocols.
@@ -50,57 +62,304 @@ import type { MessageStream } from '@libp2p/interface'
  * // }
  * ```
  */
-export async function select <Stream extends MessageStream> (stream: Stream, protocols: string | string[], options: MultistreamSelectInit = {}): Promise<string> {
+export async function select <Stream extends SelectStream> (stream: Stream, protocols: string | string[], options: MultistreamSelectInit): Promise<ProtocolStream<Stream>> {
   protocols = Array.isArray(protocols) ? [...protocols] : [protocols]
 
-  if (protocols.length === 0) {
-    throw new Error('At least one protocol must be specified')
+  if (protocols.length === 1 && options.negotiateFully === false) {
+    return optimisticSelect(stream, protocols[0], options)
   }
 
-  const log = stream.log.newScope('mss:select')
   const lp = lpStream(stream, {
     ...options,
-    maxDataLength: MAX_PROTOCOL_LENGTH,
-    stopPropagation: true
+    maxDataLength: MAX_PROTOCOL_LENGTH
   })
+  const protocol = protocols.shift()
+
+  if (protocol == null) {
+    throw new Error('At least one protocol must be specified')
+  }
+
+  options.log.trace('select: write ["%s", "%s"]', PROTOCOL_ID, protocol)
+  const p1 = uint8ArrayFromString(`${PROTOCOL_ID}\n`)
+  const p2 = uint8ArrayFromString(`${protocol}\n`)
+  await multistream.writeAll(lp, [p1, p2], options)
+
+  options.log.trace('select: reading multistream-select header')
+  let response = await multistream.readString(lp, options)
+  options.log.trace('select: read "%s"', response)
+
+  // Read the protocol response if we got the protocolId in return
+  if (response === PROTOCOL_ID) {
+    options.log.trace('select: reading protocol response')
+    response = await multistream.readString(lp, options)
+    options.log.trace('select: read "%s"', response)
+  }
+
+  // We're done
+  if (response === protocol) {
+    return { stream: lp.unwrap(), protocol }
+  }
 
-  for (let i = 0; i < protocols.length; i++) {
-    const protocol = protocols[i]
-    let response: string
-
-    if (i === 0) {
-      // Write the multistream-select header along with the first protocol
-      log.trace('write ["%s", "%s"]', PROTOCOL_ID, protocol)
-      const p1 = uint8ArrayFromString(`${PROTOCOL_ID}\n`)
-      const p2 = uint8ArrayFromString(`${protocol}\n`)
-      await lp.writeV([p1, p2], options)
-
-      log.trace('reading multistream-select header')
-      response = await readString(lp, options)
-      log.trace('read "%s"', response)
-
-      // Read the protocol response if we got the protocolId in return
-      if (response !== PROTOCOL_ID) {
-        log.error('did not read multistream-select header from response')
-        break
+  // We haven't gotten a valid ack, try the other protocols
+  for (const protocol of protocols) {
+    options.log.trace('select: write "%s"', protocol)
+    await multistream.write(lp, uint8ArrayFromString(`${protocol}\n`), options)
+    options.log.trace('select: reading protocol response')
+    const response = await multistream.readString(lp, options)
+    options.log.trace('select: read "%s" for "%s"', response, protocol)
+
+    if (response === protocol) {
+      return { stream: lp.unwrap(), protocol }
+    }
+  }
+
+  throw new UnsupportedProtocolError('protocol selection failed')
+}
+
+/**
+ * Optimistically negotiates a protocol.
+ *
+ * It *does not* block writes waiting for the other end to respond. Instead, it
+ * simply assumes the negotiation went successfully and starts writing data.
+ *
+ * Use when it is known that the receiver supports the desired protocol.
+ */
+function optimisticSelect <Stream extends SelectStream> (stream: Stream, protocol: string, options: MultistreamSelectInit): ProtocolStream<Stream> {
+  const originalSink = stream.sink.bind(stream)
+  const originalSource = stream.source
+
+  let negotiated = false
+  let negotiating = false
+  const doneNegotiating = pDefer()
+
+  let sentProtocol = false
+  let sendingProtocol = false
+  const doneSendingProtocol = pDefer()
+
+  let readProtocol = false
+  let readingProtocol = false
+  const doneReadingProtocol = pDefer()
+
+  const lp = lpStream({
+    sink: originalSink,
+    source: originalSource
+  }, {
+    ...options,
+    maxDataLength: MAX_PROTOCOL_LENGTH
+  })
+
+  stream.sink = async source => {
+    const { sink } = lp.unwrap()
+
+    await sink(async function * () {
+      let sentData = false
+
+      for await (const buf of source) {
+        // started reading before the source yielded, wait for protocol send
+        if (sendingProtocol) {
+          await doneSendingProtocol.promise
+        }
+
+        // writing before reading, send the protocol and the first chunk of data
+        if (!sentProtocol) {
+          sendingProtocol = true
+
+          options.log.trace('optimistic: write ["%s", "%s", data(%d)] in sink', PROTOCOL_ID, protocol, buf.byteLength)
+
+          const protocolString = `${protocol}\n`
+
+          // send protocols in first chunk of data written to transport
+          yield new Uint8ArrayList(
+            Uint8Array.from([19]), // length of PROTOCOL_ID plus newline
+            uint8ArrayFromString(`${PROTOCOL_ID}\n`),
+            varint.encode(protocolString.length),
+            uint8ArrayFromString(protocolString),
+            buf
+          ).subarray()
+
+          options.log.trace('optimistic: wrote ["%s", "%s", data(%d)] in sink', PROTOCOL_ID, protocol, buf.byteLength)
+
+          sentProtocol = true
+          sendingProtocol = false
+          doneSendingProtocol.resolve()
+
+          // read the negotiation response but don't block more sending
+          negotiate()
+            .catch(err => {
+              options.log.error('could not finish optimistic protocol negotiation of %s', protocol, err)
+            })
+        } else {
+          yield buf
+        }
+
+        sentData = true
       }
-    } else {
-      // We haven't gotten a valid ack, try the other protocols
-      log.trace('write "%s"', protocol)
-      await lp.write(uint8ArrayFromString(`${protocol}\n`), options)
+
+      // special case - the source passed to the sink has ended but we didn't
+      // negotiated the protocol yet so do it now
+      if (!sentData) {
+        await negotiate()
+      }
+    }())
+  }
+
+  async function negotiate (): Promise<void> {
+    if (negotiating) {
+      options.log.trace('optimistic: already negotiating %s stream', protocol)
+      await doneNegotiating.promise
+      return
     }
 
-    log.trace('reading protocol response')
-    response = await readString(lp, options)
-    log.trace('read "%s"', response)
+    negotiating = true
 
-    if (response === protocol) {
-      log.trace('selected "%s" after negotiation', response)
-      lp.unwrap()
+    try {
+      // we haven't sent the protocol yet, send it now
+      if (!sentProtocol) {
+        options.log.trace('optimistic: doing send protocol for %s stream', protocol)
+        await doSendProtocol()
+      }
+
+      // if we haven't read the protocol response yet, do it now
+      if (!readProtocol) {
+        options.log.trace('optimistic: doing read protocol for %s stream', protocol)
+        await doReadProtocol()
+      }
+    } finally {
+      negotiating = false
+      negotiated = true
+      doneNegotiating.resolve()
+    }
+  }
+
+  async function doSendProtocol (): Promise<void> {
+    if (sendingProtocol) {
+      await doneSendingProtocol.promise
+      return
+    }
+
+    sendingProtocol = true
 
-      return protocol
+    try {
+      options.log.trace('optimistic: write ["%s", "%s", data] in source', PROTOCOL_ID, protocol)
+      await lp.writeV([
+        uint8ArrayFromString(`${PROTOCOL_ID}\n`),
+        uint8ArrayFromString(`${protocol}\n`)
+      ])
+      options.log.trace('optimistic: wrote ["%s", "%s", data] in source', PROTOCOL_ID, protocol)
+    } finally {
+      sentProtocol = true
+      sendingProtocol = false
+      doneSendingProtocol.resolve()
     }
   }
 
-  throw new UnsupportedProtocolError(`Protocol selection failed - could not negotiate ${protocols}`)
+  async function doReadProtocol (): Promise<void> {
+    if (readingProtocol) {
+      await doneReadingProtocol.promise
+      return
+    }
+
+    readingProtocol = true
+
+    try {
+      options.log.trace('optimistic: reading multistream select header')
+      let response = await multistream.readString(lp, options)
+      options.log.trace('optimistic: read multistream select header "%s"', response)
+
+      if (response === PROTOCOL_ID) {
+        response = await multistream.readString(lp, options)
+      }
+
+      options.log.trace('optimistic: read protocol "%s", expecting "%s"', response, protocol)
+
+      if (response !== protocol) {
+        throw new UnsupportedProtocolError('protocol selection failed')
+      }
+    } finally {
+      readProtocol = true
+      readingProtocol = false
+      doneReadingProtocol.resolve()
+    }
+  }
+
+  stream.source = (async function * () {
+    // make sure we've done protocol negotiation before we read stream data
+    await negotiate()
+
+    options.log.trace('optimistic: reading data from "%s" stream', protocol)
+    yield * lp.unwrap().source
+  })()
+
+  if (stream.closeRead != null) {
+    const originalCloseRead = stream.closeRead.bind(stream)
+
+    stream.closeRead = async (opts) => {
+      // we need to read & write to negotiate the protocol so ensure we've done
+      // this before closing the readable end of the stream
+      if (!negotiated) {
+        await negotiate().catch(err => {
+          options.log.error('could not negotiate protocol before close read', err)
+        })
+      }
+
+      // protocol has been negotiated, ok to close the readable end
+      await originalCloseRead(opts)
+    }
+  }
+
+  if (stream.closeWrite != null) {
+    const originalCloseWrite = stream.closeWrite.bind(stream)
+
+    stream.closeWrite = async (opts) => {
+      // we need to read & write to negotiate the protocol so ensure we've done
+      // this before closing the writable end of the stream
+      if (!negotiated) {
+        await negotiate().catch(err => {
+          options.log.error('could not negotiate protocol before close write', err)
+        })
+      }
+
+      // protocol has been negotiated, ok to close the writable end
+      await originalCloseWrite(opts)
+    }
+  }
+
+  if (stream.close != null) {
+    const originalClose = stream.close.bind(stream)
+
+    stream.close = async (opts) => {
+      // if we are in the process of negotiation, let it finish before closing
+      // because we may have unsent early data
+      const tasks = []
+
+      if (sendingProtocol) {
+        tasks.push(doneSendingProtocol.promise)
+      }
+
+      if (readingProtocol) {
+        tasks.push(doneReadingProtocol.promise)
+      }
+
+      if (tasks.length > 0) {
+        // let the in-flight protocol negotiation finish gracefully
+        await raceSignal(
+          Promise.all(tasks),
+          opts?.signal
+        )
+      } else {
+        // no protocol negotiation attempt has occurred so don't start one
+        negotiated = true
+        negotiating = false
+        doneNegotiating.resolve()
+      }
+
+      // protocol has been negotiated, ok to close the writable end
+      await originalClose(opts)
+    }
+  }
+
+  return {
+    stream,
+    protocol
+  }
 }