@madeinoz67/voice-server 0.1.9 → 0.1.10
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.
- package/CHANGELOG.md +6 -0
- package/CLAUDE.md +5 -0
- package/cliff.toml +3 -1
- package/docs/api.md +4 -0
- package/docs/assets/queue-error-handling-flow.png +0 -0
- package/docs/assets/queue-request-flow-success.png +0 -0
- package/docs/assets/queue-states.png +0 -0
- package/docs/assets/queue-system-overview.png +0 -0
- package/docs/assets/voice-server-architecture.png +0 -0
- package/docs/fifo-queue.md +175 -0
- package/docs/queue-architecture.md +182 -0
- package/mkdocs.yml +3 -0
- package/package.json +1 -1
- package/specs/002-fifo-notify-queue/checklists/requirements.md +50 -0
- package/specs/002-fifo-notify-queue/contracts/api.yaml +283 -0
- package/specs/002-fifo-notify-queue/data-model.md +379 -0
- package/specs/002-fifo-notify-queue/plan.md +320 -0
- package/specs/002-fifo-notify-queue/quickstart.md +273 -0
- package/specs/002-fifo-notify-queue/research.md +374 -0
- package/specs/002-fifo-notify-queue/spec.md +125 -0
- package/specs/002-fifo-notify-queue/tasks.md +136 -0
- package/src/ts/models/queue.ts +140 -0
- package/src/ts/server.ts +98 -19
- package/src/ts/services/mlx-tts-client.ts +75 -20
- package/src/ts/services/notification-queue.ts +382 -0
- package/tests/integration/queue-api.test.ts +298 -0
- package/tests/unit/services/notification-queue.test.ts +622 -0
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
openapi: 3.0.3
|
|
2
|
+
info:
|
|
3
|
+
title: MadeInOz Voice Server - FIFO Notification Queue API
|
|
4
|
+
description: API for the FIFO notification queue feature that prevents audio overlap
|
|
5
|
+
version: 0.2.0
|
|
6
|
+
contact:
|
|
7
|
+
name: MadeInOz
|
|
8
|
+
url: https://github.com/madeinoz67/madeinoz-voice-server
|
|
9
|
+
|
|
10
|
+
servers:
|
|
11
|
+
- url: http://127.0.0.1:8888
|
|
12
|
+
description: Local development server
|
|
13
|
+
|
|
14
|
+
tags:
|
|
15
|
+
- name: Queue
|
|
16
|
+
description: Queue operations
|
|
17
|
+
- name: Health
|
|
18
|
+
description: Health and status endpoints
|
|
19
|
+
|
|
20
|
+
paths:
|
|
21
|
+
/notify:
|
|
22
|
+
post:
|
|
23
|
+
tags: [Queue]
|
|
24
|
+
summary: Queue a voice notification
|
|
25
|
+
description: |
|
|
26
|
+
Submits a voice notification to the queue for processing.
|
|
27
|
+
Returns 201 Accepted immediately when queued successfully.
|
|
28
|
+
Audio playback happens asynchronously in FIFO order.
|
|
29
|
+
operationId: queueNotification
|
|
30
|
+
requestBody:
|
|
31
|
+
required: true
|
|
32
|
+
content:
|
|
33
|
+
application/json:
|
|
34
|
+
schema:
|
|
35
|
+
$ref: '#/components/schemas/NotificationRequest'
|
|
36
|
+
examples:
|
|
37
|
+
basic:
|
|
38
|
+
summary: Basic notification
|
|
39
|
+
value:
|
|
40
|
+
message: "Hello, world"
|
|
41
|
+
withTitle:
|
|
42
|
+
summary: Notification with title
|
|
43
|
+
value:
|
|
44
|
+
title: "System Alert"
|
|
45
|
+
message: "Process completed successfully"
|
|
46
|
+
withVoiceSettings:
|
|
47
|
+
summary: Notification with custom voice
|
|
48
|
+
value:
|
|
49
|
+
title: "Reminder"
|
|
50
|
+
message: "Meeting starting in 5 minutes"
|
|
51
|
+
voice_id: "marrvin"
|
|
52
|
+
voice_settings:
|
|
53
|
+
stability: 0.5
|
|
54
|
+
similarity: 0.75
|
|
55
|
+
speed: 1.0
|
|
56
|
+
volume: 0.8
|
|
57
|
+
responses:
|
|
58
|
+
'201':
|
|
59
|
+
description: Notification queued successfully
|
|
60
|
+
content:
|
|
61
|
+
application/json:
|
|
62
|
+
schema:
|
|
63
|
+
$ref: '#/components/schemas/SuccessResponse'
|
|
64
|
+
example:
|
|
65
|
+
status: "success"
|
|
66
|
+
message: "Notification queued"
|
|
67
|
+
'400':
|
|
68
|
+
description: Invalid request (malformed JSON, missing fields, invalid voice_id)
|
|
69
|
+
content:
|
|
70
|
+
application/json:
|
|
71
|
+
schema:
|
|
72
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
73
|
+
examples:
|
|
74
|
+
missingMessage:
|
|
75
|
+
summary: Missing required field
|
|
76
|
+
value:
|
|
77
|
+
status: "error"
|
|
78
|
+
message: "Missing required field: message"
|
|
79
|
+
invalidVoiceId:
|
|
80
|
+
summary: Invalid voice ID
|
|
81
|
+
value:
|
|
82
|
+
status: "error"
|
|
83
|
+
message: "Invalid voice_id: unknown_voice"
|
|
84
|
+
emptyAfterSanitization:
|
|
85
|
+
summary: Empty message after sanitization
|
|
86
|
+
value:
|
|
87
|
+
status: "error"
|
|
88
|
+
message: "Invalid input after sanitization"
|
|
89
|
+
'429':
|
|
90
|
+
description: Queue is at maximum capacity (100 items)
|
|
91
|
+
content:
|
|
92
|
+
application/json:
|
|
93
|
+
schema:
|
|
94
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
95
|
+
example:
|
|
96
|
+
status: "error"
|
|
97
|
+
message: "Queue is full (100 items)"
|
|
98
|
+
'500':
|
|
99
|
+
description: Internal server error
|
|
100
|
+
content:
|
|
101
|
+
application/json:
|
|
102
|
+
schema:
|
|
103
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
104
|
+
example:
|
|
105
|
+
status: "error"
|
|
106
|
+
message: "Internal server error"
|
|
107
|
+
|
|
108
|
+
/queue/status:
|
|
109
|
+
get:
|
|
110
|
+
tags: [Health]
|
|
111
|
+
summary: Get queue status
|
|
112
|
+
description: |
|
|
113
|
+
Returns the current state of the notification queue including depth,
|
|
114
|
+
processing status, and health indicator.
|
|
115
|
+
operationId: getQueueStatus
|
|
116
|
+
responses:
|
|
117
|
+
'200':
|
|
118
|
+
description: Queue status retrieved successfully
|
|
119
|
+
content:
|
|
120
|
+
application/json:
|
|
121
|
+
schema:
|
|
122
|
+
$ref: '#/components/schemas/QueueStateResponse'
|
|
123
|
+
examples:
|
|
124
|
+
emptyQueue:
|
|
125
|
+
summary: Empty queue, idle
|
|
126
|
+
value:
|
|
127
|
+
depth: 0
|
|
128
|
+
processing_status: "idle"
|
|
129
|
+
health: "healthy"
|
|
130
|
+
processing:
|
|
131
|
+
summary: Queue with items, actively processing
|
|
132
|
+
value:
|
|
133
|
+
depth: 3
|
|
134
|
+
processing_status: "active"
|
|
135
|
+
health: "healthy"
|
|
136
|
+
metrics:
|
|
137
|
+
average_wait_time_ms: 5000
|
|
138
|
+
items_processed: 127
|
|
139
|
+
items_failed: 2
|
|
140
|
+
degraded:
|
|
141
|
+
summary: Queue near capacity
|
|
142
|
+
value:
|
|
143
|
+
depth: 85
|
|
144
|
+
processing_status: "active"
|
|
145
|
+
health: "degraded"
|
|
146
|
+
metrics:
|
|
147
|
+
average_wait_time_ms: 45000
|
|
148
|
+
items_processed: 542
|
|
149
|
+
items_failed: 12
|
|
150
|
+
unavailable:
|
|
151
|
+
summary: TTS system unavailable
|
|
152
|
+
value:
|
|
153
|
+
depth: 5
|
|
154
|
+
processing_status: "idle"
|
|
155
|
+
health: "unavailable"
|
|
156
|
+
|
|
157
|
+
components:
|
|
158
|
+
schemas:
|
|
159
|
+
NotificationRequest:
|
|
160
|
+
type: object
|
|
161
|
+
description: Request to queue a voice notification
|
|
162
|
+
properties:
|
|
163
|
+
title:
|
|
164
|
+
type: string
|
|
165
|
+
maxLength: 100
|
|
166
|
+
description: Notification title (optional for backward compatibility)
|
|
167
|
+
message:
|
|
168
|
+
type: string
|
|
169
|
+
minLength: 1
|
|
170
|
+
maxLength: 500
|
|
171
|
+
description: Text message to synthesize (required)
|
|
172
|
+
voice_id:
|
|
173
|
+
type: string
|
|
174
|
+
description: Voice identifier to use (defaults to server default)
|
|
175
|
+
voice_name:
|
|
176
|
+
type: string
|
|
177
|
+
deprecated: true
|
|
178
|
+
description: Alias for voice_id (use voice_id instead)
|
|
179
|
+
voice_settings:
|
|
180
|
+
$ref: '#/components/schemas/ProsodySettings'
|
|
181
|
+
volume:
|
|
182
|
+
type: number
|
|
183
|
+
minimum: 0.0
|
|
184
|
+
maximum: 1.0
|
|
185
|
+
description: Playback volume (0.0-1.0, defaults to voice setting)
|
|
186
|
+
required:
|
|
187
|
+
- message
|
|
188
|
+
|
|
189
|
+
ProsodySettings:
|
|
190
|
+
type: object
|
|
191
|
+
description: Voice prosody configuration
|
|
192
|
+
properties:
|
|
193
|
+
stability:
|
|
194
|
+
type: number
|
|
195
|
+
minimum: 0.0
|
|
196
|
+
maximum: 1.0
|
|
197
|
+
description: Voice stability (lower = more expressive)
|
|
198
|
+
similarity:
|
|
199
|
+
type: number
|
|
200
|
+
minimum: 0.0
|
|
201
|
+
maximum: 1.0
|
|
202
|
+
description: Voice similarity boost
|
|
203
|
+
style:
|
|
204
|
+
type: string
|
|
205
|
+
description: Voice style (model-dependent)
|
|
206
|
+
speed:
|
|
207
|
+
type: number
|
|
208
|
+
minimum: 0.25
|
|
209
|
+
maximum: 4.0
|
|
210
|
+
description: Playback speed multiplier
|
|
211
|
+
|
|
212
|
+
SuccessResponse:
|
|
213
|
+
type: object
|
|
214
|
+
description: Successful API response
|
|
215
|
+
properties:
|
|
216
|
+
status:
|
|
217
|
+
type: string
|
|
218
|
+
enum: [success]
|
|
219
|
+
description: Response status indicator
|
|
220
|
+
message:
|
|
221
|
+
type: string
|
|
222
|
+
description: Human-readable success message
|
|
223
|
+
required:
|
|
224
|
+
- status
|
|
225
|
+
- message
|
|
226
|
+
|
|
227
|
+
ErrorResponse:
|
|
228
|
+
type: object
|
|
229
|
+
description: Error API response
|
|
230
|
+
properties:
|
|
231
|
+
status:
|
|
232
|
+
type: string
|
|
233
|
+
enum: [error]
|
|
234
|
+
description: Response status indicator
|
|
235
|
+
message:
|
|
236
|
+
type: string
|
|
237
|
+
description: Human-readable error message
|
|
238
|
+
required:
|
|
239
|
+
- status
|
|
240
|
+
- message
|
|
241
|
+
|
|
242
|
+
QueueStateResponse:
|
|
243
|
+
type: object
|
|
244
|
+
description: Current queue state
|
|
245
|
+
properties:
|
|
246
|
+
depth:
|
|
247
|
+
type: integer
|
|
248
|
+
minimum: 0
|
|
249
|
+
maximum: 100
|
|
250
|
+
description: Current number of items in queue
|
|
251
|
+
processing_status:
|
|
252
|
+
type: string
|
|
253
|
+
enum: [idle, active]
|
|
254
|
+
description: Whether queue is actively processing items
|
|
255
|
+
health:
|
|
256
|
+
type: string
|
|
257
|
+
enum: [healthy, degraded, unavailable]
|
|
258
|
+
description: Overall system health indicator
|
|
259
|
+
metrics:
|
|
260
|
+
type: object
|
|
261
|
+
description: Optional queue metrics
|
|
262
|
+
properties:
|
|
263
|
+
average_wait_time_ms:
|
|
264
|
+
type: integer
|
|
265
|
+
minimum: 0
|
|
266
|
+
description: Average wait time for queued items (milliseconds)
|
|
267
|
+
items_processed:
|
|
268
|
+
type: integer
|
|
269
|
+
minimum: 0
|
|
270
|
+
description: Total items processed since server start
|
|
271
|
+
items_failed:
|
|
272
|
+
type: integer
|
|
273
|
+
minimum: 0
|
|
274
|
+
description: Total items that failed since server start
|
|
275
|
+
required:
|
|
276
|
+
- depth
|
|
277
|
+
- processing_status
|
|
278
|
+
- health
|
|
279
|
+
|
|
280
|
+
examples:
|
|
281
|
+
null
|
|
282
|
+
|
|
283
|
+
security: []
|
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
# Data Model: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Feature**: FIFO Notification Queue
|
|
4
|
+
**Date**: 2026-02-09
|
|
5
|
+
**Status**: Draft
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
This document defines the data structures and entities for the FIFO notification queue system.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Core Entities
|
|
14
|
+
|
|
15
|
+
### QueuedNotification
|
|
16
|
+
|
|
17
|
+
Represents a single notification request awaiting or undergoing processing.
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
interface QueuedNotification {
|
|
21
|
+
/** Unique identifier for this queued item */
|
|
22
|
+
id: string;
|
|
23
|
+
|
|
24
|
+
/** Notification title (optional) */
|
|
25
|
+
title?: string;
|
|
26
|
+
|
|
27
|
+
/** Text message to synthesize (required) */
|
|
28
|
+
message: string;
|
|
29
|
+
|
|
30
|
+
/** Voice identifier to use */
|
|
31
|
+
voice_id: string;
|
|
32
|
+
|
|
33
|
+
/** Voice prosody settings (optional) */
|
|
34
|
+
voice_settings?: ProsodySettings;
|
|
35
|
+
|
|
36
|
+
/** Playback volume (0.0-1.0) */
|
|
37
|
+
volume: number;
|
|
38
|
+
|
|
39
|
+
/** Timestamp when request was received (ms since epoch) */
|
|
40
|
+
arrived_at: number;
|
|
41
|
+
|
|
42
|
+
/** Current processing status */
|
|
43
|
+
status: QueuedNotificationStatus;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
type QueuedNotificationStatus =
|
|
47
|
+
| "pending" // Awaiting processing
|
|
48
|
+
| "processing" // Currently being synthesized
|
|
49
|
+
| "completed" // Successfully played
|
|
50
|
+
| "failed"; // Failed during synthesis/playback
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Relationships**: None (standalone entity)
|
|
54
|
+
|
|
55
|
+
**Lifecycle**: `pending` → `processing` → `completed` OR `failed`
|
|
56
|
+
|
|
57
|
+
**Validation Rules**:
|
|
58
|
+
- `id`: Non-empty string, UUID format
|
|
59
|
+
- `message`: 1-500 characters after sanitization
|
|
60
|
+
- `voice_id`: Must match available voice or use default
|
|
61
|
+
- `volume`: 0.0-1.0 inclusive
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
### QueueState
|
|
66
|
+
|
|
67
|
+
Represents the current state of the notification queue for monitoring.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
interface QueueState {
|
|
71
|
+
/** Current number of items in queue */
|
|
72
|
+
depth: number;
|
|
73
|
+
|
|
74
|
+
/** Whether queue is actively processing */
|
|
75
|
+
processing_status: ProcessingStatus;
|
|
76
|
+
|
|
77
|
+
/** Overall system health indicator */
|
|
78
|
+
health: HealthIndicator;
|
|
79
|
+
|
|
80
|
+
/** Optional metrics for monitoring */
|
|
81
|
+
metrics?: QueueMetrics;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
type ProcessingStatus = "idle" | "active";
|
|
85
|
+
|
|
86
|
+
type HealthIndicator = "healthy" | "degraded" | "unavailable";
|
|
87
|
+
|
|
88
|
+
interface QueueMetrics {
|
|
89
|
+
/** Average wait time for queued items (milliseconds) */
|
|
90
|
+
average_wait_time_ms: number;
|
|
91
|
+
|
|
92
|
+
/** Total items processed since server start */
|
|
93
|
+
items_processed: number;
|
|
94
|
+
|
|
95
|
+
/** Total items that failed since server start */
|
|
96
|
+
items_failed: number;
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Relationships**: References `QueuedNotification` (aggregate)
|
|
101
|
+
|
|
102
|
+
**State Transitions**:
|
|
103
|
+
- `processing_status`: `idle` ↔ `active` based on whether worker is running
|
|
104
|
+
- `health`: Determined by TTS availability and queue depth
|
|
105
|
+
|
|
106
|
+
**Health Determination Logic**:
|
|
107
|
+
```
|
|
108
|
+
if (TTS unavailable) → unavailable
|
|
109
|
+
else if (queue depth >= 80) → degraded
|
|
110
|
+
else → healthy
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
### QueueConfig
|
|
116
|
+
|
|
117
|
+
Configuration for queue behavior.
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
interface QueueConfig {
|
|
121
|
+
/** Maximum number of items allowed in queue */
|
|
122
|
+
maxDepth: number;
|
|
123
|
+
|
|
124
|
+
/** Timeout for queue drain during shutdown (milliseconds) */
|
|
125
|
+
drainTimeoutMs: number;
|
|
126
|
+
|
|
127
|
+
/** Threshold for degraded health status (percentage of maxDepth) */
|
|
128
|
+
degradedThreshold: number;
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**Default Values**:
|
|
133
|
+
- `maxDepth`: 100
|
|
134
|
+
- `drainTimeoutMs`: 30000 (30 seconds)
|
|
135
|
+
- `degradedThreshold`: 0.8 (80%)
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Data Flow
|
|
140
|
+
|
|
141
|
+
### Request → Queue → Processing Flow
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
┌─────────────┐
|
|
145
|
+
│ HTTP Request│
|
|
146
|
+
└──────┬──────┘
|
|
147
|
+
│
|
|
148
|
+
▼
|
|
149
|
+
┌─────────────────┐
|
|
150
|
+
│ Input Validation│ (schema, voice_id, sanitization)
|
|
151
|
+
└──────┬──────────┘
|
|
152
|
+
│
|
|
153
|
+
▼ (if valid)
|
|
154
|
+
┌─────────────┐
|
|
155
|
+
│ Enqueue │ (add to queue array)
|
|
156
|
+
└──────┬──────┘
|
|
157
|
+
│
|
|
158
|
+
▼
|
|
159
|
+
┌─────────────────┐
|
|
160
|
+
│ Return 201 │ (immediate, async processing)
|
|
161
|
+
└─────────────────┘
|
|
162
|
+
│
|
|
163
|
+
▼ (background)
|
|
164
|
+
┌─────────────────┐
|
|
165
|
+
│ Queue Worker │ (process items sequentially)
|
|
166
|
+
└──────┬──────────┘
|
|
167
|
+
│
|
|
168
|
+
▼
|
|
169
|
+
┌─────────────────┐
|
|
170
|
+
│ TTS Synthesis │ (processTTS function)
|
|
171
|
+
└──────┬──────────┘
|
|
172
|
+
│
|
|
173
|
+
▼
|
|
174
|
+
┌─────────────────┐
|
|
175
|
+
│ Audio Playback │
|
|
176
|
+
└─────────────────┘
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
---
|
|
180
|
+
|
|
181
|
+
## State Management
|
|
182
|
+
|
|
183
|
+
### Queue Processing State
|
|
184
|
+
|
|
185
|
+
The queue maintains a processing flag to prevent concurrent processing:
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
class NotificationQueue {
|
|
189
|
+
private queue: QueuedNotification[] = [];
|
|
190
|
+
private processing = false; // Single worker flag
|
|
191
|
+
|
|
192
|
+
private async processQueue(): Promise<void> {
|
|
193
|
+
if (this.processing || this.queue.length === 0) return;
|
|
194
|
+
this.processing = true;
|
|
195
|
+
|
|
196
|
+
try {
|
|
197
|
+
while (this.queue.length > 0) {
|
|
198
|
+
const item = this.queue.shift();
|
|
199
|
+
// Process item...
|
|
200
|
+
}
|
|
201
|
+
} finally {
|
|
202
|
+
this.processing = false;
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Graceful Shutdown State
|
|
209
|
+
|
|
210
|
+
During shutdown, the queue enters a draining state:
|
|
211
|
+
|
|
212
|
+
```typescript
|
|
213
|
+
interface QueueState {
|
|
214
|
+
draining: boolean; // true during shutdown
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Shutdown sequence:
|
|
219
|
+
1. Set `draining = true`
|
|
220
|
+
2. Stop accepting new requests
|
|
221
|
+
3. Wait for queue to empty (with timeout)
|
|
222
|
+
4. Exit process
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Error State Transitions
|
|
227
|
+
|
|
228
|
+
### Item Failure
|
|
229
|
+
|
|
230
|
+
When TTS synthesis fails for a queued item:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
pending → processing → failed
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Behavior:
|
|
237
|
+
- Log error with item ID
|
|
238
|
+
- Skip to next item
|
|
239
|
+
- Increment `items_failed` metric
|
|
240
|
+
- Continue processing remaining items
|
|
241
|
+
|
|
242
|
+
### Queue Overflow
|
|
243
|
+
|
|
244
|
+
When enqueue would exceed `maxDepth`:
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
HTTP Request → 429 Too Many Requests
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Behavior:
|
|
251
|
+
- Return 429 immediately
|
|
252
|
+
- Do not add item to queue
|
|
253
|
+
- Client may retry later
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Persistence Strategy
|
|
258
|
+
|
|
259
|
+
### In-Memory Only (Per Spec)
|
|
260
|
+
|
|
261
|
+
- Queue data stored in JavaScript array
|
|
262
|
+
- No persistence to disk or database
|
|
263
|
+
- Server restart = queue cleared
|
|
264
|
+
- Queue depth limit (100) prevents memory issues
|
|
265
|
+
|
|
266
|
+
### Rationale
|
|
267
|
+
|
|
268
|
+
- Voice notifications are transient (3-10s playback)
|
|
269
|
+
- Local voice server (not distributed)
|
|
270
|
+
- Persistence would add complexity without significant benefit
|
|
271
|
+
- Server restarts are infrequent
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Type Dependencies
|
|
276
|
+
|
|
277
|
+
### Existing Types Used
|
|
278
|
+
|
|
279
|
+
From `src/ts/models/notification.ts`:
|
|
280
|
+
- `NotificationRequest`
|
|
281
|
+
- `PaiNotificationRequest`
|
|
282
|
+
- `SuccessResponse`
|
|
283
|
+
- `ErrorResponse`
|
|
284
|
+
|
|
285
|
+
From `src/ts/models/voice-config.ts`:
|
|
286
|
+
- `ProsodySettings`
|
|
287
|
+
|
|
288
|
+
From `src/ts/models/health.ts`:
|
|
289
|
+
- `HealthStatus` (extended with queue fields)
|
|
290
|
+
|
|
291
|
+
### New Types Defined
|
|
292
|
+
|
|
293
|
+
- `QueuedNotification`
|
|
294
|
+
- `QueuedNotificationStatus`
|
|
295
|
+
- `QueueState`
|
|
296
|
+
- `ProcessingStatus`
|
|
297
|
+
- `HealthIndicator`
|
|
298
|
+
- `QueueMetrics`
|
|
299
|
+
- `QueueConfig`
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## Indexes and Ordering
|
|
304
|
+
|
|
305
|
+
### FIFO Ordering
|
|
306
|
+
|
|
307
|
+
Queue maintains strict FIFO ordering:
|
|
308
|
+
- Items added with `push()` to end of array
|
|
309
|
+
- Items removed with `shift()` from beginning of array
|
|
310
|
+
- `arrived_at` timestamp preserves order for debugging
|
|
311
|
+
|
|
312
|
+
### No Indexes Required
|
|
313
|
+
|
|
314
|
+
- In-memory array access is O(1) for push
|
|
315
|
+
- O(n) shift is acceptable for n ≤ 100
|
|
316
|
+
- No lookup by ID required
|
|
317
|
+
- No sorting or reordering needed
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Memory Considerations
|
|
322
|
+
|
|
323
|
+
### Per-Item Memory
|
|
324
|
+
|
|
325
|
+
Approximate memory per `QueuedNotification`:
|
|
326
|
+
- `id`: 36 bytes (UUID string)
|
|
327
|
+
- `message`: ~100 bytes average
|
|
328
|
+
- `voice_id`: 20 bytes
|
|
329
|
+
- `voice_settings`: ~50 bytes
|
|
330
|
+
- Metadata: ~50 bytes
|
|
331
|
+
- **Total**: ~250 bytes per item
|
|
332
|
+
|
|
333
|
+
### Total Memory
|
|
334
|
+
|
|
335
|
+
- 100 items × 250 bytes = ~25 KB
|
|
336
|
+
- Negligible impact on server memory
|
|
337
|
+
- Well under 2GB memory limit (Constitution)
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## Concurrency Model
|
|
342
|
+
|
|
343
|
+
### Single-Threaded Event Loop
|
|
344
|
+
|
|
345
|
+
Bun/JavaScript is single-threaded:
|
|
346
|
+
- No mutex needed for queue operations
|
|
347
|
+
- Array operations are atomic
|
|
348
|
+
- `processing` flag prevents race conditions
|
|
349
|
+
|
|
350
|
+
### Multiple Producers
|
|
351
|
+
|
|
352
|
+
Multiple HTTP requests can call `enqueue()` concurrently:
|
|
353
|
+
- Each request is handled by event loop
|
|
354
|
+
- `enqueue()` returns immediately after array push
|
|
355
|
+
- `processQueue()` is idempotent (checks `processing` flag)
|
|
356
|
+
|
|
357
|
+
### Single Consumer
|
|
358
|
+
|
|
359
|
+
Background worker processes items sequentially:
|
|
360
|
+
- Only one `processQueue()` runs at a time
|
|
361
|
+
- Ensures strict FIFO ordering
|
|
362
|
+
- Prevents audio overlap
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Validation Rules Summary
|
|
367
|
+
|
|
368
|
+
| Field | Validation | Error Response |
|
|
369
|
+
|-------|-----------|----------------|
|
|
370
|
+
| `message` | 1-500 chars, not empty after sanitization | 400 Bad Request |
|
|
371
|
+
| `voice_id` | Valid voice from available list | 400 Bad Request |
|
|
372
|
+
| `volume` | 0.0-1.0 inclusive | 400 Bad Request |
|
|
373
|
+
| Queue depth | < maxDepth (100) | 429 Too Many Requests |
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## Next Steps
|
|
378
|
+
|
|
379
|
+
Proceed to API contract generation in `/contracts/` directory.
|