@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.
@@ -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.