js-multistream-select

JavaScript implementation of multistream-select with support for lazy select.

Table of Contents

- Background
- What is multistream-select?
- Select a protocol flow
- Install
- Usage
- Dialer
- Listener
- API
- new Dialer(duplex)
- Parameters
- Returns
- Examples
- [dialer.select(protocols, [options])](#dialerselectprotocols-options)
- Parameters
- Returns
- Examples
- [dialer.ls([options])](#dialerlsoptions)
- Parameters
- Returns
- Examples
- new Listener(duplex)
- Parameters
- Returns
- Examples
- [listener.handle(protocols, [options])](#listenerhandleprotocols-options)
- Parameters
- Returns
- Examples
- License
- Contribution

Background

$3

TLDR; multistream-select is protocol multiplexing per connection/stream. Full spec here

#### Select a protocol flow

The caller will send "interactive" messages, expecting for some acknowledgement from the callee, which will "select" the handler for the desired and supported protocol:

``console
< /multistream-select/0.3.0 # i speak multistream-select/0.3.0
> /multistream-select/0.3.0 # ok, let's speak multistream-select/0.3.0
> /ipfs-dht/0.2.3 # i want to speak ipfs-dht/0.2.3
< na # ipfs-dht/0.2.3 is not available
> /ipfs-dht/0.1.9 # What about ipfs-dht/0.1.9 ?
< /ipfs-dht/0.1.9 # ok let's speak ipfs-dht/0.1.9 -- in a sense acts as an ACK
>
>
>
`

This mode also packs a ls option, so that the callee can list the protocols it currently supports

Install

`sh
npm i @libp2p/multistream-select
`

Usage

`js
import { Dialer, Listener } from '@libp2p/multistream-select'
// You can now use
// Dialer - actively select a protocol with a remote
// Listener - handle a protocol with a remote
`

$3

`js
import { pipe } from 'it-pipe'
import { Dialer } from '@libp2p/multistream-select'
import { Mplex } from '@libp2p/mplex'

const muxer = new Mplex()
const muxedStream = muxer.newStream()

const mss = new Dialer(muxedStream)

// mss.select(protocol(s))
// Select from one of the passed protocols (in priority order)
// Returns selected stream and protocol
const { stream: dhtStream, protocol } = await mss.select([
// This might just be different versions of DHT, but could be different impls
'/ipfs-dht/2.0.0', // Most of the time this will probably just be one item.
'/ipfs-dht/1.0.0'
])

// Typically this stream will be passed back to the caller of libp2p.dialProtocol
//
// ...it might then do something like this:
// try {
// await pipe(
// [uint8ArrayFromString('Some DHT data')]
// dhtStream,
// async source => {
// for await (const chunk of source)
// // DHT response data
// }
// )
// } catch (err) {
// // Error in stream
// }
`

$3

`js
import { pipe } from 'it-pipe'
import { Listener } from '@libp2p/multistream-select'
import { Mplex } from '@libp2p/mplex'

const muxer = new Mplex({
async onStream (muxedStream) {
const mss = new Listener(muxedStream)

// mss.handle(handledProtocols)
// Returns selected stream and protocol
const { stream, protocol } = await mss.handle([
'/ipfs-dht/1.0.0',
'/ipfs-bitswap/1.0.0'
])

// Typically here we'd call the handler function that was registered in
// libp2p for the given protocol:
// e.g. handlers[protocol].handler(stream)
//
// If protocol was /ipfs-dht/1.0.0 it might do something like this:
// try {
// await pipe(
// dhtStream,
// source => (async function * () {
// for await (const chunk of source)
// // Incoming DHT data -> process and yield to respond
// })(),
// dhtStream
// )
// } catch (err) {
// // Error in stream
// }
}
})
`

API

$3

Create a new multistream select "dialer" instance which can be used to negotiate a protocol to use, list all available protocols the remote supports, or do both.

#### Parameters

* duplex (Object) - A duplex iterable stream to dial on.

#### Returns

A new multistream select dialer instance.

#### Examples

`js
const dialer = new MSS.Dialer(duplex)
`

$3

Negotiate a protocol to use from a list of protocols.

#### Parameters

* protocols (String[]/String) - A list of protocols (or single protocol) to negotiate with. Protocols are attempted in order until a match is made.
* options ({ signal: AbortSignal, lazy: boolean }) - an options object containing an AbortSignal and lazy flag. If lazy is set to try, and only 1 protocol is available for selection then the dialer will optimistically assume protocol selection and start writing data without waiting for the protocol selection response.

#### Returns

Promise<{ stream