Y-Redis

https://github.com/yjs/y-redis
Admin
Y-Redis is a scalable and memory-efficient backend for y-websocket that uses Redis for real-time...
Tokens:7,524
Snippets:31
Trust Score:8.1
License:AGPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Development Setup for Y-Redis with Docker Compose

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

This bash snippet details how to set up a development environment for Y-Redis using Docker Compose. It covers cloning the repository, installing dependencies, configuring environment variables by copying a template and generating keys, and then running the services with docker compose. This approach simplifies the setup of Redis, MinIO (for S3 storage), and the Y-Redis server and worker.

```bash
git clone https://github.com/yjs/y-redis.git
cd y-redis
npm install

# Setup environment
cp .env.template .env
npx 0ecdsa-generate-keypair --name auth >> .env
nano .env # Edit configuration

# Run with docker-compose
cd demos/auth-express
docker compose up

# Or run components separately
npm run redis    # Redis on port 6379
npm run minio    # MinIO on ports 9000, 9001
npm run start:server  # Server on port 3002
npm run start:worker  # Worker process

```

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

### Run y-redis Express Demo

Source: https://github.com/yjs/y-redis/blob/master/README.md

Navigates to the auth-express demo directory, installs its Node.js dependencies, and starts the Express server. This demo application is typically accessed via a web browser.

```shell
# start the express server in a separater terminal
cd demos/auth-express
npm i
npm start
```

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

### Y-Redis Environment Configuration Example

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

This bash snippet shows a comprehensive example of environment variables for configuring the Y-Redis server. It includes settings for Redis connection, server port, optional S3 or PostgreSQL storage backends, authentication keys and callbacks, document update callbacks, logging levels, and expert settings for Redis. This configuration allows for flexible deployment scenarios.

```bash
# Redis
REDIS=redis://localhost:6379
REDIS_PREFIX=y

# Server
PORT=3002

# S3 Storage (comment out for PostgreSQL)
S3_ENDPOINT=s3.amazonaws.com
S3_PORT=443
S3_SSL=true
S3_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# PostgreSQL Storage (comment out for S3)
POSTGRES=postgres://user:pass@localhost:5432/yredis
POSTGRES_TESTDB=yredis_tests

# Authentication (generate with: npx 0ecdsa-generate-keypair --name auth)
AUTH_PUBLIC_KEY={"kty":"EC","crv":"P-256","x":"...","y":"..."}
AUTH_PRIVATE_KEY={"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."}
AUTH_PERM_CALLBACK=https://api.example.com/auth/perm

# Optional: Called when documents are persisted
YDOC_UPDATE_CALLBACK=https://api.example.com/ydoc

# Logging
LOG=* # or "" for none, or regex like "@y/redis"

# Expert settings
REDIS_MIN_MESSAGE_LIFETIME=60000 # 1 minute
REDIS_TASK_DEBOUNCE=10000 # 10 seconds

```

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

### Run y-redis Demo with Docker Compose

Source: https://github.com/yjs/y-redis/blob/master/README.md

Starts the y-redis demo application using Docker Compose. This command sets up Redis, Minio (for S3), a y-redis server, and a y-redis worker, allowing you to test the setup locally.

```shell
cd ./demos/auth-express
docker compose up
```

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

### Install Dependencies with npm

Source: https://github.com/yjs/y-redis/blob/master/README.md

Installs the necessary project dependencies using npm. This is a standard step before running or setting up the project.

```shell
npm i
```

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

### Start Redis Instance using Docker

Source: https://github.com/yjs/y-redis/blob/master/README.md

Starts the official Redis Docker container, exposing the default port 6379. This is useful for debugging Redis streams or for a quick local setup. Alternatively, the command `npm run redis` can be used if npm scripts are configured.

```shell
# start the official redis docker container on port 6379
docker run -p 6379:6379 redis
# or `npm run redis`
```

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

### Clone y-redis Project and Install Dependencies

Source: https://github.com/yjs/y-redis/blob/master/README.md

Clones the y-redis repository from GitHub and installs its Node.js dependencies using npm. This is the initial step to start working with the project locally.

```shell
git clone https://github.com/yjs/y-redis.git
cd y-redis
npm i
```

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

### Run Y-Redis Server and Worker using npm and Environment Variables

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

