Y Websocket Server

https://github.com/yjs/y-websocket-server
Admin
A simple backend server for y-websocket that handles authentication, authorization, and offers...
Tokens:4,256
Snippets:45
Trust Score:8.1
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start a y-websocket server

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Start a basic y-websocket server using npx. Environment variables HOST and PORT can be set.

```sh
HOST=localhost PORT=1234 npx y-websocket
```

--------------------------------

### setupWSConnection - WebSocket Connection Handler

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Integrate the setupWSConnection function into an existing HTTP server to manage WebSocket connections, document synchronization, and awareness protocol. Includes basic HTTP server setup and WebSocket upgrade handling with authentication.

```javascript
import http from 'http'
import WebSocket from 'ws'
import { setupWSConnection } from '@y/websocket-server/utils'

const wss = new WebSocket.Server({ noServer: true })
const server = http.createServer((request, response) => {
  response.writeHead(200, { 'Content-Type': 'text/plain' })
  response.end('WebSocket server is running')
})

// Handle WebSocket connections
wss.on('connection', setupWSConnection)

// Handle HTTP upgrade to WebSocket with authentication
server.on('upgrade', (request, socket, head) => {
  // Implement authentication here
  const url = new URL(request.url, `http://${request.headers.host}`)
  const token = url.searchParams.get('token')

  if (!isValidToken(token)) {
    socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
    socket.destroy()
    return
  }

  // Upgrade connection after authentication
  wss.handleUpgrade(request, socket, head, ws => {
    wss.emit('connection', ws, request)
  })
})

server.listen(1234, 'localhost', () => {
  console.log('Server running at ws://localhost:1234')
})

function isValidToken(token) {
  // Implement your token validation logic
  return token === 'valid-token'
}
```

--------------------------------

### Install y-websocket-server

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Install the y-websocket-server package using npm.

```sh
npm i @y/websocket-server
```

--------------------------------

### Start Server with HTTP Callback

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Start the y-websocket server with an HTTP callback URL for document updates. Environment variables configure callback behavior.

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

--------------------------------

### Start y-websocket Server

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Run the y-websocket server using npx. Environment variables can be used to configure host, port, and HTTP callbacks.

```bash
npx y-websocket
```

```bash
HOST=localhost PORT=1234 npx y-websocket
```

```bash
CALLBACK_URL=http://localhost:3000/ CALLBACK_OBJECTS='{"prosemirror":"XmlFragment"}' npx y-websocket
```

--------------------------------

### Docker Compose Example for y-websocket-server

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Configure and run the y-websocket-server using Docker Compose, specifying ports, host, and garbage collection settings.

```yaml
version: '3.8'
services:
  y-websocket:
    build: .
    ports:
      - "1234:1234"
    environment:
      - PORT=1234
      - HOST=::
      - GC=true
    restart: unless-stopped
```

--------------------------------

### setupWSConnection with Custom Options

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Customize the setupWSConnection behavior by providing options for document naming and garbage collection. Document names can be extracted from the URL path, and garbage collection can be enabled or disabled.

```javascript
import { setupWSConnection } from '@y/websocket-server/utils'

// Custom connection setup with options
wss.on('connection', (conn, req) => {
  // Extract custom document name from URL path
  const docName = req.url.slice(1).split('?')[0] || 'default-room'

  // Disable garbage collection for documents that need snapshots
  const enableGC = !req.url.includes('?gc=false')

  setupWSConnection(conn, req, {
    docName: docName,
    gc: enableGC
  })
})
```

--------------------------------

### Initialize and Use WSSharedDoc in JavaScript

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Demonstrates how to initialize a WSSharedDoc, access its properties like name and connected clients, and interact with awareness states.

```javascript
import { WSSharedDoc, getYDoc } from '@y/websocket-server/utils'

// Documents are instances of WSSharedDoc
const doc = getYDoc('example-room')

// Access the document name
console.log('Document name:', doc.name)

// Get all connected WebSocket clients
console.log('Connected clients:', doc.conns.size)

// Access awareness for presence features
const awareness = doc.awareness

// Get all awareness states (user presence data)
const states = awareness.getStates()
states.forEach((state, clientId) => {
  console.log(`Client ${clientId}:`, state)
})

// Wait for document initialization (if using setContentInitializor)
await doc.whenInitialized

// Listen for document updates
doc.on('update', (update, origin) => {
  console.log('Document updated, origin:', origin)
})

