18 KiB
Realtime Collaboration (Hocuspocus + Y.js)
Status: in_progress (novel-editor-collab-shipped, other-editors-deferred) Task-ID: #59 Phase: 05 Estimated Effort: 3-4 Wochen für Novel-Editor; weitere Editoren ca. 1 Woche pro Owner: unassigned
Problem
Die Boilerplate hat aktuell keine Mehrbenutzer-Collaboration im Editor. Wenn zwei Users gleichzeitig denselben KB-Artikel/Workflow/Rich-Text editieren, gewinnt der spätere Save und überschreibt die Änderungen des ersten (last-write-wins). Use-Cases die heute scheitern:
- Zwei CRM-User editieren gleichzeitig Contact-Notes
- Team schreibt KB-Artikel zusammen
- Workflow-Builder mit zwei Designern parallel
- Wiki-style Dokumentation
Konkurrenz-Tools (Notion, Linear, Figma) liefern das nativ. Ohne Realtime-Collab ist die Boilerplate für Teams >2 unattraktiv. Zusätzliches Symptom: keine User-Cursor / Awareness ("ich sehe Patrick tippt gerade hier"). Konkret betroffene Editoren:
- Novel-Editor in
apps/web/app/components/novel/(Rich-Text, primärer Anwendungsfall) - Spätere Erweiterung: Rows-Edit (Tabellenstruktur), Workflow-Builder (Graph-Struktur)
Depends on
05-business-features/feature-flags.md(#53) — Realtime-Feature pro Tenant via Flag aktivierbar (Gradual-Rollout + Plan-Tier-Gating)02-observability/sentry-wiring-api-worker.md(#11) — Hocuspocus-Connection-Errors landen in Sentry02-observability/opentelemetry.md(#13) — Tracing über Hocuspocus-Connection- Existierender Novel-Editor + Tiptap-Setup in
apps/web/app/components/novel/
Blocks
- Spätere Erweiterung auf andere Editoren (Rows, Workflows) — sind out-of-scope dieser Task, aber Pattern wird hier etabliert
Approach
Hocuspocus + Y.js als Standard-Stack:
- Hocuspocus-Server als separater Container (Node.js-Service). Auth via JWT-Hook gegen toolctrl-Session. Persistence-Adapter zu Postgres (Y.js-Doc als BLOB pro Resource, regelmäßiger Snapshot).
- Tiptap-Extensions im Novel-Editor —
@tiptap/extension-collaboration+@tiptap/extension-collaboration-cursor+@hocuspocus/providerclientside. Awareness mit User-Name + Avatar + Color. - Graceful-Degradation — wenn
HOCUSPOCUS_URLnicht gesetzt oder Service unreachable, Editor läuft als Single-User mit existing REST-Save (kein Bruch in Self-Hosted-Setups die das Feature nicht wollen).
Begründung der Architektur-Wahl:
- Hocuspocus statt eigenem Sync-Server: Y.js + Hocuspocus sind battle-tested in Notion-Likes (TipTap-Cloud, App-Stack); selber bauen wäre 6-Monats-Projekt.
- Separater Container statt In-Process: Hocuspocus läuft als WebSocket-Server mit persistent Connections. Wenn er im Web-App-Container mitläuft, blockiert WebSocket-Konzurrenz die Request-Pipeline. Separater Container = saubere Skalierung + unabhängiges Deploy.
- Postgres-Persistence-Adapter: wir haben bereits Postgres, kein Bedarf für Redis-Persistence (Hocuspocus-Default). Wenn später Last steigt, Migration auf Redis-Persistence einfach möglich.
- Y.js statt Operational Transform: Y.js (CRDT) ist konfliktfrei mergebar ohne zentralen Server-Reorder; OT braucht zentralen Server der alle Operations linearisiert. CRDT skaliert besser + Offline-fähig.
- Optionale Aktivierung: existing Self-Hosted-Setups dürfen Realtime einfach disablen, sonst zusätzlicher Container-Pflichtbestandteil → Friction bei Customer-Onboarding.
Implementation Steps
- Hocuspocus-Container-Setup —
apps/hocuspocus/neues Workspace-Package mitDockerfile,package.json(deps:@hocuspocus/server,@hocuspocus/extension-database,@hocuspocus/extension-logger, prisma-client),src/index.tsals Entry. Server-Config: Port 1234 (default), Auth-Hook, Database-Adapter, Logger.docker-compose.yml-Snippet hinzufügen +docker-compose.staging.ymlErweiterung.- Files:
apps/hocuspocus/Dockerfile,apps/hocuspocus/package.json,apps/hocuspocus/src/index.ts,docker-compose.yml,docker-compose.staging.yml - Commit:
05/realtime-collab: hocuspocus server container scaffold
- Files:
- Y.js-Doc-Persistence-Schema — Prisma-Model
CollabDoc { id, tenantId, resourceType (kb-article|crm-note|workflow|...), resourceId, ydocState Bytes, lastUpdatedAt, lastSnapshotAt, version Int }mit Unique-Index(tenantId, resourceType, resourceId). Migration.- Files:
prisma/schema.prisma,prisma/migrations/<ts>_collab_docs/migration.sql - Commit:
05/realtime-collab: collab doc persistence schema
- Files:
- Hocuspocus-Database-Extension — implementiert
fetch({ documentName })undstore({ documentName, state })gegenCollabDoc-Tabelle. DocumentName-Format:${tenantId}:${resourceType}:${resourceId}. Bei Fetch: BLOB laden + zurückgeben. Bei Store: Upsert mit version-increment.- Files:
apps/hocuspocus/src/extensions/database.ts, Test - Commit:
05/realtime-collab: postgres persistence adapter
- Files:
- Auth-Hook —
onAuthenticate({ token, requestParameters })-Hook in Hocuspocus. Token = signed JWT mituserId + tenantId, in Client beim Verbinden mitgegeben. Validierung gegen toolctrl-JWT-Secret (HOCUSPOCUS_SECRET). Permission-Check: hat User Zugriff auf(tenantId, resourceType, resourceId)? Lookup gegen DB-Resource-Specific-Permission-Helper (z.B. KB-Article-Permission-Check). Bei Fail: Connection refused mit 403.- Files:
apps/hocuspocus/src/extensions/auth.ts, Permission-Helpers (Shared mit Web-App viapackages/auth-permissions/oder duplicate-helpers für Container-Independence) - Commit:
05/realtime-collab: jwt auth and per-resource permission check
- Files:
- Snapshot-Strategy + Cleanup-Job — alle 10min oder alle 50 Updates: snapshot ydocState in
CollabDoc.ydocState+ UpdatelastSnapshotAt. Cleanup-Cron: alte CollabDocs ohne Connections >30 Tage werden archiviert (separate TabelleCollabDocArchive, daraus wiederherstellbar). Verhindert unbeschränktes BLOB-Wachstum.- Files:
apps/hocuspocus/src/extensions/snapshot.ts,apps/worker/src/cron/collab-cleanup.ts, Tests - Commit:
05/realtime-collab: snapshot strategy and cleanup cron
- Files:
- Tiptap-Collaboration-Extensions im Novel-Editor —
apps/web/app/components/novel/: deps hinzufügen (@tiptap/extension-collaboration,@tiptap/extension-collaboration-cursor,@hocuspocus/provider,yjs). Editor-Config erweitert: beienableCollab=true && HOCUSPOCUS_URL setinstanziiereHocuspocusProvider({ url, name: docName, token })+Collaboration.configure({ document })+CollaborationCursor.configure({ user: { name, color } }). Provider-State-Events handhaben:connected,disconnected,synced,awarenessUpdate.- Files:
apps/web/app/components/novel/Editor.tsx(oder relevante Editor-Datei), neueruseHocuspocusProvider.ts-Hook - Commit:
05/realtime-collab: integrate tiptap collaboration in novel editor
- Files:
- Awareness-UI — neben Editor user-presence-bar mit Avatar-Stack der aktuell connected User. CollaborationCursor zeigt User-Cursor mit Name-Tooltip. Color-Assignment deterministisch aus userId (Hash → HSL).
- Files:
apps/web/app/components/collab/PresenceBar.tsx, Integration in Editor-Wrapper - Commit:
05/realtime-collab: presence ui with cursor and avatar stack
- Files:
- Graceful-Degradation-Pfad — Editor-Wrapper prüft Connection-State: bei
disconnected > 10szeige subtilen Status "Offline — Änderungen werden lokal gespeichert" + fallback auf REST-Save via existing Save-Pfad. Beisyncedzeige nichts oder grünen Indikator. WennHOCUSPOCUS_URLenv nicht gesetzt: Editor läuft komplett Single-User wie vorher (kein Provider initialisiert).- Files: Update Editor-Wrapper, Status-Component
- Commit:
05/realtime-collab: graceful degradation when hocuspocus unavailable
- JWT-Issuer-Endpoint —
apps/web/app/routes/api.collab.token.tsxaction: Auth-required, gibt kurzlebigen JWT (15min TTL) mituserId+tenantId+resourceType+resourceId-Claims signed mitHOCUSPOCUS_SECRET. Client refresht alle 10min.- Files:
apps/web/app/routes/api.collab.token.tsx, Test - Commit:
05/realtime-collab: jwt token endpoint for collab auth
- Files:
- Doku —
docs/features/realtime-collaboration.md: Architektur-Diagramm, Hocuspocus-Container-Setup, Y.js-Konzept-Erklärung, Auth-Flow, Persistence-Strategie, Permission-Modell, How-to neue Editor-Integration für Phase-2 (Rows, Workflows), Troubleshooting (häufige Sync-Issues, Snapshot-Recovery).- Files:
docs/features/realtime-collaboration.md - Commit:
05/realtime-collab: docs
- Files:
Test Requirements
- Unit-Tests:
- Database-Extension:
fetch/storegegen Test-DB, Versions-Increment korrekt - Auth-Hook: valid JWT → accept; expired → refuse; wrong-tenant → refuse; missing-permission → refuse
- Snapshot-Strategy: nach N Updates wird snapshot getrigert
- JWT-Issuer: nicht-autorisierter Request → 401; autorisiert → valider Token mit korrekten Claims
- Database-Extension:
- Integration-Tests:
- Hocuspocus-Server lokal starten (testcontainer), Client connecten, Doc-Update senden → Persistenz in DB verifizieren
- Zwei Clients connecten zu gleichem Doc → Updates eines werden im anderen sichtbar (Y.js-Merge)
- Awareness: zwei Clients setzen User-State → beide sehen sich gegenseitig
- Snapshot-Recovery: Server-Restart → Doc wird aus DB rehydriert
- E2E-Tests (Playwright):
- Two-Browser-Tab-Test: User A öffnet KB-Artikel → User B öffnet selben Artikel → A tippt → B sieht innerhalb 1s; B-Cursor in A-Tab sichtbar
- Offline-Test: Hocuspocus-Container stoppen → User sieht "Offline"-Indikator → Tippt weiter → Container zurück → Re-Sync ohne Datenverlust
- Permission-Test: User C ohne Read-Permission auf Artikel → Connection refused
- Coverage-Target: 80% für
apps/hocuspocus/, 70% für Editor-Integration - Test-Files:
apps/hocuspocus/src/**/*.test.ts,apps/web/app/components/novel/*.test.tsx, E2Eapps/web/tests/e2e/collab-novel.spec.ts
NICHT als completed markieren bevor alle Tests grün sind.
Acceptance Criteria
- Hocuspocus-Container baut + läuft im docker-compose
CollabDocPrisma-Model + Migration applied- Database-Extension persistiert Y.js-Docs zuverlässig
- JWT-Auth-Hook mit Permission-Check funktional
- Snapshot-Strategy + Cleanup-Cron aktiv
- Novel-Editor mit Collaboration + Cursor + Awareness
- Presence-Bar zeigt connected Users
- Graceful-Degradation: ohne
HOCUSPOCUS_URLläuft Editor Single-User, mit Service-Down zeigt Offline-Indikator - JWT-Issuer-Endpoint mit 15min-TTL
docs/features/realtime-collaboration.mdmit Architektur + Setup + Editor-Integration-Guide.env.exampleenthältHOCUSPOCUS_URL,HOCUSPOCUS_SECRETpnpm lint,pnpm typecheck,pnpm testgrün- Coverage-Gates erfüllt
- Atomic Commits gepushed auf
agent/05-realtime-collab - Detail-MD Progress-Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
- Feature-Flag-Disable:
realtime-collab-enabledglobal oder pro Tenant. Wenn off, Editor läuft Single-User. - Env-Disable:
HOCUSPOCUS_URLaus Env entfernen → Editor-Wrapper initialisiert keinen Provider, läuft im Legacy-REST-Save-Mode. - Container-Removal: docker-compose-Service stoppen + entfernen; Web-App funktioniert vollständig weiter.
- DB-Rollback:
CollabDoc-Tabelle gefahrlos droppbar (kein anderer Code referenziert sie). - Data-Recovery bei Doc-Korruption: Snapshot-History in
CollabDocArchiveerlaubt Restore. Bei Total-Loss-Doc: User-Lokal-Y.js-State kann re-uploaded werden (out-of-scope-Notfall-Tool).
Security Notes
- JWT-Lifetime: 15min ist kompromiss zwischen Replay-Risiko und Refresh-Aufwand. Client-Refresh alle 10min minimiert Connection-Drops.
- Cross-Tenant-Doc-Access: DocumentName enthält tenantId. Auth-Hook prüft Token-Tenant vs Document-Tenant — Mismatch = refuse. Defense-in-Depth: Database-Extension prüft zusätzlich beim Store.
- Permission-Sync-Lag: User verliert Permission während Connection aktiv → Connection bleibt zunächst. Mitigation: Permission-Re-Check auf Auth-Refresh-Roundtrip alle 10min. Bei kritischer Permission-Revoke → manual Connection-Drop via API.
- Resource-Exhaustion: Hocuspocus-Connections sind langlebig. Limit per Tenant via Hocuspocus-
onConnect-Hook prüft Concurrent-Connection-Count gegen Plan-Quota. Default 50/Tenant. - CRDT-State-Bloat: unbeschränkte Edits führen zu wachsendem Y.js-State. Snapshot-Strategy + periodische Compaction (
Yjs.encodeStateAsUpdate(doc)) reduziert State-Size. - WebSocket-Endpoint öffentlich: Hocuspocus-Container exposed WebSocket-Port — sollte hinter Reverse-Proxy (Traefik/Caddy) mit TLS + ggf. Rate-Limit pro Source-IP stehen.
Subagent Recommendations
- Planning:
Plan-Subagent mit Detail-MD-Input. - Research:
Explore-Subagent: "Analysiere existing Novel-Editor in apps/web/app/components/novel — welche Extensions sind schon geladen? Wo wird Save aktuell ausgelöst? Wie kann Collaboration-Extension non-invasive eingebaut werden?" - Implementation Step 1-4 (Container + Persistence + Auth):
general-purpose-Subagent. - Implementation Step 5 (Snapshot/Cleanup):
general-purpose-Subagent. - Implementation Step 6-7 (Tiptap-Integration + Presence-UI):
general-purpose-Subagent +subframe:designfür Presence-Bar. - Implementation Step 8-9 (Degradation + JWT-Endpoint):
general-purpose-Subagent. - Tests: separater
general-purpose-Subagent inkl. Two-Browser-Playwright-Setup. - Verification:
gsd-verifier+ manueller Two-Tab-Test. - Code-Review:
gsd-code-reviewer+security-review-Skill (JWT/Permission kritisch).
Staging-Deployment-Steps
- Branch
agent/05-realtime-collabpushen - Hocuspocus-Container in Coolify als neuen Service anlegen mit:
Traefik-Label für
hocuspocus: image: <built-image-from-apps/hocuspocus> environment: - DATABASE_URL=${DATABASE_URL} - HOCUSPOCUS_SECRET=${HOCUSPOCUS_SECRET} - PORT=1234 ports: - "1234:1234" restart: unless-stopped depends_on: - postgreswss://collab.staging.toolctrl.demit TLS-Termination + Subdomain-Routing. HOCUSPOCUS_URL=wss://collab.staging.toolctrl.deundHOCUSPOCUS_SECRET=<generated>in Web-App-Env setzen- Migration
pnpm prisma migrate deploy - Staging-Test:
- Two-Browser-Test: zwei User-Sessions auf gleichem KB-Artikel → Live-Sync verifizieren
- Awareness: Cursor + Presence-Bar zeigen beide User
- Permission-Test: zweiter User mit removed-permission → Connection refused (Browser-Devtools-Network)
- Hocuspocus-Container kurzzeitig stoppen → Offline-Indikator → Container restart → Re-Sync
- Snapshot-DB-Check: nach 50+ Updates
SELECT version, lastSnapshotAt FROM "CollabDoc"zeigt Increment - WebSocket-TLS-Check:
wscat -c wss://collab.staging.toolctrl.deverbindet
- Last-Test: 10 simultane Connections auf gleichem Doc — Sync-Latenz <300ms p95
Deviations from Plan
- Step 5 (Snapshot strategy + Cleanup-Cron) deferred — initial slice ships Hocuspocus' default debounced persistence (2-10s). A follow-up will land
apps/worker/src/cron/collab-cleanup.ts+ theCollabDocArchivetable + periodicY.encodeStateAsUpdatecompaction. - Step 7 (Presence-Bar avatar-stack UI) deferred —
CollaborationCursorships live name+colour cursor labels (the most visible piece of awareness). A dedicated avatar-stack sidebar is a UI polish follow-up. - Auth permission helper integration deferred — current
onAuthenticatevalidates the JWT and matches its claims to the documentName triple. Per-resource permission helpers (e.g. KB-article read-permission check) are documented as a follow-up; the JWT already encodes the tenant scope so cross-tenant leakage is closed. - Token-refresh client logic deferred — the 15-minute JWT TTL is enforced; the editor relies on a fresh token being fetched per session today. A drop-in interval-refresh hook on
useHocuspocusProvideris the natural extension. - Rows + Workflow editor integrations deferred — the Novel-Editor lands the pattern (hook + token endpoint + Tiptap extension factory). Other editors will reuse the same primitives in their own tasks.
Progress Log
- 2026-05-17 —
66a5e9f4— hocuspocus server container scaffold (workspace app, Dockerfile, docker-compose service underrealtimeprofile, minimal Server bootstrap with Logger extension wired into @toolctrl/logger). - 2026-05-17 —
56a8d786— CollabDoc Prisma model + migration20260517145000_05_collab_docs(unique on tenantId+resourceType+resourceId, indexes on tenantId+resourceType+lastUpdatedAt and lastUpdatedAt). - 2026-05-17 —
3cd89b94— JWT auth hook in apps/hocuspocus (verifies HS256, refuses on tenant/resourceType/resourceId mismatch). 12 unit tests. - 2026-05-17 —
f99fe4f1— Postgres database extension (fetch/store against CollabDoc; max-payload guard; version increment). 8 unit tests. - 2026-05-17 —
bb845694— Novel-Editor client integration: deps (@hocuspocus/provider4.0.0,@tiptap/extension-collaboration(-cursor)2.11.5,yjs13.6.30,y-prosemirror1.3.7,y-protocols1.0.6),useHocuspocusProviderhook, conditional Collaboration + CollaborationCursor extensions, status banner, StarterKit history disabled when collab is active. 6 unit tests. - 2026-05-17 —
6f062692—POST /api/collab/tokenissues 15-min HS256 JWT, gated behindrealtime-collab-enabledfeature flag (returns 403 when off → graceful single-user fallback) andHOCUSPOCUS_AUTH_SECRETenv (returns 503 when missing). 6 unit tests. - 2026-05-17 —
1dccba6a— env catalog entries (HOCUSPOCUS_AUTH_SECRET, VITE_HOCUSPOCUS_URL, HOCUSPOCUS_URL/PORT/HOST/MAX_PAYLOAD_BYTES) +docs/features/realtime-collab.md(architecture, activation, embedding contract, graceful degradation).