534c417ed0 | ||
---|---|---|
.github/workflows | ||
.gitignore | ||
LICENSE | ||
README.md | ||
index.js | ||
messages.js | ||
package.json | ||
test.js |
README.md
protomux
Multiplex multiple message oriented protocols over a stream
npm install protomux
Usage
const Protomux = require('protomux')
const c = require('compact-encoding')
// By framed stream, it has be a stream that preserves the messages, ie something that length prefixes
// like @hyperswarm/secret-stream
const mux = new Protomux(aStreamThatFrames)
// Now add some protocols
const cool = mux.addProtocol({
name: 'cool-protocol',
version: {
major: 1,
minor: 0
},
// an array of compact encoders, each encoding/decoding the messages sent
messages: [
c.string,
c.bool
],
onremoteopen () {
console.log('the other side opened this protocol!')
},
onemoteclose () {
console.log('the other side closed this protocol!')
},
onmessage (type, message) {
console.log('the other side sent a message', type, message)
}
})
// And send some messages
cool.send(0, 'a string')
cool.send(1, true)
API
mux = new Protomux(stream, [options])
Make a new instance. stream
should be a framed stream, preserving the messages written.
Options include:
{
// Called when the muxer wants to allocate a message that is written, defaults to Buffer.allocUnsafe.
alloc (size) {},
// Hook that is called when an unknown protocol is received. Should return true/false.
async onacceptprotocol ({ name, version }) {}
// How many protocols can be remote open, that we haven't opened yet?
// Only used if you don't provide an accept hook.
backlog: 128
}
mux = Protomux.from(stream | muxer, [options])
Helper to accept either an existing muxer instance or a stream (which creates a new one).
const p = mux.addProtocol(opts)
Add a new protocol.
Options include:
{
// Used to match the protocol
name: 'name of the protocol',
// You can have multiple versions of the same protocol on the same stream.
// Protocols are matched using the major version only.
version: {
major: 0,
minor: 0
},
// Array of the message types you want to send/receive. Should be compact-encoders
messages: [
...
],
// Called when the remote side adds this protocol.
// Errors here are caught and forwared to stream.destroy
async onremoteopen () {},
// Called when the remote side closes or rejects this protocol.
// Errors here are caught and forwared to stream.destroy
async onremoteclose () {},
// Called when the remote sends a message
// Errors here are caught and forwared to stream.destroy
async onmessage (type, message) {}
}
Each of the functions can also be set directly on the instance with the same name.
p.close()
Closes the protocol
p.send(type, message)
Send a message, type is the offset into the messages array.
p.cork()
Corking the protocol, makes it buffer messages and send them all in a batch when it uncorks.
p.uncork()
Uncork and send the batch.
mux.cork()
Same as p.cork
but on the muxer instance.
mux.uncork()
Same as p.uncork
but on the muxer instance.
License
MIT