Use websockets via async iterables, both client and server.
npm i it-ws
const connect = require('it-ws/client') // OR: require('it-ws').connect
const pipe = require('it-pipe')
const stream = connect(WS_URL)
await stream.connected() // Wait for websocket to be connected (optional)
pipe(source, stream, sink)
const createServer = require('it-ws/server')
const pipe = require('it-pipe')
const server = createServer(stream => {
//pipe the stream somewhere.
//eg, echo server
pipe(stream, stream)
})
await server.listen(PORT)
connect(url, { binary: boolean })
Create a websocket client connection. Set binary: true
to get a stream of arrayBuffers (on the browser). Defaults to true on node, but to strings on the browser. This may cause a problems if your application assumes binary.
For adding options to the Websocket instance, as websockets/ws/blob/master/doc/ws.md#new-websocketaddress-protocols-options, you can provide an object with the websocket
property into the connect options.
const stream = connect(url)
// stream is duplex and is both a `source` and `sink`.
// See this for more information:
// https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it
Create async iterable websocket servers.
createServer(options?, onConnection)
options
takes the same server options as ws module
onConnection(stream)
is called every time a connection is received.
One duplex service you may want to use this with is muxrpc
var ws = require('pull-ws')
var pull = require('pull-stream')
ws.createServer(function (stream) {
//pipe duplex style to your service.
pull(stream, service.createStream(), stream)
})
.listen(9999)
var stream = ws.connect('ws://localhost:9999')
pull(stream, client.createStream(), stream)
if the connection fails, the first read from the stream will be an error, otherwise, to get a handle of stream end/error pass a callback to connect.
ws.connect('ws://localhost:9999', function (err, stream) {
if(err) return handleError(err)
//stream is now ready
})
To run the server over TLS:
var tlsOpts = {
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
};
ws.createServer(tlsOpts, function (stream) {
//pipe duplex style to your service.
pull(stream, service.createStream(), stream)
})
.listen(9999)
To add client-authentication to the server, you can set verifyClient
.
Documentation here.
function verifyClient (info) {
return info.secure == true
}
ws.createServer({ verifyClient: verifyClient }, onStream)
if you have an http server that you also need to serve stuff
over, and want to use a single port, use the server
option.
var http = require('http')
var server = http.createServer(function(req, res){...}).listen(....)
ws.createServer({server: server}, function (stream) { ... })
these modules are used internally, to wrap a websocket. you probably won't need to touch these, but they are documented anyway.
turn a websocket into a duplex pull stream.
If provided, opts
is passed to pws.sink(socket, opts)
.
Websockets do not support half open mode. see allowHalfOpen option in net module
If you have a protocol that assumes halfOpen connections, but are using a networking protocol like websockets that does not support it, I suggest using pull-goodbye with your protocol.
The duplex stream will also contain a copy of the properties from
the http request that became the websocket. they are method
, url
,
headers
and upgrade
.
also exposed at: var duplex = require('pull-ws')
Create a pull-stream Sink
that will write data to the socket
.
opts
may be {closeOnEnd: true, onClose: onClose}
.
onClose
will be called when the sink ends. If closeOnEnd=false
the stream will not close, it will just stop emitting data.
(by default closeOnEnd
is true)
If opts
is a function, then onClose = opts; opts.closeOnEnd = true
.
var pull = require('pull-stream');
var wsSink = require('pull-ws');
// connect to the echo endpoint for test/server.js
var socket = new WebSocket('wss://echo.websocket.org');
// write values to the socket
pull(
pull.infinite(function() {
return 'hello @ ' + Date.now()
}),
// throttle so it doesn't go nuts
pull.asyncMap(function(value, cb) {
setTimeout(function() {
cb(null, value);
}, 100);
}),
wsSink(socket)
);
socket.addEventListener('message', function(evt) {
console.log('received: ' + evt.data);
});
also exposed at require('pull-ws').sink
Create a pull-stream Source
that will read data from the socket
.
var pull = require('pull-stream');
// we just need the source, so cherrypick
var wsSource = require('pull-ws/source');
pull(
// connect to the test/server.js endpoint
wsSource(new WebSocket('ws://localhost:3000/read')),
pull.log()
);
also exposed at require('pull-ws').source
MIT