diff --git a/.planning/notes/2026-10-18-livekit-server-sdk-go.md b/.planning/notes/2026-10-18-livekit-server-sdk-go.md new file mode 100644 index 00000000..2dd4fb00 --- /dev/null +++ b/.planning/notes/2026-10-18-livekit-server-sdk-go.md @@ -0,0 +1,30 @@ +# Decision: livekit/server-sdk-go/v2 for Chat video RoomService + +**Date:** 2026-10-18 +**Status:** Accepted +**Context:** Phase 19.1 plan 05 (`sm-chatvideo-plugin`), D-13 / D-14 / D-15, 19.1-RESEARCH.md Pitfall 9, 19.1-COVERAGE.md LiveKit RoomService table + +## Decision + +`sm-chatvideo-plugin` depends on `github.com/livekit/server-sdk-go/v2` at **v2.19.0** (2026-10-08, Apache-2.0) for LiveKit RoomService (create, delete, remove participant, participant count, list rooms) and as the official token-helper source. Confirmed this session: `go list -m -versions github.com/livekit/server-sdk-go/v2` lists v2.19.0 as current. + +- The official module path is **`github.com/livekit/server-sdk-go/v2`**. The v1 path `github.com/livekit/server-sdk-go` is frozen at v1.1.8 (2024-01-25) and is not used. Do not reopen the library choice. +- The frozen PHP plugin (`golem15/chatvideo` @ 25135b4) talks to LiveKit through Agence104 RoomServiceClient and mints join JWTs with firebase/jwt (`LiveKitService.php` lines 80–99). The Go port needs the same Room API surface and the same HS256 claims, not a hand-rolled Twirp client. +- The library is Apache-2.0. Transitive: `github.com/livekit/protocol`, twirp, protobuf. **Flag (Pitfall 9):** v2.19.0 also pulls `github.com/pion/webrtc/v4`, `github.com/livekit/media-sdk`, and `github.com/moby/buildkit`. Those are the realtime / media / container stack. Tests that import pion download buildkit. +- Production talks to a narrow **`RoomAPI` interface** only: `CreateRoom`, `DeleteRoom` (missing-room is a no-op), `RemoveParticipant`, `ParticipantCount` (missing-room returns 0), `ActiveRoomNames`. The official client is constructed with `lksdk.NewRoomServiceClient`. Production and tests **must not construct `lksdk.Room`** (that is the realtime WebRTC client). +- Tests ship an in-memory `RoomAPI` fake. Tests must not import pion, media-sdk, or buildkit, and must not construct `lksdk.Room`. +- HTTP to the operator URL uses **`fetchguard.Policy{Mode: fetchguard.TrustedMode}`**. The URL is operator-configured (`livekit_admin_url`, else `livekit_url` with `wss://`/`ws://` rewritten to `https://`/`http://`) and may be loopback (`http://localhost:7880`). It is never user-supplied. TrustedMode is the only fetchguard mode allowed for this hop. +- Token claims are golden against PHP `LiveKitService.php` lines 80–99: HS256; `iss` = API key; `sub` = user id string; `name`; `iat`/`nbf`/`exp` with `token_ttl` default 900; nested `video` grant `room` / `roomJoin` / `canPublish` / `canSubscribe`; optional `metadata` JSON string (avatar). Prefer `github.com/livekit/protocol/auth` `ToJWT` when it matches. **If `ToJWT` differs** (omits `name` / `nbf` / nested `video` keys, or grant JSON keys do not match PHP), mint with **`jwt/v5` `MapClaims`** copying the PHP payload, still inside the same LiveKit wrapper. `TestLiveKitTokenClaims` is the lock. + +## Related dependencies + +- `fetchguard` (in-tree) is the SSRF boundary for the operator RoomService URL: TrustedMode only. PublicOnly would refuse loopback and break a local SFU. +- `github.com/golang-jwt/jwt/v5` is already a framework dependency (v5.3.1). The golden fallback uses the same module. Chatvideo does not add a second JWT library. +- `github.com/livekit/protocol` (auth + Twirp types) arrives as a transitive of server-sdk-go/v2. Tokens actually live in `protocol/auth`; the plugin still requires the official `/v2` SDK for `NewRoomServiceClient`. + +## Consequences + +- `sm-chatvideo-plugin/go.mod` requires `github.com/livekit/server-sdk-go/v2 v2.19.0` only **after** this note exists. `go get github.com/livekit/server-sdk-go/v2@v2.19.0` must not run before this file is committed. +- The only production importer of the SDK is the RoomAPI wrapper (`classes/livekit.go`). Tests inject a fake and never construct `lksdk.Room`. +- Swapping the SDK later is a local wrapper change (D-13 reversibility). A later bump still needs a note confirming the RoomAPI surface, the pion/media-sdk/buildkit flag, TrustedMode for the operator URL, and the jwt/v5 MapClaims golden fallback. +- Config keys carry over unchanged: `livekit_url`, `livekit_api_key`, `livekit_api_secret`, `max_duration`, `token_ttl`, `livekit_admin_url`, `max_participants`, `screen_share`.