From bc4e386309689ab4ac6379dbef2397fd5ea0d05a Mon Sep 17 00:00:00 2001 From: shijing xian Date: Fri, 20 Nov 2026 12:00:09 -0800 Subject: [PATCH] fix(api): apply a timeout to every API request MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TwirpClient.request forwarded its `timeout` argument to session.post even when it was None. aiohttp reads an explicit `timeout=None` as "no timeout at all" — only a *missing* argument selects the session timeout — so every call that did not pass its own timeout ran unbounded and the session's 10s default never applied. A host that accepts the connection and never answers therefore blocked the call forever, and region failover never started, because failover only begins once an attempt fails. The same function already read `self._session.timeout.total` to size the failover budget, so it assumed the session timeout governed the request while the post call discarded it. Resolve the timeout once, per call override -> client default -> session, and pass the result explicitly, so both uses agree. Also make `LiveKitAPI(timeout=...)` mean something when the caller supplies a session. It was read only on the path where the SDK built the session, so `LiveKitAPI(session=..., timeout=...)` silently ignored the timeout even though it is documented as the request timeout. The value now reaches TwirpClient through Service, letting a caller give API calls a deadline without changing the timeout of other traffic on a shared session. A supplied session with no explicit timeout keeps its own, as before. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/api-request-timeout.md | 5 + livekit-api/livekit/api/_service.py | 3 +- .../livekit/api/agent_dispatch_service.py | 3 +- livekit-api/livekit/api/connector_service.py | 3 +- livekit-api/livekit/api/egress_service.py | 4 +- livekit-api/livekit/api/ingress_service.py | 4 +- livekit-api/livekit/api/livekit_api.py | 29 ++- livekit-api/livekit/api/room_service.py | 4 +- livekit-api/livekit/api/sip_service.py | 3 +- livekit-api/livekit/api/twirp_client.py | 24 ++- tests/api/test_request_timeout.py | 192 ++++++++++++++++++ 11 files changed, 253 insertions(+), 21 deletions(-) create mode 100644 .changeset/api-request-timeout.md create mode 100644 tests/api/test_request_timeout.py diff --git a/.changeset/api-request-timeout.md b/.changeset/api-request-timeout.md new file mode 100644 index 000000000..85f96dc07 --- /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 cca5eeb0b..5dd559336 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 dfd4dec6f..850729ac7 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 a5ec11d1b..716b93980 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 76dce7f76..4342fa0ab 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 40d592b1e..a89b933db 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 8c62b6493..ab6b42b41 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 7981c364b..9a7dff222 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 920862c4c..9b7da3598 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 4fdb27357..3d807f9cd 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 000000000..028a2a6f9 --- /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())