// Listen for errors
doc.on('error', (err) => {
  console.error('Document error:', err)
})
```

--------------------------------

### Deploy with Docker

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Build and run the y-websocket-server container image.

```bash
# Build the Docker image
docker build -t y-websocket-server .

# Run with default settings (port 1234)
docker run -p 1234:1234 y-websocket-server
```

--------------------------------

### Configure Custom Persistence Layer

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Implement bindState and writeState to handle document loading and saving. Ensure the storage directory exists before initializing persistence.

```javascript
import { setPersistence } from '@y/websocket-server/utils'
import * as Y from 'yjs'
import fs from 'fs/promises'
import path from 'path'

const STORAGE_DIR = './yjs-docs'

// Ensure storage directory exists
await fs.mkdir(STORAGE_DIR, { recursive: true })

setPersistence({
  // Called when a document is first accessed
  bindState: async (docName, ydoc) => {
    const filePath = path.join(STORAGE_DIR, `${docName}.yjs`)

    try {
      // Load existing document state
      const data = await fs.readFile(filePath)
      Y.applyUpdate(ydoc, new Uint8Array(data))
      console.log(`Loaded document: ${docName}`)
    } catch (err) {
      if (err.code !== 'ENOENT') throw err
      console.log(`New document: ${docName}`)
    }

    // Subscribe to updates for incremental persistence
    ydoc.on('update', async (update, origin) => {
      // Save on each update (consider debouncing in production)
      const state = Y.encodeStateAsUpdate(ydoc)
      await fs.writeFile(filePath, state)
    })
  },

  // Called when last client disconnects
  writeState: async (docName, ydoc) => {
    const filePath = path.join(STORAGE_DIR, `${docName}.yjs`)
    const state = Y.encodeStateAsUpdate(ydoc)
    await fs.writeFile(filePath, state)
    console.log(`Persisted document: ${docName}`)
  }
})
```

--------------------------------

### Run y-websocket-server with Custom Configuration

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Deploy the y-websocket-server using Docker with custom environment variables for port, callback URL, and callback objects.

```bash
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e CALLBACK_URL=http://host.docker.internal:3000/webhook \
  -e CALLBACK_OBJECTS='{"content":"Text"}' \
  y-websocket-server
```

--------------------------------

### Configure HTTP Callbacks

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Set environment variables to enable webhook notifications and implement an Express server to process document update payloads.

```bash
# Environment variables for callback configuration
CALLBACK_URL=http://localhost:3000/webhook \
CALLBACK_DEBOUNCE_WAIT=2000 \
CALLBACK_DEBOUNCE_MAXWAIT=10000 \
CALLBACK_TIMEOUT=5000 \
CALLBACK_OBJECTS='{"content":"Text","items":"Array","metadata":"Map"}' \
npx y-websocket
```

```javascript
// Example webhook server receiving callbacks
import express from 'express'

const app = express()
app.use(express.json())

app.post('/webhook', (req, res) => {
  const { room, data } = req.body

  console.log(`Update received for room: ${room}`)

  // Process each shared object
  for (const [name, obj] of Object.entries(data)) {
    console.log(`  ${name} (${obj.type}):`, obj.content)
  }

  // Save to database, trigger notifications, etc.
  saveToDatabase(room, data)

  res.sendStatus(200)
})

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000')
})
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Build a Docker image for y-websocket-server and run it. The container defaults to port 1234 and binds to all interfaces.

```sh
docker build -t y-websocket-server .
docker run -p 1234:1234 y-websocket-server
```

--------------------------------

### Configure Persistence Programmatically

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Configure document persistence by importing and using the setPersistence utility. This requires implementing bindState and writeState methods.

```js
import { setPersistence } from '@y/websocket-server/utils'

setPersistence({
  bindState: async (docName, ydoc) => {
    // Called when a Y.Doc is first accessed.
    // Load the persisted state for `docName` and apply it to `ydoc`.
    //
    // It is recommended to also subscribe to `ydoc.on('update', update => ...)`
    // here so you can persist updates incrementally as they happen, rather
    // than only on shutdown.
  },
  writeState: async (docName, ydoc) => {
    // Called when the last connected client disconnects from this document
    // (i.e. the session is closing). Flush / persist any remaining state.
  }
})
```

--------------------------------

### Initialize New Documents

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Use setContentInitializor to populate new documents with default data or external content. This function executes only once upon initial document creation.