This bash snippet outlines the steps to install and run the Y-Redis server and worker using npm. It includes installing the package, setting essential environment variables for Redis and S3 (or other backends), and then executing the server and worker binaries. This is a common method for deploying Y-Redis in a production or development environment.

```bash
# Install
npm install @y/redis

# Configure environment
export REDIS=redis://localhost:6379
export S3_ENDPOINT=localhost
export S3_PORT=9000
export S3_SSL=false
export S3_ACCESS_KEY=minioadmin
export S3_SECRET_KEY=minioadmin
export AUTH_PERM_CALLBACK=http://localhost:5173/auth/perm
export AUTH_PUBLIC_KEY='{"kty":"EC"...}'

# Run server
npx y-redis-server
# or: node --env-file .env ./node_modules/@y/redis/bin/server.js

# Run worker in separate terminal
npx y-redis-worker
# or: node --env-file .env ./node_modules/@y/redis/bin/worker.js

```

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

### Start Minio S3 Instance using Docker

Source: https://github.com/yjs/y-redis/blob/master/README.md

Launches a Minio S3-compatible object storage server using Docker, mapping ports 9000 and 9001. This is suitable for local development and testing S3 interactions. The command `npm run minio` is an alternative if available.

```shell
docker run -p 9000:9000 -p 9001:9001 quay.io/minio/minio server /data --console-address ":9001"
# or `npm run minio`
```

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

### PostgreSQL Storage Provider

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

Guide to configuring and using the PostgreSQL storage provider for Yjs documents. This involves setting up the PostgreSQL connection and understanding the table structure used.

```APIDOC
### PostgreSQL Storage Configuration

#### Description
Instructions for setting up and utilizing the PostgreSQL storage provider to manage Yjs documents. Requires the `POSTGRES` environment variable for database connection.

#### Method
`createPostgresStorage({ database })`

#### Endpoint
N/A (Client-side library)

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Request Example
```javascript
import { createPostgresStorage } from '@y/redis/storage/postgres'

// Environment variable required:
// POSTGRES=postgres://user:password@host:port/database

const storage = await createPostgresStorage({ database: 'mydb' })

// Automatically creates table:
// CREATE TABLE yredis_docs_v1 (
//   room text,
//   doc text,
//   r SERIAL,
//   update bytea,
//   sv bytea,
//   PRIMARY KEY (room,doc,r)
// );

await storage.persistDoc('room1', 'index', ydoc)

const result = await storage.retrieveDoc('room1', 'index')
if (result) {
  const { doc, references } = result
  // doc: Uint8Array - merged updates
  // references: Array<number> - row IDs for cleanup
}

await storage.destroy()
```

#### Response
##### Success Response (200)
Methods return `Promise<void>` for persistence/deletion, `Promise<object | null>` for retrieval, containing `doc` (Uint8Array) and `references` (Array<number>).

##### Response Example
```json
{
  "doc": "Uint8Array of Yjs updates",
  "references": [
    1,
    2
  ]
}
```
```

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

### Run y-redis Server and Worker Components

Source: https://github.com/yjs/y-redis/blob/master/README.md

Starts the main server and a single worker process for the y-redis project in separate terminals. These commands are essential for the backend functionality of the y-redis system.

```shell
# run the server
npm run start:server
# run a single worker in a separate terminal
npm run start:worker
```

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

### Implement Authentication Callback Server

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

An example implementation of an authentication callback server using `uws` (uWebSockets.js). This server exposes an endpoint that `y-redis` calls to check user permissions for specific rooms. The endpoint pattern is `{AUTH_PERM_CALLBACK}/{room}/{userid}`. It returns the room, access level ('rw' or 'ro'), and user ID.

```javascript
import * as uws from 'uws'

const app = uws.App({})

// Permission check endpoint called by y-redis server
// URL pattern: {AUTH_PERM_CALLBACK}/{room}/{userid}
app.get('/auth/perm/:room/:userid', async (res, req) => {
  const room = req.getParameter(0)
  const userid = req.getParameter(1)

  // Check your database/cache for permissions
  const hasWriteAccess = await checkUserPermissions(userid, room)

  res.end(JSON.stringify({
    yroom: room,
    yaccess: hasWriteAccess ? 'rw' : 'ro', // 'rw' or 'ro'
    yuserid: userid
  }))
})

app.listen(5173, (token) => {
  if (token) console.log('Auth server listening on 5173')
})
```

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

