diff --git a/.fernignore b/.fernignore index caea8da9..9530a426 100644 --- a/.fernignore +++ b/.fernignore @@ -226,6 +226,14 @@ src/deepgram/core/parse_error.py src/deepgram/core/query_encoder.py +# Rejected WebSocket handshakes must raise ApiError on sync and async clients. +# websockets raises InvalidStatusCode from the legacy asyncio client and +# InvalidStatus from websockets.sync.client. The generated shim bound only the +# first, so the sync connect() paths raised a raw InvalidStatus instead of +# ApiError. The patch matches both classes and reads the status code from either. +# [temporarily frozen — remove when Fern's generated shim matches both classes] +src/deepgram/core/websocket_compat.py + # The generated metadata fallback must match the published SDK version in source # checkouts and carries a release-please marker so it is updated on release. # [temporarily frozen — remove when Fern emits a release-managed fallback] @@ -290,6 +298,7 @@ tests/custom/test_text_builder.py tests/custom/test_flux_tts_controls.py tests/custom/test_topics_intents_v7_compat.py tests/custom/test_transport.py +tests/custom/test_websocket_handshake_rejection.py tests/custom/test_websocket_streaming_coverage.py tests/custom/test_voice_agent_force_end_turn_example.py tests/typecheck/compat_aliases.py diff --git a/AGENTS.md b/AGENTS.md index 22bd9987..72980c9f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,7 @@ Current permanently frozen files: - `tests/custom/test_regen_response_fields.py` — hand-written regression test guarding response fields added by recent regenerations: `ListenV1Response/ResultsMetadata.diarize_info` (`model_uuid`, `arch`), per-word `speaker` / `speaker_confidence`, Nova-3 multilingual `languages` / `languages_hinted` / word and utterance `language`, and `ListenV2TurnInfo.trigger`. Same rationale as `test_latency_report_stt_compat.py`: `UncheckedBaseModel` + `skip_validation` makes response parsing lenient, so a future spec removal would silently turn these into `None` rather than failing. Fixtures are real captured payloads; the `trigger` cases pin the parsing contract for the values the server sends (`model` / `manual` / `timeout`) plus the absent case, which is what a deployment without ForceEndTurn enabled (self-hosted without the feature flag) returns. Live coverage of the same field lives in `tests/manual/listen/v2/force_end_turn/` - `tests/custom/test_secure_logging.py` — hand-written regression test that the `websockets` Authorization-header DEBUG logs are redacted (API key never logged in clear text) - `tests/custom/test_socket_unknown_fallback.py` — hand-written regression coverage that every generated socket client returns an unknown server frame as a dictionary; Speak V1 remains a strict expected failure until Fern fixes the undiscriminated-union coercion tracked above +- `tests/custom/test_websocket_handshake_rejection.py` — hand-written regression coverage that a rejected WebSocket handshake raises `ApiError` with the HTTP status code on every sync and async `connect()` (high-level and `with_raw_response`). It starts a real local `websockets` server that rejects the handshake, so it drives the real sync and legacy asyncio client libraries; a patched `connect` can only raise the exception class that the test selects - `tests/custom/test_speak_v2_interrupt_configure.py` — hand-written coverage for the Speak V2 barge-in / mid-stream reconfigure surface (`send_interrupt`, `send_configure`, `SpeechInterrupted`, `ConfigureSuccess`/`ConfigureFailure`, and the `speed`/`expressivity` connect params) - `tests/custom/test_voice_agent_force_end_turn_example.py` — hand-written regression coverage that the Voice Agent ForceEndTurn example waits for a rejection queued after `AgentAudioDone` - `tests/custom/test_text_builder.py`, `tests/custom/test_transport.py` — hand-written tests @@ -76,6 +77,7 @@ Current temporarily frozen files: - `src/deepgram/types/speak_settings_v1provider.py`, `src/deepgram/types/deepgram.py` — validate Agent TTS `expressivity` as `pydantic.StrictInt` so Pydantic v1 rejects fractional values instead of truncating them before they reach the API. Regression coverage in `tests/custom/test_socket_client_shims.py`. Unfreeze when Pydantic v1 support is dropped. - `src/deepgram/agent/v1/types/agent_v1settings_agent_context.py`, `src/deepgram/agent/v1/types/agent_v1settings_agent.py`, `src/deepgram/agent/v1/types/agent_v1settings.py`, `src/deepgram/agent/v1/requests/agent_v1settings_agent_context.py`, `src/deepgram/agent/v1/requests/agent_v1settings_agent.py`, `src/deepgram/agent/v1/requests/agent_v1settings.py` — backward-compat patches for the 2026-05-05 Agent Settings schema restructure. These preserve callable `AgentV1SettingsAgent(...)`, keep `AgentV1Settings.agent` accepting both that wrapper and `agent_id` strings, restore the legacy request TypedDict shapes, remap legacy `messages=[...]` / nested `context=AgentV1SettingsAgentContext(messages=[...])` usage into the new `context={"messages": [...]}` wire shape, and keep read-side `obj.messages` access working. - `src/deepgram/core/api_error.py`, `src/deepgram/core/parse_error.py` — credential redaction. Every websocket `connect()` path raises `ApiError(headers=dict(headers), ...)` with the full request headers, and both error types stringify that dict, so an unredacted `Authorization` reached `str(e)`, tracebacks, log aggregators and error trackers (which serialise attributes as well as the message). Both now mask credential values at construction via `_secure_logging.redact_sensitive_headers`, preserving non-sensitive headers (`dg-request-id`) for debugging. This is the same threat `_secure_logging.py` covers for the `websockets` DEBUG handshake logs, via the other path to it. Regression coverage in `tests/custom/test_api_error_redaction.py`. Unfreeze if the generator starts redacting credentials itself. +- `src/deepgram/core/websocket_compat.py` — rejected WebSocket handshakes must raise `ApiError` on both sync and async clients. `websockets` raises `InvalidStatusCode` (`exc.status_code`) from the legacy asyncio client and `InvalidStatus` (`exc.response.status_code`) from `websockets.sync.client`. The generated shim imports `InvalidStatusCode` first and falls back to `InvalidStatus` only on `ImportError`; the legacy name still imports on every supported `websockets` version, so the generated sync `connect()` methods (which use `websockets.sync.client`) never matched and raised a raw `InvalidStatus` for 401/429 instead of `ApiError`. The patch makes `InvalidWebSocketStatus` a tuple of both classes, so the generated `except InvalidWebSocketStatus` call sites stay unchanged, and `get_status_code` reads either layout. Regression coverage in `tests/custom/test_websocket_handshake_rejection.py`. Unfreeze when Fern's generated shim matches both exception classes. - `src/deepgram/core/query_encoder.py` — coerces Python bools to lowercase `"true"`/`"false"` before they reach `urllib.parse.urlencode` (which would otherwise produce `"True"`/`"False"` via `str()` and break websocket query strings). Only the four `*/connect()` paths call `urlencode`; HTTP raw clients hand params to httpx, which lowercases bools itself, so the patch is a no-op for the HTTP path. Once Fern's websocket codegen normalizes bools (or the spec types these as `boolean` end-to-end), this can be unfrozen. - `src/deepgram/listen/v2/types/listen_v2connected.py`, `src/deepgram/listen/v2/types/listen_v2turn_info.py`, `src/deepgram/listen/v2/types/listen_v2turn_info_words_item.py`, `src/deepgram/listen/v2/types/listen_v2configure_success.py`, `src/deepgram/listen/v2/types/listen_v2configure_success_thresholds.py`, `src/deepgram/listen/v2/types/listen_v2configure_failure.py`, `src/deepgram/listen/v2/types/listen_v2fatal_error.py`, `src/deepgram/listen/v2/types/listen_v2warning.py` — read-side compatibility for the SDK 7.7 Listen V2 response retype. Through 7.6, `V2SocketClientResponse` contained `typing.Any`, so every response was returned as a raw dict; fixing the union made responses typed models and broke callers using `response["field"]`. These generated response classes inherit the hand-written base above, preserving read-only wire-key subscript access alongside canonical attribute access. Restore direct `UncheckedBaseModel` inheritance and unfreeze these files in the next major release. - `src/deepgram/types/deepgram_listen_provider_v2.py`, `src/deepgram/agent/v1/types/agent_v1settings_agent_listen_provider.py`, `src/deepgram/agent/v1/types/agent_v1settings_agent_context_listen_provider.py` — behavioural back-compat shim for the `language_hint` -> `language_hints` rename (2026-06-15 regen). The public field was historically (incorrectly) singular and accepted a str or a list; the API field is `language_hints` (a list, and the server uses `deny_unknown_fields` so the singular key is rejected on the wire). Each carries a hand-added `model_validator(mode='before')` / `root_validator(pre=True)` that remaps a legacy `language_hint=` kwarg and drops the dead singular key. Remove and unfreeze the language alias when it is retired in a future major. diff --git a/examples/17-transcription-live-reconnect.py b/examples/17-transcription-live-reconnect.py index 290ba7a9..a97a4915 100644 --- a/examples/17-transcription-live-reconnect.py +++ b/examples/17-transcription-live-reconnect.py @@ -284,9 +284,9 @@ def run(self) -> None: try: outcome, detail = self._run_session() except (ApiError, InvalidStatus) as err: - # A rejected handshake surfaces as ApiError, or as the - # websockets library's InvalidStatus depending on the - # installed websockets version. + # A rejected handshake raises ApiError. Older SDK releases + # raised the websockets library's InvalidStatus from the + # sync client, so that is caught here as well. status = err.status_code if isinstance(err, ApiError) else err.response.status_code if status in (401, 403): # Bad credentials never fix themselves — do not retry. diff --git a/src/deepgram/core/websocket_compat.py b/src/deepgram/core/websocket_compat.py index caa6cd0e..1bab9e02 100644 --- a/src/deepgram/core/websocket_compat.py +++ b/src/deepgram/core/websocket_compat.py @@ -1,13 +1,24 @@ # This file was auto-generated by Fern from our API Definition. -try: - from websockets.exceptions import InvalidStatusCode as InvalidWebSocketStatus # type: ignore[attr-defined] +import typing + +from websockets.exceptions import InvalidStatus - def get_status_code(exc: InvalidWebSocketStatus) -> int: - return exc.status_code # type: ignore[attr-defined, union-attr] +# ``websockets`` raises a different exception for a rejected handshake on each client: +# the legacy asyncio client raises ``InvalidStatusCode`` and ``websockets.sync.client`` +# raises ``InvalidStatus``. The generated async ``connect()`` methods use the first and +# the sync ``connect()`` methods use the second, so ``except InvalidWebSocketStatus`` +# must match both. +try: + from websockets.exceptions import InvalidStatusCode # type: ignore[attr-defined] + InvalidWebSocketStatus: typing.Tuple[typing.Type[Exception], ...] = (InvalidStatusCode, InvalidStatus) except ImportError: - from websockets.exceptions import InvalidStatus as InvalidWebSocketStatus # type: ignore[assignment, no-redef] + InvalidWebSocketStatus = (InvalidStatus,) + - def get_status_code(exc: InvalidWebSocketStatus) -> int: # type: ignore[no-redef] - return exc.response.status_code # type: ignore[attr-defined, union-attr] +def get_status_code(exc: Exception) -> int: + status_code = getattr(exc, "status_code", None) + if status_code is not None: + return status_code + return exc.response.status_code # type: ignore[attr-defined] diff --git a/tests/custom/test_speak_v2_coverage.py b/tests/custom/test_speak_v2_coverage.py index 4dfb11fa..b45a31b0 100644 --- a/tests/custom/test_speak_v2_coverage.py +++ b/tests/custom/test_speak_v2_coverage.py @@ -262,9 +262,11 @@ def __call__(self, url, **kwargs): def _invalid_status_exc(): - # Build an InvalidWebSocketStatus without invoking its version-specific - # constructor; connect() reads the code via get_status_code, which we patch. - return speak_v2_client.InvalidWebSocketStatus.__new__(speak_v2_client.InvalidWebSocketStatus) + # InvalidWebSocketStatus is a tuple of the websockets handshake-rejection + # classes. Build one without invoking its version-specific constructor; + # connect() reads the code via get_status_code, which we patch. + exc_class = speak_v2_client.InvalidWebSocketStatus[0] + return exc_class.__new__(exc_class) class TestConnectHeaders: @@ -376,9 +378,7 @@ async def test_async_raw_connect_forwards_headers(self) -> None: @pytest.mark.parametrize("status,needle", [(401, "invalid credentials"), (503, "Unexpected error")]) def test_sync_raw_connect_handshake_failure(self, status: int, needle: str) -> None: - raising = _RaisingConnect( - speak_v2_raw_client.InvalidWebSocketStatus.__new__(speak_v2_raw_client.InvalidWebSocketStatus) - ) + raising = _RaisingConnect(_invalid_status_exc()) with ( patch.object(speak_v2_raw_client.websockets_sync_client, "connect", raising), patch.object(speak_v2_raw_client, "get_status_code", lambda exc: status), @@ -391,9 +391,7 @@ def test_sync_raw_connect_handshake_failure(self, status: int, needle: str) -> N @pytest.mark.parametrize("status,needle", [(401, "invalid credentials"), (503, "Unexpected error")]) async def test_async_raw_connect_handshake_failure(self, status: int, needle: str) -> None: - raising = _RaisingConnect( - speak_v2_raw_client.InvalidWebSocketStatus.__new__(speak_v2_raw_client.InvalidWebSocketStatus) - ) + raising = _RaisingConnect(_invalid_status_exc()) with ( patch.object(speak_v2_raw_client, "websockets_client_connect", raising), patch.object(speak_v2_raw_client, "get_status_code", lambda exc: status), diff --git a/tests/custom/test_websocket_handshake_rejection.py b/tests/custom/test_websocket_handshake_rejection.py new file mode 100644 index 00000000..c60437c4 --- /dev/null +++ b/tests/custom/test_websocket_handshake_rejection.py @@ -0,0 +1,126 @@ +"""Regression coverage for rejected WebSocket handshakes. + +When the server rejects the opening handshake (HTTP 401 for bad credentials, +429 for a rate limit, ...), every ``connect()`` must raise ``ApiError`` with the +HTTP status code. ``websockets`` has two exception classes for this: + +* the legacy asyncio client raises ``InvalidStatusCode`` (``exc.status_code``) +* ``websockets.sync.client`` raises ``InvalidStatus`` (``exc.response.status_code``) + +The async clients use the first and the sync clients use the second, so +``core/websocket_compat.py`` must match both. These tests start a real local +``websockets`` server that rejects the handshake. They drive the real client +libraries instead of a patched ``connect``, because a patched ``connect`` can +only raise the class that the test itself selects. +""" + +import contextlib +import http +import threading +import typing + +import pytest +from websockets.exceptions import InvalidStatus +from websockets.sync.server import serve + +from deepgram import AsyncDeepgramClient, DeepgramClient +from deepgram.core.api_error import ApiError +from deepgram.core.websocket_compat import InvalidWebSocketStatus, get_status_code +from deepgram.environment import DeepgramClientEnvironment + +# (leaf client path, connect kwargs) for every generated WebSocket surface. +WS_ENDPOINTS: typing.List[typing.Tuple[str, typing.Dict[str, typing.Any]]] = [ + ("listen.v1", {"model": "nova-3"}), + ("listen.v2", {"model": "flux-general-en"}), + ("speak.v1", {}), + ("speak.v2", {"model": "flux-alexis-en"}), + ("agent.v1", {}), +] +_WS_IDS = [endpoint[0] for endpoint in WS_ENDPOINTS] +_STATUSES = [401, 429] + + +@contextlib.contextmanager +def _rejecting_server(status: int) -> typing.Iterator[DeepgramClientEnvironment]: + """Run a local server that answers every handshake with ``status``.""" + + def _reject(connection: typing.Any, request: typing.Any) -> typing.Any: + return connection.protocol.reject(http.HTTPStatus(status), "rejected\n") + + def _handler(connection: typing.Any) -> None: # pragma: no cover - never reached + connection.close() + + server = serve(_handler, "127.0.0.1", 0, process_request=_reject) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + port = server.socket.getsockname()[1] + yield DeepgramClientEnvironment( + base=f"http://127.0.0.1:{port}", + production=f"ws://127.0.0.1:{port}", + agent=f"ws://127.0.0.1:{port}", + agent_rest=f"http://127.0.0.1:{port}", + ) + finally: + server.shutdown() + thread.join(timeout=5) + + +def _resolve(client: typing.Any, dotted_path: str) -> typing.Any: + obj = client + for part in dotted_path.split("."): + obj = getattr(obj, part) + return obj + + +@pytest.mark.parametrize("status", _STATUSES) +@pytest.mark.parametrize("leaf,kwargs", WS_ENDPOINTS, ids=_WS_IDS) +def test_sync_connect_maps_rejected_handshake_to_api_error( + leaf: str, kwargs: typing.Dict[str, typing.Any], status: int +) -> None: + with _rejecting_server(status) as environment: + client = DeepgramClient(api_key="test_api_key", environment=environment) + + with pytest.raises(ApiError) as high_level: + with _resolve(client, leaf).connect(**kwargs): + pass + assert high_level.value.status_code == status + + with pytest.raises(ApiError) as raw: + with _resolve(client, leaf).with_raw_response.connect(**kwargs): + pass + assert raw.value.status_code == status + + +@pytest.mark.parametrize("status", _STATUSES) +@pytest.mark.parametrize("leaf,kwargs", WS_ENDPOINTS, ids=_WS_IDS) +async def test_async_connect_maps_rejected_handshake_to_api_error( + leaf: str, kwargs: typing.Dict[str, typing.Any], status: int +) -> None: + with _rejecting_server(status) as environment: + client = AsyncDeepgramClient(api_key="test_api_key", environment=environment) + + with pytest.raises(ApiError) as high_level: + async with _resolve(client, leaf).connect(**kwargs): + pass + assert high_level.value.status_code == status + + with pytest.raises(ApiError) as raw: + async with _resolve(client, leaf).with_raw_response.connect(**kwargs): + pass + assert raw.value.status_code == status + + +def test_invalid_websocket_status_matches_the_sync_client_exception() -> None: + assert issubclass(InvalidStatus, InvalidWebSocketStatus) + + +def test_get_status_code_reads_both_exception_layouts() -> None: + legacy = type("_Legacy", (Exception,), {})() + legacy.status_code = 401 # type: ignore[attr-defined] + + current = type("_Current", (Exception,), {})() + current.response = type("_Response", (), {"status_code": 429})() # type: ignore[attr-defined] + + assert get_status_code(legacy) == 401 + assert get_status_code(current) == 429 diff --git a/tests/custom/test_websocket_streaming_coverage.py b/tests/custom/test_websocket_streaming_coverage.py index 4d440888..b4a656c0 100644 --- a/tests/custom/test_websocket_streaming_coverage.py +++ b/tests/custom/test_websocket_streaming_coverage.py @@ -124,8 +124,10 @@ async def __aexit__(self, *exc: typing.Any) -> bool: return False -def _make_invalid_status(code: int) -> InvalidWebSocketStatus: - exc = InvalidWebSocketStatus.__new__(InvalidWebSocketStatus) +def _make_invalid_status(code: int) -> Exception: + # InvalidWebSocketStatus is a tuple of the websockets handshake-rejection classes. + exc_class = InvalidWebSocketStatus[0] + exc = exc_class.__new__(exc_class) # Support both websockets layouts: legacy reads exc.status_code, newer reads # exc.response.status_code. exc.status_code = code # type: ignore[attr-defined]