livekit/cmd/test-server/README.md

LiveKit SDK test server

A stateless, per-request programmable mock of the LiveKit server HTTP API. It exists so the server SDKs (Go, Rust, Python, Node, Kotlin, Ruby) can exercise client-side behavior against one shared implementation, published as a Docker image and booted by each SDK's CI.

Why it looks the way it does

• Stateless. All behavior is selected by per-request X-Lk-Mock-* headers, so the server holds no mutable state and tests run in parallel.
• Multi-port = multi-region. The process binds one listener per simulated region (--ports). A port's position in the list is its region index; index 0 is the primary the SDK is initially pointed at. GET /settings/regions advertises all of them in order.
• One header drives every attempt. The SDK sends the same control header on the initial request and every failover retry. Each listener decides what to do from its own index, so a single X-Lk-Mock-Fail-Regions: 0 makes the primary fail while the first fallback succeeds — no coordination needed.
• The whole API is mocked with populated responses. Every RoomService, Egress, Ingress, SIP, and Connector method returns a type-correct, populated response: scalar fields that share a name with the request are echoed (e.g. name, metadata, identity, timeouts), id/sid fields get placeholder values, and list endpoints return one element. Both protobuf and JSON Twirp clients are supported. A client can override the response entirely with the X-Lk-Mock-Response header (see below). Unregistered/future methods fall back to an empty (all-default) message, which still decodes cleanly.

Running

go run ./cmd/test-server                       # primary :9999, regions :10000-10002
go run ./cmd/test-server --ports 9999,10000    # primary + one fallback

# Docker
docker build -f cmd/test-server/Dockerfile -t livekit/test-server .
docker run -p 9999-10002:9999-10002 livekit/test-server

Flag	Env	Default	Meaning
--ports	LK_TEST_SERVER_PORTS	9999,10000,10001,10002	listener ports; index = position
--advertise-host	LK_TEST_SERVER_ADVERTISE_HOST	http://127.0.0.1	base URL used in /settings/regions
--bind	LK_TEST_SERVER_BIND	0.0.0.0	bind address
--twirp-prefix	LK_TEST_SERVER_TWIRP_PREFIX	/twirp	Twirp path prefix

Control protocol

Request headers (sent by the SDK on API calls; the SDK must forward client-configured custom headers onto the /settings/regions fetch and every failover retry):

Header	Default	Effect
X-Lk-Mock-Fail-Regions	—	comma list of region indices that fail this request, e.g. 0 or 0,1. Each listener fails only if its own index is listed.
X-Lk-Mock-Fail-Mode	status	how a failing region fails: status, drop (close connection → transport error), delay.
X-Lk-Mock-Fail-Status	503	HTTP status when failing with status/delay.
X-Lk-Mock-Fail-Twirp-Code	derived from status	Twirp error code string in the failure body.
X-Lk-Mock-Delay-Ms	30000	delay before a delay-mode region responds (for timeout tests).
X-Lk-Mock-Regions-Status	200	override the status of GET /settings/regions.
X-Lk-Mock-Response	—	protojson of the response message for the called method; replaces the populated default, giving full control over the returned payload.
X-Lk-Mock-Skip-Auth	—	true disables permission enforcement for the request (use for tests that aren't about authz, e.g. failover tests with a placeholder token).

Response headers:

Header	Meaning
X-Lk-Mock-Region	index of the region that served the response (blank on a failed region). Assert on this to confirm which region a failover landed on.

Permission enforcement

Every API method requires the same token grants the real LiveKit server checks (see pkg/service/auth.go), so the mock doubles as a conformance check that an SDK attaches the right permissions automatically. Tokens are parsed and verified with the protocol's own auth helpers — the same code path the real server uses — against the mock's configured API secret (default secret, matching livekit-server --dev; override with --api-secret / LK_TEST_SERVER_API_SECRET).

• Missing, malformed, or wrongly-signed Authorization → 401 unauthenticated.
• Validly-signed token without the required grant → 403 permission_denied.
• roomAdmin-scoped methods also require the token's room to match the request's room; ForwardParticipant/MoveParticipant additionally require destinationRoom to match.

SDKs exercising permissions should sign tokens with the same API secret the mock is configured with (secret by default).

Grant	Methods
video.roomCreate	CreateRoom, DeleteRoom, all Connector calls
video.roomList	ListRooms
video.roomRecord	all Egress methods
video.ingressAdmin	all Ingress methods
video.roomAdmin (+ room)	room participant/data/metadata methods, AgentDispatchService methods
video.roomAdmin (+ room + destinationRoom)	ForwardParticipant, MoveParticipant
sip.admin	SIP trunk & dispatch-rule CRUD
sip.call	CreateSIPParticipant; TransferSIPParticipant (also needs roomAdmin)

Send X-Lk-Mock-Skip-Auth: true to bypass enforcement for tests that aren't about permissions.

Common recipes

Goal	Headers
Happy path	valid token with the method's grant → 200 from region 0
Bypass auth (failover tests)	X-Lk-Mock-Skip-Auth: true
Missing-permission error	token without the required grant → 403
Failover succeeds on region 1	X-Lk-Mock-Fail-Regions: 0
Exhaust to region 2	X-Lk-Mock-Fail-Regions: 0,1
All regions down	X-Lk-Mock-Fail-Regions: 0,1,2,3
4xx, no retry	X-Lk-Mock-Fail-Regions: 0 + X-Lk-Mock-Fail-Status: 400
Transport-error failover	X-Lk-Mock-Fail-Regions: 0 + X-Lk-Mock-Fail-Mode: drop
Region discovery unreachable	X-Lk-Mock-Regions-Status: 500
Custom response payload	X-Lk-Mock-Response: {"sid":"RM_x","name":"my-room"}

Note: SDK region failover normally only engages for *.livekit.cloud hosts. Since tests point at 127.0.0.1, set the SDK's failover-enable option to its forced-on value so failover engages against localhost.