Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .fernignore
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions examples/17-transcription-live-reconnect.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 18 additions & 7 deletions src/deepgram/core/websocket_compat.py
Original file line number Diff line number Diff line change
@@ -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]
16 changes: 7 additions & 9 deletions tests/custom/test_speak_v2_coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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),
Expand All @@ -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),
Expand Down
126 changes: 126 additions & 0 deletions tests/custom/test_websocket_handshake_rejection.py
Original file line number Diff line number Diff line change
@@ -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
6 changes: 4 additions & 2 deletions tests/custom/test_websocket_streaming_coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down