@vuer-ai/vuer-rtc-server 0.2.3 → 0.4.1

package/docs/API.md

@@ -0,0 +1,642 @@
+# Vuer RTC Server API Documentation
+
+## Overview
+
+The Vuer RTC Server provides two types of collaborative documents:
+
+1. **Graph Documents** - Collaborative 3D scene graphs with nodes, transforms, and properties
+2. **Text Documents** - Collaborative text documents using CRDT (TextRope)
+
+Each type has dedicated REST and WebSocket APIs.
+
+---
+
+## WebSocket API
+
+### Graph Documents
+
+**URL**: `ws://server/ws/graph/{roomId}?sessionId={sessionId}`
+
+**Lifecycle**:
+```
+1. Client connects → Server sends initial state
+   ← { type: 'init', snapshot: {...}, journal: [...] }
+
+2. Client sends operations
+   → { ops: [{ otype: 'node.insert', ... }], clock: {...}, lamportTime: 1 }
+
+3. Server broadcasts to all clients
+   ← { ops: [...], clock: {...}, lamportTime: 1 }
+
+4. Server sends acknowledgment
+   ← { type: 'ack', clock: {...}, lamportTime: 1 }
+
+5. Client disconnects → Server removes from room
+```
+
+**Message Types**:
+- `init` - Initial state snapshot + journal
+- `message` - CRDT operations broadcast
+- `ack` - Server acknowledgment of client messages
+- `error` - Error notification
+
+### Text Documents
+
+**URL**: `ws://server/ws/text/{docId}?sessionId={sessionId}`
+
+**Lifecycle**:
+```
+1. Client connects → Server sends initial text state
+   ← { type: 'init', snapshot: { text: "..." }, journal: [...] }
+
+2. Client sends text operations
+   → { ops: [{ otype: 'text.insert', position: 0, value: 'Hello' }], clock: {...}, lamportTime: 1 }
+
+3. Server broadcasts to all clients
+   ← { ops: [...], clock: {...}, lamportTime: 1 }
+
+4. Server sends acknowledgment
+   ← { type: 'ack', clock: {...}, lamportTime: 1 }
+
+5. Client disconnects → Server removes from document
+```
+
+**Text Operation Types**:
+- `text.insert` - Insert text at position
+- `text.delete` - Delete text at position
+- `text.replace` - Replace text (atomic delete + insert)
+
+---
+
+## REST API
+
+### Statistics
+
+#### `GET /api/stats`
+Get database statistics
+
+**Response**:
+```json
+{
+  "documents": 10,
+  "textDocuments": 5,
+  "journalBatches": 150,
+  "operations": 2500,
+  "sessions": 8
+}
+```
+
+#### `GET /api/stats/sizes`
+Get detailed size breakdown
+
+**Response**:
+```json
+{
+  "totalDocStateSize": 524288,
+  "totalJournalSize": 1048576,
+  "avgDocStateSize": 52428,
+  "avgJournalSize": 6990,
+  "documents": [...]
+}
+```
+
+---
+
+## Graph Documents API
+
+### List Graph Documents
+
+#### `GET /api/graph`
+Get all graph documents
+
+**Query Parameters**:
+- `limit` (optional) - Number of documents to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "documents": [
+    {
+      "id": "507f1f77bcf86cd799439011",
+      "name": "my-scene",
+      "ownerId": "user-123",
+      "version": 5,
+      "createdAt": "2024-01-01T00:00:00Z",
+      "updatedAt": "2024-01-01T12:00:00Z"
+    }
+  ],
+  "total": 10
+}
+```
+
+### Get Graph Document
+
+#### `GET /api/graph/:id`
+Get graph document state
+
+**Response**:
+```json
+{
+  "id": "507f1f77bcf86cd799439011",
+  "name": "my-scene",
+  "currentState": {
+    "graph": {
+      "nodes": {...},
+      "rootKey": "scene-root",
+      "lww": {},
+      "tombstones": {}
+    },
+    "vectorClock": {...},
+    "lamportTime": 100
+  },
+  "version": 5
+}
+```
+
+### Get Graph Journal
+
+#### `GET /api/graph/:id/journal`
+Get operation journal (write-ahead log)
+
+**Query Parameters**:
+- `limit` (optional) - Number of batches to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "batches": [
+    {
+      "id": "507f...",
+      "batchId": "batch-uuid",
+      "operations": [...],
+      "vectorClock": {...},
+      "lamportTime": 100,
+      "persistedAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 50
+}
+```
+
+### Get Graph Operations
+
+#### `GET /api/graph/:id/operations`
+Get all operations (expanded from journal batches)
+
+**Query Parameters**:
+- `limit` (optional) - Number of operations to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "operations": [
+    {
+      "id": "507f...",
+      "opId": "op-uuid",
+      "type": "node.insert",
+      "data": {...},
+      "vectorClock": {...},
+      "lamportTime": 100,
+      "createdAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 500
+}
+```
+
+### Get Graph Sessions
+
+#### `GET /api/graph/:id/sessions`
+Get active and recent sessions
+
+**Response**:
+```json
+{
+  "sessions": [
+    {
+      "id": "507f...",
+      "userId": "user-123",
+      "clientId": "client-abc",
+      "connected": true,
+      "connectedAt": "2024-01-01T00:00:00Z",
+      "lastSeenAt": "2024-01-01T12:00:00Z"
+    }
+  ]
+}
+```
+
+### Compact Graph Journal
+
+#### `POST /api/graph/:id/compact`
+Trigger journal compaction
+
+Folds acknowledged journal entries into snapshot and removes them from the journal.
+
+**Response**:
+```json
+{
+  "message": "Compaction triggered",
+  "before": { "journal": 150, "snapshot": 50 },
+  "after": { "journal": 0, "snapshot": 200 }
+}
+```
+
+### Coalesce Graph Operations
+
+#### `POST /api/graph/:id/coalesce`
+Trigger operation coalescing
+
+Combines redundant operations (e.g., multiple updates to the same property).
+
+**Response**:
+```json
+{
+  "message": "Coalescing triggered",
+  "coalescedOps": 50,
+  "resultingOps": 25
+}
+```
+
+### Delete Graph Document
+
+#### `DELETE /api/graph/:id`
+Permanently delete a graph document
+
+**Response**:
+```json
+{
+  "message": "Document deleted",
+  "id": "507f1f77bcf86cd799439011"
+}
+```
+
+---
+
+## Text Documents API
+
+### List Text Documents
+
+#### `GET /api/text`
+Get all text documents
+
+**Query Parameters**:
+- `limit` (optional) - Number of documents to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "documents": [
+    {
+      "id": "507f1f77bcf86cd799439011",
+      "name": "my-doc",
+      "ownerId": "user-123",
+      "version": 3,
+      "createdAt": "2024-01-01T00:00:00Z",
+      "updatedAt": "2024-01-01T12:00:00Z"
+    }
+  ],
+  "total": 5
+}
+```
+
+### Get Text Document
+
+#### `GET /api/text/:id`
+Get text document content
+
+**Response**:
+```json
+{
+  "id": "507f1f77bcf86cd799439011",
+  "name": "my-doc",
+  "currentText": "Hello, world!",
+  "version": 3
+}
+```
+
+### Get Text Journal
+
+#### `GET /api/text/:id/journal`
+Get operation journal for text document
+
+**Query Parameters**:
+- `limit` (optional) - Number of batches to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "batches": [
+    {
+      "id": "507f...",
+      "batchId": "batch-uuid",
+      "operations": [
+        {
+          "otype": "text.insert",
+          "position": 0,
+          "value": "Hello",
+          "id": "session-1-5",
+          "content": "Hello",
+          "seq": 1
+        }
+      ],
+      "vectorClock": { "session-1": 5 },
+      "lamportTime": 5,
+      "persistedAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 20
+}
+```
+
+### Get Text Operations
+
+#### `GET /api/text/:id/operations`
+Get all text operations
+
+**Query Parameters**:
+- `limit` (optional) - Number of operations to return
+- `offset` (optional) - Pagination offset
+
+**Response**:
+```json
+{
+  "operations": [
+    {
+      "id": "507f...",
+      "opId": "op-uuid",
+      "type": "text.insert",
+      "data": {
+        "position": 0,
+        "value": "Hello",
+        "id": "session-1-5",
+        "content": "Hello",
+        "seq": 1
+      },
+      "vectorClock": { "session-1": 5 },
+      "lamportTime": 5,
+      "createdAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 100
+}
+```
+
+### Get Text Sessions
+
+#### `GET /api/text/:id/sessions`
+Get active and recent sessions for text document
+
+**Response**:
+```json
+{
+  "sessions": [
+    {
+      "id": "507f...",
+      "userId": "user-123",
+      "clientId": "client-abc",
+      "connected": true,
+      "connectedAt": "2024-01-01T00:00:00Z",
+      "lastSeenAt": "2024-01-01T12:00:00Z",
+      "presence": {
+        "cursor": { "position": 10 },
+        "selection": { "start": 5, "end": 15 }
+      }
+    }
+  ]
+}
+```
+
+### Compact Text Journal
+
+#### `POST /api/text/:id/compact`
+Trigger journal compaction for text document
+
+**Response**:
+```json
+{
+  "message": "Compaction triggered",
+  "before": { "journal": 50, "text": "..." },
+  "after": { "journal": 0, "text": "..." }
+}
+```
+
+### Coalesce Text Operations
+
+#### `POST /api/text/:id/coalesce`
+Trigger operation coalescing for text document
+
+**Response**:
+```json
+{
+  "message": "Coalescing triggered",
+  "coalescedOps": 20,
+  "resultingOps": 10
+}
+```
+
+### Delete Text Document
+
+#### `DELETE /api/text/:id`
+Permanently delete a text document
+
+**Response**:
+```json
+{
+  "message": "Text document deleted",
+  "id": "507f1f77bcf86cd799439011"
+}
+```
+
+---
+
+## Legacy Endpoints (Deprecated)
+
+For backwards compatibility, the following endpoints redirect to `/api/graph/`:
+
+- `GET /api/documents` → `GET /api/graph`
+- `GET /api/documents/:id` → `GET /api/graph/:id`
+- `GET /api/rooms/:roomId/state` → `GET /api/graph/:id/state`
+- `DELETE /api/rooms/:roomId` → `DELETE /api/graph/:id`
+
+**Note**: These will be removed in a future version. Please migrate to the new endpoints.
+
+---
+
+## Error Responses
+
+All endpoints return errors in the following format:
+
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE",
+  "details": {...}
+}
+```
+
+**Common Error Codes**:
+- `404` - Document not found
+- `400` - Invalid request
+- `500` - Internal server error
+- `403` - Forbidden (authorization failed)
+
+---
+
+## CRDT Concepts
+
+### Vector Clock
+Causal ordering mechanism - tracks the logical time for each session.
+
+```json
+{
+  "session-1": 5,
+  "session-2": 3,
+  "session-3": 7
+}
+```
+
+### Lamport Time
+Global logical clock for deterministic tie-breaking.
+
+### Journal
+Write-ahead log of all operations. Provides:
+- Reliability (operations persisted before acknowledgment)
+- Undo/redo support
+- Audit trail
+- Efficient sync (send only new operations)
+
+### Compaction
+Folding acknowledged operations into snapshot to reduce journal size.
+
+---
+
+## Rate Limiting
+
+- WebSocket connections: 100 per IP
+- REST API: 1000 requests/minute per IP
+- Journal compaction: Max 1 per document per minute
+
+---
+
+## Examples
+
+### Connecting to a Graph Document
+
+```javascript
+const ws = new WebSocket('ws://localhost:8080/ws/graph/my-room?sessionId=client-123');
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+
+  if (msg.type === 'init') {
+    console.log('Initial state:', msg.snapshot);
+    console.log('Journal:', msg.journal);
+  } else if (msg.type === 'message') {
+    console.log('Operations:', msg.ops);
+  }
+};
+
+// Send an operation
+ws.send(JSON.stringify({
+  ops: [{
+    otype: 'node.insert',
+    key: 'root',
+    path: 'children',
+    value: { key: 'cube-1', tag: 'Box' }
+  }],
+  clock: { 'client-123': 1 },
+  lamportTime: 1
+}));
+```
+
+### Connecting to a Text Document
+
+```javascript
+const ws = new WebSocket('ws://localhost:8080/ws/text/my-doc?sessionId=client-456');
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+
+  if (msg.type === 'init') {
+    console.log('Initial text:', msg.snapshot.text);
+  } else if (msg.type === 'message') {
+    console.log('Text operations:', msg.ops);
+  }
+};
+
+// Send a text insert
+ws.send(JSON.stringify({
+  ops: [{
+    otype: 'text.insert',
+    position: 0,
+    value: 'Hello, world!'
+  }],
+  clock: { 'client-456': 1 },
+  lamportTime: 1
+}));
+```
+
+---
+
+## Client Libraries
+
+### JavaScript/TypeScript
+
+```bash
+npm install @vuer-ai/vuer-rtc
+```
+
+**Graph Documents**:
+```typescript
+import { createGraph } from '@vuer-ai/vuer-rtc/client';
+
+const graph = createGraph({
+  sessionId: 'my-session',
+  onSend: (msg) => websocket.send(msg)
+});
+
+graph.onEdit({
+  key: 'root',
+  otype: 'node.insert',
+  path: 'children',
+  value: { key: 'cube-1', tag: 'Box' }
+});
+
+graph.commit();
+```
+
+**Text Documents**:
+```typescript
+import { createTextDocument } from '@vuer-ai/vuer-rtc/client';
+
+const doc = createTextDocument({
+  sessionId: 'my-session',
+  onSend: (msg) => websocket.send(msg)
+});
+
+doc.insert(0, 'Hello, world!');
+doc.commit();
+```
+
+### Python
+
+```bash
+pip install vuer-rtc
+```
+
+```python
+from vuer_rtc import GraphClient, TextClient
+
+# Graph document
+graph = GraphClient(url='ws://localhost:8080/ws/graph/my-room', session_id='py-client')
+graph.insert_node('root', 'children', {'key': 'cube-1', 'tag': 'Box'})
+
+# Text document
+text = TextClient(url='ws://localhost:8080/ws/text/my-doc', session_id='py-client')
+text.insert(0, 'Hello, world!')
+```

package/examples/compression-example.ts

@@ -55,7 +55,7 @@ async function exampleBasicCompression() {
       rootKey: 'root',
     },
     vectorClock: { session1: 100, session2: 50 },
-    lamportTime: 100,
+    lt: 100,
     journalIndex: 100,
   };
 
@@ -94,7 +94,7 @@ async function exampleVerifyIntegrity() {
       rootKey: 'root',
     },
     vectorClock: { session1: 42 },
-    lamportTime: 42,
+    lt: 42,
     journalIndex: 42,
   };
 
@@ -142,7 +142,7 @@ async function exampleCompressionStats() {
     vectorClock: Object.fromEntries(
       Array.from({ length: 10 }, (_, i) => [`session${i}`, i * 10])
     ),
-    lamportTime: 100,
+    lt: 100,
     journalIndex: 100,
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuer-ai/vuer-rtc-server",
-  "version": "0.2.3",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "description": "Vuer RTC Server — RoomBroker, WebSocket transport, MongoDB persistence",
@@ -41,7 +41,7 @@
     "@prisma/client": "^5.22.0",
     "prisma": "^5.22.0",
     "ws": "^8.19.0",
-    "@vuer-ai/vuer-rtc": "^0.3.2"
+    "@vuer-ai/vuer-rtc": "^0.8.6"
   },
   "scripts": {
     "build": "prisma generate && tsc",