Extract livekit-signaling (and an unexpected eide effect, livekit-region) from livekit-api

.changeset/extract_livekit_region_crate.md

@@ -0,0 +1,9 @@
+---
+livekit-api: patch
+livekit: patch
+livekit-ffi: patch
+livekit-region: patch
+---
+
+Moves the internal region-discovery cache into a new `livekit-region` crate. No
+public API or behaviour change.

.changeset/extract_livekit_signaling_crate.md

@@ -0,0 +1,14 @@
+---
+livekit-api: patch
+livekit: patch
+livekit-ffi: patch
+livekit-signaling: patch
+---
+
+Moves the signalling client into a new `livekit-signaling` crate. livekit-api
+re-exports it under the historical `livekit_api::signal_client` path, now marked
+deprecated: it is internal SDK API, and dependents should use livekit-signaling
+directly. livekit-api no longer depends on livekit-net.
+
+Also drops two dependencies that were declared but never used: `scopeguard` and
+`bytes`.

.github/CODEOWNERS

@@ -10,3 +10,4 @@
 /livekit-wakeword/ @pham-tuan-binh
 /livekit-net/ @jhugman
 /livekit-token-source/ @MaxHeimbrock
+/livekit-signaling/ @lukasIO

.github/workflows/test-api.yml

@@ -28,8 +28,12 @@ jobs:
   # Exercise every runtime backend so a regression in one (e.g. the async/isahc
   # server API silently failing to compile) is caught. Each leg pins a single
   # runtime via --no-default-features; the mock server backs the legs that make
-  # real requests (services-*), and is a harmless no-op for the signal-client
+  # real requests (services-*), and is a harmless no-op for the livekit-signaling
   # legs, which spin up their own ephemeral listeners.
+  #
+  # The job name stays `livekit-api` even though it now also covers
+  # livekit-signaling: it is a required status check, and renaming it would break
+  # branch protection.
   livekit-api:
     runs-on: ubuntu-latest
     strategy:
@@ -40,10 +44,10 @@ jobs:
             cmd: cargo test -p livekit-api --no-default-features --features services-tokio,access-token --lib services::api_test -- --nocapture
           - name: services (async / isahc)
             cmd: cargo test -p livekit-api --no-default-features --features services-async,access-token --test services_async -- --nocapture
-          - name: signal-client (tokio)
-            cmd: cargo test -p livekit-api --no-default-features --features signal-client-tokio --lib signal_client -- --nocapture
-          - name: signal-client (async)
-            cmd: cargo test -p livekit-api --no-default-features --features signal-client-async --lib signal_client -- --nocapture
+          - name: livekit-signaling (tokio)
+            cmd: cargo test -p livekit-signaling --no-default-features --features tokio -- --nocapture
+          - name: livekit-signaling (async)
+            cmd: cargo test -p livekit-signaling --no-default-features --features async -- --nocapture
     services:
       mock-server:
         image: livekit/test-server:latest

.github/workflows/tests.yml

@@ -181,4 +181,4 @@ jobs:
         shell: bash
         run: |
           cargo test --verbose --target ${{ matrix.target }} -p livekit-net --features native-tokio
-          cargo test --verbose --target ${{ matrix.target }} -p livekit-api --features signal-client-tokio
+          cargo test --verbose --target ${{ matrix.target }} -p livekit-signaling --features native-tokio

Cargo.toml

