WebSocket API

Cloudillo provides three WebSocket endpoints for real-time features.

Authentication

Tokens are passed as a query parameter:

wss://server.com/ws/bus?token=eyJhbGc...
wss://server.com/ws/rtdb/file_123?token=eyJhbGc...
wss://server.com/ws/crdt/doc_123?token=eyJhbGc...&access=write

Additional query parameters for RTDB and CRDT:

WebSocket close codes

Message bus (/ws/bus)

The bus provides direct user-to-user messaging and notifications. All messages use the format { id, cmd, data }.

Client → Server:

Server → Client:

Messages from other users are forwarded with the same { id, cmd, data } format. The bus does not use channels or subscriptions – it’s a direct messaging system where the server forwards relevant messages to registered users.

Client-side connection

The openMessageBus() function from @cloudillo/core returns a raw WebSocket:

import { openMessageBus } from '@cloudillo/core'

const ws = openMessageBus({ idTag: 'alice', authToken: token })

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  console.log('Command:', msg.cmd, 'Data:', msg.data)
}

// Send a command
ws.send(JSON.stringify({ id: '1', cmd: 'ping', data: {} }))

Real-time database (/ws/rtdb/{file_id})

Real-time synchronization of structured data. All messages use the format { id, type, ...payload }. See RTDB for the client library documentation.

Client → server messages

Server → client messages

Transaction operations

Each operation in a transaction has a type and a path:

All operations in a transaction are atomic – if any fails, the entire transaction rolls back. Operations support computed values ($op, $fn, $query) and reference substitution (${$ref} patterns) for creating related documents in a single transaction.

Change event actions

The event.action field in change notifications can be: create, update, delete, lock, unlock, or ready.

Client-side connection

The openRTDB() function from @cloudillo/core returns a raw WebSocket. For higher-level usage, use the @cloudillo/rtdb client library:

import { createRtdbClient } from '@cloudillo/rtdb'
import { getRtdbUrl } from '@cloudillo/core'

const db = createRtdbClient({
  dbId: fileId,
  auth: { getToken: () => bus.accessToken },
  serverUrl: getRtdbUrl(bus.idTag!, fileId, bus.accessToken!)
})

Store files

RTDB supports auto-created store files using the pattern s~{app_id} (e.g. s~taskillo). These are created automatically on first WebSocket connection, providing persistent app-specific data storage without manual file creation.

Collaborative documents (/ws/crdt/{doc_id})

CRDT synchronization using the Yjs binary protocol. See CRDT for full documentation.

Protocol

The endpoint uses the y-websocket binary protocol:

The sync flow:

1. Client sends SyncStep1 (state vector)
2. Server responds with SyncStep2 (missing updates)
3. Both sides exchange Updates incrementally as edits happen
4. Awareness messages broadcast cursor positions and user presence

Read-only connections can receive sync and awareness data but cannot send Update messages.

Client-side connection

Use openYDoc() from @cloudillo/crdt, which handles authentication, client ID reuse, offline caching, and token refresh automatically:

import { openYDoc } from '@cloudillo/crdt'
import * as Y from 'yjs'

const yDoc = new Y.Doc()
const { provider, persistence, offlineCached } = await openYDoc(yDoc, 'ownerTag:docId')

// Access shared types
const yText = yDoc.getText('content')

// Awareness is available via provider.awareness

Connection lifecycle

All three endpoints share common behaviors:

• Heartbeat: Server sends WebSocket ping frames every 30 seconds
• Multi-tab support: Each connection gets a unique conn_id; multiple connections per user are supported
• Cleanup: On disconnect, locks are released (RTDB), subscriptions cancelled, and user unregistered (bus)
• Activity tracking: File access and modification times are recorded (throttled to 60-second intervals)

See also

• RTDB – real-time database client library
• CRDT – collaborative editing with Yjs
• Authentication – token management