Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/05-business-features/realtime-collab.md
T

198 lines
18 KiB
Markdown

# 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 Sentry
- `02-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:
1. **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).
2. **Tiptap-Extensions im Novel-Editor** — `@tiptap/extension-collaboration` + `@tiptap/extension-collaboration-cursor` + `@hocuspocus/provider` clientside. Awareness mit User-Name + Avatar + Color.
3. **Graceful-Degradation** — wenn `HOCUSPOCUS_URL` nicht 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
1. **Hocuspocus-Container-Setup** — `apps/hocuspocus/` neues Workspace-Package mit `Dockerfile`, `package.json` (deps: `@hocuspocus/server`, `@hocuspocus/extension-database`, `@hocuspocus/extension-logger`, prisma-client), `src/index.ts` als Entry. Server-Config: Port 1234 (default), Auth-Hook, Database-Adapter, Logger. `docker-compose.yml`-Snippet hinzufügen + `docker-compose.staging.yml` Erweiterung.
- 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`
2. **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`
3. **Hocuspocus-Database-Extension** — implementiert `fetch({ documentName })` und `store({ documentName, state })` gegen `CollabDoc`-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`
4. **Auth-Hook** — `onAuthenticate({ token, requestParameters })`-Hook in Hocuspocus. Token = signed JWT mit `userId + 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 via `packages/auth-permissions/` oder duplicate-helpers für Container-Independence)
- Commit: `05/realtime-collab: jwt auth and per-resource permission check`
5. **Snapshot-Strategy + Cleanup-Job** — alle 10min oder alle 50 Updates: snapshot ydocState in `CollabDoc.ydocState` + Update `lastSnapshotAt`. Cleanup-Cron: alte CollabDocs ohne Connections >30 Tage werden archiviert (separate Tabelle `CollabDocArchive`, 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`
6. **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: bei `enableCollab=true && HOCUSPOCUS_URL set` instanziiere `HocuspocusProvider({ 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), neuer `useHocuspocusProvider.ts`-Hook
- Commit: `05/realtime-collab: integrate tiptap collaboration in novel editor`
7. **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`
8. **Graceful-Degradation-Pfad** — Editor-Wrapper prüft Connection-State: bei `disconnected > 10s` zeige subtilen Status "Offline — Änderungen werden lokal gespeichert" + fallback auf REST-Save via existing Save-Pfad. Bei `synced` zeige nichts oder grünen Indikator. Wenn `HOCUSPOCUS_URL` env 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`
9. **JWT-Issuer-Endpoint** — `apps/web/app/routes/api.collab.token.tsx` action: Auth-required, gibt kurzlebigen JWT (15min TTL) mit `userId+tenantId+resourceType+resourceId`-Claims signed mit `HOCUSPOCUS_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`
10. **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`
## Test Requirements
- **Unit-Tests:**
- Database-Extension: `fetch`/`store` gegen 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
- **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`, E2E `apps/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
- [ ] `CollabDoc` Prisma-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_URL` läuft Editor Single-User, mit Service-Down zeigt Offline-Indikator
- [ ] JWT-Issuer-Endpoint mit 15min-TTL
- [ ] `docs/features/realtime-collaboration.md` mit Architektur + Setup + Editor-Integration-Guide
- [ ] `.env.example` enthält `HOCUSPOCUS_URL`, `HOCUSPOCUS_SECRET`
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grü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-enabled` global oder pro Tenant. Wenn off, Editor läuft Single-User.
- **Env-Disable:** `HOCUSPOCUS_URL` aus 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 `CollabDocArchive` erlaubt 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:design` fü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
1. Branch `agent/05-realtime-collab` pushen
2. Hocuspocus-Container in Coolify als neuen Service anlegen mit:
```yaml
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:
- postgres
```
Traefik-Label für `wss://collab.staging.toolctrl.de` mit TLS-Termination + Subdomain-Routing.
3. `HOCUSPOCUS_URL=wss://collab.staging.toolctrl.de` und `HOCUSPOCUS_SECRET=<generated>` in Web-App-Env setzen
4. Migration `pnpm prisma migrate deploy`
5. 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.de` verbindet
6. 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` + the `CollabDocArchive` table + periodic `Y.encodeStateAsUpdate` compaction.
- **Step 7 (Presence-Bar avatar-stack UI) deferred** — `CollaborationCursor` ships 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 `onAuthenticate` validates 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 `useHocuspocusProvider` is 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 under `realtime` profile, minimal Server bootstrap with Logger extension wired into @toolctrl/logger).
- 2026-05-17 — `56a8d786` — CollabDoc Prisma model + migration `20260517145000_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/provider` 4.0.0, `@tiptap/extension-collaboration(-cursor)` 2.11.5, `yjs` 13.6.30, `y-prosemirror` 1.3.7, `y-protocols` 1.0.6), `useHocuspocusProvider` hook, conditional Collaboration + CollaborationCursor extensions, status banner, StarterKit history disabled when collab is active. 6 unit tests.
- 2026-05-17 — `6f062692` — `POST /api/collab/token` issues 15-min HS256 JWT, gated behind `realtime-collab-enabled` feature flag (returns 403 when off → graceful single-user fallback) and `HOCUSPOCUS_AUTH_SECRET` env (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).