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/_sync.py ADDED
@@ -0,0 +1,649 @@
1
+ """The threaded WebSocket client: ``TTSWebSocket`` and its contexts.
2
+
3
+ A background reader thread per connection routes every message through the
4
+ core (the same one the asyncio client uses) under one lock; waiting callers
5
+ sleep on conditions of that lock. Timers (retry backoff and reconnects) run
6
+ on short-lived daemon threads, and a watchdog thread enforces the read timeout.
7
+ """
8
+
9
+ # The driver is the client's own internals.
10
+ # pyright: reportPrivateUsage=false
11
+
12
+ from __future__ import annotations
13
+
14
+ import inspect
15
+ import threading
16
+ import time
17
+ from collections.abc import Callable, Iterable, Iterator, Mapping
18
+ from types import TracebackType
19
+ from typing import TYPE_CHECKING, Any, cast
20
+
21
+ from typing_extensions import Self, Unpack, override
22
+ from websockets.exceptions import ConnectionClosed
23
+ from websockets.sync import client as _sync_client
24
+ from websockets.sync.client import ClientConnection, connect
25
+
26
+ from .._constants import WS_CLOSE_TIMEOUT, WS_MAX_MESSAGE_BYTES
27
+ from .._exceptions import APIStatusError, BakbakError
28
+ from .._retry import retry_delay
29
+ from .._utils import logger, redact_url, user_agent
30
+ from ..text import Segmenter
31
+ from ..types import RequestDefaults, SendParams
32
+ from ._common import (
33
+ WEBSOCKET_LOGGER,
34
+ build_request,
35
+ check_context_id,
36
+ connect_error,
37
+ open_failure,
38
+ text_delta,
39
+ )
40
+ from ._core import Connection, Core, Outcome, Request, State
41
+ from .events import Chunk, Failed, RequestResult, WebSocketEvent
42
+
43
+ if TYPE_CHECKING:
44
+ from .._client import Bakbak
45
+
46
+ __all__ = ["Context", "RequestHandle", "TTSWebSocket"]
47
+
48
+
49
+ # From websockets 17.1 the threaded client follows redirects, through the
50
+ # `reconnect` connecter that `connect` uses. A redirect would carry X-API-Key
51
+ # to another origin (§8), so the SDK builds that connecter itself with
52
+ # redirects refused. Earlier releases never follow redirects.
53
+ _Reconnect: Any = getattr(_sync_client, "reconnect", None)
54
+ _FOLLOWS_REDIRECTS = _Reconnect is not None and "legacy" in inspect.signature(connect).parameters
55
+
56
+
57
+ def _connect(url: str, **kwargs: Any) -> ClientConnection:
58
+ if not _FOLLOWS_REDIRECTS:
59
+ return cast("ClientConnection", connect(url, **kwargs))
60
+ connecter = _Reconnect(url, **kwargs)
61
+ connecter.process_redirect = _refuse_redirect
62
+ connection = cast("ClientConnection", connecter.connect())
63
+ # The SDK manages the connection's lifetime itself (websockets' "legacy" use).
64
+ connection.pending_legacy_warning = False # pyright: ignore[reportAttributeAccessIssue]
65
+ return connection
66
+
67
+
68
+ def _refuse_redirect(exc: Exception) -> Exception | str:
69
+ """Never follow a redirect: a 3xx is raised as ``InvalidStatus`` and
70
+ becomes an ``APIStatusError``."""
71
+ return exc
72
+
73
+
74
+ class _Signal:
75
+ """A condition on the WebSocket's lock. Use it with the lock held."""
76
+
77
+ __slots__ = ("_cond",)
78
+
79
+ def __init__(self, lock: threading.RLock) -> None:
80
+ self._cond = threading.Condition(lock)
81
+
82
+ def notify(self) -> None:
83
+ self._cond.notify_all()
84
+
85
+ def wait(self, timeout: float | None = None) -> None:
86
+ self._cond.wait(timeout)
87
+
88
+
89
+ def _signal(core_signal: object) -> _Signal:
90
+ assert isinstance(core_signal, _Signal)
91
+ return core_signal
92
+
93
+
94
+ class RequestHandle:
95
+ """One request sent on a context.
96
+
97
+ ``handle.result()`` waits for its outcome and raises its error if it
98
+ failed. ``for audio in handle`` yields its audio; that reads the context's
99
+ events up to the end of this request, so use either the handles or
100
+ ``ctx.events()``/``ctx.audio()``, not both.
101
+ """
102
+
103
+ __slots__ = ("_context", "_request")
104
+
105
+ def __init__(self, request: Request, context: Context) -> None:
106
+ self._request = request
107
+ self._context = context
108
+
109
+ @property
110
+ def context_id(self) -> str:
111
+ return self._context.context_id
112
+
113
+ @property
114
+ def request_id(self) -> str | None:
115
+ """The server's id for the request, once its first message arrived."""
116
+ return self._request.request_id
117
+
118
+ @property
119
+ def audio_bytes(self) -> int:
120
+ """Audio delivered so far."""
121
+ return self._request.audio_bytes
122
+
123
+ @property
124
+ def done(self) -> bool:
125
+ """Whether the request has an outcome."""
126
+ return self._request.state is State.DONE
127
+
128
+ def result(self, timeout: float | None = None) -> RequestResult:
129
+ """Wait for the outcome.
130
+
131
+ Raises:
132
+ BakbakError: the request's error, if it failed.
133
+ TimeoutError: if ``timeout`` seconds pass first.
134
+ """
135
+ request = self._request
136
+ deadline = None if timeout is None else time.monotonic() + timeout
137
+ with self._context._ws._lock:
138
+ while request.state is not State.DONE:
139
+ remaining = None if deadline is None else deadline - time.monotonic()
140
+ if remaining is not None and remaining <= 0:
141
+ raise TimeoutError("The request did not finish in time.")
142
+ _signal(request.signal).wait(remaining)
143
+ if request.outcome is Outcome.FAILED and request.error is not None:
144
+ raise request.error
145
+ return RequestResult(
146
+ request.request_id, request.audio_bytes, cancelled=request.outcome is Outcome.CANCELLED
147
+ )
148
+
149
+ def __iter__(self) -> Iterator[bytes]:
150
+ ws = self._context._ws
151
+ core = ws._core
152
+ request = self._request
153
+ while True:
154
+ with ws._lock:
155
+ while True:
156
+ event, finished = core.pop_request_event(request)
157
+ if event is not None or finished:
158
+ break
159
+ _signal(request.context.signal).wait()
160
+ if event is None:
161
+ if request.outcome is Outcome.FAILED and request.error is not None:
162
+ raise request.error
163
+ return
164
+ if isinstance(event, Chunk):
165
+ yield event.audio # pyright: ignore[reportUnknownMemberType]
166
+ elif isinstance(event, Failed):
167
+ raise event.error
168
+ else:
169
+ return
170
+
171
+ @override
172
+ def __repr__(self) -> str:
173
+ return (
174
+ f"RequestHandle(context_id={self.context_id!r}, request_id={self.request_id!r}, "
175
+ f"done={self.done!r}, audio_bytes={self.audio_bytes})"
176
+ )
177
+
178
+
179
+ class Context:
180
+ """A sequence of requests whose audio plays in order (BEHAVIOR.md §6.2).
181
+
182
+ Requests on one context run one after another; different contexts run at
183
+ the same time. Get one from ``ws.context()``. Its methods are thread-safe.
184
+ """
185
+
186
+ __slots__ = ("_ctx", "_defaults", "_ws", "context_id")
187
+
188
+ def __init__(self, ws: TTSWebSocket, context_id: str, defaults: dict[str, object]) -> None:
189
+ self._ws = ws
190
+ self.context_id = context_id
191
+ self._defaults = defaults
192
+ with ws._lock:
193
+ self._ctx = ws._core.context(context_id)
194
+
195
+ def send(
196
+ self, *, extra_body: dict[str, object] | None = None, **params: Unpack[SendParams]
197
+ ) -> RequestHandle:
198
+ """Send one request. Fields left out come from the context's and the
199
+ WebSocket's defaults; ``extra_body`` adds fields the SDK does not
200
+ model yet.
201
+
202
+ It blocks only while the connection's limits are reached (64
203
+ unfinished requests, or 16 busy contexts); a server-side failure does
204
+ not raise here but becomes the request's outcome.
205
+ """
206
+ handle = self._send(params, extra_body, None)
207
+ assert handle is not None
208
+ return handle
209
+
210
+ def _send(
211
+ self,
212
+ params: Mapping[str, object],
213
+ extra_body: Mapping[str, object] | None,
214
+ epoch: int | None,
215
+ ) -> RequestHandle | None:
216
+ """Send one request; with ``epoch``, send nothing (and return None) if
217
+ the context was cancelled since that epoch."""
218
+ ws = self._ws
219
+ core = ws._core
220
+ ctx = self._ctx
221
+ wire, width = build_request(
222
+ {**ws._defaults, **self._defaults}, params, extra_body, self.context_id
223
+ )
224
+ with ws._lock:
225
+ while True:
226
+ if core.closed:
227
+ raise BakbakError("This WebSocket is closed.")
228
+ if ctx.input_ended:
229
+ raise BakbakError("end_input() was called on this context; use a new context.")
230
+ if epoch is not None and ctx.cancel_epoch != epoch:
231
+ return None
232
+ if not core.at_capacity(ctx):
233
+ break
234
+ _signal(core.capacity).wait()
235
+ request = core.submit(ctx, wire, width, lambda r: RequestHandle(r, self))
236
+ ws._flush()
237
+ handle: RequestHandle = request.handle
238
+ return handle
239
+
240
+ def send_stream(
241
+ self,
242
+ tokens: Iterable[object],
243
+ *,
244
+ end_input: bool = True,
245
+ segmenter: Segmenter | None = None,
246
+ **params: Unpack[RequestDefaults],
247
+ ) -> list[RequestHandle]:
248
+ """Send text that arrives in pieces, such as LLM tokens, sentence by
249
+ sentence as each sentence is final.
250
+
251
+ ``tokens`` is an iterable of ``str``, or of stream events from an LLM
252
+ SDK (OpenAI, Anthropic or Gemini style; the text delta is found by
253
+ duck typing). It blocks until ``tokens`` is exhausted, so read the
254
+ audio on another thread. A ``cancel()`` of the context stops it: it
255
+ sends nothing more and returns (after the next token arrives). Calls
256
+ ``end_input()`` at the end unless ``end_input=False``, also when
257
+ ``tokens`` raises.
258
+
259
+ Args:
260
+ segmenter: a configured :class:`bakbak.text.Segmenter`, e.g. with
261
+ ``eager_first_clause=True`` for an earlier first request.
262
+ """
263
+ splitter = segmenter or Segmenter()
264
+ handles: list[RequestHandle] = []
265
+ epoch = self._ctx.cancel_epoch
266
+ try:
267
+ for item in tokens:
268
+ if self._ctx.cancel_epoch != epoch:
269
+ return handles
270
+ text = text_delta(item)
271
+ if not text:
272
+ continue
273
+ for sentence in splitter.push(text):
274
+ handle = self._send({**params, "text": sentence}, None, epoch)
275
+ if handle is None:
276
+ return handles
277
+ handles.append(handle)
278
+ for sentence in splitter.flush():
279
+ handle = self._send({**params, "text": sentence}, None, epoch)
280
+ if handle is None:
281
+ return handles
282
+ handles.append(handle)
283
+ finally:
284
+ if end_input:
285
+ self.end_input()
286
+ return handles
287
+
288
+ def end_input(self) -> None:
289
+ """No more requests: ``events()`` and ``audio()`` end once every
290
+ request has an outcome."""
291
+ with self._ws._lock:
292
+ self._ws._core.end_input(self._ctx)
293
+
294
+ def cancel(self) -> None:
295
+ """Cancel every unfinished request of this context.
296
+
297
+ Their audio stops at once (what arrives before the server's
298
+ acknowledgement is discarded) and each ends as ``Cancelled``. Returns
299
+ when the server has acknowledged; the context is then ready for new
300
+ requests.
301
+ """
302
+ ws = self._ws
303
+ core = ws._core
304
+ with ws._lock:
305
+ conn = core.cancel(self._ctx)
306
+ message = core.cancel_message(self._ctx)
307
+ if conn is not None:
308
+ ws._write(conn, message)
309
+ with ws._lock:
310
+ while self._ctx.cancels_pending and not core.closed:
311
+ _signal(self._ctx.cancel_signal).wait()
312
+
313
+ def events(self) -> Iterator[WebSocketEvent[RequestHandle]]:
314
+ """Yield ``Chunk``, ``Done``, ``Failed`` and ``Cancelled`` in order.
315
+
316
+ Ends after ``end_input()`` once every request has its outcome."""
317
+ ws = self._ws
318
+ core = ws._core
319
+ ctx = self._ctx
320
+ while True:
321
+ with ws._lock:
322
+ while True:
323
+ event = core.pop_event(ctx)
324
+ if event is not None:
325
+ break
326
+ if core.events_finished(ctx):
327
+ return
328
+ _signal(ctx.signal).wait()
329
+ yield event
330
+
331
+ def audio(self) -> Iterator[bytes]:
332
+ """Yield only the audio, and raise the first failure."""
333
+ for event in self.events():
334
+ if isinstance(event, Chunk):
335
+ yield event.audio
336
+ elif isinstance(event, Failed):
337
+ raise event.error
338
+
339
+ @override
340
+ def __repr__(self) -> str:
341
+ return f"Context(context_id={self.context_id!r})"
342
+
343
+
344
+ class TTSWebSocket:
345
+ """Many streaming requests over one WebSocket (BEHAVIOR.md §6).
346
+
347
+ ``ws.connect()`` (or ``with``) opens it ahead of time so the first request
348
+ pays no handshake; otherwise the first send opens it. Reconnects, resends
349
+ and holds are handled for you; every unfinished request gets an outcome
350
+ when a connection is lost.
351
+ """
352
+
353
+ def __init__(
354
+ self,
355
+ client: Bakbak,
356
+ defaults: RequestDefaults,
357
+ on_error: Callable[[APIStatusError], None] | None,
358
+ ) -> None:
359
+ self._client = client
360
+ self._defaults: dict[str, object] = dict(defaults)
361
+ self._on_error = on_error
362
+ self._lock = threading.RLock()
363
+ self._send_lock = threading.Lock()
364
+ self._connect_lock = threading.Lock()
365
+ self._notices: list[APIStatusError] = []
366
+ self._watchdog: threading.Thread | None = None
367
+ self._wake = threading.Event()
368
+ self._readers: list[threading.Thread] = []
369
+ self._core = Core(self, max_retries=client.max_retries, read_timeout=client.timeout.read)
370
+
371
+ # Public API
372
+
373
+ @property
374
+ def url(self) -> str:
375
+ """The WebSocket URL (it never contains the API key)."""
376
+ return self._client.websocket_url
377
+
378
+ @property
379
+ def connected(self) -> bool:
380
+ """Whether a connection is open and accepting requests."""
381
+ with self._lock:
382
+ return self._core.usable()
383
+
384
+ def __enter__(self) -> Self:
385
+ return self.connect()
386
+
387
+ def __exit__(
388
+ self,
389
+ exc_type: type[BaseException] | None,
390
+ exc: BaseException | None,
391
+ tb: TracebackType | None,
392
+ ) -> None:
393
+ self.close()
394
+
395
+ def connect(self) -> Self:
396
+ """Open the connection now, so the first request pays no handshake.
397
+
398
+ Raises:
399
+ AuthenticationError: the key was refused (or another
400
+ ``APIStatusError`` for another refusal).
401
+ APIConnectionError: the server could not be reached.
402
+ """
403
+ with self._lock:
404
+ if self._core.closed:
405
+ raise BakbakError("This WebSocket is closed.")
406
+ with self._connect_lock:
407
+ with self._lock:
408
+ usable = self._core.usable()
409
+ if not usable:
410
+ self._open()
411
+ return self
412
+
413
+ def context(
414
+ self, context_id: str | None = None, **defaults: Unpack[RequestDefaults]
415
+ ) -> Context:
416
+ """A context: requests on it play in order.
417
+
418
+ Args:
419
+ context_id: 1 to 128 characters of ``A-Z a-z 0-9 . _ -``; a random
420
+ ``ctx_…`` id when left out.
421
+ **defaults: request fields for this context, over the WebSocket's.
422
+ """
423
+ with self._lock:
424
+ if self._core.closed:
425
+ raise BakbakError("This WebSocket is closed.")
426
+ return Context(self, check_context_id(context_id), dict(defaults))
427
+
428
+ def close(self) -> None:
429
+ """Close the WebSocket. Unfinished requests fail with
430
+ ``WebSocketClosedError``."""
431
+ with self._lock:
432
+ connections = self._core.close()
433
+ readers = list(self._readers)
434
+ self._wake.set()
435
+ # Close every connection at once, and never wait much more than
436
+ # WS_CLOSE_TIMEOUT for peers that do not answer.
437
+ closers = [
438
+ threading.Thread(target=self._close_transport, args=(c.transport,), daemon=True)
439
+ for c in connections
440
+ ]
441
+ for closer in closers:
442
+ closer.start()
443
+ deadline = time.monotonic() + WS_CLOSE_TIMEOUT + 0.25
444
+ current = threading.current_thread()
445
+ for thread in [*closers, *readers]:
446
+ if thread is not current:
447
+ thread.join(max(deadline - time.monotonic(), 0.0))
448
+
449
+ @override
450
+ def __repr__(self) -> str:
451
+ return f"TTSWebSocket(url={self.url!r}, connected={self.connected!r})"
452
+
453
+ # Driver: called by the core with the lock held, never blocking
454
+
455
+ def new_signal(self) -> _Signal:
456
+ return _Signal(self._lock)
457
+
458
+ def schedule_flush(self) -> None:
459
+ self._spawn(self._flush)
460
+
461
+ def schedule_retry(self, request: Request, delay: float) -> None:
462
+ def run() -> None:
463
+ self._client._sleep(delay)
464
+ with self._lock:
465
+ self._core.retry_due(request)
466
+
467
+ self._spawn(run)
468
+
469
+ def schedule_reconnect(self, delay: float, *, force: bool) -> None:
470
+ def run() -> None:
471
+ if delay:
472
+ self._client._sleep(delay)
473
+ self._flush(force_connect=force)
474
+
475
+ self._spawn(run)
476
+
477
+ def abort(self, connection: Connection) -> None:
478
+ self._spawn(lambda: self._close_transport(connection.transport))
479
+
480
+ def notice(self, error: APIStatusError) -> None:
481
+ self._notices.append(error)
482
+
483
+ # Internals
484
+
485
+ @staticmethod
486
+ def _spawn(target: Callable[[], None]) -> None:
487
+ threading.Thread(target=target, name="bakbak-ws", daemon=True).start()
488
+
489
+ def _dispatch_notices(self) -> None:
490
+ with self._lock:
491
+ notices, self._notices = self._notices, []
492
+ for error in notices:
493
+ if self._on_error is None:
494
+ logger.debug("WebSocket error about no request: %s", error.message)
495
+ continue
496
+ try:
497
+ self._on_error(error)
498
+ except Exception:
499
+ logger.debug("the on_error callback raised", exc_info=True)
500
+
501
+ def _open(self) -> None:
502
+ """Open a connection, retrying what can be retried."""
503
+ url = self.url
504
+ retries = 0
505
+ while True:
506
+ started = time.monotonic()
507
+ try:
508
+ transport = _connect(
509
+ url,
510
+ additional_headers=self._client.websocket_headers(),
511
+ user_agent_header=user_agent(),
512
+ compression=None,
513
+ open_timeout=self._client.timeout.connect,
514
+ close_timeout=WS_CLOSE_TIMEOUT,
515
+ max_size=WS_MAX_MESSAGE_BYTES,
516
+ logger=WEBSOCKET_LOGGER,
517
+ )
518
+ except Exception as exc:
519
+ mapped = connect_error(exc)
520
+ if mapped is None:
521
+ raise
522
+ error, retry_after = mapped
523
+ else:
524
+ break
525
+ # Raised outside the except block: the error carries no chained
526
+ # exception from the WebSocket library.
527
+ if not getattr(error, "retryable", False) or retries >= self._core.max_retries:
528
+ raise error
529
+ retries += 1
530
+ delay = retry_delay(retries, retry_after)
531
+ logger.debug("WebSocket connect failed (%s); retrying in %.2f s", error.message, delay)
532
+ self._client._sleep(delay)
533
+ logger.debug(
534
+ "WebSocket connected to %s in %.0f ms",
535
+ redact_url(url),
536
+ (time.monotonic() - started) * 1000,
537
+ )
538
+ with self._lock:
539
+ if self._core.closed:
540
+ closed = True
541
+ else:
542
+ closed = False
543
+ conn = self._core.opened(transport)
544
+ reader = threading.Thread(
545
+ target=self._read, args=(conn,), name="bakbak-ws-reader", daemon=True
546
+ )
547
+ self._readers = [r for r in self._readers if r.is_alive()]
548
+ self._readers.append(reader)
549
+ reader.start()
550
+ self._ensure_watchdog()
551
+ if closed:
552
+ self._close_transport(transport)
553
+ return
554
+
555
+ def _flush(self, force_connect: bool = False) -> None:
556
+ """Open a connection if a request needs one, then send what can go."""
557
+ core = self._core
558
+
559
+ def needed() -> bool:
560
+ with self._lock:
561
+ return (
562
+ not core.closed
563
+ and not core.usable()
564
+ and (force_connect or core.needs_connection())
565
+ )
566
+
567
+ if needed():
568
+ with self._connect_lock:
569
+ if needed():
570
+ try:
571
+ self._open()
572
+ except Exception as exc:
573
+ with self._lock:
574
+ core.fail_waiting(open_failure(exc))
575
+ return
576
+ with self._send_lock:
577
+ with self._lock:
578
+ batch = core.take_sendable()
579
+ for conn, wire in batch:
580
+ if not self._send(conn, wire):
581
+ break
582
+
583
+ def _write(self, conn: Connection, wire: str) -> None:
584
+ with self._send_lock:
585
+ self._send(conn, wire)
586
+
587
+ def _send(self, conn: Connection, wire: str) -> bool:
588
+ transport: ClientConnection = conn.transport
589
+ try:
590
+ transport.send(wire)
591
+ except Exception:
592
+ # The reader sees the close and resends or fails what was in flight.
593
+ logger.debug("WebSocket send failed on connection %d", conn.id, exc_info=True)
594
+ self._close_transport(transport)
595
+ return False
596
+ return True
597
+
598
+ def _read(self, conn: Connection) -> None:
599
+ transport: ClientConnection = conn.transport
600
+ try:
601
+ for message in transport:
602
+ if isinstance(message, str):
603
+ with self._lock:
604
+ self._core.on_message(conn, message)
605
+ if self._notices:
606
+ self._dispatch_notices()
607
+ except ConnectionClosed:
608
+ pass
609
+ except Exception:
610
+ logger.debug("WebSocket reader failed on connection %d", conn.id, exc_info=True)
611
+ finally:
612
+ if transport.close_code is None:
613
+ self._close_transport(transport)
614
+ with self._lock:
615
+ self._core.on_close(
616
+ conn, transport.close_code or 1006, transport.close_reason or ""
617
+ )
618
+ self._dispatch_notices()
619
+
620
+ @staticmethod
621
+ def _close_transport(transport: ClientConnection) -> None:
622
+ try:
623
+ transport.close()
624
+ except Exception:
625
+ logger.debug("closing a WebSocket failed", exc_info=True)
626
+
627
+ def _ensure_watchdog(self) -> None:
628
+ if self._core.read_timeout is None:
629
+ return
630
+ if self._watchdog is None or not self._watchdog.is_alive():
631
+ self._wake.clear()
632
+ self._watchdog = threading.Thread(
633
+ target=self._watch, name="bakbak-ws-watchdog", daemon=True
634
+ )
635
+ self._watchdog.start()
636
+
637
+ def _watch(self) -> None:
638
+ """Fail requests that hear nothing for the read timeout."""
639
+ core = self._core
640
+ idle = core.read_timeout or 60.0
641
+ while True:
642
+ with self._lock:
643
+ if core.closed or not core.connections:
644
+ self._watchdog = None
645
+ return
646
+ wait, sends = core.check_timeouts()
647
+ for conn, wire in sends:
648
+ self._write(conn, wire)
649
+ self._wake.wait(idle if wait is None else min(wait, idle))