```javascript
import { setContentInitializor } from '@y/websocket-server/utils'

setContentInitializor(async (ydoc) => {
  // Check if document is empty
  const yText = ydoc.getText('content')

  if (yText.length === 0) {
    // Initialize with default content
    yText.insert(0, '# Welcome\n\nStart editing this document...')
  }

  // Or load from external source
  const yArray = ydoc.getArray('items')
  if (yArray.length === 0) {
    const defaultItems = await fetchDefaultItems()
    yArray.push(defaultItems)
  }
})

async function fetchDefaultItems() {
  // Fetch from database or API
  return [
    { id: 1, text: 'First item' },
    { id: 2, text: 'Second item' }
  ]
}
```

--------------------------------

### Basic Client Connection

Source: https://github.com/yjs/y-websocket-server/blob/main/README.md

Connect a Yjs document to the y-websocket server. The status event logs connection status.

```js
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"
})
```

--------------------------------

### setContentInitializor

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Initializes new Yjs documents with default content or external data when they are first created.

```APIDOC
## setContentInitializor

### Description
Initializes new Yjs documents with default content or loads content from external sources. This function is called once when a document is first created.

### Parameters
- **initializor** (function) - Required - An async function that receives the `ydoc` instance to perform initialization logic.
```

--------------------------------

### Client Connection with WebsocketProvider

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Connect to a y-websocket server from a client application using WebsocketProvider. This handles synchronization, reconnection, and awareness updates. Listen for status and sync events, and interact with the shared document and awareness API.

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

// Create a new Yjs document
const doc = new Y.Doc()

// Connect to the websocket server
// URL format: ws://host:port
// Room name determines which document to join
const wsProvider = new WebsocketProvider(
  'ws://localhost:1234',
  'my-roomname',
  doc
)

// Listen for connection status changes
wsProvider.on('status', event => {
  console.log(event.status) // 'connected' or 'disconnected'
})

// Listen for sync completion
wsProvider.on('sync', isSynced => {
  if (isSynced) {
    console.log('Document is synced with server')
  }
})

// Use the shared document
const yText = doc.getText('shared-text')
yText.insert(0, 'Hello, collaborative world!')

// Access awareness for presence features
const awareness = wsProvider.awareness
awareness.setLocalStateField('user', {
  name: 'User ' + Math.floor(Math.random() * 100),
  color: '#' + Math.floor(Math.random() * 16777215).toString(16)
})
```

--------------------------------

### HTTP Callback on Document Updates

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Configures the server to send HTTP POST callbacks when documents are updated, allowing for external integration.

```APIDOC
## HTTP Callback on Document Updates

### Description
Configures the server to send HTTP POST callbacks when documents are updated. Useful for triggering external processes or saving to databases.

### Request Body
- **room** (string) - The name of the room/document updated.
- **data** (object) - The content of the shared objects updated in the document.

### Response Example
{
  "room": "my-document",
  "data": {
    "content": { "type": "Text", "content": "Hello world" },
    "items": { "type": "Array", "content": [1, 2, 3] },
    "metadata": { "type": "Map", "content": { "author": "John" } }
  }
}
```

--------------------------------

### Access and Manage Documents

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Retrieve Yjs documents by name and inspect their state, connections, and awareness data.

```javascript
import { getYDoc, docs } from '@y/websocket-server/utils'

// Get or create a document
const doc = getYDoc('my-document', true) // gc enabled

// Access document data
const yText = doc.getText('content')
console.log('Document content:', yText.toString())

// Access awareness states
const awarenessStates = doc.awareness.getStates()
console.log('Connected users:', awarenessStates.size)

// List all active documents
console.log('Active documents:', Array.from(docs.keys()))

// Check document connections
console.log('Connected clients:', doc.conns.size)
```

--------------------------------

### getYDoc

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Retrieves or creates a Yjs document by name, managing its lifecycle in memory.

```APIDOC
## getYDoc

### Description
Retrieves or creates a Yjs document by name. Documents are stored in memory and shared across all connections to the same room.

### Parameters
- **docName** (string) - Required - The name of the document.
- **gc** (boolean) - Optional - Whether garbage collection is enabled for the document.
```

--------------------------------

### setPersistence

Source: https://context7.com/yjs/y-websocket-server/llms.txt

Configures a custom persistence layer to store and retrieve Yjs documents using bindState and writeState hooks.

```APIDOC
## setPersistence

### Description
Configures a custom persistence layer to store and retrieve Yjs documents. The persistence object must implement `bindState` for loading documents and `writeState` for saving them when all clients disconnect.

### Parameters
- **persistence** (object) - Required - An object containing `bindState(docName, ydoc)` and `writeState(docName, ydoc)` functions.
```
Tokens:
Raw