Package Exports

pull-ws
pull-ws/client
pull-ws/server

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (pull-ws) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

pull-ws

A simple (but effective) implementation of a pull-stream Source and Sink that is compatible both with native browser WebSockets and ws created clients.

Reference

`pws(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.

`pws.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 ws = 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);
  }),
  ws.sink(socket)
);

socket.addEventListener('message', function(evt) {
  console.log('received: ' + evt.data);
});

`pws.source(socket)`

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 ws = require('pull-ws/source');

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

pull-ws-server

create pull stream websockets, servers, and clients.

example

one duplex service you may want to use this with is muxrpc

var ws = require('pull-ws-server')
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.

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)
})
.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) { ... })