remove options to simplify

davidzhao · davidzhao · commit a1436224e30a · 2026-06-28T16:41:29.000+02:00
diff --git a/livekit-api/livekit/api/__init__.py b/livekit-api/livekit/api/__init__.py
@@ -38,7 +38,6 @@
 
 from .twirp_client import TwirpError, TwirpErrorCode
 from .livekit_api import LiveKitAPI
-from ._failover import FailoverOptions
 from .access_token import (
     InferenceGrants,
     ObservabilityGrants,
@@ -67,5 +66,4 @@
     "WebhookReceiver",
     "TwirpError",
     "TwirpErrorCode",
-    "FailoverOptions",
 ]
diff --git a/livekit-api/livekit/api/_failover.py b/livekit-api/livekit/api/_failover.py
@@ -24,48 +24,27 @@
 
 import time
 from dataclasses import dataclass
-from typing import Dict, List, Optional, TypedDict
+from typing import Dict, List, Optional
 from urllib.parse import urlparse
 
 import aiohttp
 
-_DEFAULT_MAX_ATTEMPTS = 3
-_DEFAULT_BACKOFF_BASE = 0.2
+FAILOVER_MAX_ATTEMPTS = 3
+FAILOVER_BACKOFF_BASE = 0.2  # seconds
 
 
-class FailoverOptions(TypedDict, total=False):
-    """Region-failover tuning, passed as the ``failover`` argument. Use it as a
-    plain dict, e.g. ``failover={"max_attempts": 5}``. All keys are optional.
-
-    Keys:
-        max_attempts: total number of attempts including the initial request —
-            the original host plus up to ``max_attempts - 1`` fallback regions.
-            Defaults to 3. Set to 1 to disable failover (a single attempt).
-        backoff_base: seconds before the first retry; each subsequent retry
-            doubles it. Defaults to 0.2.
-    """
-
-    max_attempts: int
-    backoff_base: float
-
-
-def failover_attempts(failover: Optional[FailoverOptions], host: Optional[str]) -> int:
-    """Total request attempts including the initial one; 1 means no failover.
-
-    With no config (``None``) failover is enabled only for LiveKit Cloud hosts.
-    An explicit config enables it for any host; ``max_attempts=1`` disables it.
+def failover_attempts(enabled: bool, host: Optional[str], force: bool = False) -> int:
+    """Total request attempts for a host; 1 means no failover. Failover only
+    engages when enabled and the host is a LiveKit Cloud domain. ``force``
+    bypasses the cloud-host check and is for internal testing only.
     """
-    if failover is None:
-        return _DEFAULT_MAX_ATTEMPTS if (bool(host) and is_cloud(host)) else 1  # type: ignore[arg-type]
-    return max(1, failover.get("max_attempts", _DEFAULT_MAX_ATTEMPTS))
-
-
-def failover_backoff_base(failover: Optional[FailoverOptions]) -> float:
-    return (failover or {}).get("backoff_base", _DEFAULT_BACKOFF_BASE)
+    if enabled and (force or (bool(host) and is_cloud(host))):
+        return FAILOVER_MAX_ATTEMPTS
+    return 1
 
 
 def is_cloud(host: str) -> bool:
-    # Auto mode only enables failover for LiveKit Cloud project domains.
+    # Failover only engages for LiveKit Cloud project domains.
     return host.endswith(".livekit.cloud")
 
 
diff --git a/livekit-api/livekit/api/_service.py b/livekit-api/livekit/api/_service.py
@@ -3,8 +3,6 @@
 import aiohttp
 from abc import ABC
 from .twirp_client import TwirpClient
-from ._failover import FailoverOptions
-from typing import Optional
 from .access_token import AccessToken, VideoGrants, SIPGrants
 
 AUTHORIZATION = "authorization"
@@ -17,7 +15,7 @@ def __init__(
         host: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         self._client = TwirpClient(session, host, "livekit", failover=failover)
         self.api_key = api_key
diff --git a/livekit-api/livekit/api/agent_dispatch_service.py b/livekit-api/livekit/api/agent_dispatch_service.py
@@ -8,7 +8,6 @@
     ListAgentDispatchResponse,
 )
 from ._service import Service
-from ._failover import FailoverOptions
 from .access_token import VideoGrants
 
 SVC = "AgentDispatchService"
@@ -33,7 +32,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/connector_service.py b/livekit-api/livekit/api/connector_service.py
@@ -17,8 +17,6 @@
     ConnectTwilioCallResponse,
 )
 from ._service import Service
-from ._failover import FailoverOptions
-from typing import Optional
 from .access_token import VideoGrants
 
 SVC = "Connector"
@@ -43,7 +41,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/egress_service.py b/livekit-api/livekit/api/egress_service.py
@@ -13,8 +13,6 @@
     ListEgressResponse,
 )
 from ._service import Service
-from ._failover import FailoverOptions
-from typing import Optional
 from .access_token import VideoGrants
 
 SVC = "Egress"
@@ -41,7 +39,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/ingress_service.py b/livekit-api/livekit/api/ingress_service.py
@@ -8,8 +8,6 @@
     ListIngressResponse,
 )
 from ._service import Service
-from ._failover import FailoverOptions
-from typing import Optional
 from .access_token import VideoGrants
 
 SVC = "Ingress"
@@ -36,7 +34,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/livekit_api.py b/livekit-api/livekit/api/livekit_api.py
@@ -6,7 +6,6 @@
 from .sip_service import SipService
 from .agent_dispatch_service import AgentDispatchService
 from .connector_service import ConnectorService
-from ._failover import FailoverOptions
 from typing import Any, Optional
 
 
@@ -32,7 +31,7 @@ def __init__(
         *,
         timeout: Optional[aiohttp.ClientTimeout] = None,
         session: Optional[aiohttp.ClientSession] = None,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         """Create a new LiveKitAPI instance.
 