### Implement Custom AbstractStorage Interface in JavaScript

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

This snippet demonstrates how to extend the AbstractStorage class from '@y/redis' to create a custom storage solution. It covers methods for persisting, retrieving, and deleting documents, as well as retrieving state vectors and managing the storage instance. The example shows how to encode Yjs updates and state vectors for storage and decode them upon retrieval. It also shows how to use the custom storage with a Y-Websocket server.

```javascript
import { AbstractStorage } from '@y/redis'
import * as Y from 'yjs'

class CustomStorage extends AbstractStorage {
  async persistDoc(room, docname, ydoc) {
    const update = Y.encodeStateAsUpdateV2(ydoc)
    const stateVector = Y.encodeStateVector(ydoc)

    // Store in your custom backend
    await this.db.insert({
      room,
      doc: docname,
      update,
      stateVector,
      timestamp: Date.now()
    })
  }

  async retrieveDoc(room, docname) {
    const rows = await this.db.query(
      'SELECT update, id FROM docs WHERE room = ? AND doc = ?',
      [room, docname]
    )

    if (rows.length === 0) return null

    return {
      doc: Y.mergeUpdatesV2(rows.map(r => r.update)),
      references: rows.map(r => r.id)
    }
  }

  async retrieveStateVector(room, docname) {
    // Optional: Implement for better performance
    const row = await this.db.queryOne(
      'SELECT stateVector FROM docs WHERE room = ? AND doc = ? LIMIT 1',
      [room, docname]
    )
    return row?.stateVector || null
  }

  async deleteReferences(room, docname, storeReferences) {
    await this.db.delete(
      'DELETE FROM docs WHERE room = ? AND doc = ? AND id IN (?)',
      [room, docname, storeReferences]
    )
  }

  async destroy() {
    await this.db.close()
  }
}

// Use with server/worker
const storage = new CustomStorage()
const server = await createYWebsocketServer({ store: storage, /* ... */ })

```

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

### Subscribe to Redis Streams with @y/redis

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

This example illustrates how to subscribe to multiple Redis streams using the Y-Redis API client. It shows how to configure the streams to listen to and how to poll for new messages. The received messages are Yjs updates ready to be applied to a Y.Doc.

```javascript
import { createApiClient } from '@y/redis'
import { createMemoryStorage } from '@y/redis/storage/memory'

const store = createMemoryStorage()
const api = await createApiClient(store, 'y')

// Subscribe to multiple streams
const streams = [
  { key: 'y:room:my-room:index', id: '0' },
  { key: 'y:room:another-room:index', id: '1234567890-0' }
]

// Poll for new messages (blocking for 1 second)
const messages = await api.getMessages(streams)

messages.forEach(({ stream, messages, lastId }) => {
  console.log(`Stream: ${stream}`)
  console.log(`Last ID: ${lastId}`)
  console.log(`Messages: ${messages.length}`)

  // Messages are merged Yjs updates ready to apply
  messages.forEach(msg => {
    // Apply to your Y.Doc
  })
})

await api.destroy()
```

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

### S3 Storage Provider

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

Configuration and usage guide for the S3 storage provider. This allows persisting and retrieving Yjs documents from an S3-compatible storage service.

```APIDOC
## Storage Providers

### S3 Storage Configuration

#### Description
Details on configuring and using the S3 storage provider for persisting and retrieving Yjs documents. Requires specific environment variables for S3 connection.

#### Method
`createS3Storage(bucketName)`

#### Endpoint
N/A (Client-side library)

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Request Example
```javascript
import { createS3Storage } from '@y/redis/storage/s3'

// Environment variables required:
// S3_ENDPOINT=s3.amazonaws.com (or localhost for MinIO)
// S3_PORT=443 (or 9000 for MinIO)
// S3_SSL=true (or false for MinIO)
// S3_ACCESS_KEY=your-access-key
// S3_SECRET_KEY=your-secret-key

const storage = createS3Storage('my-bucket-name')

// Storage methods
await storage.persistDoc('room1', 'index', ydoc)

const result = await storage.retrieveDoc('room1', 'index')
if (result) {
  const { doc, references } = result
  // doc: Uint8Array - merged Yjs update V2
  // references: Array<string> - S3 object names for cleanup
}

const stateVector = await storage.retrieveStateVector('room1', 'index')

