Skip to content
Simple pull-streams for websocket client and server connections
Branch: master
Clone or download
Latest commit 9c1a9cf Jan 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Use the echo server for the write example Oct 24, 2014
.bithoundrc bithound ignore rules Mar 24, 2015
.gitignore Initial commit Oct 24, 2014
.travis.yml fix: better buffer handling Sep 4, 2017
LICENSE Use MIT Jun 26, 2016 fix readme example Jan 18, 2019
client.js pass the whole duplex stream to the onConnect callback instead of jus… Sep 24, 2016
duplex.js require('pull-ws/client') without including `http` Jul 27, 2016
index.js fix module exports Jul 31, 2016
package.json 3.3.2 Jan 18, 2019
ready.js handle case where stream errors instead of opening Nov 11, 2014
server.js some module systems don't put a closure around everything, and choke … Apr 9, 2018
sink.js Use setImmediate if available Aug 30, 2016
web-socket.js do not load ws module when in the browser Jul 21, 2016
ws-url.js use relative-url Jun 1, 2016


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 == 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://');

// write values to the socket
  pull.infinite(function() {
    return 'hello @ ' +
  // 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: ' +;

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



You can’t perform that action at this time.