feat: auto failover APIs with LK Cloud

.changeset/feat_auto_failover_apis_with_lk_cloud.md

@@ -0,0 +1,7 @@
+---
+livekit: patch
+livekit-api: minor
+livekit-ffi: patch
+---
+
+feat: auto failover APIs with LK Cloud - #1196 (@davidzhao)

.github/workflows/test-api.yml

@@ -0,0 +1,64 @@
+# 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.
+
+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:
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+        with:
+          submodules: true
+
+      - name: Setup Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
+        with:
+          cache: false
+          rustflags: ""
+
+      - name: Install Protoc
+        uses: arduino/setup-protoc@a8b67ba40b37d35169e222f3bb352603327985b6 # v2.1.0
+        with:
+          version: "25.2"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - 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: cargo test -p livekit-api --lib services::api_test -- --nocapture

livekit-api/Cargo.toml

@@ -45,8 +45,8 @@ __signal-client-async-compatible = [
 ]
 
 
-services-tokio = ["dep:reqwest"]
-services-async = ["dep:isahc"]
+services-tokio = ["dep:reqwest", "dep:tokio", "tokio/time"]
+services-async = ["dep:isahc", "dep:futures-timer"]
 access-token = ["dep:jsonwebtoken", "dep:hmac", "dep:signature"]
 webhooks = ["access-token", "dep:serde_json", "dep:base64"]
 
@@ -134,6 +134,8 @@ bytes = { workspace = true, optional = true }
 http = "1.1"
 reqwest = { version = "0.12", default-features = false, features = [ "json" ], optional = true }
 isahc = { version = "1.7.2", default-features = false, features = [ "json", "text-decoding" ], optional = true }
+# Runtime-agnostic timer for failover backoff on the non-tokio (isahc) backend.
+futures-timer = { version = "3", optional = true }
 
 flate2 = { version = "1", optional = true }
 scopeguard = "1.2.0"

livekit-api/src/http_client.rs

@@ -163,6 +163,12 @@ mod async_std {
                 self
             }
 
+            pub fn timeout(mut self, timeout: std::time::Duration) -> Self {
+                use isahc::config::Configurable;
+                self.builder = self.builder.timeout(timeout);
+                self
+            }
+
             pub async fn send(self) -> io::Result<Response> {
                 let request = self.builder.body(self.body).unwrap();
                 let response = self.client.send_async(request).await?;

livekit-api/src/lib.rs

@@ -39,6 +39,18 @@ pub mod signal_client;
 ))]
 mod http_client;
 
+// Region-discovery helpers shared by the signaling region provider
+// (signal_client::region_url_provider) and the API failover region cache
+// (services::failover).
+#[cfg(any(
+    feature = "signal-client-tokio",
+    feature = "signal-client-async",
+    feature = "signal-client-dispatcher",
+    feature = "services-tokio",
+    feature = "services-async"
+))]
+mod region;
+
 #[cfg(feature = "webhooks")]
 pub mod webhooks;