await storage.deleteReferences('room1', 'index', references)
await storage.destroy()
```

#### Response
##### Success Response (200)
Methods return `Promise<void>` for persistence/deletion, `Promise<object | null>` for retrieval, containing `doc` (Uint8Array) and `references` (Array<string>).

##### Response Example
```json
{
  "doc": "Uint8Array of Yjs updates",
  "references": [
    "object-name-1",
    "object-name-2"
  ]
}
```
```

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

### Create WebSocket Server with S3 Storage

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

Sets up a Yjs WebSocket server using Redis for distribution and S3 for persistent storage. It includes configuration for the S3 bucket, Redis prefix, and an authentication callback URL. An optional `initDocCallback` can be provided to initialize documents when accessed for the first time. Requires `@y/redis` and `@y/redis/storage/s3`.

```javascript
import { createYWebsocketServer } from '@y/redis'
import { createS3Storage } from '@y/redis/storage/s3'

// Configure S3 storage
const store = createS3Storage('ydocs-bucket')

// Create server with authentication callback
const server = await createYWebsocketServer({
  port: 3002,
  store,
  redisPrefix: 'y',
  checkPermCallbackUrl: 'https://api.example.com/auth/perm',
  initDocCallback: async (room, docname, client) => {
    // Optional: Initialize empty documents
    console.log(`Document ${room}/${docname} accessed for first time`)
  }
})

// Server now listening on port 3002
// Clean up when done
await server.destroy()
```

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

### PostgreSQL Storage Configuration with @y/redis/storage/postgres

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

This code explains how to set up PostgreSQL as a storage backend for Yjs documents using Y-Redis. It highlights the necessary POSTGRES environment variable and shows the automatic table creation. The snippet covers persisting, retrieving documents, and cleaning up references within the PostgreSQL database.

```javascript
import { createPostgresStorage } from '@y/redis/storage/postgres'

// Environment variable required:
// POSTGRES=postgres://user:password@host:port/database

const storage = await createPostgresStorage({ database: 'mydb' })

// Automatically creates table:
// CREATE TABLE yredis_docs_v1 (
//   room text,
//   doc text,
//   r SERIAL,
//   update bytea,
//   sv bytea,
//   PRIMARY KEY (room,doc,r)
// );

await storage.persistDoc('room1', 'index', ydoc)

const result = await storage.retrieveDoc('room1', 'index')
if (result) {
  const { doc, references } = result
  // doc: Uint8Array - merged updates
  // references: Array<number> - row IDs for cleanup
}

await storage.destroy()
```

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

### Create WebSocket Server with Memory Storage (Development)

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

Initializes a Yjs WebSocket server using Redis and in-memory storage. This is suitable for development and testing as data will be lost upon server restart. Requires `@y/redis` and `@y/redis/storage/memory`.

```javascript
import { createYWebsocketServer } from '@y/redis'
import { createMemoryStorage } from '@y/redis/storage/memory'

// In-memory storage for testing (data lost on restart)
const store = createMemoryStorage()

const server = await createYWebsocketServer({
  port: 3002,
  store,
  checkPermCallbackUrl: 'http://localhost:5173/auth/perm'
})
```

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

### Configure Environment Variables for y-redis

Source: https://github.com/yjs/y-redis/blob/master/README.md

Copies the environment variable template file and opens it for editing using nano. This step is crucial for configuring project-specific settings and secrets for local development.

```shell
# setup environment variables
cp .env.template .env
nano .env
```

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

### API Client for Direct Access

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

Demonstrates how to create and use an API client for direct interaction with Yjs documents stored via Redis. This includes fetching documents, adding messages to streams, and retrieving state vectors.

```APIDOC
## API Client

### Create API Client for Direct Access

#### Description
This section provides instructions on how to instantiate and utilize an API client for direct management of Yjs documents stored in Redis. It covers fetching, updating, and retrieving document states.

#### Method
`createApiClient(storage, prefix)`

#### Endpoint
N/A (Client-side library)

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Request Example
```javascript
import { createApiClient } from '@y/redis'
import { createS3Storage } from '@y/redis/storage/s3'

const store = createS3Storage('ydocs-bucket')
const api = await createApiClient(store, 'y')

// Get full document with Redis stream and storage data
const { ydoc, awareness, redisLastId, storeReferences, docChanged } = 
  await api.getDoc('my-room', 'index')

