|
10 | 10 | (including ``utils.conversation_utils``, which the RQ workers import, and |
11 | 11 | ``SessionStore``) without risk of an import cycle. |
12 | 12 |
|
13 | | -**Scope (Stage 1):** the session-scoped pointer/lock keys and the |
14 | | -``speech_detection_job`` family. Other key families (``transcription:*``, |
15 | | -``audio:stream:*``, ``sse:*``, …) are still built inline and may migrate here later. |
| 13 | +**Current scope:** session-scoped pointer/lock keys, ``speech_detection_job`` keys, |
| 14 | +raw audio stream names, final transcription result stream names, and device |
| 15 | +downlink channels. Other key families (``sse:*``, some admin/debug keys, …) are |
| 16 | +still built inline and may migrate here later. |
16 | 17 |
|
17 | 18 | **Invariant:** every WebSocket recording has a unique ``session_id``. A client may |
18 | 19 | have many historical sessions, and each session owns an immutable raw-audio WAL. |
19 | 20 | """ |
20 | 21 |
|
| 22 | +from dataclasses import dataclass |
| 23 | + |
| 24 | + |
| 25 | +@dataclass(frozen=True) |
| 26 | +class _Identity: |
| 27 | + """Runtime-distinct string identity. |
| 28 | +
|
| 29 | + These are intentionally not ``NewType`` aliases. ``NewType`` helps static |
| 30 | + checkers, but at runtime it is still just ``str``. These value objects let key |
| 31 | + builders reject a session identity where a device identity is required. |
| 32 | + """ |
| 33 | + |
| 34 | + value: str |
| 35 | + |
| 36 | + @classmethod |
| 37 | + def from_value(cls, value: object, field_name: str | None = None): |
| 38 | + label = field_name or cls.__name__ |
| 39 | + if value is None: |
| 40 | + raise ValueError(f"{label} is required") |
| 41 | + if isinstance(value, bytes): |
| 42 | + value = value.decode() |
| 43 | + if not isinstance(value, str): |
| 44 | + raise TypeError(f"{label} must be a string") |
| 45 | + value = value.strip() |
| 46 | + if not value: |
| 47 | + raise ValueError(f"{label} cannot be empty") |
| 48 | + return cls(value) |
| 49 | + |
| 50 | + def __str__(self) -> str: |
| 51 | + return self.value |
| 52 | + |
| 53 | + |
| 54 | +class ClientId(_Identity): |
| 55 | + """Stable connected device identity, e.g. ``a421c9-elato``.""" |
| 56 | + |
| 57 | + |
| 58 | +class SessionId(_Identity): |
| 59 | + """Per-WebSocket/audio-stream identity.""" |
| 60 | + |
| 61 | + |
| 62 | +class UserId(_Identity): |
| 63 | + """Chronicle user identity carried across process boundaries.""" |
| 64 | + |
| 65 | + |
| 66 | +class AudioStreamName(_Identity): |
| 67 | + """Redis stream name for raw audio WAL entries.""" |
| 68 | + |
| 69 | + |
| 70 | +class DeviceDownlinkChannel(_Identity): |
| 71 | + """Redis Pub/Sub channel consumed by a connected device WebSocket.""" |
| 72 | + |
| 73 | + |
| 74 | +class TranscriptionResultsStream(_Identity): |
| 75 | + """Redis stream name for final transcription results.""" |
| 76 | + |
| 77 | + |
| 78 | +def _identity_value(identity: _Identity | str) -> str: |
| 79 | + return identity.value if isinstance(identity, _Identity) else identity |
| 80 | + |
| 81 | + |
| 82 | +def _require_identity(value: object, expected_type: type[_Identity]) -> _Identity: |
| 83 | + if not isinstance(value, expected_type): |
| 84 | + raise TypeError( |
| 85 | + f"expected {expected_type.__name__}, got {type(value).__name__}" |
| 86 | + ) |
| 87 | + return value |
| 88 | + |
| 89 | + |
21 | 90 | # --- session-scoped --- |
22 | 91 |
|
23 | 92 |
|
24 | | -def audio_session(session_id: str) -> str: |
| 93 | +def audio_session(session_id: str | SessionId) -> str: |
25 | 94 | """Hash holding the cross-process session state (owned by ``SessionStore``).""" |
26 | | - return f"audio:session:{session_id}" |
| 95 | + return f"audio:session:{_identity_value(session_id)}" |
27 | 96 |
|
28 | 97 |
|
29 | | -def session_signal(session_id: str) -> str: |
| 98 | +def session_signal(session_id: str | SessionId) -> str: |
30 | 99 | """Pub/sub channel for session lifecycle signals.""" |
31 | | - return f"session:signal:{session_id}" |
| 100 | + return f"session:signal:{_identity_value(session_id)}" |
32 | 101 |
|
33 | 102 |
|
34 | | -def session_conversation_count(session_id: str) -> str: |
| 103 | +def session_conversation_count(session_id: str | SessionId) -> str: |
35 | 104 | """Counter of conversations opened during the session.""" |
36 | | - return f"session:conversation_count:{session_id}" |
| 105 | + return f"session:conversation_count:{_identity_value(session_id)}" |
37 | 106 |
|
38 | 107 |
|
39 | | -def conversation_current(session_id: str) -> str: |
| 108 | +def conversation_current(session_id: str | SessionId) -> str: |
40 | 109 | """Pointer to the session's current conversation (drives WAV rotation).""" |
41 | | - return f"conversation:current:{session_id}" |
| 110 | + return f"conversation:current:{_identity_value(session_id)}" |
42 | 111 |
|
43 | 112 |
|
44 | | -def conversation_create_lock(session_id: str) -> str: |
| 113 | +def conversation_create_lock(session_id: str | SessionId) -> str: |
45 | 114 | """Per-session lock serializing first-conversation creation across workers.""" |
46 | | - return f"conversation:create_lock:{session_id}" |
| 115 | + return f"conversation:create_lock:{_identity_value(session_id)}" |
47 | 116 |
|
48 | 117 |
|
49 | | -def speech_detection_job(session_id: str) -> str: |
| 118 | +def speech_detection_job(session_id: str | SessionId) -> str: |
50 | 119 | """Pointer to the live speech-detection job id for the session.""" |
51 | | - return f"speech_detection_job:{session_id}" |
| 120 | + return f"speech_detection_job:{_identity_value(session_id)}" |
52 | 121 |
|
53 | 122 |
|
54 | | -def speech_detection_enqueue_lock(session_id: str) -> str: |
| 123 | +def speech_detection_enqueue_lock(session_id: str | SessionId) -> str: |
55 | 124 | """Single-flight lock guarding speech-detection job enqueue bursts.""" |
56 | | - return f"speech_detection_enqueue_lock:{session_id}" |
| 125 | + return f"speech_detection_enqueue_lock:{_identity_value(session_id)}" |
| 126 | + |
| 127 | + |
| 128 | +def audio_stream(session_id: SessionId) -> AudioStreamName: |
| 129 | + """Redis stream for the session's raw audio WAL.""" |
| 130 | + session_id = _require_identity(session_id, SessionId) |
| 131 | + return AudioStreamName.from_value(f"audio:stream:{session_id}") |
| 132 | + |
| 133 | + |
| 134 | +def parse_audio_stream_name(stream_name: str | AudioStreamName) -> SessionId: |
| 135 | + """Extract a ``SessionId`` from ``audio:stream:{session_id}``.""" |
| 136 | + value = _identity_value(stream_name) |
| 137 | + prefix = "audio:stream:" |
| 138 | + if not value.startswith(prefix): |
| 139 | + raise ValueError(f"not an audio stream name: {value!r}") |
| 140 | + return SessionId.from_value(value.removeprefix(prefix), "session_id") |
| 141 | + |
| 142 | + |
| 143 | +def transcription_results_stream(session_id: SessionId) -> TranscriptionResultsStream: |
| 144 | + """Redis stream for the session's final transcription results.""" |
| 145 | + session_id = _require_identity(session_id, SessionId) |
| 146 | + return TranscriptionResultsStream.from_value(f"transcription:results:{session_id}") |
| 147 | + |
| 148 | + |
| 149 | +def device_downlink_channel(client_id: ClientId) -> DeviceDownlinkChannel: |
| 150 | + """Redis Pub/Sub channel for backend-to-device output.""" |
| 151 | + client_id = _require_identity(client_id, ClientId) |
| 152 | + return DeviceDownlinkChannel.from_value(f"device:downlink:{client_id}") |
0 commit comments