Simple pull-streams for websocket client connections
npm install pull-wsUse websockets via pull-stream interface. both client and server.
 
js
var connect = require('pull-ws/client')
// OR: require('pull-ws').connectconnect(WS_URL, function (err, stream) {
if(err) throw err //handle err
pull(source, stream, sink)
})
`
example - server
js
var createServer = require('pull-ws/server')
createServer(function (stream) {
//pipe the stream somewhere.
//eg, echo server
pull(stream, stream)
}).listen(PORT)
`api
$3
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.
else, just provide the callback.
js
connect(url, function (err, stream) {
...
})
`
$3
create pull stream websocket servers.
the servers take a lot more options than clients.
is called every time a connection is received.opts takes the same server options as ws module
#### example
one duplex service you may want to use this with is muxrpc
` js
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.
js
ws.connect('ws://localhost:9999', function (err, stream) {
if(err) return handleError(err)
//stream is now ready
})`To run the server over TLS:
js
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
.
Documentation here.`js
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
option.` js
var http = require('http')
var server = http.createServer(function(req, res){...}).listen(....)
ws.createServer({server: server}, function (stream) { ... })`$3
these modules are used internally, to wrap a websocket.
you probably won't need to touch these,
but they are documented anyway.
$3
turn a websocket into a duplex pull stream.
If provided,
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')$3
Create a pull-stream
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 is true)If
opts is a function, then onClose = opts; opts.closeOnEnd = true.`js
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
$3
Create a pull-stream
that will read data from the socket.`js
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
MIT