console.log(`Document clients: ${ydoc.store.clients.size}`)
console.log(`Awareness states: ${awareness.states.size}`)
console.log(`Last Redis ID: ${redisLastId}`)

// Add message to Redis stream (distributed to all connected clients)
const message = Buffer.from([0, 2, /* Yjs update data */])
await api.addMessage('my-room', 'index', message)

// Get state vector
const stateVector = await api.getStateVector('my-room', 'index')

// Clean up
await api.destroy()
```

#### Response
##### Success Response (200)
Returns an object containing:
- `ydoc`: The Yjs document.
- `awareness`: The Yjs awareness management instance.
- `redisLastId`: The last message ID from the Redis stream.
- `storeReferences`: References for cleanup if using specific storage providers.
- `docChanged`: A boolean indicating if the document changed.

##### Response Example
```json
{
  "ydoc": "Y.Doc object",
  "awareness": "Y.Awareness object",
  "redisLastId": "1234567890-0",
  "storeReferences": [],
  "docChanged": true
}
```
```

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

### Generate Authentication Keypair for Environment

Source: https://github.com/yjs/y-redis/blob/master/README.md

Generates a unique authentication keypair and appends it to the .env file. This is used for setting up secure communication and authentication within the y-redis environment.

```shell
cp .env.docker.template .env
npx 0ecdsa-generate-keypair --name auth >> .env
```

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

### Create WebSocket Server with PostgreSQL Storage

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

Configures a Yjs WebSocket server using Redis and PostgreSQL for persistence. The PostgreSQL connection string should be set via the `POSTGRES` environment variable. The server will automatically create the necessary table if it doesn't exist. Requires `@y/redis` and `@y/redis/storage/postgres`.

```javascript
import { createYWebsocketServer } from '@y/redis'
import { createPostgresStorage } from '@y/redis/storage/postgres'

// Set environment variable: POSTGRES=postgres://user:pass@localhost/database
const store = await createPostgresStorage({ database: 'yredis' })

const server = await createYWebsocketServer({
  port: 3002,
  store,
  checkPermCallbackUrl: 'http://localhost:5173/auth/perm'
})

// Server automatically creates yredis_docs_v1 table if it doesn't exist
```

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

### S3 Storage Configuration with @y/redis/storage/s3

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

This snippet details the configuration for using S3 as a storage provider for Yjs documents within the Y-Redis project. It outlines the required environment variables for S3 access and demonstrates persisting, retrieving, and deleting document data and references from an S3 bucket.

```javascript
import { createS3Storage } from '@y/redis/storage/s3'

// Environment variables required:
// S3_ENDPOINT=s3.amazonaws.com (or localhost for MinIO)
// S3_PORT=443 (or 9000 for MinIO)
// S3_SSL=true (or false for MinIO)
// S3_ACCESS_KEY=your-access-key
// S3_SECRET_KEY=your-secret-key

const storage = createS3Storage('my-bucket-name')

// Storage methods
await storage.persistDoc('room1', 'index', ydoc)

const result = await storage.retrieveDoc('room1', 'index')
if (result) {
  const { doc, references } = result
  // doc: Uint8Array - merged Yjs update V2
  // references: Array<string> - S3 object names for cleanup
}

const stateVector = await storage.retrieveStateVector('room1', 'index')

await storage.deleteReferences('room1', 'index', references)
await storage.destroy()
```

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

### Create API Client for Direct Access with @y/redis

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

This code snippet shows how to create an API client for direct access to Yjs documents stored in Redis. It utilizes S3 for document storage and demonstrates fetching a document, logging its metadata, adding messages to a Redis stream, retrieving the state vector, and cleaning up the client.

```javascript
import { createApiClient } from '@y/redis'
import { createS3Storage } from '@y/redis/storage/s3'

const store = createS3Storage('ydocs-bucket')
const api = await createApiClient(store, 'y')

// Get full document with Redis stream and storage data
const { ydoc, awareness, redisLastId, storeReferences, docChanged } =
  await api.getDoc('my-room', 'index')

console.log(`Document clients: ${ydoc.store.clients.size}`)
console.log(`Awareness states: ${awareness.states.size}`)
console.log(`Last Redis ID: ${redisLastId}`)

// Add message to Redis stream (distributed to all connected clients)
const message = Buffer.from([0, 2, /* Yjs update data */])
await api.addMessage('my-room', 'index', message)

// Get state vector
const stateVector = await api.getStateVector('my-room', 'index')

// Clean up
await api.destroy()
```

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

