deapi-sdk 0.6.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. deapi_sdk/__init__.py +409 -0
  2. deapi_sdk/_cards.py +313 -0
  3. deapi_sdk/_client.py +411 -0
  4. deapi_sdk/_config.py +77 -0
  5. deapi_sdk/_constants.py +61 -0
  6. deapi_sdk/_download.py +37 -0
  7. deapi_sdk/_exceptions.py +184 -0
  8. deapi_sdk/_files.py +59 -0
  9. deapi_sdk/_payload.py +50 -0
  10. deapi_sdk/_polling.py +157 -0
  11. deapi_sdk/_realtime/__init__.py +7 -0
  12. deapi_sdk/_realtime/_discovery.py +43 -0
  13. deapi_sdk/_realtime/_engine.py +419 -0
  14. deapi_sdk/_realtime/_protocol.py +152 -0
  15. deapi_sdk/_realtime/_session.py +529 -0
  16. deapi_sdk/_types.py +31 -0
  17. deapi_sdk/_version.py +3 -0
  18. deapi_sdk/py.typed +0 -0
  19. deapi_sdk/resources/__init__.py +35 -0
  20. deapi_sdk/resources/account.py +149 -0
  21. deapi_sdk/resources/audio.py +386 -0
  22. deapi_sdk/resources/embeddings.py +116 -0
  23. deapi_sdk/resources/images.py +616 -0
  24. deapi_sdk/resources/keys.py +277 -0
  25. deapi_sdk/resources/models.py +161 -0
  26. deapi_sdk/resources/ocr.py +152 -0
  27. deapi_sdk/resources/prompts.py +137 -0
  28. deapi_sdk/resources/transcription.py +308 -0
  29. deapi_sdk/resources/video.py +985 -0
  30. deapi_sdk/transcript.py +142 -0
  31. deapi_sdk/types/__init__.py +68 -0
  32. deapi_sdk/types/account.py +115 -0
  33. deapi_sdk/types/audio.py +35 -0
  34. deapi_sdk/types/common.py +174 -0
  35. deapi_sdk/types/embeddings.py +11 -0
  36. deapi_sdk/types/images.py +40 -0
  37. deapi_sdk/types/keys.py +53 -0
  38. deapi_sdk/types/ocr.py +14 -0
  39. deapi_sdk/types/prompts.py +26 -0
  40. deapi_sdk/types/transcription.py +14 -0
  41. deapi_sdk/types/video.py +84 -0
  42. deapi_sdk/types/websocket.py +36 -0
  43. deapi_sdk/webhook.py +159 -0
  44. deapi_sdk-0.6.1.dist-info/METADATA +644 -0
  45. deapi_sdk-0.6.1.dist-info/RECORD +47 -0
  46. deapi_sdk-0.6.1.dist-info/WHEEL +4 -0
  47. deapi_sdk-0.6.1.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,419 @@
