06 — Calls: go-meet and LiveKit

Roles
| Component | Responsibility |
|---|---|
| go-meet (per tenant) | Meeting domain: rooms, access (owner/admin/member, teams), lobby, invitations, recording control and post-processing, files metadata. Terminates the browser OIDC session. Owns authorization of who may do what in a room. |
| Token broker (control plane) | Signs LiveKit tokens, scoped to an exact room, for a verified tenant. The only holder of the LiveKit API secret. |
| Event router (control plane) | Receives LiveKit's single webhook stream, routes by room prefix, re-signs per tenant. |
| LiveKit SFU + Egress (shared) | Media routing and recording. Knows nothing about tenants beyond room names. |
go-meet is a drop-in replacement of the Django backend of La Suite Meet (same
/api/v1.0 contract, so the upstream React frontend works unchanged). It does
no media processing.
Why a broker: what LiveKit can and cannot enforce
Verified against LiveKit's docs and noted in the corrections in 11:
- Token
videogrants carry an exactroomname. There is no prefix or wildcard grant, so aRoomPrefixclaim (suggested in one discussion) does not exist. - Multiple API key/secret pairs are supported, but LiveKit does not authorize or route webhooks per key. A tenant holding its own secret could still mint a token for any room name.
- Self-hosted LiveKit cannot revoke issued tokens → short TTL is the control.
- Webhooks are one configured URL list with retries, not guaranteed delivery.
Therefore tenant stacks never receive an API secret. Everything that needs a signature goes through the CP.
Room naming
<slug>__<uuid> (double underscore, forbidden in slugs). The broker derives
the tenant from the verified caller token and refuses any room not under
that tenant's prefix. The UUID is go-meet's room id, so a name is globally
unique and unguessable.
Flows
Join (see diagram 06)
- Browser calls go-meet with its session cookie; go-meet authorizes access (owner/member/team/lobby/guest).
- go-meet calls
POST /internal/v1/livekit/tokenwith its service-account bearer:{ room, identity, name, permissions }. - Broker verifies caller (org id ↔ tenant slug), maps requested permissions to
a
VideoGrant(roomJoin,room,canPublish,canSubscribe,canPublishData,canUpdateOwnMetadata), signs, TTL ≤ 1 h, returns. - go-meet returns
{ livekit_url, token }; the browser connects.
Token refresh: LiveKit clients re-fetch before expiry through go-meet (same path). Rooms last as long as someone is in them; participants re-auth at TTL.
Room administration (mute, remove, update metadata)
go-meet needs to act on a live room. Two patterns are used:
| Operation | Path |
|---|---|
| Per-room admin (mute, remove, update participant, send data) | Exact-room roomAdmin token obtained from the broker, cached until TTL, used directly against LiveKit's RoomService |
Not room-scoped (CreateRoom, ListRooms) | Broker proxies the call after checking prefix; most rooms are auto-created by the first join, so this is rare |
go-meet's existing everyone_can_mute policy and participant-permission
validation stay in go-meet; LiveKit only sees the resulting grants.
Events (see diagram 06, steps 8–10)
LiveKit → broker /internal/v1/livekit/webhook. The router validates the
LiveKit signature (JWT over the body hash), extracts the slug from
room.name, looks up room_routes, and forwards the original JSON with a
tenant-specific HMAC (X-Fortspace-Signature) plus event id for dedupe. Unknown
slug → drop + metric. Delivery is at-least-once: go-meet must be idempotent on
the event id and run a periodic reconcile of its room/egress state (list via a
broker-issued token).
Egress lifecycle events arrive on the same stream (egress_started,
egress_updated, egress_ended); a per-request custom callback URL is not
relied on (unverified in LiveKit docs).
Recording and transcripts (diagram 07)
- Host starts a recording in go-meet (authorization: room administrator;
recording row
initiated). - go-meet obtains an exact-room
roomRecordtoken and calls Egress (StartRoomCompositeEgress) with the tenant-scoped S3 output (buckettenant-<slug>, tenant key). No global storage credential exists on the Egress workers (draftcompose.livekit.yamlmust dropRUSTFS_*globals). - Egress streams multipart to RustFS; SSE encrypts on write.
egress_ended→ router → go-meet; a River job moves the recording throughsaved → processed. The real Egress worker, strict production wiring and status mapping are implemented (see go-meetPROGRESS.md); end-to-end Egress/S3 playback is still a staging gate.- Optional transcription: agent reads audio with the tenant key, writes
transcripts/<id>.json|.vtt; optional deletion of raw audio per tenant policy. - go-meet posts "Recording ready" and the summary into the meeting's Matrix room (07).
- Playback: go-meet authorizes (user/team/owner) → presigned GET (15 min, tenant key) or its media-auth hook behind Traefik. Browser downloads directly; RustFS decrypts.
- Lifecycle rules expire
recordings/after 7–30 days (tenant policy); transcripts follow a separate policy.
Egress workers need SYS_ADMIN (as drafted), isolated tmpfs and CPU headroom;
scale them independently of the SFU.
go-meet prototype → multi-tenant changes
| Area | Prototype today | Change |
|---|---|---|
| IdP | Keycloak-style claims, team_ids claim | Zitadel adapter: org-id check, project-role → team mapping (03) |
| LiveKit credentials | go-meet signs tokens with LIVEKIT_API_KEY/SECRET | Replace token minting with a broker client (LiveKitSigner interface with a direct and a broker implementation; direct kept for local dev) |
| Egress storage | One global bucket in Egress config | Per-request tenant S3 output |
| Webhooks | Direct from LiveKit (single tenant) | Receive router-forwarded, tenant-signed events; verify HMAC |
| Config source | Env vars | Env vars hydrated by infisical run |
| DB | meet schema in shared platform DB | Dedicated DB meet_<slug> on a shard (schema-per-product convention stays valid for core services) |
| Room callback / subtitle | 501 stubs | Unchanged for now; tracked in go-meet PROGRESS.md |
| Matrix | n/a | New internal/integration/matrix (appservice client) |
Capacity and failure
- One LiveKit node behind frp is the current reality; a second node needs a second public media endpoint (see 09).
- Broker on the join path: ≥ 2 replicas, p99 budget < 50 ms, in-memory caches of tenant → status and the signing key.
- If the broker is down, existing calls continue; new joins fail with 503 and go-meet surfaces a friendly retry.