diff --git a/.changeset/api-request-timeout.md b/.changeset/api-request-timeout.md new file mode 100644 index 00000000..85f96dc0 --- /dev/null +++ b/.changeset/api-request-timeout.md @@ -0,0 +1,5 @@ +--- +"livekit-api": patch +--- + +Apply a timeout to every API request. Requests previously ignored the session timeout and waited indefinitely, so a host that accepted the connection but never answered blocked the call and prevented region failover. `LiveKitAPI(timeout=...)` now also applies when a session is supplied by the caller, giving API calls a deadline without changing the timeout of other traffic sharing that session. diff --git a/livekit-api/livekit/api/_service.py b/livekit-api/livekit/api/_service.py index cca5eeb0..5dd55933 100644 --- a/livekit-api/livekit/api/_service.py +++ b/livekit-api/livekit/api/_service.py @@ -24,8 +24,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: aiohttp.ClientTimeout | None = None, ): - self._client = TwirpClient(session, host, "livekit", failover=failover) + self._client = TwirpClient(session, host, "livekit", failover=failover, timeout=timeout) self.api_key = api_key self.api_secret = api_secret # A pre-signed token set by LiveKitAPI for token auth; sent verbatim, diff --git a/livekit-api/livekit/api/agent_dispatch_service.py b/livekit-api/livekit/api/agent_dispatch_service.py index dfd4dec6..850729ac 100644 --- a/livekit-api/livekit/api/agent_dispatch_service.py +++ b/livekit-api/livekit/api/agent_dispatch_service.py @@ -33,8 +33,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def create_dispatch(self, req: CreateAgentDispatchRequest) -> AgentDispatch: """Create an explicit dispatch for an agent to join a room. diff --git a/livekit-api/livekit/api/connector_service.py b/livekit-api/livekit/api/connector_service.py index a5ec11d1..716b9398 100644 --- a/livekit-api/livekit/api/connector_service.py +++ b/livekit-api/livekit/api/connector_service.py @@ -44,8 +44,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def dial_whatsapp_call( self, request: DialWhatsAppCallRequest diff --git a/livekit-api/livekit/api/egress_service.py b/livekit-api/livekit/api/egress_service.py index 76dce7f7..4342fa0a 100644 --- a/livekit-api/livekit/api/egress_service.py +++ b/livekit-api/livekit/api/egress_service.py @@ -15,6 +15,7 @@ ) from ._service import Service from .access_token import VideoGrants +from typing import Optional SVC = "Egress" """@private""" @@ -41,8 +42,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def start_room_composite_egress(self, start: RoomCompositeEgressRequest) -> EgressInfo: """Starts a composite recording of a room.""" diff --git a/livekit-api/livekit/api/ingress_service.py b/livekit-api/livekit/api/ingress_service.py index 40d592b1..a89b933d 100644 --- a/livekit-api/livekit/api/ingress_service.py +++ b/livekit-api/livekit/api/ingress_service.py @@ -9,6 +9,7 @@ ) from ._service import Service from .access_token import VideoGrants +from typing import Optional SVC = "Ingress" """@private""" @@ -35,8 +36,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def create_ingress(self, create: CreateIngressRequest) -> IngressInfo: return await self._client.request( diff --git a/livekit-api/livekit/api/livekit_api.py b/livekit-api/livekit/api/livekit_api.py index 8c62b649..ab6b42b4 100644 --- a/livekit-api/livekit/api/livekit_api.py +++ b/livekit-api/livekit/api/livekit_api.py @@ -49,7 +49,11 @@ def __init__( token: Pre-signed access token (read from `LIVEKIT_TOKEN` environment variable if not provided) token_provider: Async callable that returns a token for the grants of each call, in place of signing one with api_key and api_secret - timeout: Request timeout (default: 10 seconds) + timeout: Per-request timeout, applied to every API call. Defaults to + 10 seconds when this instance creates its own session. When a + `session` is supplied, it defaults to that session's timeout; + pass this to give API calls a deadline of their own without + changing the timeout of other traffic sharing the session. session: aiohttp.ClientSession instance to use for requests, if not provided, a new one will be created """ url = url or os.getenv("LIVEKIT_URL") @@ -84,12 +88,17 @@ def __init__( # the token, injected into each service below. key = api_key or "" secret = api_secret or "" - self._room = RoomService(self._session, url, key, secret, failover) - self._ingress = IngressService(self._session, url, key, secret, failover) - self._egress = EgressService(self._session, url, key, secret, failover) - self._sip = SipService(self._session, url, key, secret, failover) - self._agent_dispatch = AgentDispatchService(self._session, url, key, secret, failover) - self._connector = ConnectorService(self._session, url, key, secret, failover) + # Passed to every service so that `timeout` applies to API calls even + # when the session belongs to the caller, whose timeout is typically + # tuned for other traffic sharing that session. + self._room = RoomService(self._session, url, key, secret, failover, timeout) + self._ingress = IngressService(self._session, url, key, secret, failover, timeout) + self._egress = EgressService(self._session, url, key, secret, failover, timeout) + self._sip = SipService(self._session, url, key, secret, failover, timeout) + self._agent_dispatch = AgentDispatchService( + self._session, url, key, secret, failover, timeout + ) + self._connector = ConnectorService(self._session, url, key, secret, failover, timeout) if token or token_provider: for svc in ( @@ -122,7 +131,11 @@ def with_token( Args: token: Pre-signed access token url: LiveKit server URL (read from `LIVEKIT_URL` if not provided) - timeout: Request timeout (default: 10 seconds) + timeout: Per-request timeout, applied to every API call. Defaults to + 10 seconds when this instance creates its own session. When a + `session` is supplied, it defaults to that session's timeout; + pass this to give API calls a deadline of their own without + changing the timeout of other traffic sharing the session. session: aiohttp.ClientSession to use; a new one is created if omitted """ return cls(url, token=token, timeout=timeout, session=session, failover=failover) diff --git a/livekit-api/livekit/api/room_service.py b/livekit-api/livekit/api/room_service.py index 7981c364..9a7dff22 100644 --- a/livekit-api/livekit/api/room_service.py +++ b/livekit-api/livekit/api/room_service.py @@ -26,6 +26,7 @@ from livekit.protocol.models import Room, ParticipantInfo from ._service import Service from .access_token import VideoGrants +from typing import Optional SVC = "RoomService" """@private""" @@ -52,8 +53,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def create_room( self, diff --git a/livekit-api/livekit/api/sip_service.py b/livekit-api/livekit/api/sip_service.py index 920862c4..9b7da359 100644 --- a/livekit-api/livekit/api/sip_service.py +++ b/livekit-api/livekit/api/sip_service.py @@ -76,8 +76,9 @@ def __init__( api_key: str, api_secret: str, failover: bool = True, + timeout: Optional[aiohttp.ClientTimeout] = None, ): - super().__init__(session, url, api_key, api_secret, failover=failover) + super().__init__(session, url, api_key, api_secret, failover=failover, timeout=timeout) async def create_inbound_trunk( self, create: CreateSIPInboundTrunkRequest diff --git a/livekit-api/livekit/api/twirp_client.py b/livekit-api/livekit/api/twirp_client.py index 4fdb2735..3d807f9c 100644 --- a/livekit-api/livekit/api/twirp_client.py +++ b/livekit-api/livekit/api/twirp_client.py @@ -195,6 +195,7 @@ def __init__( prefix: str = DEFAULT_PREFIX, failover: bool = True, *, + timeout: Optional[aiohttp.ClientTimeout] = None, _failover_force: bool = False, _failover_backoff: float = FAILOVER_BACKOFF_BASE, ) -> None: @@ -208,6 +209,10 @@ def __init__( self.pkg = pkg self.prefix = prefix self._session = session + # Applies to every request this client issues, unless a call passes its + # own. Lets a caller who supplies a shared session still give the API a + # deadline of its own, without touching the session's. + self._timeout = timeout # _failover_force / _failover_backoff are internal test-only knobs. self._failover = failover self._failover_force = _failover_force @@ -237,11 +242,18 @@ async def request( headers[REQUEST_ID_HEADER] = str(uuid.uuid4()) serialized_data = data.SerializeToString() - # The effective per-attempt timeout is the per-call override, or the - # session default; used to gate failover for short requests. - effective_timeout = timeout.total if timeout else None - if effective_timeout is None and self._session.timeout is not None: - effective_timeout = self._session.timeout.total + # The per-attempt timeout is the per-call override, then this client's + # default, then the session default. aiohttp treats an explicit + # ``timeout=None`` as "no timeout at all" rather than "use the session + # default" — only a *missing* argument selects the session timeout — so + # resolve the fallback here and pass the result explicitly. + request_timeout = timeout + if request_timeout is None: + request_timeout = self._timeout + if request_timeout is None: + request_timeout = self._session.timeout + # Used to gate failover for short requests. + effective_timeout = request_timeout.total if request_timeout is not None else None host = urlparse(self._origin).hostname max_attempts = failover_attempts( self._failover, host, self._failover_force, effective_timeout @@ -263,7 +275,7 @@ async def request( error_data: Dict = {} try: async with self._session.post( - url, headers=headers, data=serialized_data, timeout=timeout + url, headers=headers, data=serialized_data, timeout=request_timeout ) as resp: if resp.status == 200: return response_class.FromString(await resp.read()) diff --git a/tests/api/test_request_timeout.py b/tests/api/test_request_timeout.py new file mode 100644 index 00000000..028a2a6f --- /dev/null +++ b/tests/api/test_request_timeout.py @@ -0,0 +1,192 @@ +# 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. + +import asyncio +import time +from typing import List, Optional + +import aiohttp +import pytest +from aiohttp import web + +from livekit.api import LiveKitAPI +from livekit.api.twirp_client import TwirpClient +from livekit.protocol.room import ListRoomsRequest, ListRoomsResponse + +API_KEY = "devkey" +API_SECRET = "secret-that-is-long-enough-000000" + +_MISSING = object() + + +class _Response: + status = 200 + + async def read(self) -> bytes: + return ListRoomsResponse().SerializeToString() + + +class _Post: + async def __aenter__(self) -> _Response: + return _Response() + + async def __aexit__(self, *exc) -> None: + return None + + +class _RecordingSession: + """Captures the timeout actually handed to aiohttp for each request.""" + + def __init__(self, timeout: aiohttp.ClientTimeout) -> None: + self.timeout = timeout + self.timeouts: List[object] = [] + + def post(self, url: str, **kwargs) -> _Post: + self.timeouts.append(kwargs.get("timeout", _MISSING)) + return _Post() + + +def _record_timeout( + session_timeout: aiohttp.ClientTimeout, + client_timeout: Optional[aiohttp.ClientTimeout] = None, + call_timeout: Optional[aiohttp.ClientTimeout] = None, +) -> object: + """Returns the timeout the client hands to aiohttp for one request.""" + session = _RecordingSession(session_timeout) + client = TwirpClient( + session, # type: ignore[arg-type] + "http://localhost:7880", + "livekit", + timeout=client_timeout, + ) + kwargs = {} if call_timeout is None else {"timeout": call_timeout} + asyncio.run( + client.request( + "RoomService", "ListRooms", ListRoomsRequest(), {}, ListRoomsResponse, **kwargs + ) + ) + assert len(session.timeouts) == 1 + return session.timeouts[0] + + +def test_session_timeout_is_forwarded_when_no_override() -> None: + """Regression: the session timeout must reach aiohttp. + + Passing ``timeout=None`` explicitly means "no timeout at all" to aiohttp, + not "use the session default" — only a missing argument selects the + session timeout. Forwarding None left every call unbounded, so a host that + accepted the connection and never answered was waited on forever. + """ + assert _record_timeout(aiohttp.ClientTimeout(total=10)) == aiohttp.ClientTimeout(total=10) + + +def test_client_default_timeout_applies() -> None: + timeout = _record_timeout( + aiohttp.ClientTimeout(total=300), + client_timeout=aiohttp.ClientTimeout(total=10), + ) + assert timeout == aiohttp.ClientTimeout(total=10) + + +def test_per_call_timeout_wins_over_client_and_session() -> None: + timeout = _record_timeout( + aiohttp.ClientTimeout(total=300), + client_timeout=aiohttp.ClientTimeout(total=10), + call_timeout=aiohttp.ClientTimeout(total=30), + ) + assert timeout == aiohttp.ClientTimeout(total=30) + + +def test_timeout_applies_to_a_caller_supplied_session() -> None: + """``timeout`` used to be ignored unless the SDK created the session.""" + + async def check() -> None: + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=300)) as session: + lk = LiveKitAPI( + "http://localhost:7880", + API_KEY, + API_SECRET, + session=session, + timeout=aiohttp.ClientTimeout(total=10), + ) + assert lk._room._client._timeout == aiohttp.ClientTimeout(total=10) + # The shared session is left alone; only API calls get the deadline. + assert session.timeout == aiohttp.ClientTimeout(total=300) + + asyncio.run(check()) + + +def test_caller_supplied_session_without_timeout_is_unchanged() -> None: + """Back-compat: no ``timeout`` means the session's own timeout still governs.""" + + async def check() -> None: + async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=300)) as session: + lk = LiveKitAPI("http://localhost:7880", API_KEY, API_SECRET, session=session) + assert lk._room._client._timeout is None + + asyncio.run(check()) + + +def test_sdk_created_session_keeps_its_ten_second_default() -> None: + async def check() -> None: + lk = LiveKitAPI("http://localhost:7880", API_KEY, API_SECRET) + try: + assert lk._session.timeout == aiohttp.ClientTimeout(total=10) + assert lk._room._client._timeout == aiohttp.ClientTimeout(total=10) + finally: + await lk.aclose() + + asyncio.run(check()) + + +@pytest.mark.parametrize("use_custom_session", [False, True]) +def test_request_fails_instead_of_hanging(use_custom_session: bool) -> None: + """End to end against a host that accepts the connection and never answers.""" + + async def check() -> None: + async def hang(request: web.Request) -> web.Response: + await asyncio.sleep(3600) + return web.Response() + + app = web.Application() + app.router.add_route("*", "/{tail:.*}", hang) + # The handler never returns, so don't let teardown wait out its + # default 60s grace period. + runner = web.AppRunner(app, shutdown_timeout=0.1) + await runner.setup() + site = web.TCPSite(runner, "127.0.0.1", 0) + await site.start() + port = runner.addresses[0][1] + + timeout = aiohttp.ClientTimeout(total=1) + session = aiohttp.ClientSession(timeout=timeout) if use_custom_session else None + lk = LiveKitAPI( + f"http://127.0.0.1:{port}", API_KEY, API_SECRET, session=session, timeout=timeout + ) + + start = time.monotonic() + try: + with pytest.raises(asyncio.TimeoutError): + # Generous ceiling: the point is that it terminates at all, and + # without the fix it would run until the wait_for cancelled it. + await asyncio.wait_for(lk.room.list_rooms(ListRoomsRequest()), 20) + assert time.monotonic() - start < 15 + finally: + await lk.aclose() + if session is not None: + await session.close() + await runner.shutdown() + await runner.cleanup() + + asyncio.run(check())