Real-time collaboration server for the Vitruv Methodologist: syncs project edits between users with Yjs over WebSockets and writes them back to the backend.
Design: vitruv-tools/Vitruv-UI-Methodologist#635
Status: in development. The server checks access, loads projects from the backend and writes changes back. The frontend doesn't use it yet.
- Clients connect over WebSocket with the y-websocket protocol (
WebsocketProviderin the browser). - The URL path names the room:
ws://localhost:1234/vsum:12joins the roomvsum:12. Everyone in a room shares one Yjs document. - Before a connection is accepted, the backend is asked for the user's role in the project (
GET /api/v1/vsums/{id}/detailswith the user's token). Viewers can read but not change the document. - When the first user opens a project, the server loads it from the backend (
GET /api/internal/v1/vsums/{id}/detailswith its own service account) into the room's document. Connections are accepted once that's done. If loading fails, the connection is rejected and that empty document is never written back; the next connection tries loading again. - Changes are written back automatically (
PUT /api/internal/v1/vsums/{id}/sync-changes): 5 seconds after the last change, at the latest every 60 seconds, when the last user leaves and when the server stops. Each writeback sends the complete state; Postgres stays the source of truth. A failed writeback keeps the changes and is reported in the document'sstatus.writebackError. It is retried with a growing delay if the backend failed or didn't answer; otherwise (e.g.400), it is tried again after the next change and when the last user leaves. An element the server can't read is reported the same way instead of being written back. - A room is dropped once its last user left and its changes are written back; a room whose changes the backend keeps rejecting stays in memory until a user fixes them or the server stops. Documents are kept in memory only, so changes from the last seconds before a crash are lost.
- The document's layout (metamodels, relations, views, positions, status) is described in
src/document.ts. GET /healthreturns200with{"status":"UP"}.
- Node.js 20 (see
.nvmrc; with nvm:nvm use) - npm
npm ci
export KEYCLOAK_URL=http://localhost:7668 KEYCLOAK_CLIENT_SECRET=dev-only-collaboration-service-secret
npm run dev # starts the server with reload on changes, on port 1234The server reads its settings from environment variables (see .env.example), e.g. PORT=4000 npm run dev.
| Variable | Default | Meaning |
|---|---|---|
PORT |
1234 |
Port for HTTP and WebSocket connections |
BACKEND_URL |
http://localhost:9811 |
Base URL of the backend |
KEYCLOAK_URL |
(required) | Base URL of Keycloak, where the server gets the token of its service account |
KEYCLOAK_REALM |
methodologist |
Keycloak realm |
KEYCLOAK_CLIENT_ID |
collaboration-service |
Client of the service account |
KEYCLOAK_CLIENT_SECRET |
(required) | Secret of that client |
| Script | What it does |
|---|---|
npm run dev |
Runs src/index.ts with reload on changes |
npm run build |
Compiles TypeScript into dist/ |
npm start |
Runs the compiled server (dist/index.js) |
npm test |
Runs the tests (npm test -- --coverage for coverage) |
npm run typecheck |
Type-checks sources and tests |
docker build -t collaboration-service .
docker run -p 1234:1234 -e KEYCLOAK_URL=http://host.docker.internal:7668 \
-e KEYCLOAK_CLIENT_SECRET=dev-only-collaboration-service-secret collaboration-service
curl http://localhost:1234/health- Reaction files of members: the backend writes the changes back as the project's owner, so it accepts only reaction files the owner uploaded or the project already uses. A reaction file a member uploaded for a new relation is rejected (
404), which blocks the writeback until the relation is removed. This needs a change in the backend. - Soft delete: soft-deleted elements are left out of the writeback, so the backend deletes them. Restoring a metamodel afterwards adds it again from the model library, without the project's own changes to its Ecore.
- Fine-granular mappings are plain JSON, replaced as a whole. If a user changes a relation's mappings at the moment the server adds new IDs to them, one of the two changes is lost.
- Outdated client documents: a client that reconnects with its old document after a room was dropped or the server restarted merges it into the newly loaded one (#11).
- Rejected changes stay in memory: a room whose changes the backend keeps rejecting stays until a user fixes them or the server stops; then they are lost.
- y-websocket version: the server part comes from
y-websocket@2(y-websocket/bin/utils). Newer releases moved it into@y/websocket-server, whose current version depends on the Yjs 14 beta, while the clients use Yjs 13. - Server code imports Yjs from
src/yjs.ts, not fromyjs: y-websocket's server part is CommonJS and loads Yjs's CommonJS build, whileimport 'yjs'would load its separate ES build. The two copies don't recognize each other's types ("Unexpected content type"). - LevelDB warnings during
npm ci: y-websocket has an optional LevelDB persistence that this server doesn't use. Its native module may print warnings or fail to build on some machines (e.g. Apple Silicon); that doesn't affect the server. - Adding dependencies: npm 10 can crash with
Cannot read properties of null (reading 'edgesOut')when resolving Vitest's peer dependencies.npm ciworks; to add or update packages, use npm 11 (npx npm@11 install <package>).