feat: auto failover APIs with LK Cloud

.github/workflows/generate-protobufs.yml

@@ -0,0 +1,82 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Regenerates the vendored protobuf/Twirp stubs (lib/livekit/proto) from the
+# `protocol` submodule and commits them back, so generated code is never
+# produced on a developer's machine. Runs on PRs that bump the submodule (or
+# change the generation task) and commits the regenerated files onto the PR
+# branch; also available on demand.
+
+name: Generate Protobufs
+
+permissions:
+  contents: write
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [main]
+    paths:
+      - "protocol"
+      - "Rakefile"
+      - ".github/workflows/generate-protobufs.yml"
+
+concurrency:
+  group: generate-protobufs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    # Actions cannot push to a fork's branch, so skip generation there. The
+    # checked-in files are still validated by the gem's test workflow.
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          # Commit regenerated files back onto the PR branch (or the dispatched branch).
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1.190.0
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+
+      - name: Install protoc
+        uses: arduino/setup-protoc@v3
+        with:
+          version: "30.2"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install protoc-gen-twirp_ruby
+        run: go install github.com/arthurnn/twirp-ruby/protoc-gen-twirp_ruby@v1.14.1
+
+      - name: Generate protobufs
+        run: |
+          export PATH="$(go env GOPATH)/bin:$PATH"
+          bundle exec rake proto
+
+      - name: Commit regenerated protobufs
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: regenerate protobufs"
+          file_pattern: "lib/livekit/proto/**"

.github/workflows/test-api.yml

@@ -0,0 +1,43 @@
+name: Test API
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  failover:
+    runs-on: ubuntu-latest
+    services:
+      mock-server:
+        image: livekit/test-server:latest
+        ports:
+          - 9999:9999
+          - 10000:10000
+          - 10001:10001
+          - 10002:10002
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1.190.0
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Wait for mock server
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf http://127.0.0.1:9999/settings/regions >/dev/null && exit 0
+            sleep 1
+          done
+          echo "mock server did not become ready" && exit 1
+
+      - name: Run API tests
+        run: bundle exec rspec spec/api

.github/workflows/test.yml

@@ -1,4 +1,7 @@
-on: [push, pull_request]
+on:
+  push:
+    branches: [main]
+  pull_request:
 name: Test
 jobs:
   test:
@@ -7,17 +10,17 @@ jobs:
     strategy:
       matrix:
         include:
-          - { os: ubuntu-latest, ruby_version: "3.0" }
-          - { os: ubuntu-latest, ruby_version: "3.3" }
+          # Ruby 3.1 is the floor (google-protobuf 4.x requires >= 3.1; 3.0 is EOL).
+          - { os: ubuntu-latest, ruby_version: "3.1" }
+          - { os: ubuntu-latest, ruby_version: "3.4" }
           - { os: ubuntu-latest, ruby_version: "jruby-9.4" }
     steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
       - name: Setup Ruby, JRuby and TruffleRuby
-        uses: ruby/setup-ruby@v1.190.0
+        uses: ruby/setup-ruby@v1.315.0
         with:
-          bundler: 1
           ruby-version: ${{ matrix.ruby_version }}
-      - name: Checkout code
-        uses: actions/checkout@v2
       - name: Run tests
         run: |
           gem install bundler:2.3.7

Gemfile.lock

@@ -1,68 +1,90 @@
 PATH
   remote: .
   specs:
