y-websocket 🎩

WebSocket Provider for Yjs

The Websocket Provider implements a classical client server model. Clients connect to a single endpoint over Websocket. The server distributes awareness information and document updates among clients.

The Websocket Provider is a solid choice if you want a central source that handles authentication and authorization. Websockets also send header information and cookies, so you can use existing authentication mechanisms with this server.

Supports cross-tab communication. When you open the same document in the same browser, changes on the document are exchanged via cross-tab communication (Broadcast Channel and localStorage as fallback).
Supports exchange of awareness information (e.g. cursors).

Quick Start

Client Code:

import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc)

wsProvider.on('status', event => {
  console.log(event.status) // logs "connected" or "disconnected"
})

Client Code in Node.js

The WebSocket provider requires a WebSocket object to create connection to a server. You can polyfill WebSocket support in Node.js using the ws package.

const wsProvider = new WebsocketProvider('ws://localhost:1234', 'my-roomname', doc, { WebSocketPolyfill: require('ws') })

Start a Websocket Server:

PORT=1234 npx y-websocket-server

Since npm symlinks the y-websocket-server executable from your local ./node_modules/.bin folder, you can simply run npx. The PORT environment variable already defaults to 1234.

Websocket Server with Persistence

Persist document updates in a LevelDB database.

See LevelDB Persistence for more info.

PORT=1234 YPERSISTENCE=./dbDir node ./node_modules/y-websocket/bin/server.js

Websocket Server with HTTP callback

Send a debounced callback to an HTTP server (POST) on document update.

Can take the following ENV variables:

CALLBACK_URL : Callback server URL
CALLBACK_DEBOUNCE_WAIT : Debounce time between callbacks (in ms). Defaults to 2000 ms
CALLBACK_DEBOUNCE_MAXWAIT : Maximum time to wait before callback. Defaults to 10 seconds
CALLBACK_TIMEOUT : Timeout for the HTTP call. Defaults to 5 seconds
CALLBACK_OBJECTS : JSON of shared objects to get data ('{"SHARED_OBJECT_NAME":"SHARED_OBJECT_TYPE}')

CALLBACK_URL=http://localhost:3000/ CALLBACK_OBJECTS='{"prosemirror":"XmlFragment"}' npm start

This sends a debounced callback to localhost:3000 2 seconds after receiving an update (default DEBOUNCE_WAIT) with the data of an XmlFragment named "prosemirror" in the body.

Scaling

These are mere suggestions how you could scale your server environment.

Option 1: Websocket servers communicate with each other via a PubSub server. A room is represented by a PubSub channel. The downside of this approach is that the same shared document may be handled by many servers. But the upside is that this approach is fault tolerant, does not have a single point of failure, and is fit for route balancing.

Option 2: Sharding with consistent hashing. Each document is handled by a unique server. This pattern requires an entity, like etcd, that performs regular health checks and manages servers. Based on the list of available servers (which is managed by etcd) a proxy calculates which server is responsible for each requested document. The disadvantage of this approach is that load distribution may not be fair. Still, this approach may be the preferred solution if you want to store the shared document in a database - e.g. for indexing.

AdventureBeard / y-websocket