Skip to main content

06 — Calls: go-meet and LiveKit

Call flow Recording pipeline

Roles​

ComponentResponsibility
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 video grants carry an exact room name. There is no prefix or wildcard grant, so a RoomPrefix claim (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)​

  1. Browser calls go-meet with its session cookie; go-meet authorizes access (owner/member/team/lobby/guest).
  2. go-meet calls POST /internal/v1/livekit/token with its service-account bearer: { room, identity, name, permissions }.
  3. Broker verifies caller (org id ↔ tenant slug), maps requested permissions to a VideoGrant (roomJoin, room, canPublish, canSubscribe, canPublishData, canUpdateOwnMetadata), signs, TTL ≤ 1 h, returns.
  4. 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:

OperationPath
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)​

  1. Host starts a recording in go-meet (authorization: room administrator; recording row initiated).
  2. go-meet obtains an exact-room roomRecord token and calls Egress (StartRoomCompositeEgress) with the tenant-scoped S3 output (bucket tenant-<slug>, tenant key). No global storage credential exists on the Egress workers (draft compose.livekit.yaml must drop RUSTFS_* globals).
  3. Egress streams multipart to RustFS; SSE encrypts on write.
  4. egress_ended → router → go-meet; a River job moves the recording through saved → processed. The real Egress worker, strict production wiring and status mapping are implemented (see go-meet PROGRESS.md); end-to-end Egress/S3 playback is still a staging gate.
  5. Optional transcription: agent reads audio with the tenant key, writes transcripts/<id>.json|.vtt; optional deletion of raw audio per tenant policy.
  6. go-meet posts "Recording ready" and the summary into the meeting's Matrix room (07).
  7. 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.
  8. 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​

AreaPrototype todayChange
IdPKeycloak-style claims, team_ids claimZitadel adapter: org-id check, project-role → team mapping (03)
LiveKit credentialsgo-meet signs tokens with LIVEKIT_API_KEY/SECRETReplace token minting with a broker client (LiveKitSigner interface with a direct and a broker implementation; direct kept for local dev)
Egress storageOne global bucket in Egress configPer-request tenant S3 output
WebhooksDirect from LiveKit (single tenant)Receive router-forwarded, tenant-signed events; verify HMAC
Config sourceEnv varsEnv vars hydrated by infisical run
DBmeet schema in shared platform DBDedicated DB meet_<slug> on a shard (schema-per-product convention stays valid for core services)
Room callback / subtitle501 stubsUnchanged for now; tracked in go-meet PROGRESS.md
Matrixn/aNew 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.