@@ -4,6 +4,7 @@ members = [
     "livekit",
     "livekit-api",
     "livekit-protocol",
+    "livekit-region",
     "livekit-common",
     "livekit-data-stream",
     "livekit-ffi",
@@ -14,6 +15,7 @@ members = [
     "livekit-ffi-node-bindings",
     "livekit-net",
     "livekit-runtime",
+    "livekit-signaling",
     "livekit-wakeword",
     "libwebrtc",
     "soxr-sys",
@@ -55,12 +57,14 @@ livekit = { version = "0.8.3", path = "livekit" }
 livekit-api = { version = "0.6.3", path = "livekit-api" }
 livekit-ffi = { version = "0.12.75", path = "livekit-ffi" }
 livekit-datatrack = { version = "0.1.13", path = "livekit-datatrack" }
+livekit-signaling = { version = "0.1.0", path = "livekit-signaling" }
 livekit-token = { version = "0.1.0", path = "livekit-token" }
 livekit-token-source = { version = "0.1.1", path = "livekit-token-source" }
 livekit-common = { version = "0.1.1", path = "livekit-common" }
 livekit-data-stream = { version = "0.1.2", path = "livekit-data-stream" }
 livekit-net = { version = "0.1.2", path = "livekit-net" }
 livekit-protocol = { version = "0.7.12", path = "livekit-protocol" }
+livekit-region = { version = "0.1.0", path = "livekit-region" }
 # default-features off so each consumer selects its runtime explicitly
 # (livekit-runtime/tokio | /async | /dispatcher); otherwise the default `tokio`
 # feature is forced on everywhere and collides with `async`/`dispatcher` builds.

knope.toml

@@ -94,6 +94,24 @@ versioned_files = [
 changelog = "livekit-token/CHANGELOG.md"
 scopes = ["livekit-token"]
 
+[packages.livekit-region]
+versioned_files = [
+  "livekit-region/Cargo.toml",
+  "Cargo.lock",
+  { path = "Cargo.toml", dependency = "livekit-region" },
+]
+changelog = "livekit-region/CHANGELOG.md"
+scopes = ["livekit-region"]
+
+[packages.livekit-signaling]
+versioned_files = [
+  "livekit-signaling/Cargo.toml",
+  "Cargo.lock",
+  { path = "Cargo.toml", dependency = "livekit-signaling" },
+]
+changelog = "livekit-signaling/CHANGELOG.md"
+scopes = ["livekit-signaling"]
+
 [packages.libwebrtc]
 versioned_files = [
   "libwebrtc/Cargo.toml",

livekit-api/Cargo.toml

@@ -11,28 +11,19 @@ readme = "README.md"
 # By default ws TLS is not enabled
 default = ["services-tokio", "access-token", "webhooks"]
 
-# Signalling client, blind to the transport backend. Pulls livekit-net (no
-# backend), the tokio crate (signal_client uses tokio::sync directly), and
-# protobuf helpers. The livekit-runtime flavor comes from the signal-client-<rt>
-# wrappers below or the top crate — not here, so async/dispatcher don't collide
-# with tokio under the one-runtime guard. Needs a runtime flavor to compile, and
-# a registered livekit_net::transport() at runtime.
-signal-client = [
-    "dep:livekit-net",
-    "dep:livekit-runtime",
-    "dep:tokio",
-    "dep:base64",
-    "dep:flate2",
-    "dep:bytes",
-    "dep:serde_json",
-]
+# Signalling client. This is an internal compatibility shim: prefer depending on
+# the livekit-signaling crate directly. Enabling it here only re-exports that
+# crate under the historical `livekit_api::signal_client` path, which is marked
+# deprecated. Resolution is unchanged from when signal_client lived here:
+# livekit-signaling/native-<rt> forwards to livekit-net/native-<rt>, which
+# already folds in livekit-runtime/<rt>.
+signal-client            = ["dep:livekit-signaling"]
+signal-client-tokio      = ["signal-client", "livekit-signaling/native-tokio"]
+signal-client-async      = ["signal-client", "livekit-signaling/native-async"]
+signal-client-dispatcher = ["signal-client", "livekit-signaling/native-dispatcher"]
 
-signal-client-tokio      = ["signal-client", "livekit-net/native-tokio", "livekit-runtime/tokio"]
-signal-client-async      = ["signal-client", "livekit-net/native-async",      "livekit-runtime/async"]
-signal-client-dispatcher = ["signal-client", "livekit-net/native-dispatcher",  "livekit-runtime/dispatcher"]
-
-services-tokio = ["access-token", "dep:reqwest", "dep:tokio", "tokio/time", "dep:livekit-runtime", "livekit-runtime/tokio"]
-services-async = ["access-token", "dep:isahc", "dep:livekit-runtime", "livekit-runtime/async"]
+services-tokio = ["access-token", "dep:livekit-region", "dep:reqwest", "dep:tokio", "tokio/time", "dep:livekit-runtime", "livekit-runtime/tokio"]
+services-async = ["access-token", "dep:livekit-region", "dep:isahc", "dep:livekit-runtime", "livekit-runtime/async"]
 access-token = ["dep:livekit-token"]
 webhooks = ["access-token", "dep:serde_json", "dep:base64"]
 
@@ -57,28 +48,27 @@ webhooks = ["access-token", "dep:serde_json", "dep:base64"]
 #      the embedded certificates can expire, requiring a fresh build to update them.
 
 # Uses the platform's native TLS implementation (OpenSSL on Linux, Secure Transport on macOS, SChannel on Windows)
-native-tls              = ["livekit-net?/native-tls",             "reqwest?/native-tls"]
+native-tls              = ["livekit-signaling?/native-tls",             "reqwest?/native-tls"]
 # Same as native-tls but compiles OpenSSL from source (useful for cross-compilation)
-native-tls-vendored     = ["livekit-net?/native-tls-vendored",    "reqwest?/native-tls-vendored"]
+native-tls-vendored     = ["livekit-signaling?/native-tls-vendored",    "reqwest?/native-tls-vendored"]
 # Uses rustls with the operating system's CA certificate store.
 # Requires ca-certificates to be installed in container environments.
-rustls-tls-native-roots = ["livekit-net?/rustls-tls-native-roots", "reqwest?/rustls-tls-native-roots"]
+rustls-tls-native-roots = ["livekit-signaling?/rustls-tls-native-roots", "reqwest?/rustls-tls-native-roots"]
 # Uses rustls with Mozilla's bundled root certificates.
 # RECOMMENDED for container deployments - no system CA certificates required.
-rustls-tls-webpki-roots = ["livekit-net?/rustls-tls-webpki-roots", "reqwest?/rustls-tls-webpki-roots"]
-__rustls-tls            = ["livekit-net?/__rustls-tls",             "reqwest?/__rustls"]
+rustls-tls-webpki-roots = ["livekit-signaling?/rustls-tls-webpki-roots", "reqwest?/rustls-tls-webpki-roots"]
+__rustls-tls            = ["livekit-signaling?/__rustls-tls",             "reqwest?/__rustls"]
 
 [dependencies]
-livekit-net = { workspace = true, optional = true }
+livekit-signaling = { workspace = true, optional = true }
 livekit-protocol = { workspace = true }
+livekit-region = { workspace = true, optional = true }
 livekit-token = { workspace = true, optional = true }
-livekit-common = { workspace = true }
 thiserror = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 sha2 = "0.10"
 url = "2.3"
 log = { workspace = true }
-parking_lot = { workspace = true }
 prost = "0.12"
 pbjson-types = "0.6"
 
@@ -95,15 +85,9 @@ 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 }
 
-flate2 = { version = "1", optional = true }
-bytes = { workspace = true, optional = true }
-scopeguard = "1.2.0"
 rand = { workspace = true }
-os_info = "3.14.0"
-device-info = { workspace = true }
 
 [dev-dependencies]
 tokio = { workspace = true, features = ["rt", "rt-multi-thread", "net", "time", "macros", "io-util"] }
 # Minimal executor to drive the runtime-agnostic `services-async` (isahc) tests.
 futures = "0.3"
-async-trait = "0.1"

livekit-api/src/lib.rs

@@ -24,17 +24,23 @@ pub use livekit_token as access_token;
 #[cfg(any(feature = "services-tokio", feature = "services-async"))]
 pub mod services;
 
+// The signalling client lives in the livekit-signaling crate. Unlike
+// `access_token`, this path is NOT supported API: nothing in the workspace uses
+// it any more and it exists only so existing dependents keep compiling.
+//
+// The deprecation fires on `use livekit_api::signal_client;` but not on
+// `use livekit_api::signal_client::{Item}` — rustc only lints a deprecated
+// module when it is the final path segment. `#[doc(hidden)]` keeps it out of the
+// published docs so it stops reading as blessed API.
 #[cfg(feature = "signal-client")]
-pub mod signal_client;
+#[deprecated(note = "internal SDK API; depend on livekit-signaling directly")]
+#[doc(hidden)]
+pub mod signal_client {
+    pub use livekit_signaling::*;
+}
 
 #[cfg(any(feature = "services-tokio", feature = "services-async"))]
 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", feature = "services-tokio", feature = "services-async"))]
-mod region;
-
 #[cfg(feature = "webhooks")]
 pub mod webhooks;

livekit-api/src/services/failover.rs

@@ -24,7 +24,7 @@ use std::{sync::OnceLock, time::Duration};
 use http::header::{HeaderMap, CONTENT_LENGTH, CONTENT_TYPE};
 use url::Url;
 
-use crate::region::{is_cloud_host, parse_max_age, Cached, RegionCache, RegionsResponse};
+use livekit_region::{is_cloud_host, parse_max_age, Cached, RegionCache, RegionsResponse};
 
 /// Total attempts (the original request plus fallback regions) and the base
 /// retry backoff are fixed, not user-configurable, so retries can't be tuned to
@@ -119,7 +119,7 @@ pub(crate) async fn backoff_sleep(d: Duration) {
 const DISCOVERY_TIMEOUT: Duration = Duration::from_secs(2);
 
 /// Process-wide region cache for the API failover path. Owns the API instance of
-/// the shared [`RegionCache`] (which stores `http(s)` URLs; see [`crate::region`]).
+/// the shared [`RegionCache`] (which stores `http(s)` URLs; see [`livekit_region`]).
 fn region_cache() -> &'static RegionCache {
     static CACHE: OnceLock<RegionCache> = OnceLock::new();
     CACHE.get_or_init(|| RegionCache::new(RegionCache::DEFAULT_TTL))

livekit-region/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "livekit-region"
+version = "0.1.0"
+license.workspace = true
+description = "Internal region-discovery cache shared by the LiveKit signalling and server-API clients"
+edition.workspace = true
+repository.workspace = true
+readme = "README.md"
+
+[dependencies]
+serde = { workspace = true, features = ["derive"] }

livekit-region/README.md

@@ -0,0 +1,8 @@
+# LiveKit Region
+
+An internal crate holding the region-discovery cache shared by the LiveKit
+signalling client and the server-API failover path: the `/settings/regions`
+response types, the cloud-host and `Cache-Control` helpers, and `RegionCache`.
+
+To build applications with LiveKit, please use the public APIs provided by the
+[livekit](../livekit) and [livekit-api](../livekit-api) crates.