### Memory Storage Provider (Testing)

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

Information on using the in-memory storage provider, ideal for testing and development purposes. Note that data is lost when the process terminates.

```APIDOC
### Memory Storage (Testing)

#### Description
Information on the in-memory storage provider, suitable for development and testing environments. Data persistence is not guaranteed as it resides solely in memory.

#### Method
`createMemoryStorage()`

#### Endpoint
N/A (Client-side library)

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Request Example
```javascript
import { createMemoryStorage } from '@y/redis/storage/memory'

// Simple in-memory storage for testing
const storage = createMemoryStorage()

await storage.persistDoc('room1', 'index', ydoc)
const result = await storage.retrieveDoc('room1', 'index')

// Data lost when process exits
// References are random UUIDs
await storage.destroy()
```

#### Response
##### Success Response (200)
Methods return `Promise<void>` for persistence/deletion, `Promise<object | null>` for retrieval.

##### Response Example
```json
{
  "doc": "Uint8Array of Yjs updates",
  "references": ["uuid-reference-1"]
}
```
```

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

### Subscribe to Redis Streams

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

Explains how to subscribe to Redis streams to receive Yjs updates in real-time. This includes configuring the streams to monitor and processing incoming messages.

```APIDOC
### Subscribe to Redis Streams

#### Description
This section details how to subscribe to Redis streams to receive real-time Yjs updates. It covers setting up stream subscriptions and processing the received messages.

#### Method
`getMessages(streams)`

#### Endpoint
N/A (Client-side library)

#### Parameters

##### Path Parameters
None

##### Query Parameters
None

##### Request Body
None

#### Request Example
```javascript
import { createApiClient } from '@y/redis'
import { createMemoryStorage } from '@y/redis/storage/memory'

const store = createMemoryStorage()
const api = await createApiClient(store, 'y')

// Subscribe to multiple streams
const streams = [
  { key: 'y:room:my-room:index', id: '0' },
  { key: 'y:room:another-room:index', id: '1234567890-0' }
]

// Poll for new messages (blocking for 1 second)
const messages = await api.getMessages(streams)

messages.forEach(({ stream, messages, lastId }) => {
  console.log(`Stream: ${stream}`)
  console.log(`Last ID: ${lastId}`)
  console.log(`Messages: ${messages.length}`)

  // Messages are merged Yjs updates ready to apply
  messages.forEach(msg => {
    // Apply to your Y.Doc
  })
})

await api.destroy()
```

#### Response
##### Success Response (200)
Returns an array of stream objects, each containing:
- `stream`: The name of the Redis stream.
- `messages`: An array of Yjs update messages.
- `lastId`: The ID of the last processed message in the stream.

##### Response Example
```json
[
  {
    "stream": "y:room:my-room:index",
    "messages": [
      "Yjs update data 1",
      "Yjs update data 2"
    ],
    "lastId": "1234567890-1"
  }
]
```
```

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

### Memory Storage (Testing) with @y/redis/storage/memory

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

This snippet demonstrates the use of in-memory storage, provided by '@y/redis/storage/memory', which is ideal for testing purposes. It shows the basic operations of persisting and retrieving Yjs documents. It also notes that data is lost when the process exits and references are random UUIDs.

```javascript
import { createMemoryStorage } from '@y/redis/storage/memory'

// Simple in-memory storage for testing
const storage = createMemoryStorage()

await storage.persistDoc('room1', 'index', ydoc)
const result = await storage.retrieveDoc('room1', 'index')

// Data lost when process exits
// References are random UUIDs
await storage.destroy()
```

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

### Create Worker to Persist Documents

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

Sets up a worker process that listens to Redis streams and persists Yjs documents to a specified storage backend (e.g., S3). It can be configured with `tryClaimCount` and an `updateCallback` that is triggered after a document is persisted. Requires `@y/redis`, `yjs`, and a storage module like `@y/redis/storage/s3`.

