LiveKit.Twirp (LiveKit v0.1.0)

Shared HTTP transport for LiveKit's Twirp service APIs.

LiveKit server APIs are Twirp endpoints of the form POST /twirp/<protobuf service>/<method>. This module owns endpoint construction, service-token signing, protobuf encoding/decoding and error normalization, so service modules stay declarative:

LiveKit.Twirp.call(
  client,
  "livekit.RoomService",
  "ListRooms",
  %LiveKit.Proto.ListRoomsRequest{},
  LiveKit.Proto.ListRoomsResponse,
  grants: [video: %LiveKit.Grants.Video{room_list: true}]
)

Requests are sent with Content-Type: application/protobuf, Accept: application/protobuf and an Authorization: Bearer <jwt> header holding a short-lived token carrying only the requested grants.

Errors

call/6 never raises during normal operation. Every failure is returned as {:error, %LiveKit.Error{}}: Twirp JSON error bodies keep their code and meta, other HTTP failures become :http errors, connection problems become :transport or :timeout, and unparseable bodies become :decoding. Neither the service token nor the API secret is ever included in an error.

Summary

Functions

call(client, service, method, request, response_module, opts \\ [])

Performs a Twirp call.

endpoint(client, service, method)

Builds the Twirp endpoint URL for a service and method.

Functions

call(client, service, method, request, response_module, opts \\ [])

@spec call(LiveKit.Client.t(), String.t(), String.t(), struct(), module(), keyword()) ::
  {:ok, struct()} | {:error, LiveKit.Error.t()}

Performs a Twirp call.

Arguments

client - a LiveKit.Client.
service - fully qualified protobuf service, e.g. "livekit.RoomService".
method - protobuf method name, e.g. "ListRooms".
request - protobuf request struct.
response_module - protobuf module used to decode the response.
opts - options, see below.

Options

:grants - keyword list of video:, sip: and/or agent: grants required by this call. May also be given as :video_grant, :sip_grant, :agent_grant.
:identity - identity to embed in the service token.
:ttl - service token lifetime in seconds.
:clock - zero-arity clock function, for deterministic tests.
:request_options - extra Req options merged on top of the client's.

Examples

iex> client = LiveKit.Client.new!(url: "http://localhost:1", api_key: "k", api_secret: "s")
iex> {:error, error} = LiveKit.Twirp.call(client, "livekit.RoomService", "ListRooms", %{}, Map, [])
iex> error.type
:authentication

endpoint(client, service, method)

@spec endpoint(LiveKit.Client.t(), String.t(), String.t()) :: String.t()

Builds the Twirp endpoint URL for a service and method.

Examples

iex> client = LiveKit.Client.new!(url: "https://example.livekit.cloud", api_key: "k", api_secret: "s")
iex> LiveKit.Twirp.endpoint(client, "livekit.Egress", "ListEgress")
"https://example.livekit.cloud/twirp/livekit.Egress/ListEgress"