it-ws
Use websockets via async iterables, both client and server.
Install
npm i it-ws
Usage
Example - client
const connect = require('it-ws/client')
const { pipeline } = require('streaming-iterables')
const stream = connect(WS_URL)
pipeline(() => source, stream.sink)
pipeline(() => stream.source, sink)
Example - server
const createServer = require('it-ws/server')
const server = createServer(stream => {
pipeline(() => stream.source, stream.sink)
})
await server.listen(PORT)
API
connect = require('it-ws/client')
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.
const stream = connect(url)
createServer = require('it-ws/server')
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.
TODO convert the following docs:
Example
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) {
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)
})
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) {
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)
use with an http server
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) { ... })
core, websocket wrapping functions
these modules are used internally, to wrap a websocket.
you probably won't need to touch these,
but they are documented anyway.
require('pull-ws/duplex')(socket, opts?)
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')
require('pull-ws/sink')(socket, opts?)
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');
var socket = new WebSocket('wss://echo.websocket.org');
pull(
pull.infinite(function() {
return 'hello @ ' + Date.now()
}),
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
require('pull-ws/source')(socket)
Create a pull-stream Source
that will read data from the socket
.
var pull = require('pull-stream');
var wsSource = require('pull-ws/source');
pull(
wsSource(new WebSocket('ws://localhost:3000/read')),
pull.log()
);
also exposed at require('pull-ws').source
License
MIT