Protomux

Protomux multiplexes multiple message-oriented subprotocols over one framed stream. It is typically layered on top of NoiseSecretStream and uses compact-encoding for message schemas. For source and releases, see the Protomux repository.

Install

npm i protomux

Quickstart

import Protomux from 'protomux'
import cenc from 'compact-encoding'

const mux = new Protomux(aFramedEncryptedStream)

const channel = mux.createChannel({
  protocol: 'chat',
  onopen() {
    console.log('chat channel opened')
  }
})

const message = channel.addMessage({
  encoding: cenc.string,
  onmessage(text) {
    console.log(text)
  }
})

channel.open()
message.send('hello')

API Reference

Constructor and mux helpers

mux = new Protomux(stream, [options])

src

Make a new instance. stream should be a framed stream, preserving the messages written.

{
  // Called when the muxer wants to allocate a message that is written.
  // Defaults to the stream's own alloc method when it has one, otherwise Buffer.allocUnsafe.
  alloc (size) {}
}

mux = Protomux.from(stream | muxer, [options])

src

Helper to accept either an existing muxer instance or a stream (which creates a new one).

• Returns: Protomux — The existing or newly created Protomux instance.

const mux = Protomux.from(someStream)

Protomux.isProtomux(mux)

src

Returns true when value looks like a Protomux instance.

• Returns: boolean — true when mux is a Protomux instance.

Protomux.isProtomux(mux) // true
Protomux.isProtomux({})  // false

mux.cork()

src

Same as channel.cork but on the muxer instance.

• Returns: void

mux.cork()
channelA.messages[0].send('hello')
channelB.messages[0].send('world')
mux.uncork() // sends both as one frame

mux.uncork()

src

Same as channel.uncork but on the muxer instance.

• Returns: void

mux.cork()
msg.send('hello')
mux.uncork()

mux.isIdle()

src

Convenience method that returns true when no channels are open and no closed channel is still awaiting the remote's acknowledgement.

• Returns: boolean — true when the muxer has no open channels and none awaiting a remote close acknowledgement.

if (mux.isIdle()) console.log('no open channels')

for (const channel of muxer) { ... }

The muxer instance is iterable, so you can iterate over all the channels.

Pairing and channel discovery

mux.pair({ protocol, id }, callback)

src

Register a callback to be called everytime a new channel is requested.

• Returns: void

mux.pair({ protocol: 'my-protocol' }, async (id) => {
  const channel = mux.createChannel({ protocol: 'my-protocol' })
  channel.open()
})

mux.unpair({ protocol, id })

src

Unregisters the pair callback.

• Returns: void

mux.unpair({ protocol: 'my-protocol' })

mux.opened({ protocol, id })

src

Boolean that indicates if the channel is opened.

• Returns: boolean — true when one or more matching channels are open.

if (mux.opened({ protocol: 'my-protocol' })) {
  console.log('already open')
}

mux.getLastChannel(options)

src

Returns the channel that most recently opened. Returns null once that channel closes, even if older channels with the same protocol and id are still open.

• Returns: Channel\|null — The most recently opened matching channel, or null.

const ch = mux.getLastChannel({ protocol: 'my-protocol' })

Creating channels

mux.createChannel(opts)

src

Add a new protocol channel.

• Returns: Channel\|null — The new channel, or null if it cannot be opened.

Mux properties

mux.stream

src

The framed transport stream backing this mux.

• Returns: object

mux.drained

src

The current writable backpressure state from the underlying stream.

• Returns: boolean

Channel lifecycle

channel.open([handshake])

src

Open the channel.

• Returns: void

const channel = mux.createChannel({ protocol: 'my-protocol' })
channel.open()

channel.fullyOpened()

src

Resolves to true when the channel fully opens or false if it closes first.

• Returns: Promise<boolean>

const opened = await channel.fullyOpened()
if (opened) console.log('channel is open')

channel.fullyClosed()

src

Resolves once the channel has been destroyed and all pending async handlers have finished.

• Returns: Promise<void>

await channel.fullyClosed()
console.log('channel destroyed')

channel.close()

src

Closes the protocol channel.

• Returns: void

channel.close()

channel.cork()

src

Corking the protocol channel, makes it buffer messages and send them all in a batch when it uncorks.

• Returns: void

channel.cork()
one.send('hello')
two.send(true)
channel.uncork() // sends both as a single batch

channel.uncork()

src

Uncork and send the batch.

• Returns: void

channel.cork()
one.send('hello')
channel.uncork()

Registering and sending messages

channel.addMessage(opts)

src

Add/register a message type for a certain encoding. Options include:

• Returns: object — Message object with a send(data) method for sending encoded messages.

m.send(data)

Send a message.

m.encoding

The encoding for this message.

m.onmessage

Function that is called when a message arrives.

Channel properties

channel.userData

src

• Returns: The arbitrary metadata value passed to mux.createChannel(...).

channel.protocol

src

• Returns: The channel protocol name.

channel.aliases

src

• Returns: The list of alternate protocol names registered for this channel family.

channel.id

src

• Returns: The optional binary identifier distinguishing this channel family.

channel.handshake

src

• Returns: The decoded handshake payload after the channel fully opens, or null when no handshake encoder was configured.

channel.messages

src

• Returns: The array of registered message descriptors in type order.

channel.opened

src

channel.closed

src

• Returns: true after either side closes the channel.

channel.destroyed

src

• Returns: true after the close lifecycle and pending handlers have fully drained.

channel.drained

src

true when the underlying stream's write buffer is empty.

• Returns: boolean

Lifecycle callbacks

channel.onopen

src

• Returns: Called when the channel opens. handshake is the decoded open payload or null, and channel is the channel instance.

channel.onclose

src

• Returns: Called when the channel closes. isRemote is true when the remote side initiated the close, and channel is the channel instance.

channel.ondestroy

src

• Returns: Called when the channel is destroyed. channel is the destroyed channel instance.

channel.ondrain

src

• Returns: Called when the channel's underlying mux becomes writable again. channel is that channel instance.

Types

ProtomuxOptions

Options for allocating buffers in a Protomux instance.

CreateChannelOptions

Options for creating a protocol channel.

AddMessageOptions

Options for registering a message type on a channel.

ChannelKey

Protocol + id selector used by pair/unpair/opened/getLastChannel.

See also

• NoiseSecretStream—the encrypted framed stream most commonly used underneath Protomux.
• compact-encoding—the schema toolkit Protomux uses for handshakes and message payloads.
• Hyperswarm—common peer-transport entry point before you layer on NoiseSecretStream and Protomux.
• Upstream Protomux repository—source, releases, and implementation details.