https://github.com/porsager/pws

🤝 Persistent Web Sockets
https://github.com/porsager/pws

Last synced: 16 days ago
JSON representation

🤝 Persistent Web Sockets

• Host: GitHub
• URL: https://github.com/porsager/pws
• Owner: porsager
• License: wtfpl
• Created: 2017-02-06T01:02:44.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2024-06-19T16:47:45.000Z (5 months ago)
• Last Synced: 2024-10-13T00:35:24.396Z (about 1 month ago)
• Language: JavaScript
• Homepage:
• Size: 101 KB
• Stars: 99
• Watchers: 7
• Forks: 10
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
[![NPM version](https://img.shields.io/npm/v/pws.svg)](https://www.npmjs.com/package/pws)

[![Size](https://img.shields.io/bundlephobia/minzip/pws.svg)]()

[![license](https://img.shields.io/github/license/porsager/pws.svg)]()

# 🤝 PWS - PersistentWebSocket

PWS gives you a reconnecting websocket to use in the browser or in node simply by switching out `new WebSocket` with `new PersistentWebSocket`.

It behaves the same as a regular browser WebSocket, but reconnects automatically with a simple backoff algorithm if the connection closes.

## Getting started

```js

const pws = new PersistentWebSocket(url)

// Called every time a connection is established

pws.onopen = () => pws.send('Hello')

// Echo messages received

pws.onmessage = event => pws.send('You said: ' + event.data)

```

More details at https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket

## Using in node

You can also use PWS with the nodejs WebSocket library [ws](https://github.com/websockets/ws)

```

const WebSocket = require('ws')

    , Pws = require('pws')

const pws = Pws(url, WebSocket)

// as in the browser...

```

More details at https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketaddress-protocols-options

### Heartbeat

To ensure a persistent connection it's necessary to send messages at regular intervals from the server to keep the connection alive. The WebSocket protocol only implements a ping to be sent from the server, but not in the other direction. This can leave the client in a half open state where it thinks it's connected, but doesn't receive messages from the server.

To prevent this state PWS let's you set a specific timeout after which to force a reconnection if you did not receive any messages from the server.

```js

new PersistentWebSocket(url, {

  pingTimeout: 30 * 1000 // Reconnect if no message received in 30s.

})

```

### Backoff algorithm

The backoff algorithm is inspired by primus and  http://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html, and stops at a maximum reconnection timeout of 5 minutes.

### Reconnect on browser `online`

PWS will also reconnect on the browsers `online` event, irregardless of the current timeout for the next reconnect, to ensure a connection is regained as fast as possible.