@madeinoz67/voice-server 0.1.9 → 0.1.11

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,273 @@
1
+ # FIFO Notification Queue - Quickstart
2
+
3
+ **Feature**: FIFO Notification Queue
4
+ **Branch**: `001-fifo-notify-queue`
5
+ **Last Updated**: 2026-02-09
6
+
7
+ ## Overview
8
+
9
+ This quickstart guide helps you set up and work with the FIFO notification queue feature locally.
10
+
11
+ ---
12
+
13
+ ## Prerequisites
14
+
15
+ - Bun runtime installed
16
+ - macOS (platform requirement per Constitution)
17
+ - MLX-audio CLI installed and configured
18
+ - Kokoro-82M voice model available
19
+
20
+ ---
21
+
22
+ ## Development Setup
23
+
24
+ ### 1. Start the Voice Server
25
+
26
+ ```bash
27
+ # From repository root
28
+ bun run dev
29
+ ```
30
+
31
+ Server starts on `http://127.0.0.1:8888`
32
+
33
+ ### 2. Verify Queue Status
34
+
35
+ ```bash
36
+ curl http://127.0.0.1:8888/queue/status
37
+ ```
38
+
39
+ Expected response (empty queue):
40
+ ```json
41
+ {
42
+ "depth": 0,
43
+ "processing_status": "idle",
44
+ "health": "healthy"
45
+ }
46
+ ```
47
+
48
+ ---
49
+
50
+ ## API Usage
51
+
52
+ ### Queue a Notification
53
+
54
+ ```bash
55
+ curl -X POST http://127.0.0.1:8888/notify \
56
+ -H "Content-Type: application/json" \
57
+ -d '{
58
+ "message": "This is a test notification"
59
+ }'
60
+ ```
61
+
62
+ Expected response:
63
+ ```json
64
+ {
65
+ "status": "success",
66
+ "message": "Notification queued"
67
+ }
68
+ ```
69
+
70
+ **HTTP Status**: `201 Created`
71
+
72
+ ### Queue Multiple Notifications (Test FIFO)
73
+
74
+ ```bash
75
+ # Send 3 rapid requests
76
+ for i in 1 2 3; do
77
+ curl -X POST http://127.0.0.1:8888/notify \
78
+ -H "Content-Type: application/json" \
79
+ -d "{\"message\": \"Notification $i\"}"
80
+ done
81
+ ```
82
+
83
+ All three return `201 Created` immediately, audio plays sequentially.
84
+
85
+ ### Check Queue Status During Processing
86
+
87
+ ```bash
88
+ curl http://127.0.0.1:8888/queue/status
89
+ ```
90
+
91
+ Example response:
92
+ ```json
93
+ {
94
+ "depth": 2,
95
+ "processing_status": "active",
96
+ "health": "healthy",
97
+ "metrics": {
98
+ "average_wait_time_ms": 5000,
99
+ "items_processed": 5,
100
+ "items_failed": 0
101
+ }
102
+ }
103
+ ```
104
+
105
+ ---
106
+
107
+ ## Testing Queue Behavior
108
+
109
+ ### Test Sequential Playback
110
+
111
+ 1. Start server: `bun run dev`
112
+ 2. In another terminal, send multiple requests:
113
+ ```bash
114
+ for i in {1..5}; do
115
+ curl -X POST http://127.0.0.1:8888/notify \
116
+ -H "Content-Type: application/json" \
117
+ -d "{\"message\": \"Test notification $i\"}"
118
+ sleep 0.5
119
+ done
120
+ ```
121
+ 3. **Expected**: Audio plays 1, 2, 3, 4, 5 in order with no overlap
122
+
123
+ ### Test Queue Overflow
124
+
125
+ ```bash
126
+ # Fill queue to capacity (100 items)
127
+ for i in {1..100}; do
128
+ curl -X POST http://127.0.0.1:8888/notify \
129
+ -H "Content-Type: application/json" \
130
+ -d "{\"message\": \"Fill queue $i\"}" &
131
+ done
132
+ wait
133
+
134
+ # Next request should fail
135
+ curl -X POST http://127.0.0.1:8888/notify \
136
+ -H "Content-Type: application/json" \
137
+ -d '{"message": "This should fail"}'
138
+ ```
139
+
140
+ Expected response:
141
+ ```json
142
+ {
143
+ "status": "error",
144
+ "message": "Queue is full (100 items)"
145
+ }
146
+ ```
147
+
148
+ **HTTP Status**: `429 Too Many Requests`
149
+
150
+ ### Test Invalid Request Rejection
151
+
152
+ ```bash
153
+ # Missing message field
154
+ curl -X POST http://127.0.0.1:8888/notify \
155
+ -H "Content-Type: application/json" \
156
+ -d '{"title": "No message"}'
157
+ ```
158
+
159
+ Expected response:
160
+ ```json
161
+ {
162
+ "status": "error",
163
+ "message": "Missing required field: message"
164
+ }
165
+ ```
166
+
167
+ **HTTP Status**: `400 Bad Request`
168
+
169
+ ### Test Graceful Shutdown
170
+
171
+ 1. Queue several notifications
172
+ 2. Send SIGTERM: `kill -TERM <pid>`
173
+ 3. **Expected**: All queued notifications play before server exits
174
+
175
+ ---
176
+
177
+ ## Running Tests
178
+
179
+ ### Unit Tests
180
+
181
+ ```bash
182
+ bun test tests/unit/services/notification-queue.test.ts
183
+ ```
184
+
185
+ ### Integration Tests
186
+
187
+ ```bash
188
+ bun test tests/integration/queue-api.test.ts
189
+ ```
190
+
191
+ ### All Tests
192
+
193
+ ```bash
194
+ bun test
195
+ ```
196
+
197
+ ---
198
+
199
+ ## Development Workflow
200
+
201
+ ### Code Structure
202
+
203
+ ```
204
+ src/ts/
205
+ ├── services/
206
+ │ └── notification-queue.ts # Queue implementation
207
+ ├── models/
208
+ │ └── queue.ts # Queue types
209
+ └── server.ts # Updated with queue handlers
210
+
211
+ tests/
212
+ ├── unit/
213
+ │ └── services/
214
+ │ └── notification-queue.test.ts
215
+ └── integration/
216
+ └── queue-api.test.ts
217
+ ```
218
+
219
+ ### Implementation Checklist
220
+
221
+ - [ ] Create `NotificationQueue` class
222
+ - [ ] Add `/queue/status` endpoint handler
223
+ - [ ] Update `/notify` to use queue
224
+ - [ ] Implement graceful shutdown with queue drain
225
+ - [ ] Add queue event logging
226
+ - [ ] Write unit tests for queue operations
227
+ - [ ] Write integration tests for API endpoints
228
+ - [ ] Update Codanna index
229
+
230
+ ---
231
+
232
+ ## Troubleshooting
233
+
234
+ ### Audio Not Playing
235
+
236
+ 1. Check queue status: `curl http://127.0.0.1:8888/queue/status`
237
+ 2. Check health: `curl http://127.0.0.1:8888/health`
238
+ 3. Verify TTS system: Ensure MLX-audio CLI is working
239
+ 4. Check logs: Server logs show queue events
240
+
241
+ ### Requests Immediately Return 429
242
+
243
+ - Cause: Queue is at capacity (100 items)
244
+ - Solution: Wait for queue to drain, or increase `maxDepth` in config
245
+
246
+ ### Invalid voice_id Errors
247
+
248
+ - Check available voices: `curl http://127.0.0.1:8888/health | jq '.available_voices'`
249
+ - Use valid voice_id from list
250
+ - Or omit voice_id to use default
251
+
252
+ ---
253
+
254
+ ## Configuration
255
+
256
+ Queue behavior is configured via environment variables and code defaults:
257
+
258
+ | Setting | Default | Description |
259
+ |---------|---------|-------------|
260
+ | `QUEUE_MAX_DEPTH` | 100 | Maximum queue depth |
261
+ | `QUEUE_DRAIN_TIMEOUT_MS` | 30000 | Shutdown drain timeout |
262
+ | `QUEUE_DEGRADED_THRESHOLD` | 0.8 | Health degraded threshold |
263
+
264
+ ---
265
+
266
+ ## Next Steps
267
+
268
+ After implementing:
269
+
270
+ 1. Run tests: `bun test`
271
+ 2. Type check: `bun run typecheck`
272
+ 3. Lint: `bun run lint`
273
+ 4. Create PR for review
@@ -0,0 +1,374 @@
1
+ # Research: FIFO Notification Queue
2
+
3
+ **Feature**: FIFO Notification Queue
4
+ **Date**: 2026-02-09
5
+ **Status**: Complete
6
+
7
+ ## Overview
8
+
9
+ This document consolidates research findings for implementing a FIFO queue for the voice server's `/notify` endpoint. The queue must handle concurrent requests, process them sequentially, and return 201 Accepted immediately.
10
+
11
+ ---
12
+
13
+ ## Queue Implementation Strategy
14
+
15
+ ### Decision: Array-based In-Memory Queue with Async/Await Processing
16
+
17
+ **Rationale**:
18
+ - Bun/TypeScript has native support for async/await and Promise-based patterns
19
+ - Array operations are fast for queue sizes ≤ 100 items
20
+ - No external dependencies required
21
+ - Simple to implement and maintain
22
+ - Preserves FIFO ordering naturally (shift/push operations)
23
+
24
+ **Alternatives Considered**:
25
+ - **Linked List**: More complex to implement in TypeScript, no performance benefit for small queues
26
+ - **Bun Atomics**: Overkill for single-worker scenario, adds complexity
27
+ - **Bun Workers**: Unnecessary overhead for single-threaded queue processing
28
+ - **External Queue Libraries** (bull, bee-queue): Too heavy for local voice server use case
29
+
30
+ **Implementation Pattern**:
31
+ ```typescript
32
+ interface QueuedNotification {
33
+ id: string;
34
+ message: string;
35
+ title?: string;
36
+ voice_id: string;
37
+ voice_settings?: ProsodySettings;
38
+ volume: number;
39
+ arrived_at: number;
40
+ status: "pending" | "processing" | "completed" | "failed";
41
+ }
42
+
43
+ class NotificationQueue {
44
+ private queue: QueuedNotification[] = [];
45
+ private processing = false;
46
+ private maxDepth = 100;
47
+
48
+ async enqueue(request: NotificationRequest): Promise<boolean> {
49
+ if (this.queue.length >= this.maxDepth) return false;
50
+ this.queue.push({ ...request, id: crypto.randomUUID(), arrived_at: Date.now(), status: "pending" });
51
+ this.processQueue().catch(() => {});
52
+ return true;
53
+ }
54
+
55
+ private async processQueue(): Promise<void> {
56
+ if (this.processing || this.queue.length === 0) return;
57
+ this.processing = true;
58
+
59
+ while (this.queue.length > 0) {
60
+ const item = this.queue.shift();
61
+ if (!item) break;
62
+
63
+ try {
64
+ await processTTS(item.message, item.voice_id, item.voice_settings || {}, item.volume);
65
+ } catch (error) {
66
+ logger.warn("TTS processing failed for queued item", { id: item.id, error });
67
+ }
68
+ }
69
+
70
+ this.processing = false;
71
+ }
72
+ }
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Concurrency & Producer-Consumer Pattern
78
+
79
+ ### Decision: Single Async Worker with Promise-Based Queue Processing
80
+
81
+ **Rationale**:
82
+ - Single worker maintains strict FIFO ordering (no concurrent processing)
83
+ - Async/await naturally handles the producer-consumer pattern
84
+ - Multiple producers (HTTP requests) can call `enqueue()` concurrently
85
+ - Queue is protected by JavaScript's single-threaded event loop
86
+ - `processing` flag prevents concurrent queue processing
87
+
88
+ **Alternatives Considered**:
89
+ - **Bun Workers**: Adds complexity with message passing, unnecessary for TTS bottleneck
90
+ - **Mutex/Semaphore**: JavaScript is single-threaded, atomic operations not needed
91
+ - **Concurrent Processing**: Would violate FIFO requirement and cause audio overlap
92
+
93
+ **Flow**:
94
+ 1. HTTP request arrives → `enqueue()` adds to array
95
+ 2. `enqueue()` triggers `processQueue()` if not already processing
96
+ 3. `processQueue()` marks processing flag, processes items sequentially
97
+ 4. Each item: `processTTS()` (await) → next item
98
+ 5. Queue empty → processing flag cleared
99
+
100
+ ---
101
+
102
+ ## Graceful Shutdown Strategy
103
+
104
+ ### Decision: Await Queue Drain with Timeout
105
+
106
+ **Rationale**:
107
+ - Ensures all queued notifications are played before exit
108
+ - Local voice server with short notifications (3-10s) makes this practical
109
+ - Users expect voice feedback to complete even during shutdown
110
+ - Timeout prevents indefinite hangs on errors
111
+
112
+ **Alternatives Considered**:
113
+ - **Immediate Shutdown**: Loses queued notifications, poor UX
114
+ - **Best-Effort Drain**: Same as chosen approach with explicit timeout
115
+ - **Persist Queue**: Out of scope per assumptions
116
+
117
+ **Implementation Pattern**:
118
+ ```typescript
119
+ const shutdown = async () => {
120
+ logger.info("Shutting down server...");
121
+
122
+ // Stop accepting new requests
123
+ server.stop();
124
+
125
+ // Drain queue with timeout
126
+ const drainTimeout = 30000; // 30 seconds
127
+ const startTime = Date.now();
128
+
129
+ while (queue.length > 0 && Date.now() - startTime < drainTimeout) {
130
+ await new Promise(resolve => setTimeout(resolve, 100));
131
+ }
132
+
133
+ if (queue.length > 0) {
134
+ logger.warn("Queue drain timeout, exiting with pending items", { remaining: queue.length });
135
+ }
136
+
137
+ logger.info("Server stopped");
138
+ process.exit(0);
139
+ };
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Error Handling Strategy
145
+
146
+ ### Decision: Skip Failed Items, Continue Processing
147
+
148
+ **Rationale**:
149
+ - Single TTS failure shouldn't block entire queue
150
+ - Users want to hear remaining notifications
151
+ - Logging provides visibility into failures
152
+ - Graceful degradation aligns with Constitution Principle III
153
+
154
+ **Alternatives Considered**:
155
+ - **Stop on First Error**: Blocks remaining items, poor UX
156
+ - **Retry Failed Items**: Adds complexity, could cause indefinite loops
157
+ - **Dead Letter Queue**: Overkill for local voice server
158
+
159
+ **Validation Timing**:
160
+ - **Schema Validation**: Immediate (before enqueue) — return 400 Bad Request
161
+ - **Voice ID Validation**: Immediate (before enqueue) — return 400 Bad Request
162
+ - **TTS Synthesis Failure**: Deferred (during processing) — skip to next item
163
+
164
+ ---
165
+
166
+ ## Health Monitoring Strategy
167
+
168
+ ### Decision: Extend Existing HealthStatus Model with Queue Fields
169
+
170
+ **Rationale**:
171
+ - Existing `/health` endpoint infrastructure already in place
172
+ - Consistent with current monitoring patterns
173
+ - Simple addition of queue-related fields
174
+ - Health indicator (healthy/degraded/unavailable) aligns with existing status values
175
+
176
+ **Alternatives Considered**:
177
+ - **Separate `/queue/status` Endpoint**: Creates separate API surface, but required by spec
178
+ - **Circuit Breaker Pattern**: Overkill for local server
179
+ - **Push Notifications**: Out of scope per spec
180
+
181
+ **QueueState Model**:
182
+ ```typescript
183
+ interface QueueState {
184
+ depth: number;
185
+ processing_status: "idle" | "active";
186
+ health: "healthy" | "degraded" | "unavailable";
187
+ metrics?: {
188
+ average_wait_time_ms: number;
189
+ items_processed: number;
190
+ items_failed: number;
191
+ };
192
+ }
193
+ ```
194
+
195
+ **Health Determination**:
196
+ - `healthy`: TTS available, queue < 80% capacity
197
+ - `degraded`: TTS available but queue ≥ 80% capacity
198
+ - `unavailable`: TTS health check failed
199
+
200
+ ---
201
+
202
+ ## Rate Limiting Integration
203
+
204
+ ### Decision: Apply Rate Limits Before Queue Admission
205
+
206
+ **Rationale**:
207
+ - Existing rate limiter middleware applies to POST requests
208
+ - Rate limiting prevents abuse regardless of queue state
209
+ - Queue overflow (429) is separate from rate limit (429)
210
+ - Both protections apply at different layers
211
+
212
+ **Distinction**:
213
+ - **Rate Limit 429**: Too many requests from this client (time-window based)
214
+ - **Queue Full 429**: Server queue at capacity (depth-based)
215
+
216
+ **Response Codes**:
217
+ - Rate limit exceeded: `429 Too Many Requests` with existing rate limiter message
218
+ - Queue full: `429 Too Many Requests` with queue-specific message
219
+ - Both use same status code but different error messages
220
+
221
+ **No Retry-After Header**: Spec doesn't require it, can be added later if needed
222
+
223
+ ---
224
+
225
+ ## Dependencies & Integration Points
226
+
227
+ ### Existing Components Used
228
+
229
+ 1. **MLX TTS Client** (`src/ts/services/mlx-tts-client.ts`)
230
+ - Already has `synthesize()` method with streaming support
231
+ - Health check method available
232
+ - Used by existing `processTTS()` function
233
+
234
+ 2. **Logger** (`src/ts/utils/logger.ts`)
235
+ - Existing logging infrastructure
236
+ - Use for queue event logging (FR-008)
237
+
238
+ 3. **Text Sanitizer** (`src/ts/utils/text-sanitizer.ts`)
239
+ - Input validation before queuing
240
+ - Returns empty string for invalid input
241
+
242
+ 4. **Voice Loader** (`src/ts/services/voice-loader.ts`)
243
+ - Validate voice_id against available voices
244
+ - Returns list of available voices
245
+
246
+ 5. **Rate Limiter** (`src/ts/middleware/rate-limiter.ts`)
247
+ - Existing middleware, applies before queue check
248
+ - No changes needed
249
+
250
+ ### New Components Required
251
+
252
+ 1. **NotificationQueue Class** (`src/ts/services/notification-queue.ts`)
253
+ - Queue management
254
+ - Enqueue/dequeue operations
255
+ - Graceful shutdown support
256
+
257
+ 2. **QueueState Type** (`src/ts/models/queue.ts`)
258
+ - Type definitions for queue state
259
+ - Status response types
260
+
261
+ 3. **Queue Status Handler** (`src/ts/server.ts`)
262
+ - GET `/queue/status` endpoint handler
263
+
264
+ ---
265
+
266
+ ## Testing Strategy
267
+
268
+ ### Decision: Test-First with TDD Approach (Constitution Principle V)
269
+
270
+ **Unit Tests** (`tests/unit/services/notification-queue.test.ts`):
271
+ - Queue enqueue/dequeue operations
272
+ - FIFO ordering verification
273
+ - Max depth enforcement
274
+ - Processing state management
275
+ - Error handling (skip failed items)
276
+
277
+ **Integration Tests** (`tests/integration/queue-api.test.ts`):
278
+ - POST `/notify` returns 201 Accepted
279
+ - Multiple requests process sequentially
280
+ - Queue overflow returns 429
281
+ - Invalid requests return 400
282
+ - GET `/queue/status` returns correct state
283
+
284
+ **Test Doubles**:
285
+ - Mock `processTTS()` for unit tests
286
+ - Mock MLX TTS client for integration tests
287
+ - Fake timers for timing-sensitive tests
288
+
289
+ ---
290
+
291
+ ## Performance Considerations
292
+
293
+ ### Queue Operations
294
+
295
+ - **Enqueue**: O(1) array push
296
+ - **Dequeue**: O(n) array shift, but n ≤ 100 so negligible
297
+ - **Memory**: ~1KB per queued item (100 items = ~100KB max)
298
+
299
+ ### Response Times
300
+
301
+ - **201 Accepted**: < 10ms (validation + array push)
302
+ - **Queue Status**: < 5ms (array length + status check)
303
+ - **Processing**: 3-10s per item (TTS synthesis time)
304
+
305
+ ### Bottlenecks
306
+
307
+ - **TTS Synthesis**: Primary bottleneck, queue doesn't solve this
308
+ - **Sequential Processing**: By design (FIFO requirement)
309
+ - **Queue Depth**: Limited to 100 items prevents memory issues
310
+
311
+ ---
312
+
313
+ ## Security Considerations
314
+
315
+ ### Input Validation (Before Queue)
316
+
317
+ 1. **JSON Parse**: Handle malformed JSON, return 400
318
+ 2. **Schema Validation**: Required fields present, return 400
319
+ 3. **Type Validation**: String types, length limits, return 400
320
+ 4. **Voice ID Validation**: Against available voices, return 400
321
+ 5. **Text Sanitization**: Remove dangerous characters, return 400 if empty
322
+
323
+ ### Rate Limiting (Before Queue)
324
+
325
+ - Existing rate limiter applies (10 req/min per client)
326
+ - Prevents queue flooding from abusive clients
327
+
328
+ ### Queue Isolation
329
+
330
+ - In-memory queue = per-server instance
331
+ - No cross-client pollution
332
+ - Server restart = queue cleared
333
+
334
+ ---
335
+
336
+ ## Documentation Requirements
337
+
338
+ ### API Documentation (OpenAPI/Swagger)
339
+
340
+ **POST /notify**:
341
+ - Request body schema
342
+ - 201 Accepted response
343
+ - 400 Bad Request response (validation failure)
344
+ - 429 Too Many Requests response (queue full)
345
+
346
+ **GET /queue/status**:
347
+ - Response schema with queue depth, status, health
348
+ - 200 OK response (always, even when TTS unavailable)
349
+
350
+ ### Code Documentation
351
+
352
+ - JSDoc comments for `NotificationQueue` class
353
+ - Type definitions with documentation
354
+ - Inline comments for non-obvious logic
355
+
356
+ ---
357
+
358
+ ## Open Questions Resolved
359
+
360
+ All questions from spec clarification have been addressed:
361
+
362
+ 1. ✅ **Shutdown Behavior**: Drain queue before exit with 30s timeout
363
+ 2. ✅ **Queue Status Returns**: 200 OK with health indicator field
364
+ 3. ✅ **Invalid Request Handling**: Reject immediately (400) before queuing
365
+
366
+ ---
367
+
368
+ ## Next Steps
369
+
370
+ Proceed to Phase 1: Design & Contracts
371
+ - Generate `data-model.md` with entity definitions
372
+ - Generate API contracts in `/contracts/`
373
+ - Generate `quickstart.md` with development setup
374
+ - Update agent context with queue-specific information