libp2p-mplex-curltech
v0.10.3
Published
JavaScript implementation of https://github.com/libp2p/mplex
Downloads
13
Maintainers
Readme
js-libp2p-mplex
JavaScript implementation of mplex.
Lead Maintainer
Install
npm install libp2p-mplex
Usage
const Mplex = require('libp2p-mplex')
const pipe = require('it-pipe')
const muxer = new Mplex({
onStream: stream => { // Receive a duplex stream from the remote
// ...receive data from the remote and optionally send data back
},
onStreamEnd: stream => {
// ...handle any tracking you may need of stream closures
}
})
pipe(conn, muxer, conn) // conn is duplex connection to another peer
const stream = muxer.newStream() // Create a new duplex stream to the remote
// Use the duplex stream to send some data to the remote...
pipe([1, 2, 3], stream)
API
const muxer = new Mplex([options])
Create a new duplex stream that can be piped together with a connection in order to allow multiplexed communications.
e.g.
const Mplex = require('libp2p-mplex')
const pipe = require('it-pipe')
// Create a duplex muxer
const muxer = new Mplex()
// Use the muxer in a pipeline
pipe(conn, muxer, conn) // conn is duplex connection to another peer
options
is an optional Object
that may have the following properties:
onStream
- A function called when receiving a new stream from the remote. e.g.
Note: The// Receive a new stream on the muxed connection const onStream = stream => { // Read from this stream and write back to it (echo server) pipe( stream, source => (async function * () { for await (const data of source) yield data })(), stream ) } const muxer = new Mplex({ onStream }) // ...
onStream
function can be passed in place of theoptions
object. i.e.new Mplex(stream => { /* ... */ })
onStreamEnd
- A function called when a stream ends// Receive a notification when a stream ends const onStreamEnd = stream => { // Manage any tracking changes, etc } const muxer = new Mplex({ onStreamEnd }) // ...
signal
- AnAbortSignal
which can be used to abort the muxer, including all of it's multiplexed connections. e.g.const controller = new AbortController() const muxer = new Mplex({ signal: controller.signal }) pipe(conn, muxer, conn) controller.abort()
maxMsgSize
- The maximum size in bytes the data field of multiplexed messages may contain (default 1MB)
muxer.onStream
Use this property as an alternative to passing onStream
as an option to the Mplex
constructor.
muxer.onStreamEnd
Use this property as an alternative to passing onStreamEnd
as an option to the Mplex
constructor.
muxer.streams
Returns an Array
of streams that are currently open. Closed streams will not be returned.
const stream = muxer.newStream([options])
Initiate a new stream with the remote. Returns a duplex stream.
e.g.
// Create a new stream on the muxed connection
const stream = muxer.newStream()
// Use this new stream like any other duplex stream:
pipe([1, 2, 3], stream, consume)
In addition to sink
and source
properties, this stream also has the following API, that will normally not be used by stream consumers.
stream.close()
Closes the stream for reading. If iterating over the source of this stream in a for await of
loop, it will return (exit the loop) after any buffered data has been consumed.
This function is called automatically by the muxer when it receives a CLOSE
message from the remote.
The source will return normally, the sink will continue to consume.
stream.abort([err])
Closes the stream for reading and writing. This should be called when a local error has occurred.
Note, if called without an error any buffered data in the source can still be consumed and the stream will end normally.
This will cause a RESET
message to be sent to the remote, unless the sink has already ended.
The sink will return and the source will throw if an error is passed or return normally if not.
stream.reset()
Closes the stream immediately for reading and writing. This should be called when a remote error has occurred.
This function is called automatically by the muxer when it receives a RESET
message from the remote.
The sink will return and the source will throw.
stream.timeline
Returns an object
with close
and open
times of the stream.
stream.id
Returns a string
with an identifier unique to this muxer. Identifiers are not unique across muxers.
Contribute
The libp2p implementation in JavaScript is a work in progress. As such, there are a few things you can do right now to help out:
- Go through the modules and check out existing issues. This is especially useful for modules in active development. Some knowledge of IPFS/libp2p may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically.
- Perform code reviews. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
- Add tests. There can never be enough tests.
License
MIT © Protocol Labs