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 a single per-request X-Lk-Mock header (a JSON object), 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: {"failRegions":[0]} makes the primary fail while the first fallback succeeds — no coordination needed.
• Realistic latency. Methods that block in the real server block here too: CreateSIPParticipant with wait_until_answered and TransferSIPParticipant take ~11s before responding, so SDKs can exercise their timeouts.
• 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 response field (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

Control protocol

All behavior is driven by a single X-Lk-Mock request header whose value is a JSON object. The SDK sends the same header on API calls, on the /settings/regions fetch, and on every failover retry (it must forward client-configured custom headers onto all of them). Omit the header — or any field — for normal behavior. Every field is optional:

Example: X-Lk-Mock: {"skipAuth":true,"failRegions":[0],"failStatus":400}

Deprecated: the older per-setting headers — X-Lk-Mock-Fail-Regions, X-Lk-Mock-Fail-Mode (incl. the delay mode), X-Lk-Mock-Fail-Status, X-Lk-Mock-Fail-Twirp-Code, X-Lk-Mock-Delay-Ms, X-Lk-Mock-Regions-Status, X-Lk-Mock-Response, X-Lk-Mock-Skip-Auth — are still honored for existing clients and will be removed later. When X-Lk-Mock is also present, its fields take precedence per-field. New clients should use X-Lk-Mock only.

Response headers:

Signal connection (WebSocket) mocking

The mock also speaks enough of the LiveKit signal protocol for SDKs to run end-to-end signal-connection tests (connect, keepalive, reconnect, leave, and the failure/timeout modes a client must classify). Signal behavior is selected by a participant attribute (lk.mock) in the access token (see below) — the WebSocket client can't set request headers, so it can't carry a control header. Selecting via the token means parallel tests need no shared state.

Endpoints (both protocol versions are supported and behave identically):

• The access token is read from the access_token query param (or a Bearer Authorization header) and verified against the API secret. A missing/malformed/expired/wrongly-signed token makes validate return 401 (and the WS refuse the upgrade).
• Wire format is binary protobuf: SignalRequest in, SignalResponse out.
• The v1 embedded publisher offer (join_request connection param) is ignored — no valid offer is required.
• Keepalive uses a short pingTimeout=3s / pingInterval=1s in the join so timeout tests run fast.

Mode selection is via a participant attribute. After the token is verified, the server reads the lk.mock entry from the token's attributes claim (ClaimGrants.Attributes, a map[string]string). The value of that attribute is a stringified JSON control object whose signal field picks the behavior. The lk.mock namespace is the attribute key (dot notation, matching LiveKit's convention for internal attributes), so the value has no inner parent:

attribute key:   lk.mock
attribute value: {"signal":"no_pong"}

The control object also accepts an optional leaveAction field — a LeaveRequest_Action, given either as the number (0=DISCONNECT, 1=RESUME, 2=RECONNECT) or the enum name ("RECONNECT", case-insensitive) — that sets the action on the LeaveRequest the leave-sending modes emit (leave_when_connected, leave_first_message, leave_during_reconnect). When absent it defaults to 0 (DISCONNECT). Examples:

attribute value: {"signal":"leave_when_connected","leaveAction":"RECONNECT"}

If the lk.mock attribute is absent/empty, its value is unparseable, or its signal is unknown, the mode defaults to happy. Both the WS handlers and the validate handlers read the mode from this same attribute.

Behavior modes (any unknown/absent signal = happy):

LeaveRequests carry reason=SERVER_SHUTDOWN and action from the control's optional leaveAction (default DISCONNECT (0)).

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).

Send X-Lk-Mock: {"skipAuth":true} to bypass enforcement for tests that aren't about permissions.

Common recipes

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.