chickinfry 0.5.0.dev1__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.
chickinfry/realtime.py ADDED
@@ -0,0 +1,522 @@
1
+ """Ordered realtime subscriptions for generated async clients."""
2
+
3
+ import asyncio
4
+ import json
5
+ import logging
6
+ import re
7
+ from collections import deque
8
+ from collections.abc import AsyncIterator, Awaitable, Callable
9
+ from contextvars import ContextVar
10
+ from dataclasses import dataclass
11
+ from datetime import datetime, timezone
12
+ from functools import partial
13
+ from typing import cast
14
+ from uuid import uuid4
15
+
16
+ from websockets.asyncio.client import ClientConnection, connect
17
+ from websockets.exceptions import WebSocketException
18
+
19
+ from .errors import ClientError, OperationError
20
+ from .http import AsyncTransport, _Authenticated
21
+
22
+ _UUID = re.compile(r"[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}")
23
+ _ENDPOINT = re.compile(r"wss://" + _UUID.pattern + r"\.chickinfry\.app/realtime")
24
+ _CODE = re.compile(r"[a-z_]{1,64}")
25
+ _FRAME_ERRORS = {
26
+ "unauthorized_channel": "permission_denied",
27
+ "already_subscribed": "internal",
28
+ "too_many_channels": "resource_exhausted",
29
+ "replay_failed": "unavailable",
30
+ "realtime_unavailable": "unavailable",
31
+ }
32
+ _MAX_BYTES = 66_560
33
+ _BUDGET = 30
34
+ _LOG = logging.Logger("chickinfry.websocket", logging.CRITICAL + 1)
35
+
36
+
37
+ def _endpoint(value: object) -> str:
38
+ if not isinstance(value, str) or not _ENDPOINT.fullmatch(value):
39
+ raise ClientError("internal")
40
+ return value
41
+
42
+
43
+ def _uuid(value: object) -> bool:
44
+ return isinstance(value, str) and _UUID.fullmatch(value) is not None
45
+
46
+
47
+ def _cursor(value: object) -> str:
48
+ if isinstance(value, str) and (not value or _uuid(value)):
49
+ return value
50
+ raise ClientError("internal")
51
+
52
+
53
+ class _Connect(connect):
54
+ # The ticket must never follow a redirect, including one on the same host.
55
+ def process_redirect(self, exc: Exception) -> Exception:
56
+ return exc
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class RealtimeEvent:
61
+ channel: str
62
+ payload: object
63
+
64
+ @property
65
+ def type(self) -> str:
66
+ return "event"
67
+
68
+
69
+ @dataclass(frozen=True)
70
+ class RealtimeGap:
71
+ channel: str
72
+
73
+ @property
74
+ def type(self) -> str:
75
+ return "gap"
76
+
77
+
78
+ @dataclass(frozen=True)
79
+ class SubscribeOptions:
80
+ on_gap: Callable[[RealtimeGap], Awaitable[None]] | None = None
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class _Probe:
85
+ endpoint: Callable[[object], str]
86
+ point: Callable[[str], None]
87
+ inspect: Callable[[Callable[[], dict[str, int]]], None]
88
+ dispatch: Callable[[str, Callable[[], Awaitable[None]]], Awaitable[None]]
89
+
90
+
91
+ _probe: ContextVar[_Probe | None] = ContextVar("realtime_probe", default=None)
92
+
93
+
94
+ class RealtimeClient:
95
+ def __init__(self, transport: AsyncTransport) -> None:
96
+ self._transport = transport
97
+
98
+ async def subscribe(
99
+ self, channel: str, options: SubscribeOptions | None = None
100
+ ) -> "RealtimeSubscription":
101
+ try:
102
+ valid = 0 < len(channel.encode("utf-8")) <= 128
103
+ except (AttributeError, UnicodeError):
104
+ valid = False
105
+ if not valid or any(ord(char) < 32 or ord(char) == 127 for char in channel):
106
+ raise ClientError("invalid_argument")
107
+ sub = RealtimeSubscription(
108
+ self._transport, channel, options or SubscribeOptions(), _probe.get()
109
+ )
110
+ return await sub._start()
111
+
112
+
113
+ @dataclass(eq=False)
114
+ class _Connection:
115
+ socket: ClientConnection
116
+ prepared: bool = False
117
+ confirmation: str | None = None
118
+ checkpoint: str | None = None
119
+
120
+
121
+ @dataclass(eq=False)
122
+ class _Recovery:
123
+ cursor: str
124
+ complete: bool = False
125
+ connection: _Connection | None = None
126
+
127
+
128
+ class _Events:
129
+ def __init__(self, subscription: "RealtimeSubscription") -> None:
130
+ self._subscription = subscription
131
+ self._consumed = False
132
+
133
+ def __aiter__(self) -> AsyncIterator[RealtimeEvent]:
134
+ if self._consumed:
135
+ raise ClientError("failed_precondition")
136
+ self._consumed = True
137
+ return self._subscription._events()
138
+
139
+
140
+ class RealtimeSubscription:
141
+ def __init__(
142
+ self,
143
+ transport: AsyncTransport,
144
+ channel: str,
145
+ options: SubscribeOptions,
146
+ probe: _Probe | None,
147
+ ) -> None:
148
+ self.events = _Events(self)
149
+ self._transport = transport
150
+ self._channel = channel
151
+ self._on_gap = options.on_gap
152
+ self._probe = probe
153
+ self._id = str(uuid4())
154
+ self._last = ""
155
+ self._queue: deque[tuple[str, object]] = deque()
156
+ self._changed = asyncio.Event()
157
+ self._ready: asyncio.Future[None] = asyncio.get_running_loop().create_future()
158
+ self._connection: _Connection | None = None
159
+ self._recovery: _Recovery | None = None
160
+ self._deadline: asyncio.TimerHandle | None = None
161
+ self._worker: asyncio.Task[None] | None = None
162
+ self._renewal: asyncio.Task[None] | None = None
163
+ self._callback: asyncio.Task[None] | None = None
164
+ self._active = True
165
+ self._first_ready = False
166
+ self._demand = False
167
+ self._failure: ClientError | None = None
168
+ self._loss_budgets = 0
169
+ self._connections_started = 0
170
+
171
+ async def _start(self) -> "RealtimeSubscription":
172
+ if self._probe:
173
+ self._probe.inspect(self._metrics)
174
+ self._arm_budget()
175
+ self._worker = asyncio.create_task(self._run())
176
+ if (
177
+ isinstance(self._transport, _Authenticated)
178
+ and self._transport._store is not None
179
+ ):
180
+ self._renewal = asyncio.create_task(self._renew(self._transport))
181
+ try:
182
+ await self._ready
183
+ return self
184
+ except asyncio.CancelledError:
185
+ await self.unsubscribe()
186
+ raise
187
+
188
+ def _metrics(self) -> dict[str, int]:
189
+ return {
190
+ "pendingReads": int(self._active and self._demand),
191
+ "activeRenewalWatchers": int(self._active and self._renewal is not None),
192
+ "reprepareBudgetMs": _BUDGET * 1000 if self._loss_budgets else 0,
193
+ "budgetResets": max(0, self._loss_budgets - 1),
194
+ "connectionsStarted": self._connections_started,
195
+ }
196
+
197
+ def _arm_budget(self) -> None:
198
+ if self._deadline is None:
199
+ self._loss_budgets += int(self._first_ready)
200
+ self._deadline = asyncio.get_running_loop().call_later(
201
+ _BUDGET, self._stop, ClientError("deadline_exceeded")
202
+ )
203
+
204
+ def _stop(self, error: ClientError | None = None) -> None:
205
+ if not self._active:
206
+ return
207
+ self._active = False
208
+ self._failure = error
209
+ self._queue.clear()
210
+ self._connection = None
211
+ self._recovery = None
212
+ if self._deadline is not None:
213
+ self._deadline.cancel()
214
+ if not self._ready.done():
215
+ self._ready.set_exception(error or ClientError("canceled"))
216
+ for task in (self._worker, self._renewal):
217
+ if task is not None and task is not asyncio.current_task():
218
+ task.cancel()
219
+ self._changed.set()
220
+
221
+ async def unsubscribe(self) -> None:
222
+ current = self._connection
223
+ if current is not None:
224
+ await self._send(current, "unsubscribe")
225
+ self._stop()
226
+ for task in (self._worker, self._renewal):
227
+ if task is not None and task is not asyncio.current_task():
228
+ await asyncio.gather(task, return_exceptions=True)
229
+
230
+ async def _events(self) -> AsyncIterator[RealtimeEvent]:
231
+ try:
232
+ while True:
233
+ self._demand = True
234
+ try:
235
+ while self._active:
236
+ if self._recovery is not None:
237
+ self._recover()
238
+ elif (
239
+ self._connection is not None
240
+ and self._connection.prepared
241
+ and self._queue
242
+ ):
243
+ self._last, payload = self._queue.popleft()
244
+ await self._ack(self._connection)
245
+ break
246
+ self._changed.clear()
247
+ await self._changed.wait()
248
+ else:
249
+ if self._failure is not None:
250
+ raise self._failure
251
+ return
252
+ finally:
253
+ self._demand = False
254
+ if self._active:
255
+ yield RealtimeEvent(self._channel, payload)
256
+ finally:
257
+ await self.unsubscribe()
258
+
259
+ async def _send(self, current: _Connection, kind: str, **fields: object) -> bool:
260
+ try:
261
+ await current.socket.send(
262
+ json.dumps({"type": kind, "channel": self._channel, **fields})
263
+ )
264
+ return self._active and self._connection is current
265
+ except WebSocketException:
266
+ await current.socket.close()
267
+ return False
268
+
269
+ async def _ack(self, current: _Connection) -> None:
270
+ if (
271
+ current.prepared
272
+ and current.checkpoint is not None
273
+ and self._recovery is None
274
+ and not self._queue
275
+ ):
276
+ if await self._send(current, "ack", cursor=current.checkpoint):
277
+ current.checkpoint = None
278
+
279
+ def _gap(self, cursor: str) -> None:
280
+ if self._on_gap is None:
281
+ self._stop(ClientError("data_loss"))
282
+ return
283
+ self._recovery = _Recovery(cursor)
284
+ self._queue.clear()
285
+ if self._connection is not None:
286
+ self._connection.prepared = False
287
+ self._arm_budget()
288
+ if self._probe:
289
+ self._probe.point("gap")
290
+ self._recover()
291
+
292
+ def _recover(self) -> None:
293
+ recovery, callback = self._recovery, self._on_gap
294
+ if (
295
+ not self._active
296
+ or recovery is None
297
+ or callback is None
298
+ or recovery.complete
299
+ or self._callback is not None
300
+ or (self._first_ready and not self._demand)
301
+ ):
302
+ return
303
+
304
+ async def reload() -> None:
305
+ try:
306
+ if not self._active or recovery is not self._recovery:
307
+ return
308
+ await callback(RealtimeGap(self._channel))
309
+ if self._active and recovery is self._recovery:
310
+ recovery.complete = True
311
+ self._last = recovery.cursor
312
+ self._queue.clear()
313
+ current, self._connection = self._connection, None
314
+ if current is not None:
315
+ await current.socket.close()
316
+ except Exception as cause:
317
+ if self._active and recovery is self._recovery:
318
+ failure = ClientError("unknown")
319
+ failure.__cause__ = cause
320
+ self._stop(failure)
321
+ finally:
322
+ self._callback = None
323
+ self._changed.set()
324
+
325
+ self._callback = asyncio.create_task(reload())
326
+
327
+ async def _receive(self, current: _Connection, message: str | bytes) -> None:
328
+ if not self._active or self._connection is not current:
329
+ if self._probe:
330
+ self._probe.point("discarded")
331
+ return
332
+ try:
333
+ if (
334
+ not isinstance(message, str)
335
+ or len(message.encode("utf-8")) > _MAX_BYTES
336
+ ):
337
+ raise ClientError("internal")
338
+ value = json.loads(message)
339
+ if not isinstance(value, dict):
340
+ raise ClientError("internal")
341
+ frame = cast(dict[str, object], value)
342
+ kind = frame.get("type")
343
+ if frame.get("channel") != self._channel and not (
344
+ kind == "error" and "channel" not in frame
345
+ ):
346
+ raise ClientError("internal")
347
+ if kind == "ready":
348
+ cursor = _cursor(frame.get("cursor"))
349
+ nonce = frame.get("confirmation")
350
+ ack = frame.get("acknowledge", False)
351
+ if not isinstance(ack, bool) or (
352
+ "confirmation" in frame and not _uuid(nonce)
353
+ ):
354
+ raise ClientError("internal")
355
+ current.checkpoint = cursor if ack else None
356
+ if nonce is None:
357
+ if current.confirmation is None:
358
+ current.confirmation = str(uuid4())
359
+ await self._send(
360
+ current, "confirm", confirmation=current.confirmation
361
+ )
362
+ return
363
+ if nonce != current.confirmation:
364
+ return
365
+ recovery = self._recovery
366
+ if recovery is not None:
367
+ if not recovery.complete or recovery.connection is not current:
368
+ return
369
+ self._recovery = None
370
+ if self._probe:
371
+ self._probe.point("recovered")
372
+ current.prepared = self._first_ready = True
373
+ if self._deadline is not None:
374
+ self._deadline.cancel()
375
+ self._deadline = None
376
+ if not self._ready.done():
377
+ self._ready.set_result(None)
378
+ await self._ack(current)
379
+ self._changed.set()
380
+ elif kind == "gap":
381
+ self._gap(_cursor(frame.get("cursor")))
382
+ elif kind == "event":
383
+ cursor = _cursor(frame.get("cursor"))
384
+ previous = _cursor(frame.get("previous"))
385
+ if not cursor or "payload" not in frame:
386
+ raise ClientError("internal")
387
+ if cursor == self._last or any(
388
+ item[0] == cursor for item in self._queue
389
+ ):
390
+ return
391
+ expected = (
392
+ self._queue[-1][0]
393
+ if self._queue
394
+ else (
395
+ self._recovery.cursor
396
+ if self._recovery is not None
397
+ else self._last
398
+ )
399
+ )
400
+ full = len(self._queue) >= (512 if self._probe else 256)
401
+ if full or previous != expected:
402
+ if full and self._probe:
403
+ self._probe.point("overflow")
404
+ self._gap(cursor)
405
+ else:
406
+ self._queue.append((cursor, frame["payload"]))
407
+ self._changed.set()
408
+ elif kind == "error":
409
+ code = frame.get("error")
410
+ if not isinstance(code, str) or not _CODE.fullmatch(code):
411
+ raise ClientError("internal")
412
+ self._stop(ClientError(_FRAME_ERRORS.get(code, "unknown")))
413
+ else:
414
+ raise ClientError("internal")
415
+ except (UnicodeError, ValueError, RecursionError):
416
+ self._stop(ClientError("internal"))
417
+ except ClientError as error:
418
+ self._stop(error)
419
+
420
+ async def _run(self) -> None:
421
+ backoff = 0.5
422
+ while self._active:
423
+ try:
424
+ value = await self._transport.invoke("realtime.ticket", {})
425
+ if not isinstance(value, dict):
426
+ raise ClientError("internal")
427
+ ticket = value.get("ticket")
428
+ if not _uuid(ticket):
429
+ raise ClientError("internal")
430
+ endpoint = (self._probe.endpoint if self._probe else _endpoint)(
431
+ value.get("endpoint")
432
+ )
433
+ except OperationError as error:
434
+ if not (
435
+ (error.status == 409 and not self._first_ready)
436
+ or error.status == 429
437
+ or (error.status is not None and error.status >= 500)
438
+ ):
439
+ self._stop(error)
440
+ return
441
+ except ClientError as error:
442
+ if error.code not in ("unavailable", "deadline_exceeded"):
443
+ self._stop(error)
444
+ return
445
+ except Exception:
446
+ self._stop(ClientError("internal"))
447
+ return
448
+ else:
449
+ try:
450
+ async with _Connect(
451
+ f"{endpoint}?ticket={ticket}",
452
+ proxy=None,
453
+ open_timeout=10,
454
+ close_timeout=1,
455
+ max_size=_MAX_BYTES,
456
+ compression=None,
457
+ logger=_LOG,
458
+ ) as socket:
459
+ current = _Connection(socket)
460
+ self._connection = current
461
+ self._connections_started += 1
462
+ recovery = self._recovery
463
+ if recovery is not None and recovery.complete:
464
+ recovery.connection = current
465
+ if await self._send(
466
+ current,
467
+ "subscribe",
468
+ cursor=(
469
+ recovery.cursor if recovery is not None else self._last
470
+ ),
471
+ subscription=self._id,
472
+ ):
473
+ backoff = 0.5
474
+ async for message in socket:
475
+ if isinstance(message, str) and self._probe:
476
+ await self._probe.dispatch(
477
+ message,
478
+ partial(self._receive, current, message),
479
+ )
480
+ else:
481
+ await self._receive(current, message)
482
+ if not self._active:
483
+ return
484
+ except (OSError, TimeoutError, WebSocketException):
485
+ pass
486
+ finally:
487
+ self._connection = None
488
+ self._queue.clear()
489
+ if self._active:
490
+ self._arm_budget()
491
+ self._changed.set()
492
+ if self._active:
493
+ await asyncio.sleep(backoff)
494
+ backoff = min(backoff * 2, 5)
495
+
496
+ async def _renew(self, transport: _Authenticated) -> None:
497
+ store = transport._store
498
+ assert store is not None
499
+ try:
500
+ while self._active:
501
+ credentials = store.credentials()
502
+ if credentials is None:
503
+ raise ClientError("unauthenticated")
504
+ due = datetime.fromisoformat(credentials.expires_at)
505
+ await asyncio.sleep(
506
+ max(0, (due - datetime.now(timezone.utc)).total_seconds() - 60)
507
+ )
508
+ if not self._active:
509
+ return
510
+ with store._locked():
511
+ current, generation = store._register()
512
+ try:
513
+ if current == credentials:
514
+ await transport._owner._refresh(store, credentials, generation)
515
+ if store.credentials() == credentials:
516
+ raise ClientError("internal")
517
+ finally:
518
+ store._release(generation)
519
+ except ClientError as error:
520
+ self._stop(error)
521
+ except Exception:
522
+ self._stop(ClientError("internal"))