golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(19.1-05): record livekit/server-sdk-go/v2 v2.19.0 before import

Browse Source 
Pin github.com/livekit/server-sdk-go/v2 v2.19.0 (Apache-2.0). Flag
pion/media-sdk/buildkit; production talks to RoomAPI only; tests ship a
fake and must not construct lksdk.Room. Operator HTTP uses fetchguard
TrustedMode. Token golden vs PHP LiveKitService.php 80-99; jwt/v5
MapClaims fallback if ToJWT differs.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Jakub Zych
2026-10-18 13:52:27 +02:00
parent 4f58c8fc2a
commit 43c4040256
1 changed files with 30 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
.planning/notes/2026-10-18-livekit-server-sdk-go.md Normal file
View File

@@ -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`.