bakbak-python 1.0.0rc2__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.
bakbak/_ws/_core.py ADDED
@@ -0,0 +1,819 @@
1
+ """The WebSocket protocol (BEHAVIOR.md §6) as a state machine without I/O.
2
+
3
+ The async and the sync clients drive this one implementation, so they cannot
4
+ differ in how they route messages, cancel, hold, resend or fail requests. The
5
+ core never blocks: it changes state, appends events, and asks its driver to do
6
+ anything that waits (open a connection, sleep, close a connection) through
7
+ the ``Driver`` methods, which only schedule work.
8
+
9
+ Vocabulary:
10
+
11
+ - A *request* is one synthesis request. It is ``QUEUED`` (not sent yet),
12
+ ``INFLIGHT`` (sent, no terminal message yet), ``BACKOFF`` (waiting to be
13
+ resent after a retryable error), ``HELD`` (refused by a draining connection,
14
+ waiting until its context has nothing left there) or ``DONE``.
15
+ - A *context* sends its requests in order. Its unsent requests wait in
16
+ ``pending`` (sorted by send order); its in-flight ones are in ``inflight``,
17
+ all on the connection the context is ``bound`` to.
18
+ - Messages for a context go to its oldest in-flight request: the server runs a
19
+ context's requests one after another and answers each in order. A request
20
+ that already has its outcome may stay at the head of ``inflight`` (its audio
21
+ was invalid): the server's remaining messages for it are then dropped.
22
+ - Only *busy* contexts (something unfinished, in flight or being cancelled)
23
+ are in the routing table, so a long-lived WebSocket does not grow with the
24
+ number of contexts it has served (§6.6).
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import binascii
30
+ import enum
31
+ import json
32
+ import time
33
+ import weakref
34
+ from collections import deque
35
+ from collections.abc import Callable
36
+ from typing import Any, Protocol
37
+
38
+ from .._constants import WS_HEALTHY_AFTER, WS_MAX_CONTEXTS, WS_MAX_UNFINISHED
39
+ from .._exceptions import (
40
+ APIStatusError,
41
+ APITimeoutError,
42
+ BakbakError,
43
+ WebSocketClosedError,
44
+ event_status,
45
+ make_interrupted_error,
46
+ make_status_error,
47
+ )
48
+ from .._retry import backoff_delay
49
+ from .._streaming import SampleAligner, decode_audio
50
+ from .._utils import as_mapping, logger
51
+ from .events import Cancelled, Chunk, Done, Failed
52
+
53
+ __all__ = ["Connection", "Context", "Core", "Driver", "Request", "Signal", "State"]
54
+
55
+ _DRAINING_PHRASE = "Reconnect and send the request again"
56
+
57
+
58
+ class State(enum.Enum):
59
+ QUEUED = "queued"
60
+ INFLIGHT = "inflight"
61
+ BACKOFF = "backoff"
62
+ HELD = "held"
63
+ DONE = "done"
64
+
65
+
66
+ class Outcome(enum.Enum):
67
+ DONE = "done"
68
+ FAILED = "failed"
69
+ CANCELLED = "cancelled"
70
+ WITHDRAWN = "withdrawn" # its send() was cancelled before it was written
71
+
72
+
73
+ class Signal(Protocol):
74
+ """Wakes whoever waits on a context, a request or the send capacity."""
75
+
76
+ def notify(self) -> None: ...
77
+
78
+
79
+ class Driver(Protocol):
80
+ """What the core asks of the async or sync client. None of it blocks."""
81
+
82
+ def new_signal(self) -> Signal: ...
83
+
84
+ def schedule_flush(self) -> None:
85
+ """Send whatever became sendable (opening a connection if needed)."""
86
+ ...
87
+
88
+ def schedule_retry(self, request: Request, delay: float) -> None:
89
+ """After ``delay`` (with the injectable sleep), call ``retry_due``."""
90
+ ...
91
+
92
+ def schedule_reconnect(self, delay: float, *, force: bool) -> None:
93
+ """After ``delay``, flush; with ``force``, open a connection even if
94
+ nothing is waiting to be sent."""
95
+ ...
96
+
97
+ def abort(self, connection: Connection) -> None:
98
+ """Close a connection from the client side (code 1000)."""
99
+ ...
100
+
101
+ def notice(self, error: APIStatusError) -> None:
102
+ """Deliver an error that is about no request."""
103
+ ...
104
+
105
+
106
+ class Connection:
107
+ """One WebSocket connection."""
108
+
109
+ __slots__ = ("closed", "closing", "draining", "id", "opened_at", "received", "transport")
110
+
111
+ def __init__(self, conn_id: int, transport: Any, opened_at: float) -> None:
112
+ self.id = conn_id
113
+ self.transport: Any = transport
114
+ self.opened_at = opened_at
115
+ self.draining = False
116
+ self.closing = False # the client asked to close it
117
+ self.closed = False
118
+ self.received = False
119
+
120
+ def __repr__(self) -> str:
121
+ return f"<connection {self.id}>"
122
+
123
+
124
+ class Request:
125
+ """One request, as the core tracks it. ``handle`` is the driver's view."""
126
+
127
+ __slots__ = (
128
+ "aligner",
129
+ "audio_bytes",
130
+ "conn",
131
+ "context",
132
+ "drained",
133
+ "error",
134
+ "had_audio",
135
+ "handle",
136
+ "outcome",
137
+ "queued_events",
138
+ "request_id",
139
+ "retries",
140
+ "seq",
141
+ "signal",
142
+ "state",
143
+ "wire",
144
+ )
145
+
146
+ def __init__(self, seq: int, context: Context, wire: str, width: int, signal: Signal) -> None:
147
+ self.seq = seq
148
+ self.context = context
149
+ self.wire = wire
150
+ self.aligner = SampleAligner(width)
151
+ self.signal = signal
152
+ self.state = State.QUEUED
153
+ self.conn: Connection | None = None
154
+ self.audio_bytes = 0
155
+ self.had_audio = False
156
+ self.request_id: str | None = None
157
+ self.retries = 0
158
+ self.drained = False # a draining connection refused it once already
159
+ self.outcome: Outcome | None = None
160
+ self.error: BakbakError | None = None
161
+ self.queued_events = 0
162
+ self.handle: Any = None
163
+
164
+
165
+ class Context:
166
+ """One context, as the core tracks it."""
167
+
168
+ __slots__ = (
169
+ "__weakref__",
170
+ "bound",
171
+ "cancel_conn",
172
+ "cancel_epoch",
173
+ "cancel_signal",
174
+ "cancels_pending",
175
+ "events",
176
+ "id",
177
+ "inflight",
178
+ "input_ended",
179
+ "last_activity",
180
+ "pending",
181
+ "signal",
182
+ "unfinished",
183
+ )
184
+
185
+ def __init__(self, context_id: str, signal: Signal, cancel_signal: Signal) -> None:
186
+ self.id = context_id
187
+ self.signal = signal
188
+ self.cancel_signal = cancel_signal
189
+ self.pending: deque[Request] = deque()
190
+ self.inflight: deque[Request] = deque()
191
+ self.bound: Connection | None = None
192
+ self.cancels_pending = 0
193
+ self.cancel_conn: Connection | None = None
194
+ self.cancel_epoch = 0 # bumped by every cancel(): stops a send_stream feeding it
195
+ self.events: deque[tuple[Request, Any]] = deque()
196
+ self.input_ended = False
197
+ self.last_activity = 0.0
198
+ self.unfinished = 0
199
+
200
+ @property
201
+ def busy(self) -> bool:
202
+ return self.unfinished > 0 or self.cancels_pending > 0 or bool(self.inflight)
203
+
204
+
205
+ def _insert_in_order(pending: deque[Request], request: Request) -> None:
206
+ """Put a request back among the unsent ones, keeping send order."""
207
+ for i, other in enumerate(pending):
208
+ if other.seq > request.seq:
209
+ pending.insert(i, request)
210
+ return
211
+ pending.append(request)
212
+
213
+
214
+ def _is_draining(status: int | None, message: object) -> bool:
215
+ """A draining refusal: 503 and the reconnect phrase. ``error_code`` alone
216
+ never is: ``service_unavailable`` also means billing is down (§6.4)."""
217
+ return status == 503 and isinstance(message, str) and _DRAINING_PHRASE in message
218
+
219
+
220
+ class Core:
221
+ """Routing, ordering, cancels, holds, resends and failures."""
222
+
223
+ def __init__(
224
+ self,
225
+ driver: Driver,
226
+ *,
227
+ max_retries: int,
228
+ read_timeout: float | None,
229
+ clock: Callable[[], float] = time.monotonic,
230
+ ) -> None:
231
+ self.driver = driver
232
+ self.max_retries = max_retries
233
+ self.read_timeout = read_timeout
234
+ self.clock = clock
235
+ # The routing table: busy contexts only. Every live context, busy or
236
+ # not, can still be found by id while its owner holds it.
237
+ self.contexts: dict[str, Context] = {}
238
+ self._known: weakref.WeakValueDictionary[str, Context] = weakref.WeakValueDictionary()
239
+ self.connections: list[Connection] = []
240
+ self.current: Connection | None = None
241
+ self.unfinished = 0
242
+ self.failures = 0 # consecutive connections lost before they proved healthy
243
+ self.closed = False
244
+ self.capacity = driver.new_signal()
245
+ self._seq = 0
246
+ self._conn_seq = 0
247
+
248
+ # Contexts and capacity
249
+
250
+ def context(self, context_id: str) -> Context:
251
+ ctx = self._known.get(context_id)
252
+ if ctx is None:
253
+ ctx = Context(context_id, self.driver.new_signal(), self.driver.new_signal())
254
+ self._known[context_id] = ctx
255
+ return ctx
256
+
257
+ def at_capacity(self, ctx: Context) -> bool:
258
+ """Whether a new request on ``ctx`` must wait (§6.2 back-pressure)."""
259
+ if self.unfinished >= WS_MAX_UNFINISHED:
260
+ return True
261
+ if ctx.busy:
262
+ return False
263
+ return sum(1 for c in self.contexts.values() if c.busy) >= WS_MAX_CONTEXTS
264
+
265
+ def submit(
266
+ self, ctx: Context, wire: str, width: int, make_handle: Callable[[Request], Any]
267
+ ) -> Request:
268
+ self._seq += 1
269
+ request = Request(self._seq, ctx, wire, width, self.driver.new_signal())
270
+ request.handle = make_handle(request)
271
+ ctx.pending.append(request)
272
+ ctx.unfinished += 1
273
+ self.unfinished += 1
274
+ self.contexts[ctx.id] = ctx
275
+ return request
276
+
277
+ def withdraw(self, request: Request) -> bool:
278
+ """Take back a request whose ``send()`` was abandoned, if it was not
279
+ written yet. Its caller never got a handle: no event is emitted."""
280
+ if request.state is not State.QUEUED:
281
+ return False
282
+ ctx = request.context
283
+ ctx.pending.remove(request)
284
+ request.state = State.DONE
285
+ request.outcome = Outcome.WITHDRAWN
286
+ ctx.unfinished -= 1
287
+ self.unfinished -= 1
288
+ request.signal.notify()
289
+ ctx.signal.notify()
290
+ self.capacity.notify()
291
+ self._forget_if_idle(ctx)
292
+ return True
293
+
294
+ def end_input(self, ctx: Context) -> None:
295
+ ctx.input_ended = True
296
+ ctx.signal.notify()
297
+
298
+ def _forget_if_idle(self, ctx: Context) -> None:
299
+ if not ctx.busy and self.contexts.get(ctx.id) is ctx:
300
+ del self.contexts[ctx.id]
301
+
302
+ # Sending
303
+
304
+ def usable(self) -> bool:
305
+ conn = self.current
306
+ return conn is not None and not conn.closed and not conn.draining
307
+
308
+ def _waiting_for_connection(self, ctx: Context) -> bool:
309
+ return (
310
+ not ctx.cancels_pending
311
+ and bool(ctx.pending)
312
+ and ctx.pending[0].state is State.QUEUED
313
+ and ctx.bound is None
314
+ )
315
+
316
+ def needs_connection(self) -> bool:
317
+ """Whether a request is ready to go and there is no usable connection."""
318
+ return (
319
+ not self.closed
320
+ and not self.usable()
321
+ and any(self._waiting_for_connection(c) for c in self.contexts.values())
322
+ )
323
+
324
+ def opened(self, transport: Any) -> Connection:
325
+ self._conn_seq += 1
326
+ conn = Connection(self._conn_seq, transport, self.clock())
327
+ self.connections.append(conn)
328
+ self.current = conn
329
+ return conn
330
+
331
+ def take_sendable(self) -> list[tuple[Connection, str]]:
332
+ """Mark every request that may be sent now as in flight on the current
333
+ connection, and return the messages, in send order. The driver must
334
+ write all of them (it shields the writes from cancellation)."""
335
+ conn = self.current
336
+ if self.closed or conn is None or conn.closed or conn.draining:
337
+ return []
338
+ heads: list[Context] = [
339
+ c
340
+ for c in self.contexts.values()
341
+ if not c.cancels_pending
342
+ and c.pending
343
+ and c.pending[0].state is State.QUEUED
344
+ and (c.bound is None or c.bound is conn)
345
+ ]
346
+ out: list[tuple[Connection, str]] = []
347
+ now = self.clock()
348
+ while heads:
349
+ ctx = min(heads, key=lambda c: c.pending[0].seq)
350
+ request = ctx.pending.popleft()
351
+ if not ctx.inflight:
352
+ ctx.last_activity = now
353
+ request.state = State.INFLIGHT
354
+ request.conn = conn
355
+ ctx.inflight.append(request)
356
+ ctx.bound = conn
357
+ out.append((conn, request.wire))
358
+ if not ctx.pending or ctx.pending[0].state is not State.QUEUED:
359
+ heads.remove(ctx)
360
+ return out
361
+
362
+ def fail_waiting(self, error: BakbakError) -> None:
363
+ """No connection could be opened: fail every request waiting for one."""
364
+ for ctx in list(self.contexts.values()):
365
+ if ctx.bound is not None:
366
+ continue
367
+ for request in [r for r in ctx.pending if r.state is State.QUEUED]:
368
+ ctx.pending.remove(request)
369
+ self._finish(request, Outcome.FAILED, error)
370
+
371
+ # Receiving
372
+
373
+ def on_message(self, conn: Connection, text: str) -> None:
374
+ try:
375
+ message = as_mapping(json.loads(text))
376
+ except ValueError:
377
+ logger.debug("ignoring a WebSocket message that is not JSON")
378
+ return
379
+ if message is None:
380
+ return
381
+ conn.received = True
382
+ self.failures = 0
383
+ kind = message.get("type")
384
+ context_id = message.get("context_id")
385
+ ctx = self.contexts.get(context_id) if isinstance(context_id, str) else None
386
+ if ctx is None:
387
+ if kind == "error" and context_id is None:
388
+ self.driver.notice(make_status_error(event_status(message), dict(message)))
389
+ else:
390
+ logger.debug("dropping a %s message for a context with nothing in flight", kind)
391
+ return
392
+ ctx.last_activity = self.clock()
393
+ if kind == "cancelled":
394
+ self._cancel_acknowledged(ctx, conn)
395
+ return
396
+ if ctx.cancels_pending:
397
+ return # cancelled: discard everything until the acknowledgement
398
+ if ctx.bound is not conn or not ctx.inflight:
399
+ logger.debug("dropping a %s message with no request in flight", kind)
400
+ return
401
+ request = ctx.inflight[0]
402
+ if request.state is State.DONE:
403
+ # It already failed (invalid audio); drop the rest of its stream.
404
+ if kind in ("done", "error"):
405
+ self._pop_inflight(ctx)
406
+ return
407
+ request_id = message.get("request_id")
408
+ if isinstance(request_id, str) and request_id:
409
+ request.request_id = request_id
410
+ if kind == "chunk":
411
+ self._on_chunk(ctx, request, message)
412
+ elif kind == "done":
413
+ self._pop_inflight(ctx)
414
+ self._finish(request, Outcome.DONE)
415
+ elif kind == "error":
416
+ self._on_error(conn, ctx, request, dict(message))
417
+
418
+ def _on_chunk(self, ctx: Context, request: Request, message: Any) -> None:
419
+ try:
420
+ raw = decode_audio(message)
421
+ except (binascii.Error, ValueError):
422
+ # The stream broke here (§6.4): fail the request now, and keep it
423
+ # at the head of the context until its stream ends, so its other
424
+ # messages are not taken for the next request's.
425
+ self._finish(
426
+ request,
427
+ Outcome.FAILED,
428
+ make_interrupted_error(
429
+ None,
430
+ audio_bytes=request.audio_bytes,
431
+ header_request_id=request.request_id,
432
+ default_message="The server sent audio that is not valid base64.",
433
+ ),
434
+ )
435
+ return
436
+ if not raw:
437
+ return
438
+ request.had_audio = True
439
+ audio = request.aligner.feed(raw)
440
+ if audio:
441
+ request.audio_bytes += len(audio)
442
+ self._emit(ctx, request, Chunk(audio, request.handle))
443
+
444
+ def _on_error(
445
+ self, conn: Connection, ctx: Context, request: Request, message: dict[str, object]
446
+ ) -> None:
447
+ self._pop_inflight(ctx)
448
+ if request.had_audio:
449
+ self._finish(
450
+ request,
451
+ Outcome.FAILED,
452
+ make_interrupted_error(message, audio_bytes=request.audio_bytes),
453
+ )
454
+ return
455
+ error = make_status_error(event_status(message), message)
456
+ if _is_draining(error.status, message.get("message")):
457
+ # Stop sending here; new requests go to a new connection.
458
+ logger.debug("connection %d is draining", conn.id)
459
+ conn.draining = True
460
+ if self.current is conn:
461
+ self.current = None
462
+ if not request.drained:
463
+ # Hold it (and, through ordering, everything after it in its
464
+ # context) until the context has nothing left on this
465
+ # connection, then resend it on a new one. No retry is spent.
466
+ request.drained = True
467
+ request.state = State.HELD
468
+ request.conn = conn
469
+ _insert_in_order(ctx.pending, request)
470
+ if ctx.bound is None:
471
+ self._release_held(ctx)
472
+ self._close_if_drained(conn)
473
+ return
474
+ # Refused while draining a second time: an ordinary retryable
475
+ # error, resent on a new connection. Later requests of a draining
476
+ # connection are refused too, so this keeps the context's order.
477
+ self._close_if_drained(conn)
478
+ if request.retries < self.max_retries:
479
+ self._back_off(request, error)
480
+ return
481
+ self._finish(request, Outcome.FAILED, error)
482
+ return
483
+ if error.retryable and not ctx.inflight and request.retries < self.max_retries:
484
+ # Nothing later of this context was sent, so resending keeps order.
485
+ self._back_off(request, error)
486
+ return
487
+ self._finish(request, Outcome.FAILED, error)
488
+
489
+ def _back_off(self, request: Request, error: APIStatusError) -> None:
490
+ request.retries += 1
491
+ request.state = State.BACKOFF
492
+ request.conn = None
493
+ _insert_in_order(request.context.pending, request)
494
+ delay = backoff_delay(request.retries)
495
+ logger.debug("retrying a request in %.2f s after: %s", delay, error.message)
496
+ self.driver.schedule_retry(request, delay)
497
+
498
+ def _pop_inflight(self, ctx: Context) -> None:
499
+ conn = ctx.bound
500
+ ctx.inflight.popleft()
501
+ if ctx.inflight:
502
+ return
503
+ ctx.bound = None
504
+ if conn is not None and conn.draining:
505
+ self._release_held(ctx)
506
+ self._close_if_drained(conn)
507
+ self._forget_if_idle(ctx)
508
+
509
+ def _release_held(self, ctx: Context) -> None:
510
+ """``ctx`` has nothing left on a draining connection: what it holds,
511
+ and what it queued meanwhile, goes to a new connection now. Like the
512
+ resends after a 1001, this costs no retry."""
513
+ for request in ctx.pending:
514
+ if request.state is State.HELD:
515
+ request.state = State.QUEUED
516
+ request.conn = None
517
+ if self._waiting_for_connection(ctx):
518
+ self.driver.schedule_flush()
519
+
520
+ def _close_if_drained(self, conn: Connection) -> None:
521
+ """Close a draining connection once no context needs it any more,
522
+ rather than wait for the server (§6.4)."""
523
+ if conn.closed or conn.closing or not conn.draining:
524
+ return
525
+ if any(c.bound is conn or c.cancel_conn is conn for c in self.contexts.values()):
526
+ return
527
+ conn.closing = True
528
+ self.driver.abort(conn)
529
+
530
+ def retry_due(self, request: Request) -> None:
531
+ if request.state is State.BACKOFF:
532
+ request.state = State.QUEUED
533
+ self.driver.schedule_flush()
534
+
535
+ # Closing and reconnecting
536
+
537
+ def on_close(self, conn: Connection, code: int, reason: str) -> None:
538
+ if conn.closed:
539
+ return
540
+ conn.closed = True
541
+ if conn in self.connections:
542
+ self.connections.remove(conn)
543
+ if self.current is conn:
544
+ self.current = None
545
+ if self.closed:
546
+ return
547
+ logger.debug("connection %d closed with %d", conn.id, code)
548
+ if code in (1008, 1009):
549
+ error = WebSocketClosedError(
550
+ f"The server closed the WebSocket ({code}): {reason or 'policy violation'}",
551
+ code=code,
552
+ reason=reason,
553
+ retryable=False,
554
+ )
555
+ self._fail_all(error)
556
+ return
557
+ resend = 0
558
+ unfinished = False
559
+ for ctx in list(self.contexts.values()):
560
+ if ctx.cancel_conn is conn:
561
+ self._settle_cancels(ctx)
562
+ if ctx.bound is conn:
563
+ for request in list(ctx.inflight):
564
+ if request.state is State.DONE:
565
+ continue # already failed; its stream is gone with the connection
566
+ unfinished = True
567
+ if request.had_audio:
568
+ self._finish(
569
+ request,
570
+ Outcome.FAILED,
571
+ make_interrupted_error(
572
+ None,
573
+ audio_bytes=request.audio_bytes,
574
+ header_request_id=request.request_id,
575
+ default_message="The WebSocket closed before the audio was complete.",
576
+ ),
577
+ )
578
+ else:
579
+ request.state = State.QUEUED
580
+ request.conn = None
581
+ _insert_in_order(ctx.pending, request)
582
+ resend += 1
583
+ ctx.inflight.clear()
584
+ ctx.bound = None
585
+ for request in ctx.pending:
586
+ if request.state is State.HELD and request.conn is conn:
587
+ request.state = State.QUEUED
588
+ request.conn = None
589
+ resend += 1
590
+ self._forget_if_idle(ctx)
591
+ # Going away (1001), a draining connection, or a 1000 that arrives with
592
+ # work unfinished: reconnect at once and resend; this costs no retry.
593
+ if code == 1001 or conn.draining or conn.closing or (code == 1000 and unfinished):
594
+ self.driver.schedule_reconnect(0.0, force=code == 1001)
595
+ return
596
+ if resend == 0:
597
+ # Nothing was in flight here, but requests may be waiting for a
598
+ # connection (queued behind a cancel this close just settled).
599
+ if self.needs_connection():
600
+ self.driver.schedule_reconnect(0.0, force=False)
601
+ return
602
+ healthy = conn.received or self.clock() - conn.opened_at >= WS_HEALTHY_AFTER
603
+ self.failures = 0 if healthy else self.failures + 1
604
+ if self.failures > self.max_retries:
605
+ self.failures = 0
606
+ self.fail_waiting(
607
+ WebSocketClosedError(
608
+ f"The WebSocket kept closing ({code}) before any answer arrived.",
609
+ code=code,
610
+ reason=reason,
611
+ retryable=True,
612
+ )
613
+ )
614
+ return
615
+ delay = backoff_delay(self.failures) if self.failures else 0.0
616
+ self.driver.schedule_reconnect(delay, force=False)
617
+
618
+ def _fail_all(self, error: BakbakError) -> None:
619
+ for ctx in list(self.contexts.values()):
620
+ requests = sorted([*ctx.inflight, *ctx.pending], key=lambda r: r.seq)
621
+ ctx.inflight.clear()
622
+ ctx.pending.clear()
623
+ ctx.bound = None
624
+ self._settle_cancels(ctx)
625
+ for request in requests:
626
+ self._finish(request, Outcome.FAILED, error)
627
+ self._forget_if_idle(ctx)
628
+
629
+ def close(self) -> list[Connection]:
630
+ """The user closed the WebSocket: fail what is unfinished and return
631
+ the connections to close."""
632
+ if self.closed:
633
+ return []
634
+ self._fail_all(
635
+ WebSocketClosedError(
636
+ "The WebSocket was closed by the client.", code=1000, retryable=False
637
+ )
638
+ )
639
+ self.closed = True
640
+ for ctx in list(self._known.values()):
641
+ ctx.signal.notify()
642
+ ctx.cancel_signal.notify()
643
+ self.capacity.notify()
644
+ conns = list(self.connections)
645
+ self.current = None
646
+ return conns
647
+
648
+ # Cancelling
649
+
650
+ def cancel(self, ctx: Context) -> Connection | None:
651
+ """End every unfinished request of ``ctx`` as cancelled, discard all
652
+ of its audio not handed out yet, and stop a ``send_stream`` feeding
653
+ it: a cancel means silence now (§6.3). Returns the connection to send
654
+ the cancel message on, or ``None`` if nothing on the server needs
655
+ cancelling."""
656
+ ctx.cancel_epoch += 1
657
+ self._discard_queued_audio(ctx)
658
+ conn = ctx.bound
659
+ requests = sorted([*ctx.inflight, *ctx.pending], key=lambda r: r.seq)
660
+ had_inflight = bool(ctx.inflight)
661
+ ctx.inflight.clear()
662
+ ctx.pending.clear()
663
+ ctx.bound = None
664
+ for request in requests:
665
+ self._finish(request, Outcome.CANCELLED)
666
+ ctx.signal.notify()
667
+ if not had_inflight or conn is None or conn.closed:
668
+ self._forget_if_idle(ctx)
669
+ return None
670
+ ctx.cancels_pending += 1
671
+ ctx.cancel_conn = conn
672
+ ctx.last_activity = self.clock()
673
+ self.contexts[ctx.id] = ctx # busy until the acknowledgement
674
+ return conn
675
+
676
+ @staticmethod
677
+ def _discard_queued_audio(ctx: Context) -> None:
678
+ kept: deque[tuple[Request, Any]] = deque()
679
+ for request, event in ctx.events:
680
+ if isinstance(event, Chunk):
681
+ request.queued_events -= 1
682
+ request.audio_bytes -= len(event.audio) # it was never delivered
683
+ else:
684
+ kept.append((request, event))
685
+ ctx.events = kept
686
+
687
+ def cancel_message(self, ctx: Context) -> str:
688
+ return json.dumps({"context_id": ctx.id, "cancel": True}, separators=(",", ":"))
689
+
690
+ def _cancel_acknowledged(self, ctx: Context, conn: Connection) -> None:
691
+ if not ctx.cancels_pending or ctx.cancel_conn is not conn:
692
+ return
693
+ ctx.cancels_pending -= 1
694
+ if not ctx.cancels_pending:
695
+ self._settle_cancels(ctx)
696
+
697
+ def _settle_cancels(self, ctx: Context) -> None:
698
+ """The cancel is acknowledged, or its connection is gone. Requests the
699
+ context queued meanwhile go out now: a new connection is opened if
700
+ needed, so nothing waits behind a cancel that will never be answered."""
701
+ conn = ctx.cancel_conn
702
+ ctx.cancels_pending = 0
703
+ ctx.cancel_conn = None
704
+ ctx.cancel_signal.notify()
705
+ self.capacity.notify()
706
+ if self._waiting_for_connection(ctx):
707
+ self.driver.schedule_flush()
708
+ if conn is not None:
709
+ self._close_if_drained(conn)
710
+ self._forget_if_idle(ctx)
711
+
712
+ # Read timeouts
713
+
714
+ def check_timeouts(self) -> tuple[float | None, list[tuple[Connection, str]]]:
715
+ """Fail requests that waited longer than the read timeout. Returns the
716
+ seconds until the next deadline and cancel messages to send."""
717
+ if self.read_timeout is None or self.closed:
718
+ return None, []
719
+ now = self.clock()
720
+ soonest: float | None = None
721
+ sends: list[tuple[Connection, str]] = []
722
+ for ctx in list(self.contexts.values()):
723
+ if not ctx.inflight and not ctx.cancels_pending:
724
+ continue
725
+ deadline = ctx.last_activity + self.read_timeout
726
+ if deadline > now:
727
+ soonest = deadline if soonest is None else min(soonest, deadline)
728
+ continue
729
+ ctx.last_activity = now
730
+ if ctx.cancels_pending:
731
+ # The server did not acknowledge a cancel: the connection is
732
+ # unusable for this context. Close it; the close handling
733
+ # resends or fails what other contexts had on it.
734
+ if ctx.cancel_conn is not None and not ctx.cancel_conn.closing:
735
+ ctx.cancel_conn.closing = True
736
+ self.driver.abort(ctx.cancel_conn)
737
+ continue
738
+ conn = ctx.bound
739
+ for request in list(ctx.inflight):
740
+ if request.had_audio:
741
+ error: BakbakError = make_interrupted_error(
742
+ None,
743
+ audio_bytes=request.audio_bytes,
744
+ header_request_id=request.request_id,
745
+ default_message="No audio arrived within the read timeout.",
746
+ )
747
+ else:
748
+ error = APITimeoutError("No answer arrived within the read timeout.")
749
+ self._finish(request, Outcome.FAILED, error)
750
+ ctx.inflight.clear()
751
+ ctx.bound = None
752
+ if conn is not None and not conn.closed:
753
+ # Stop the server's work and drop its late messages.
754
+ ctx.cancels_pending += 1
755
+ ctx.cancel_conn = conn
756
+ sends.append((conn, self.cancel_message(ctx)))
757
+ else:
758
+ self._forget_if_idle(ctx)
759
+ soonest = now + self.read_timeout if soonest is None else soonest
760
+ return (None if soonest is None else max(soonest - now, 0.0)), sends
761
+
762
+ # Events
763
+
764
+ def _emit(self, ctx: Context, request: Request, event: Any) -> None:
765
+ ctx.events.append((request, event))
766
+ request.queued_events += 1
767
+ ctx.signal.notify()
768
+
769
+ def _finish(self, request: Request, outcome: Outcome, error: BakbakError | None = None) -> None:
770
+ if request.state is State.DONE:
771
+ return
772
+ request.state = State.DONE
773
+ request.outcome = outcome
774
+ request.error = error
775
+ ctx = request.context
776
+ ctx.unfinished -= 1
777
+ self.unfinished -= 1
778
+ if outcome is Outcome.DONE:
779
+ leftover = request.aligner.leftover()
780
+ if leftover:
781
+ logger.debug("dropping %d bytes of an incomplete last sample", leftover)
782
+ event: Any = Done(request.handle)
783
+ elif outcome is Outcome.CANCELLED:
784
+ event = Cancelled(request.handle)
785
+ else:
786
+ assert error is not None
787
+ event = Failed(request.handle, error)
788
+ self._emit(ctx, request, event)
789
+ request.signal.notify()
790
+ self.capacity.notify()
791
+ self._forget_if_idle(ctx)
792
+
793
+ def pop_event(self, ctx: Context) -> Any | None:
794
+ if not ctx.events:
795
+ return None
796
+ request, event = ctx.events.popleft()
797
+ request.queued_events -= 1
798
+ return event
799
+
800
+ def events_finished(self, ctx: Context) -> bool:
801
+ return not ctx.events and not ctx.unfinished and (ctx.input_ended or self.closed)
802
+
803
+ def pop_request_event(self, request: Request) -> tuple[Any | None, bool]:
804
+ """The next event of ``request``, consuming any earlier request's
805
+ events before it. Returns ``(event, finished)``; ``(None, False)``
806
+ means wait."""
807
+ ctx = request.context
808
+ while ctx.events:
809
+ owner, event = ctx.events[0]
810
+ if owner.seq < request.seq:
811
+ ctx.events.popleft()
812
+ owner.queued_events -= 1
813
+ continue
814
+ if owner is request:
815
+ ctx.events.popleft()
816
+ request.queued_events -= 1
817
+ return event, False
818
+ return None, True # a later request's events: this one's were read elsewhere
819
+ return None, request.state is State.DONE and not request.queued_events