1
+ """Asyncio connection engine: one WebSocket, one private channel, automatic reconnects.
2
+
3
+ The engine owns the protocol loop (handshake, channel authorization, keepalive,
4
+ reconnect policy) and fans incoming job status events out to *sinks*. A sink is
5
+ a non-blocking ``put`` callable, so a consumer can be an ``asyncio.Queue`` in the
6
+ engine's own loop or a thread-safe ``queue.Queue`` read from another thread
7
+ (that is how the synchronous :class:`~deapi_sdk.Realtime` uses it).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import asyncio
13
+ import logging
14
+ import threading
15
+ from collections.abc import Awaitable, Callable
16
+ from dataclasses import dataclass
17
+ from typing import TYPE_CHECKING, Final
18
+
19
+ from pydantic import ValidationError as PydanticValidationError
20
+
21
+ from deapi_sdk._exceptions import (
22
+ AuthenticationError,
23
+ DeapiError,
24
+ NetworkError,
25
+ PermissionDeniedError,
26
+ RateLimitError,
27
+ RealtimeError,
28
+ ServerError,
29
+ )
30
+ from deapi_sdk._realtime import _protocol as protocol
31
+ from deapi_sdk.types.common import JobStatusEvent
32
+
33
+ if TYPE_CHECKING:
34
+ from websockets.asyncio.client import ClientConnection
35
+
36
+ logger = logging.getLogger("deapi_sdk.realtime")
37
+
38
+ Authorizer = Callable[[str, str], Awaitable[str]]
39
+ """``(socket_id, channel) -> auth signature`` for a private channel subscription."""
40
+
41
+ _INSTALL_HINT = 'WebSocket support needs the optional "ws" extra: pip install "deapi-sdk[ws]"'
42
+
43
+ # Largest frame accepted. Status events can carry a base64 preview image.
44
+ _MAX_FRAME_BYTES: Final = 16 * 1024 * 1024
45
+ # How long a WebSocket close handshake may take before the connection is dropped.
46
+ _CLOSE_TIMEOUT: Final = 2.0
47
+
48
+
49
+ class _Reconnected:
50
+ """Sink item: the channel was re-subscribed after a connection loss (events may have been missed)."""
51
+
52
+ __slots__ = ()
53
+
54
+ def __repr__(self) -> str:
55
+ return "RECONNECTED"
56
+
57
+
58
+ RECONNECTED: Final = _Reconnected()
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class Closed:
63
+ """Sink item: the engine stopped. ``error`` is set when it stopped because of a fatal failure."""
64
+
65
+ error: BaseException | None = None
66
+
67
+
68
+ SinkItem = JobStatusEvent | _Reconnected | Closed
69
+ Sink = Callable[[SinkItem], None]
70
+
71
+
72
+ def require_websockets() -> None:
73
+ """Raise a helpful ImportError when the optional ``websockets`` dependency is missing."""
74
+ try:
75
+ import websockets.asyncio.client # noqa: F401
76
+ except ImportError as exc:
77
+ raise ImportError(_INSTALL_HINT) from exc
78
+
79
+
80
+ class _ConnectionLost(Exception):
81
+ """Internal: the current connection ended and the reconnect policy says what to do next."""
82
+
83
+ def __init__(self, action: protocol.CloseAction, reason: str) -> None:
84
+ super().__init__(reason)
85
+ self.action = action
86
+
87
+
88
+ class Engine:
89
+ """Keeps one authorized subscription to a private channel alive until closed."""
90
+
91
+ def __init__(
92
+ self,
93
+ *,
94
+ url: str | None,
95
+ channel: str | None,
96
+ authorize: Authorizer,
97
+ user_agent: str,
98
+ connect_timeout: float,
99
+ subscribe_timeout: float = 10.0,
100
+ pong_timeout: float = 30.0,
101
+ max_activity_timeout: float = 120.0,
102
+ ) -> None:
103
+ self._url: str = url or ""
104
+ self._channel: str = channel or ""
105
+ self._authorize = authorize
106
+ self._user_agent = user_agent
107
+ self._connect_timeout = connect_timeout
108
+ self._subscribe_timeout = subscribe_timeout
109
+ self._pong_timeout = pong_timeout
110
+ self._max_activity_timeout = max_activity_timeout
111
+
112
+ self._sinks: dict[int, tuple[str | None, Sink]] = {}
113
+ self._sinks_lock = threading.Lock()
114
+ self._next_sink_id = 0
115
+
116
+ self._task: asyncio.Task[None] | None = None
117
+ self._started = False
118
+ self._ready: asyncio.Event | None = None
119
+ self._connected = False
120
+ self._subscribed_once = False
121
+ self._session_subscribed = False
122
+ self._stopped = False
123
+ self._fatal: BaseException | None = None
124
+ self._last_error: BaseException | None = None
125
+
126
+ # -- sinks -------------------------------------------------------------
127
+
128
+ def add_sink(self, request_id: str | None, sink: Sink) -> int:
129
+ """Register a consumer for events of one job (``request_id``) or of all jobs (``None``).
130
+
131
+ Thread-safe. A sink added after the engine stopped immediately receives :class:`Closed`.
132
+ """
133
+ with self._sinks_lock:
134
+ sink_id = self._next_sink_id
135
+ self._next_sink_id += 1
136
+ if not self._stopped:
137
+ self._sinks[sink_id] = (request_id, sink)
138
+ return sink_id
139
+ sink(Closed(self._fatal))
140
+ return sink_id
141
+
142
+ def remove_sink(self, sink_id: int) -> None:
143
+ with self._sinks_lock:
144
+ self._sinks.pop(sink_id, None)
145
+
146
+ def _dispatch(self, item: SinkItem, request_id: str | None = None) -> None:
147
+ """Deliver a job event to the sinks of that job and to catch-all sinks; ``request_id=None`` reaches all."""
148
+ with self._sinks_lock:
149
+ targets = [
150
+ sink
151
+ for wanted, sink in self._sinks.values()
152
+ if request_id is None or wanted is None or wanted == request_id
153
+ ]
154
+ for sink in targets:
155
+ sink(item)
156
+
157
+ # -- lifecycle ---------------------------------------------------------
158
+
159
+ @property
160
+ def connected(self) -> bool:
161
+ """True while the channel subscription is active."""
162
+ return self._connected
163
+
164
+ def configure(self, url: str, channel: str) -> None:
165
+ """Set the target when it was not known at construction (discovered at connect time)."""
166
+ if self._started:
167
+ raise RealtimeError("Cannot reconfigure a started realtime session.")
168
+ self._url = url
169
+ self._channel = channel
170
+
171
+ def require_started(self) -> None:
172
+ """Raise unless :meth:`start` was called (a closed engine is fine: consumers get :class:`Closed`)."""
173
+ if not self._started:
174
+ raise RealtimeError(
175
+ "The realtime session is not connected. Use it as a context manager "
176
+ "(with client.realtime(...) as rt) or call connect() first."
177
+ )
178
+
179
+ async def start(self) -> None:
180
+ """Connect and subscribe; return once the first subscription succeeded.
181
+
182
+ Transient failures are retried until ``connect_timeout``. Fatal ones
183
+ (refused authorization, refused connection) are raised right away.
184
+ """
185
+ if self._started:
186
+ raise RealtimeError("This realtime session was already started; create a new one to reconnect.")
187
+ require_websockets()
188
+ if not self._url or not self._channel:
189
+ raise RealtimeError("The realtime session has no WebSocket URL or channel configured.")
190
+ self._started = True
191
+ self._ready = asyncio.Event()
192
+ self._task = asyncio.create_task(self._run(), name="deapi-realtime")
193
+ ready = asyncio.create_task(self._ready.wait())
194
+ try:
195
+ await asyncio.wait({ready, self._task}, timeout=self._connect_timeout, return_when=asyncio.FIRST_COMPLETED)
196
+ finally:
197
+ ready.cancel()
198
+ if self._ready.is_set():
199
+ return
200
+ error = self._fatal
201
+ await self.close()
202
+ if error is not None:
203
+ raise error
204
+ detail = f": {self._last_error}" if self._last_error is not None else ""
205
+ raise RealtimeError(f"Could not open the realtime connection within {self._connect_timeout:g}s{detail}")
206
+
207
+ async def close(self) -> None:
208
+ """Stop the engine and release every waiting consumer. Idempotent."""
209
+ task, self._task = self._task, None
210
+ # Re-cancel until the task really stops; asyncio.wait() does not re-raise the task's
211
+ # CancelledError, so a cancellation of close() itself still propagates.
212
+ while task is not None and not task.done():
213
+ task.cancel()
214
+ # Longer than _CLOSE_TIMEOUT, so a graceful WebSocket close is not interrupted.
215
+ await asyncio.wait({task}, timeout=_CLOSE_TIMEOUT + 3.0)
216
+ self._stop(self._fatal)
217
+
218
+ def _stop(self, error: BaseException | None) -> None:
219
+ self._connected = False
220
+ with self._sinks_lock:
221
+ if self._stopped:
222
+ return
223
+ self._stopped = True
224
+ sinks = list(self._sinks.values())
225
+ self._sinks.clear()
226
+ for _, sink in sinks:
227
+ sink(Closed(error))
228
+
229
+ # -- connection loop ---------------------------------------------------
230
+
231
+ async def _run(self) -> None:
232
+ attempt = 0
233
+ try:
234
+ while True:
235
+ self._session_subscribed = False
236
+ try:
237
+ await self._connect_once()
238
+ action, reason = protocol.CloseAction.BACKOFF, "connection closed"
239
+ except _ConnectionLost as lost:
240
+ action, reason = lost.action, str(lost)
241
+ except (OSError, TimeoutError, NetworkError, ServerError, RateLimitError) as exc:
242
+ action, reason = protocol.CloseAction.BACKOFF, f"{type(exc).__name__}: {exc}"
243
+ except Exception as exc:
244
+ if not _is_transient_websocket_error(exc):
245
+ raise
246
+ action, reason = protocol.CloseAction.BACKOFF, f"{type(exc).__name__}: {exc}"
247
+ finally:
248
+ self._connected = False
249
+ self._last_error = RealtimeError(reason)
250
+
251
+ if action is protocol.CloseAction.FATAL:
252
+ raise RealtimeError(f"The realtime server refused the connection: {reason}")
253
+ if self._session_subscribed:
254
+ attempt = 0 # the connection worked, so start the backoff sequence over
255
+ if action is protocol.CloseAction.RECONNECT and attempt == 0:
256
+ delay = 0.0
257
+ else:
258
+ delay = protocol.backoff_delay(attempt)
259
+ attempt += 1
260
+ logger.warning("Realtime connection lost (%s); reconnecting in %.1fs", reason, delay)
261
+ await asyncio.sleep(delay)
262
+ except asyncio.CancelledError:
263
+ raise
264
+ except Exception as exc:
265
+ self._fatal = exc
266
+ logger.error("Realtime connection stopped: %s", exc)
267
+ self._stop(exc)
268
+
269
+ async def _connect_once(self) -> None:
270
+ from websockets.asyncio.client import connect
271
+
272
+ async with connect(
273
+ self._url,
274
+ user_agent_header=self._user_agent,
275
+ open_timeout=self._connect_timeout,
276
+ # Keepalive runs at the protocol level (pusher:ping), as the server expects.
277
+ ping_interval=None,
278
+ close_timeout=_CLOSE_TIMEOUT,
279
+ max_size=_MAX_FRAME_BYTES,
280
+ ) as ws:
281
+ try:
282
+ socket_id, activity_timeout = await self._handshake(ws)
283
+ auth = await self._authorize(socket_id, self._channel)
284
+ await ws.send(protocol.subscribe_frame(self._channel, auth))
285
+ await self._await_subscription(ws, activity_timeout)
286
+ self._on_subscribed()
287
+ await self._listen(ws, activity_timeout)
288
+ except Exception as exc:
289
+ lost = _connection_closed_as_lost(exc)
290
+ if lost is not None:
291
+ raise lost from exc
292
+ raise
293
+
294
+ async def _recv(self, ws: ClientConnection, timeout: float) -> protocol.Message | None:
295
+ """Receive one frame; ``None`` when nothing arrived within ``timeout``. Answers server pings."""
296
+ # asyncio.timeout() instead of wait_for(): on Python 3.11 wait_for can swallow a
297
+ # cancellation that races with recv() completing, which would hang close().
298
+ try:
299
+ async with asyncio.timeout(timeout):
300
+ frame = await ws.recv()
301
+ except TimeoutError:
302
+ return None
303
+ message = protocol.decode(frame)
304
+ if message is None:
305
+ return protocol.Message(event="") # unknown frame: still proof of life
306
+ if message.event == protocol.PING:
307
+ await ws.send(protocol.PONG_FRAME)
308
+ elif message.event == protocol.ERROR:
309
+ self._on_pusher_error(message)
310
+ return message
311
+
312
+ async def _handshake(self, ws: ClientConnection) -> tuple[str, float]:
313
+ message = await self._recv(ws, self._connect_timeout)
314
+ while message is not None and message.event != protocol.CONNECTION_ESTABLISHED:
315
+ message = await self._recv(ws, self._connect_timeout)
316
+ if message is None:
317
+ raise _ConnectionLost(protocol.CloseAction.BACKOFF, "no connection_established from server")
318
+ data = message.data if isinstance(message.data, dict) else {}
319
+ socket_id = data.get("socket_id")
320
+ if not isinstance(socket_id, str) or not socket_id:
321
+ raise _ConnectionLost(protocol.CloseAction.BACKOFF, "connection_established without socket_id")
322
+ server_timeout = data.get("activity_timeout")
323
+ activity_timeout = self._max_activity_timeout
324
+ if isinstance(server_timeout, (int, float)) and not isinstance(server_timeout, bool) and server_timeout > 0:
325
+ activity_timeout = min(float(server_timeout), self._max_activity_timeout)
326
+ return socket_id, activity_timeout
327
+
328
+ async def _await_subscription(self, ws: ClientConnection, activity_timeout: float) -> None:
329
+ loop = asyncio.get_running_loop()
330
+ deadline = loop.time() + self._subscribe_timeout
331
+ while (remaining := deadline - loop.time()) > 0:
332
+ message = await self._recv(ws, remaining)
333
+ if message is None:
334
+ break
335
+ if message.channel != self._channel:
336
+ continue
337
+ if message.event == protocol.SUBSCRIPTION_SUCCEEDED:
338
+ return
339
+ if message.event == protocol.SUBSCRIPTION_ERROR:
340
+ raise _subscription_refused(self._channel, message.data)
341
+ raise _ConnectionLost(protocol.CloseAction.BACKOFF, f"no answer to the subscription of {self._channel}")
342
+
343
+ def _on_subscribed(self) -> None:
344
+ reconnect = self._subscribed_once
345
+ self._subscribed_once = True
346
+ self._session_subscribed = True
347
+ self._connected = True
348
+ self._last_error = None
349
+ assert self._ready is not None
350
+ self._ready.set()
351
+ if reconnect:
352
+ logger.info("Realtime connection restored")
353
+ self._dispatch(RECONNECTED)
354
+
355
+ async def _listen(self, ws: ClientConnection, activity_timeout: float) -> None:
356
+ while True:
357
+ message = await self._recv(ws, activity_timeout)
358
+ if message is None:
359
+ # Quiet for a full activity window: check the connection is still alive.
360
+ await ws.send(protocol.PING_FRAME)
361
+ message = await self._recv(ws, self._pong_timeout)
362
+ if message is None:
363
+ raise _ConnectionLost(protocol.CloseAction.RECONNECT, "no pong from server")
364
+ if message.event == protocol.STATUS_EVENT and message.channel == self._channel:
365
+ self._on_status_event(message)
366
+ elif message.event == protocol.SUBSCRIPTION_ERROR and message.channel == self._channel:
367
+ raise _subscription_refused(self._channel, message.data)
368
+
369
+ def _on_status_event(self, message: protocol.Message) -> None:
370
+ try:
371
+ event = JobStatusEvent.model_validate(message.data)
372
+ except PydanticValidationError:
373
+ logger.debug("Ignoring malformed %s payload", protocol.STATUS_EVENT)
374
+ return
375
+ self._dispatch(event, event.request_id)
376
+
377
+ def _on_pusher_error(self, message: protocol.Message) -> None:
378
+ code = protocol.error_code(message.data)
379
+ text = protocol.error_text(message.data)
380
+ if protocol.close_action(code) is protocol.CloseAction.FATAL:
381
+ raise RealtimeError(f"The realtime server refused the connection: {text} (code {code})", close_code=code)
382
+ logger.info("Realtime server error: %s (code %s)", text, code)
383
+
384
+
385
+ def _subscription_refused(channel: str, data: object) -> RealtimeError:
386
+ status = data.get("status") if isinstance(data, dict) else None
387
+ hint = ""
388
+ if status in (401, 403):
389
+ hint = " Check that client_id is the Client ID of the account that owns this API key."
390
+ return RealtimeError(
391
+ f"Subscription to {channel} was refused: {protocol.error_text(data)}.{hint}",
392
+ status_code=status if isinstance(status, int) else None,
393
+ )
394
+
395
+
396
+ def _connection_closed_as_lost(exc: BaseException) -> BaseException | None:
397
+ """Turn a websockets ``ConnectionClosed`` into a reconnect decision (or a fatal error)."""
398
+ from websockets.exceptions import ConnectionClosed
399
+
400
+ if not isinstance(exc, ConnectionClosed):
401
+ return None
402
+ close = exc.rcvd
403
+ code = close.code if close is not None else None
404
+ reason = close.reason if close is not None and close.reason else "connection closed"
405
+ action = protocol.close_action(code)
406
+ if action is protocol.CloseAction.FATAL:
407
+ return RealtimeError(f"The realtime server refused the connection: {reason} (code {code})", close_code=code)
408
+ return _ConnectionLost(action, f"{reason} (code {code})" if code is not None else reason)
409
+
410
+
411
+ def _is_transient_websocket_error(exc: BaseException) -> bool:
412
+ """Handshake failures and other websockets errors are worth retrying; SDK errors are not."""
413
+ from websockets.exceptions import WebSocketException
414
+
415
+ if isinstance(exc, (AuthenticationError, PermissionDeniedError, RealtimeError)):
416
+ return False
417
+ if isinstance(exc, DeapiError):
418
+ return False
419
+ return isinstance(exc, WebSocketException)
@@ -0,0 +1,152 @@
1
+ """Pusher Channels protocol (version 7) helpers. Pure functions, no I/O.
2
+
3
+ deAPI publishes job status updates over a Pusher-compatible WebSocket server.
4
+ Reference: https://pusher.com/docs/channels/library_auth_reference/pusher-websockets-protocol/
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import contextlib
10
+ import json
11
+ import random
12
+ from collections.abc import Callable
13
+ from dataclasses import dataclass
14
+ from enum import Enum
15
+ from typing import Any
16
+ from urllib.parse import quote, urlencode, urlsplit
17
+
18
+ PROTOCOL_VERSION = 7
19
+
20
+ BROADCASTING_AUTH_PATH = "/broadcasting/auth"
21
+
22
+ STATUS_EVENT = "request.status.updated"
23
+ CLIENT_CHANNEL_PREFIX = "private-client."
24
+
25
+ CONNECTION_ESTABLISHED = "pusher:connection_established"
26
+ ERROR = "pusher:error"
27
+ PING = "pusher:ping"
28
+ PONG = "pusher:pong"
29
+ SUBSCRIBE = "pusher:subscribe"
30
+ SUBSCRIPTION_SUCCEEDED = "pusher_internal:subscription_succeeded"
31
+ SUBSCRIPTION_ERROR = "pusher:subscription_error"
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class Message:
36
+ """One decoded protocol frame. ``data`` is already JSON-decoded when possible."""
37
+
38
+ event: str
39
+ data: Any = None
40
+ channel: str | None = None
41
+
42
+
43
+ class CloseAction(Enum):
44
+ """What a client must do after the server closes the connection."""
45
+
46
+ FATAL = "fatal" # do not reconnect with the same parameters
47
+ BACKOFF = "backoff" # reconnect after a delay
48
+ RECONNECT = "reconnect" # reconnect immediately
49
+
50
+
51
+ def check_ws_url(ws_url: str) -> None:
52
+ """Raise ``ValueError`` unless ``ws_url`` is a ``ws://`` or ``wss://`` URL."""
53
+ parts = urlsplit(ws_url)
54
+ if parts.scheme not in ("ws", "wss") or not parts.netloc:
55
+ raise ValueError(f"ws_url must be a ws:// or wss:// URL, got {ws_url!r}")
56
+
57
+
58
+ def build_url(ws_url: str, app_key: str, client_version: str) -> str:
59
+ """Build the connection URL: ``{ws_url}/app/{app_key}?protocol=7&client=...&version=...``."""
60
+ check_ws_url(ws_url)
61
+ if not app_key:
62
+ raise ValueError("app_key must not be empty")
63
+ query = urlencode({"protocol": PROTOCOL_VERSION, "client": "deapi-python", "version": client_version})
64
+ return f"{ws_url.rstrip('/')}/app/{quote(app_key, safe='')}?{query}"
65
+
66
+
67
+ def channel_for(client_id: str) -> str:
68
+ """Name of the private channel that carries a client's job updates."""
69
+ return f"{CLIENT_CHANNEL_PREFIX}{client_id}"
70
+
71
+
72
+ def decode(frame: str | bytes) -> Message | None:
73
+ """Decode a text frame. Returns ``None`` for anything that is not a protocol message.
74
+
75
+ The server JSON-encodes ``data`` a second time for most events, so a string
76
+ ``data`` is decoded again when it holds JSON and kept as-is otherwise.
77
+ """
78
+ try:
79
+ raw = json.loads(frame)
80
+ except (TypeError, ValueError):
81
+ return None
82
+ if not isinstance(raw, dict) or not isinstance(raw.get("event"), str):
83
+ return None
84
+ data = raw.get("data")
85
+ if isinstance(data, str):
86
+ with contextlib.suppress(ValueError):
87
+ data = json.loads(data)
88
+ channel = raw.get("channel")
89
+ return Message(event=raw["event"], data=data, channel=channel if isinstance(channel, str) else None)
90
+
91
+
92
+ def encode(event: str, data: dict[str, Any]) -> str:
93
+ return json.dumps({"event": event, "data": data}, separators=(",", ":"))
94
+
95
+
96
+ def subscribe_frame(channel: str, auth: str) -> str:
97
+ return encode(SUBSCRIBE, {"channel": channel, "auth": auth})
98
+
99
+
100
+ PING_FRAME = encode(PING, {})
101
+ PONG_FRAME = encode(PONG, {})
102
+
103
+
104
+ def close_action(code: int | None) -> CloseAction:
105
+ """Map a WebSocket close code to the reconnect policy of the Pusher protocol.
106
+
107
+ 4000-4099: the server refuses this connection (bad app key, over quota, ...).
108
+ 4100-4199: try again after backing off. 4200-4299: reconnect right away.
109
+ Anything else (network loss, server restart, ...) is retried with backoff.
110
+ """
111
+ if code is not None and 4000 <= code <= 4099:
112
+ return CloseAction.FATAL
113
+ if code is not None and 4200 <= code <= 4299:
114
+ return CloseAction.RECONNECT
115
+ return CloseAction.BACKOFF
116
+
117
+
118
+ def error_code(data: Any) -> int | None:
119
+ """Extract the numeric ``code`` from a ``pusher:error`` payload."""
120
+ if isinstance(data, dict):
121
+ code = data.get("code")
122
+ if isinstance(code, int) and not isinstance(code, bool):
123
+ return code
124
+ return None
125
+
126
+
127
+ def error_text(data: Any) -> str:
128
+ """Best human-readable message from a ``pusher:error`` / ``pusher:subscription_error`` payload."""
129
+ if isinstance(data, dict):
130
+ for key in ("message", "error", "type"):
131
+ value = data.get(key)
132
+ if isinstance(value, str) and value:
133
+ return value
134
+ if isinstance(data, str) and data:
135
+ return data
136
+ return "no details"
137
+
138
+
139
+ def backoff_delay(
140
+ attempt: int,
141
+ *,
142
+ base: float = 1.0,
143
+ cap: float = 30.0,
144
+ rand: Callable[[], float] = random.random,
145
+ ) -> float:
146
+ """Exponential backoff with jitter: ``base * 2**attempt`` capped at ``cap``, scaled into [50%, 100%].
147
+
148
+ Never below ``base`` (the protocol asks for at least one second between
149
+ attempts after a backoff close code).
150
+ """
151
+ ceiling = min(cap, base * (2.0 ** max(attempt, 0)))
152
+ return max(base, ceiling * (0.5 + rand() / 2))