-    livekit-server-sdk (0.8.3)
+    livekit-server-sdk (0.9.0)
       google-protobuf (~> 4.30, >= 4.30.2)
       jwt (>= 2.2.3, < 3.0)
       twirp (~> 1.13, >= 1.13.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    base64 (0.2.0)
-    bigdecimal (3.1.9)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    bigdecimal (4.1.2-java)
     coderay (1.1.3)
-    diff-lcs (1.5.0)
-    faraday (2.13.1)
+    diff-lcs (1.6.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
-    faraday-net_http (3.4.0)
-      net-http (>= 0.5.0)
-    google-protobuf (4.30.2)
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
+    ffi (1.17.4-java)
+    ffi-compiler (1.4.2)
+      ffi (>= 1.15.5)
+      rake
+    google-protobuf (4.35.1)
       bigdecimal
-      rake (>= 13)
-    google-protobuf (4.30.2-x86_64-linux)
+      rake (~> 13.3)
+    google-protobuf (4.35.1-java)
       bigdecimal
-      rake (>= 13)
-    json (2.11.3)
-    jwt (2.8.2)
+      ffi (~> 1)
+      ffi-compiler (~> 1)
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    io-console (0.8.2)
+    io-console (0.8.2-java)
+    json (2.20.0)
+    json (2.20.0-java)
+    jwt (2.10.3)
       base64
     logger (1.7.0)
-    method_source (1.0.0)
-    net-http (0.6.0)
-      uri
-    pry (0.14.2)
+    method_source (1.1.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    pry (0.16.0)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+      reline (>= 0.6.0)
+    pry (0.16.0-java)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    pry-doc (1.4.0)
+      reline (>= 0.6.0)
+      spoon (~> 0.0)
+    pry-doc (1.7.0)
       pry (~> 0.11)
-      yard (~> 0.9.11)
-    rack (3.1.13)
-    rake (13.2.1)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.1)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
+      yard (~> 0.9.21)
+    rack (3.2.6)
+    rake (13.4.2)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.3)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    spoon (0.0.6)
+      ffi
     twirp (1.13.1)
       faraday (< 3)
       google-protobuf (>= 3.25, < 5.a)
       rack (>= 2.2.3)
-    uri (1.0.3)
-    webrick (1.7.0)
-    yard (0.9.28)
-      webrick (~> 1.7.0)
+    uri (1.1.1)
+    yard (0.9.44)
 
 PLATFORMS
+  java
   ruby
   x86_64-linux
 
@@ -75,4 +97,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.3.7
+   2.6.9

Rakefile

@@ -7,7 +7,7 @@ task default: %i[spec]
 
 desc "Generate protobuf stubs"
 task :proto do
-  system("protoc",
+  ok = system("protoc",
          "--proto_path=protocol/protobufs",
          "--ruby_out=lib/livekit/proto",
          "--twirp_ruby_out=lib/livekit/proto",
@@ -20,6 +20,11 @@ task :proto do
          "./protocol/protobufs/livekit_metrics.proto",
          "./protocol/protobufs/livekit_models.proto",
          "./protocol/protobufs/livekit_room.proto",
+         "./protocol/protobufs/livekit_rtc.proto",
          "./protocol/protobufs/livekit_webhook.proto",
+         "./protocol/protobufs/livekit_connector.proto",
+         "./protocol/protobufs/livekit_connector_twilio.proto",
+         "./protocol/protobufs/livekit_connector_whatsapp.proto",
          "./protocol/protobufs/logger/options.proto")
+  abort("protoc failed to generate protobuf stubs") unless ok
 end

lib/livekit.rb

@@ -13,3 +13,4 @@
 require "livekit/ingress_service_client"
 require "livekit/sip_service_client"
 require "livekit/agent_dispatch_service_client"
+require "livekit/connector_service_client"

lib/livekit/agent_dispatch_service_client.rb

@@ -1,6 +1,7 @@
 require "livekit/proto/livekit_agent_dispatch_twirp"
 require "livekit/auth_mixin"
 require 'livekit/utils'
+require 'livekit/failover'
 
 module LiveKit
   # Client for LiveKit's Agent Dispatch Service, which manages agent assignments to rooms
@@ -10,8 +11,8 @@ class AgentDispatchServiceClient < Twirp::Client
     include AuthMixin
     attr_accessor :api_key, :api_secret
 
-    def initialize(base_url, api_key: nil, api_secret: nil)
-      super(File.join(Utils.to_http_url(base_url), "/twirp"))
+    def initialize(base_url, api_key: nil, api_secret: nil, failover: true)
+      super(LiveKit::Failover.connection(base_url, failover))
       @api_key = api_key
       @api_secret = api_secret
     end
@@ -53,7 +54,7 @@ def delete_dispatch(dispatch_id, room_name)
       self.rpc(
         :DeleteDispatch,
         request,
-        headers: auth_header(VideoGrant.new(roomAdmin: true, room: room_name)),
+        headers: auth_header(video_grant: VideoGrant.new(roomAdmin: true, room: room_name)),
       )
     end
 
@@ -69,7 +70,7 @@ def get_dispatch(dispatch_id, room_name)
       res = self.rpc(
         :ListDispatch,
         request,
-        headers: auth_header(VideoGrant.new(roomAdmin: true, room: room_name)),
+        headers: auth_header(video_grant: VideoGrant.new(roomAdmin: true, room: room_name)),
       )
       if res.agent_dispatches.size > 0
         return res.agent_dispatches[0]
@@ -87,7 +88,7 @@ def list_dispatch(room_name)
       res = self.rpc(
         :ListDispatch,
         request,
-        headers: auth_header(VideoGrant.new(roomAdmin: true, room: room_name)),
+        headers: auth_header(video_grant: VideoGrant.new(roomAdmin: true, room: room_name)),
       )
       res.agent_dispatches
     end