Y-S2

​

How it works

• Rooms — each room is a stream named rooms/<room>/index in your basin, created on first use.
• Writes — document updates and presence (cursor) updates from a client are batched and appended to the room’s stream. Messages larger than S2’s 1 MiB record limit, such as a large paste, are stored in R2 and the stream carries a pointer to them.
• Fan-out — every connection reads the room’s stream and relays new records to its client.
• Joining — a new connection loads the room’s latest snapshot from R2, reads the stream from where that snapshot ends, and sends the client the full document once it has caught up.
• Snapshots — while a room is active, connections periodically write a new snapshot to R2 and then trim the stream up to it. A lease built on fencing tokens ensures only one connection snapshots a room at a time.

​

Prerequisites

• A Cloudflare account on the Workers Paid plan. Each WebSocket connection is a single Worker invocation, and every S2 and R2 call it makes counts toward the per-invocation subrequest limit, which is 50 on the free plan.
• An R2 bucket for snapshots and large messages.
• An S2 basin with Create stream on append and Create stream on read enabled, and a scoped access token for it.
• Node.js 22 or newer.

​

Deploy

1. Clone the repository and install dependencies:
   git clone https://github.com/s2-streamstore/y-s2
   cd y-s2
   npm install
   
2. Point the R2_BUCKET binding in wrangler.jsonc at your bucket by setting its bucket_name.
3. Store your S2 credentials as Worker secrets:
   npx wrangler secret put S2_ACCESS_TOKEN
   npx wrangler secret put S2_BASIN
   
4. Deploy:
   npm run deploy
   

​

Configuration

​

Client integration

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

const room = 'room-name'
const doc = new Y.Doc()
const provider = new WebsocketProvider(
  'wss://your-worker.your-subdomain.workers.dev/ws',
  room,
  doc,
  {
    params: { room, yauth: 'your-auth-token' }
  }
)

​

Resources

• Demo
• GitHub repository
• Behind y-s2: serverless multiplayer rooms
• Yjs documentation