```javascript
import { createWorker } from '@y/redis'
import { createS3Storage } from '@y/redis/storage/s3'
import * as Y from 'yjs'

const store = createS3Storage('ydocs-bucket')

// Worker polls Redis queue and persists documents
const worker = await createWorker(store, 'y', {
  tryClaimCount: 5,
  updateCallback: async (room, ydoc) => {
    // Optional: Called when document is persisted
    const text = ydoc.getText('codemirror').toString()
    console.log(`Document ${room} updated. Content length: ${text.length}`)

    // Example: Notify external service
    await fetch(`https://api.example.com/notify/${room}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/octet-stream' },
      body: Y.encodeStateAsUpdateV2(ydoc)
    })
  }
})

// Worker runs continuously until destroyed
await worker.client.destroy()
```

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

### Connect Browser Client to Y-Redis WebSocket Server with Authentication

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

This JavaScript snippet shows how a browser client can connect to a Y-Redis WebSocket server. It demonstrates obtaining a JWT token from an authentication server and using it to establish a connection. The token can be passed either in the WebSocket subprotocol header or as a query parameter. The code also shows how to interact with the Yjs document and clean up the provider.

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

// Obtain JWT token from your auth server
const response = await fetch('https://api.example.com/auth/token')
const token = await response.text()

const ydoc = new Y.Doc()

// Connect with token in protocol header
const provider = new WebsocketProvider(
  'ws://localhost:3002',
  'my-room',
  ydoc,
  {
    protocols: [`yauth-${token}`]
  }
)

// Or pass token as query parameter
const provider2 = new WebsocketProvider(
  `ws://localhost:3002?yauth=${token}`,
  'my-room',
  ydoc
)

// Use Yjs document
const ytext = ydoc.getText('codemirror')
ytext.observe(event => {
  console.log('Text changed:', ytext.toString())
})

// Clean up
provider.destroy()

```

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

### JWT Token Generation and Usage

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

Learn how to generate and use JSON Web Tokens (JWT) for authenticating clients connecting to Yjs shared documents served via Redis. This includes generating a keypair, encoding the JWT with necessary claims, and how clients should present the token.

```APIDOC
## Generate and Use JWT Tokens

### Description
This section explains how to generate and utilize JWT tokens for client authentication when using Yjs with a Redis backend. It covers key generation, token encoding, and client-side token transmission.

### Method
N/A (Client-side generation and server-side validation)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import * as jwt from 'lib0/crypto/jwt'
import * as ecdsa from 'lib0/crypto/ecdsa'
import * as time from 'lib0/time'

// Generate keypair (do this once, store securely):
// npx 0ecdsa-generate-keypair --name auth

// Import your private key
const privateKey = await ecdsa.importKeyJwk({
  kty: 'EC',
  crv: 'P-256',
  x: 'your-x-value',
  y: 'your-y-value',
  d: 'your-private-d-value'
})

// Create token for client
const token = await jwt.encodeJwt(privateKey, {
  iss: 'YourApp',
  exp: time.getUnixTime() + 60 * 60 * 1000, // 1 hour
  yuserid: 'user123' // Required field
})

// Client connects with token in WebSocket protocol header:
// ws://localhost:3002/room-name?yauth={token}
// Or: Sec-WebSocket-Protocol: yauth-{token}
```

### Response
#### Success Response (200)
N/A (Token is generated client-side)

#### Response Example
N/A
```

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

### Generate and Use JWT Tokens with lib0/crypto

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

This snippet demonstrates how to generate an ECDSA keypair and use it to create and encode JWT tokens. It includes instructions for importing private keys and specifies the required fields for the token payload. The generated token can be used for authentication in WebSocket connections.

```javascript
import * as jwt from 'lib0/crypto/jwt'
import * as ecdsa from 'lib0/crypto/ecdsa'
import * as time from 'lib0/time'

// Generate keypair (do this once, store securely):
// npx 0ecdsa-generate-keypair --name auth

// Import your private key
const privateKey = await ecdsa.importKeyJwk({
  kty: 'EC',
  crv: 'P-256',
  x: 'your-x-value',
  y: 'your-y-value',
  d: 'your-private-d-value'
})

// Create token for client
const token = await jwt.encodeJwt(privateKey, {
  iss: 'YourApp',
  exp: time.getUnixTime() + 60 * 60 * 1000, // 1 hour
  yuserid: 'user123' // Required field
})

// Client connects with token in WebSocket protocol header:
// ws://localhost:3002/room-name?yauth={token}
// Or: Sec-WebSocket-Protocol: yauth-{token}
```
Tokens:
Raw