# pull-ws

> Simple pull-streams for websocket client connections

Latest version **3.3.2** (published 2019-01-18) · ISC license · 0 weekly downloads

## Install

```sh
npm install pull-ws
pnpm add pull-ws
yarn add pull-ws
bun add pull-ws
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.3.2 |
| Published | 2019-01-18 |
| First published | 2014-10-24 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 26.5 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 24 |
| Author | Damon Oehlman |
| Maintainers | damonoehlman, dominictarr |
| Keywords | pull-stream, websocket, ws |

## Links

- npm: https://www.npmjs.com/package/pull-ws
- Repository: https://github.com/DamonOehlman/pull-ws
- Issues: https://github.com/DamonOehlman/pull-ws/issues
- npm.io page: https://npm.io/package/pull-ws

## Dependencies (3)

- [ws](https://npm.io/package/ws.md) ^1.1.0
- [safe-buffer](https://npm.io/package/safe-buffer.md) ^5.1.1
- [relative-url](https://npm.io/package/relative-url.md) ^1.0.2

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 3.3.2 (latest) — 2019-01-18
- 3.3.1 — 2018-04-09
- 3.3.0 — 2017-09-19
- 3.2.10 — 2017-09-11
- 3.2.9 — 2017-04-18
- 3.2.8 — 2016-10-12
- 3.2.7 — 2016-10-09
- 3.2.6 — 2016-09-24
- 3.2.5 — 2016-09-21
- 3.2.4 — 2016-08-31
- 3.2.3 — 2016-08-01
- 3.2.2 — 2016-07-30
- 3.2.0 — 2016-07-29
- 3.1.3 — 2016-07-21
- 3.1.2 — 2016-07-15
- … 12 more at https://npm.io/package/pull-ws/versions

## README

# pull-ws

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

[![NPM](https://nodei.co/npm/pull-ws.png)](https://nodei.co/npm/pull-ws/)

[![unstable](https://img.shields.io/badge/stability-unstable-yellowgreen.svg)](https://github.com/dominictarr/stability#unstable) [![Build Status](https://img.shields.io/travis/DamonOehlman/pull-ws.svg?branch=master)](https://travis-ci.org/DamonOehlman/pull-ws) 

## example - client
``` js
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

``` js
var createServer = require('pull-ws/server')
createServer(function (stream) {
  //pipe the stream somewhere.
  //eg, echo server
  pull(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.

``` js
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](https://github.com/websockets/ws/blob/master/doc/ws.md#new-wsserveroptions-callback)


#### example

one duplex service you may want to use this with is [muxrpc](https://github.com/dominictarr/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 `verifyClient`.
[Documentation here](https://github.com/websockets/ws/blob/master/doc/ws.md#optionsverifyclient).

```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 `server` option.

``` js
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](
http://nodejs.org/api/net.html#net_net_createserver_options_connectionlistener)

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](https://github.com/dominictarr/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`.

```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 `require('pull-ws').sink`

### `require('pull-ws/source')(socket)`

Create a pull-stream `Source` 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 `require('pull-ws').source`

# LICENSE

MIT

---
_Source: https://npm.io/package/pull-ws · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._