pull-ws

Use websockets via pull-stream interface. both client and server.

example - client

varconnect=require('pull-ws/client')// OR: require('pull-ws').connectconnect(WS_URL,function(err,stream){if(err)throwerr//handle errpull(source,stream,sink)})

example - server

varcreateServer=require('pull-ws/server')createServer(function(stream){//pipe the stream somewhere.//eg, echo serverpull(stream,stream)}).listen(PORT)

api

connect = require('pull-ws/client')

connect(url, cb | {binary: boolean, onConnect: cb})

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.

connect(url,function(err,stream){
...
})

createServer = require('pull-ws/server')

create pull stream websocket servers. the servers take a lot more options than clients.

createServer(opts?, onConnection)

onConnect(stream) 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

varws=require('pull-ws')varpull=require('pull-stream')ws.createServer(function(stream){//pipe duplex style to your service.pull(stream,service.createStream(),stream)}).listen(9999)varstream=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)returnhandleError(err)//stream is now ready})

To run the server over TLS:

vartlsOpts={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.

functionverifyClient(info){returninfo.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.

varhttp=require('http')varserver=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.

varpull=require('pull-stream');varwsSink=require('pull-ws');// connect to the echo endpoint for test/server.jsvarsocket=newWebSocket('wss://echo.websocket.org');// write values to the socketpull(pull.infinite(function(){return'hello @ '+Date.now()}),// throttle so it doesn't go nutspull.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.

varpull=require('pull-stream');// we just need the source, so cherrypickvarwsSource=require('pull-ws/source');pull(// connect to the test/server.js endpointwsSource(newWebSocket('ws://localhost:3000/read')),pull.log());

also exposed at require('pull-ws').source

LICENSE

MIT