diff --git a/livekit-api/livekit/api/room_service.py b/livekit-api/livekit/api/room_service.py
@@ -25,7 +25,6 @@
 )
 from livekit.protocol.models import Room, ParticipantInfo
 from ._service import Service
-from ._failover import FailoverOptions
 from typing import Optional
 from .access_token import VideoGrants
 
@@ -53,7 +52,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/sip_service.py b/livekit-api/livekit/api/sip_service.py
@@ -35,7 +35,6 @@
     SIPTransport,
 )
 from ._service import Service
-from ._failover import FailoverOptions
 from .access_token import VideoGrants, SIPGrants
 
 SVC = "SIP"
@@ -60,7 +59,7 @@ def __init__(
         url: str,
         api_key: str,
         api_secret: str,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
     ):
         super().__init__(session, url, api_key, api_secret, failover=failover)
 
diff --git a/livekit-api/livekit/api/twirp_client.py b/livekit-api/livekit/api/twirp_client.py
@@ -21,10 +21,9 @@
 from urllib.parse import urlparse
 
 from ._failover import (
-    FailoverOptions,
+    FAILOVER_BACKOFF_BASE,
     RegionCache,
     failover_attempts,
-    failover_backoff_base,
     host_key,
     origin_of,
     pick_next,
@@ -109,7 +108,10 @@ def __init__(
         host: str,
         pkg: str,
         prefix: str = DEFAULT_PREFIX,
-        failover: Optional[FailoverOptions] = None,
+        failover: bool = True,
+        *,
+        _failover_force: bool = False,
+        _failover_backoff: float = FAILOVER_BACKOFF_BASE,
     ) -> None:
         parse_res = urlparse(host)
         scheme = parse_res.scheme
@@ -121,7 +123,10 @@ def __init__(
         self.pkg = pkg
         self.prefix = prefix
         self._session = session
-        self._failover: Optional[FailoverOptions] = failover
+        # _failover_force / _failover_backoff are internal test-only knobs.
+        self._failover = failover
+        self._failover_force = _failover_force
+        self._failover_backoff = _failover_backoff
         self._origin = origin_of(self.host)
 
     async def request(
@@ -146,7 +151,7 @@ async def request(
         serialized_data = data.SerializeToString()
 
         host = urlparse(self._origin).hostname
-        max_attempts = failover_attempts(self._failover, host)
+        max_attempts = failover_attempts(self._failover, host, self._failover_force)
         attempted = {host_key(self._origin)}
         region_origins: Optional[List[str]] = None
         current_origin = self._origin
@@ -197,7 +202,7 @@ async def request(
                 reason,
                 next_origin,
             )
-            await asyncio.sleep(failover_backoff_base(self._failover) * (2**attempt))
+            await asyncio.sleep(self._failover_backoff * (2**attempt))
             attempted.add(host_key(next_origin))
             current_origin = next_origin
 
diff --git a/tests/api/test_failover.py b/tests/api/test_failover.py
@@ -30,17 +30,11 @@
 import aiohttp
 import pytest
 
-from typing import Optional
-
-from livekit.api import CreateRoomRequest, FailoverOptions, Room, TwirpError
+from livekit.api import CreateRoomRequest, Room, TwirpError
 from livekit.api.twirp_client import TwirpClient
 
 BASE = os.getenv("LK_TEST_SERVER_URL", "http://127.0.0.1:9999")
 
-# An explicit config enables failover on any host (the non-cloud mock) with a
-# tiny backoff so the tests run fast.
-FORCED: FailoverOptions = {"max_attempts": 3, "backoff_base": 0.001}
-
 
 def _server_up() -> bool:
     try:
@@ -55,9 +49,18 @@ def _server_up() -> bool:
 )
 
 
-async def _call(directives: dict, failover: Optional[FailoverOptions] = FORCED) -> Room:
+# _failover_force bypasses the cloud-host check (the mock is on 127.0.0.1) and a
+# tiny backoff keeps the tests fast — both are internal, test-only knobs.
+async def _call(directives: dict, *, failover: bool = True, force: bool = True) -> Room:
     async with aiohttp.ClientSession() as session:
-        client = TwirpClient(session, BASE, "livekit", failover=failover)
+        client = TwirpClient(
+            session,
+            BASE,
+            "livekit",
+            failover=failover,
+            _failover_force=force,
+            _failover_backoff=0.001,
+        )
         headers = {"authorization": "Bearer test-token", **directives}
         return await client.request("RoomService", "CreateRoom", CreateRoomRequest(), headers, Room)
 
@@ -94,13 +97,13 @@ def test_region_discovery_unreachable():
         asyncio.run(_call({"x-lk-mock-fail-regions": "0", "x-lk-mock-regions-status": "500"}))
 
 
-def test_disabled_for_non_cloud():
-    # Default (None) against 127.0.0.1 (non-cloud) must not fail over.
+def test_not_cloud_host():
+    # Enabled but not forced; 127.0.0.1 is not a cloud host, so no failover.
     with pytest.raises(TwirpError):
-        asyncio.run(_call({"x-lk-mock-fail-regions": "0"}, failover=None))
+        asyncio.run(_call({"x-lk-mock-fail-regions": "0"}, force=False))
 
 
-def test_explicitly_disabled():
-    # max_attempts=1 (a single attempt) disables failover even with a config.
+def test_disabled():
+    # failover=False disables failover entirely.
     with pytest.raises(TwirpError):
-        asyncio.run(_call({"x-lk-mock-fail-regions": "0"}, failover={"max_attempts": 1}))
+        asyncio.run(_call({"x-lk-mock-fail-regions": "0"}, failover=False))
