Simple pull-streams for websocket client connections

Downloads in past


23103.3.25 years ago9 years agoMinified + gzip package size for pull-ws in KB


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

example - client

var connect = require('pull-ws/client')
// OR: require('pull-ws').connect

connect(WS_URL, function (err, stream) {
  if(err) throw err //handle err
  pull(source, stream, sink)

example - server

var createServer = require('pull-ws/server')
createServer(function (stream) {
  //pipe the stream somewhere.
  //eg, echo server
  pull(stream, stream)


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


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)

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)

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');

// connect to the echo endpoint for test/server.js
var socket = new WebSocket('wss://echo.websocket.org');

// write values to the socket
  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);

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');

  // connect to the test/server.js endpoint
  wsSource(new WebSocket('ws://localhost:3000/read')),

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