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.
- deapi_sdk/__init__.py +409 -0
- deapi_sdk/_cards.py +313 -0
- deapi_sdk/_client.py +411 -0
- deapi_sdk/_config.py +77 -0
- deapi_sdk/_constants.py +61 -0
- deapi_sdk/_download.py +37 -0
- deapi_sdk/_exceptions.py +184 -0
- deapi_sdk/_files.py +59 -0
- deapi_sdk/_payload.py +50 -0
- deapi_sdk/_polling.py +157 -0
- deapi_sdk/_realtime/__init__.py +7 -0
- deapi_sdk/_realtime/_discovery.py +43 -0
- deapi_sdk/_realtime/_engine.py +419 -0
- deapi_sdk/_realtime/_protocol.py +152 -0
- deapi_sdk/_realtime/_session.py +529 -0
- deapi_sdk/_types.py +31 -0
- deapi_sdk/_version.py +3 -0
- deapi_sdk/py.typed +0 -0
- deapi_sdk/resources/__init__.py +35 -0
- deapi_sdk/resources/account.py +149 -0
- deapi_sdk/resources/audio.py +386 -0
- deapi_sdk/resources/embeddings.py +116 -0
- deapi_sdk/resources/images.py +616 -0
- deapi_sdk/resources/keys.py +277 -0
- deapi_sdk/resources/models.py +161 -0
- deapi_sdk/resources/ocr.py +152 -0
- deapi_sdk/resources/prompts.py +137 -0
- deapi_sdk/resources/transcription.py +308 -0
- deapi_sdk/resources/video.py +985 -0
- deapi_sdk/transcript.py +142 -0
- deapi_sdk/types/__init__.py +68 -0
- deapi_sdk/types/account.py +115 -0
- deapi_sdk/types/audio.py +35 -0
- deapi_sdk/types/common.py +174 -0
- deapi_sdk/types/embeddings.py +11 -0
- deapi_sdk/types/images.py +40 -0
- deapi_sdk/types/keys.py +53 -0
- deapi_sdk/types/ocr.py +14 -0
- deapi_sdk/types/prompts.py +26 -0
- deapi_sdk/types/transcription.py +14 -0
- deapi_sdk/types/video.py +84 -0
- deapi_sdk/types/websocket.py +36 -0
- deapi_sdk/webhook.py +159 -0
- deapi_sdk-0.6.1.dist-info/METADATA +644 -0
- deapi_sdk-0.6.1.dist-info/RECORD +47 -0
- deapi_sdk-0.6.1.dist-info/WHEEL +4 -0
- 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))
|