@madeinoz67/voice-server 0.1.8 → 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 +39 -8
- package/CLAUDE.md +5 -0
- package/README.md +28 -0
- package/cliff.toml +7 -3
- 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 +5 -2
- 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,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
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Feature Specification: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Feature Branch**: `001-fifo-notify-queue`
|
|
4
|
+
**Created**: 2026-02-09
|
|
5
|
+
**Status**: Draft
|
|
6
|
+
**Input**: User description: "implement queue system https://github.com/madeinoz67/madeinoz-voice-server/issues/13"
|
|
7
|
+
**Related Issue**: https://github.com/madeinoz67/madeinoz-voice-server/issues/13
|
|
8
|
+
|
|
9
|
+
## User Scenarios & Testing *(mandatory)*
|
|
10
|
+
|
|
11
|
+
### User Story 1 - Sequential Audio Playback (Priority: P1)
|
|
12
|
+
|
|
13
|
+
When multiple automated agents send voice notifications simultaneously (e.g., during PAI Algorithm phase transitions), the system must play them in sequence rather than overlapping, ensuring each notification is clearly audible and intelligible.
|
|
14
|
+
|
|
15
|
+
**Why this priority**: This is the core problem - overlapping audio makes notifications unintelligible, defeating the purpose of the voice feedback system. Without sequential playback, the feature provides no value.
|
|
16
|
+
|
|
17
|
+
**Independent Test**: Can be fully tested by sending multiple simultaneous `/notify` requests and verifying that audio plays one after another without overlap. Delivers clear, sequential voice notifications.
|
|
18
|
+
|
|
19
|
+
**Acceptance Scenarios**:
|
|
20
|
+
|
|
21
|
+
1. **Given** the voice server is running, **When** three simultaneous `/notify` POST requests arrive, **Then** all three notifications play sequentially in order of arrival
|
|
22
|
+
2. **Given** a notification is currently playing, **When** a new `/notify` request arrives, **Then** the new request is queued and plays after the current notification completes
|
|
23
|
+
3. **Given** the notification queue is empty, **When** a single `/notify` request arrives, **Then** the notification plays immediately with no perceptible delay
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
### User Story 2 - Immediate Response Acknowledgment (Priority: P1)
|
|
28
|
+
|
|
29
|
+
When a client sends a notification request, they receive immediate acknowledgment that the request was accepted, without waiting for audio playback to complete. This prevents timeout issues and allows clients to continue processing immediately.
|
|
30
|
+
|
|
31
|
+
**Why this priority**: Without immediate acknowledgment, clients may timeout or block waiting for audio to finish. The 201 Accepted pattern is essential for non-blocking client behavior.
|
|
32
|
+
|
|
33
|
+
**Independent Test**: Can be fully tested by sending a `/notify` request and measuring response time. Expect immediate 201 status response regardless of audio playback duration. Delivers non-blocking API behavior.
|
|
34
|
+
|
|
35
|
+
**Acceptance Scenarios**:
|
|
36
|
+
|
|
37
|
+
1. **Given** a `/notify` request is sent, **When** the request is received, **Then** a 201 Accepted status is returned within 100ms (before audio processing begins)
|
|
38
|
+
2. **Given** a `/notify` request with a long message, **When** the request is received, **Then** the client receives immediate 201 response and can continue processing while audio plays in background
|
|
39
|
+
3. **Given** a client sends multiple rapid requests, **When** each request arrives, **Then** each receives 201 Accepted immediately and queue position is maintained
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
### User Story 3 - Queue Status Monitoring (Priority: P2)
|
|
44
|
+
|
|
45
|
+
System operators can check the current depth and status of the notification queue to understand system load and identify potential bottlenecks.
|
|
46
|
+
|
|
47
|
+
**Why this priority**: Operational visibility is important for monitoring and debugging, but the core functionality works without it. Lower priority than P1 stories that deliver the primary value.
|
|
48
|
+
|
|
49
|
+
**Independent Test**: Can be tested by querying the queue status endpoint and verifying accurate queue depth is returned. Delivers operational visibility into system state.
|
|
50
|
+
|
|
51
|
+
**Acceptance Scenarios**:
|
|
52
|
+
|
|
53
|
+
1. **Given** the voice server is running, **When** a GET request to `/queue/status` is made, **Then** the response includes current queue depth, processing status, and health indicator
|
|
54
|
+
2. **Given** three notifications are queued, **When** `/queue/status` is queried, **Then** queue depth is reported as 3 and health indicator shows "healthy"
|
|
55
|
+
3. **Given** the queue is empty, **When** `/queue/status` is queried, **Then** queue depth is reported as 0
|
|
56
|
+
4. **Given** the TTS system is unavailable, **When** `/queue/status` is queried, **Then** health indicator shows "unavailable" while still returning 200 OK
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
### Edge Cases
|
|
61
|
+
|
|
62
|
+
- When queue exceeds maximum capacity (100 items): Return 429 Too Many Requests
|
|
63
|
+
- Malformed notification request (invalid JSON, missing fields): Reject immediately with 400 Bad Request, never queued
|
|
64
|
+
- Invalid voice_id or settings: Reject immediately with 400 Bad Request before queuing
|
|
65
|
+
- Audio synthesis fails for a queued item: Skip to next item, continue processing
|
|
66
|
+
- Server shutdown with queued notifications: Drain queue — complete all pending items before exiting
|
|
67
|
+
|
|
68
|
+
## Requirements *(mandatory)*
|
|
69
|
+
|
|
70
|
+
### Functional Requirements
|
|
71
|
+
|
|
72
|
+
- **FR-001**: System MUST process voice notification requests in first-in-first-out (FIFO) order
|
|
73
|
+
- **FR-002**: System MUST return HTTP 201 Accepted status immediately upon receiving a valid notification request
|
|
74
|
+
- **FR-003**: System MUST play notification audio sequentially, with no overlap between notifications
|
|
75
|
+
- **FR-004**: System MUST maintain a queue of pending notification requests
|
|
76
|
+
- **FR-005**: System MUST limit maximum queue depth to 100 items
|
|
77
|
+
- **FR-006**: System MUST return 429 Too Many Requests when queue is at maximum capacity
|
|
78
|
+
- **FR-013**: System MUST validate request schema and voice_id immediately before queuing, returning 400 Bad Request for invalid input
|
|
79
|
+
- **FR-007**: System MUST skip to next queued item if audio synthesis fails for current item
|
|
80
|
+
- **FR-008**: System MUST log queue events (item queued, processing started, completed, failed)
|
|
81
|
+
- **FR-009**: System MUST provide `/queue/status` endpoint returning current queue depth and status
|
|
82
|
+
- **FR-010**: System MUST preserve original notification order based on arrival timestamp
|
|
83
|
+
- **FR-011**: System MUST drain all queued notifications before completing graceful shutdown
|
|
84
|
+
- **FR-012**: `/queue/status` endpoint MUST include health indicator field (healthy/degraded/unavailable)
|
|
85
|
+
|
|
86
|
+
### Key Entities
|
|
87
|
+
|
|
88
|
+
- **QueuedNotification**: Represents a notification request awaiting processing. Contains message content, voice settings, arrival timestamp, and processing status. Maintains order relative to other queued items.
|
|
89
|
+
|
|
90
|
+
- **QueueState**: Represents the current state of the notification queue. Contains current depth, processing status (idle/active), health indicator (healthy/degraded/unavailable), and optional metrics (average wait time, items processed).
|
|
91
|
+
|
|
92
|
+
## Success Criteria *(mandatory)*
|
|
93
|
+
|
|
94
|
+
### Measurable Outcomes
|
|
95
|
+
|
|
96
|
+
- **SC-001**: Multiple simultaneous notification requests (up to 10) result in sequential audio playback with no overlap
|
|
97
|
+
- **SC-002**: All valid notification requests receive 201 Accepted response within 100ms of receipt
|
|
98
|
+
- **SC-003**: Queue status endpoint returns accurate queue depth and health indicator within 50ms
|
|
99
|
+
- **SC-004**: System gracefully handles queue overflow by rejecting requests with 429 status when queue contains 100 items
|
|
100
|
+
- **SC-005**: Invalid requests (malformed JSON, missing fields, invalid voice_id) are rejected with 400 Bad Request within 50ms
|
|
101
|
+
|
|
102
|
+
## Assumptions
|
|
103
|
+
|
|
104
|
+
1. **In-memory queue**: Queue data is stored in memory and does not persist across server restarts
|
|
105
|
+
2. **Single worker**: Queue processing is handled by a single background worker to maintain strict FIFO ordering
|
|
106
|
+
3. **Standard client behavior**: Clients are expected to handle 201 Accepted as success and not retry the request
|
|
107
|
+
4. **Audio duration**: Average notification duration is 3-10 seconds, informing reasonable queue depth limits
|
|
108
|
+
5. **PAI Algorithm usage**: Primary use case is PAI Algorithm phase transitions, which generate 2-7 rapid notifications per operation
|
|
109
|
+
|
|
110
|
+
## Clarifications
|
|
111
|
+
|
|
112
|
+
### Session 2026-02-09
|
|
113
|
+
|
|
114
|
+
- Q: When the voice server shuts down gracefully (SIGTERM/SIGINT), what should happen to notifications currently queued but not yet played? → A: Drain queue before shutdown — play all queued items, then exit
|
|
115
|
+
- Q: What should the `/queue/status` endpoint return when the queue service is unhealthy or the underlying TTS system is unavailable? → B: Return 200 OK with health indicator field (healthy/degraded/unavailable)
|
|
116
|
+
- Q: When a notification request contains invalid data (malformed JSON, missing required fields, invalid voice_id), should the system reject it immediately upon receipt (before queuing) or queue it and fail during processing? → A: Reject immediately — return 400 Bad Request before queuing
|
|
117
|
+
|
|
118
|
+
## Out of Scope
|
|
119
|
+
|
|
120
|
+
- Persistent queue storage (surviving server restarts)
|
|
121
|
+
- Priority queuing (all items have equal priority)
|
|
122
|
+
- Queue item cancellation or removal
|
|
123
|
+
- Distributed/clustered queue support
|
|
124
|
+
- WebSocket or push notifications for queue events
|
|
125
|
+
- Admin APIs for queue manipulation (clear, pause, resume)
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Implementation Tasks: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Feature**: FIFO Notification Queue
|
|
4
|
+
**Branch**: 002-fifo-notify-queue
|
|
5
|
+
**Date**: 2026-02-09
|
|
6
|
+
**Status**: In Progress
|
|
7
|
+
|
|
8
|
+
## Task Legend
|
|
9
|
+
|
|
10
|
+
- `[ ]` - Pending task
|
|
11
|
+
- `[X]` - Completed task
|
|
12
|
+
- `[P]` - Parallel task (can run concurrently with other [P] tasks)
|
|
13
|
+
- `[→ N]` - Depends on task N completing first
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Phase 1: Setup
|
|
18
|
+
|
|
19
|
+
### 1.1 Project Structure
|
|
20
|
+
- [ ] 1.1.1 Verify `.gitignore` contains TypeScript patterns (`node_modules/`, `dist/`, `*.log`)
|
|
21
|
+
- [ ] 1.1.2 Create `src/ts/models/queue.ts` file
|
|
22
|
+
- [ ] 1.1.3 Create `src/ts/services/notification-queue.ts` file
|
|
23
|
+
- [ ] 1.1.4 Create `tests/unit/services/` directory
|
|
24
|
+
- [ ] 1.1.5 Create `tests/integration/` directory
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Phase 2: Core Types
|
|
29
|
+
|
|
30
|
+
### 2.1 Queue Models
|
|
31
|
+
- [ ] 2.1.1 Define `QueuedNotification` interface with id, message, voice_id, status, arrived_at
|
|
32
|
+
- [ ] 2.1.2 Define `QueueState` interface with depth, processing_status, health, metrics
|
|
33
|
+
- [ ] 2.1.3 Define `QueueConfig` interface with maxDepth, drainTimeoutMs, degradedThreshold
|
|
34
|
+
- [ ] 2.1.4 Export all types from `src/ts/models/queue.ts`
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Phase 3: Queue Service
|
|
39
|
+
|
|
40
|
+
### 3.1 NotificationQueue Class
|
|
41
|
+
- [ ] 3.1.1 Implement `NotificationQueue` class constructor
|
|
42
|
+
- [ ] 3.1.2 Implement `enqueue()` method with maxDepth validation
|
|
43
|
+
- [ ] 3.1.3 Implement `processQueue()` private method with sequential processing
|
|
44
|
+
- [ ] 3.1.4 Implement `getQueueState()` method for status monitoring
|
|
45
|
+
- [ ] 3.1.5 Implement `drain()` method for graceful shutdown
|
|
46
|
+
- [ ] 3.1.6 Add queue event logging (item queued, processing, completed, failed)
|
|
47
|
+
|
|
48
|
+
### 3.2 Queue Processing Logic
|
|
49
|
+
- [ ] 3.2.1 Implement TTS synthesis with error handling (skip on failure)
|
|
50
|
+
- [ ] 3.2.2 Implement processing flag to prevent concurrent processing
|
|
51
|
+
- [ ] 3.2.3 Implement health indicator logic (healthy/degraded/unavailable)
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Phase 4: Server Integration
|
|
56
|
+
|
|
57
|
+
### 4.1 Notify Endpoint Updates
|
|
58
|
+
- [ ] 4.1.1 Create NotificationQueue instance in server state
|
|
59
|
+
- [ ] 4.1.2 Update `handleNotify()` to use queue instead of direct TTS call
|
|
60
|
+
- [ ] 4.1.3 Return 201 Accepted immediately on successful enqueue
|
|
61
|
+
- [ ] 4.1.4 Return 400 Bad Request for invalid input (before queue)
|
|
62
|
+
- [ ] 4.1.5 Return 429 Too Many Requests when queue is full
|
|
63
|
+
|
|
64
|
+
### 4.2 Queue Status Endpoint
|
|
65
|
+
- [ ] 4.2.1 Add `handleQueueStatus()` function
|
|
66
|
+
- [ ] 4.2.2 Add GET `/queue/status` route to Bun.serve handler
|
|
67
|
+
- [ ] 4.2.3 Return QueueStateResponse with depth, status, health, metrics
|
|
68
|
+
|
|
69
|
+
### 4.3 Graceful Shutdown
|
|
70
|
+
- [ ] 4.3.1 Update shutdown handler to call `queue.drain()`
|
|
71
|
+
- [ ] 4.3.2 Implement drain timeout (30 seconds)
|
|
72
|
+
- [ ] 4.3.3 Log remaining items on timeout
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Phase 5: Tests
|
|
77
|
+
|
|
78
|
+
### 5.1 Unit Tests [P]
|
|
79
|
+
- [ ] 5.1.1 Test `enqueue()` adds items to queue
|
|
80
|
+
- [ ] 5.1.2 Test `enqueue()` rejects when maxDepth exceeded
|
|
81
|
+
- [ ] 5.1.3 Test FIFO ordering with multiple items
|
|
82
|
+
- [ ] 5.1.4 Test `processQueue()` processes items sequentially
|
|
83
|
+
- [ ] 5.1.5 Test `processQueue()` skips failed items
|
|
84
|
+
- [ ] 5.1.6 Test `getQueueState()` returns correct state
|
|
85
|
+
- [ ] 5.1.7 Test `drain()` completes within timeout
|
|
86
|
+
- [ ] 5.1.8 Test queue event logging
|
|
87
|
+
|
|
88
|
+
### 5.2 Integration Tests [P]
|
|
89
|
+
- [ ] 5.2.1 Test POST /notify returns 201 Accepted
|
|
90
|
+
- [ ] 5.2.2 Test multiple requests process sequentially
|
|
91
|
+
- [ ] 5.2.3 Test queue overflow returns 429
|
|
92
|
+
- [ ] 5.2.4 Test invalid requests return 400
|
|
93
|
+
- [ ] 5.2.5 Test GET /queue/status returns correct state
|
|
94
|
+
- [ ] 5.2.6 Test health indicator reflects TTS availability
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Phase 6: Validation
|
|
99
|
+
|
|
100
|
+
### 6.1 Code Quality
|
|
101
|
+
- [ ] 6.1.1 Run `bun run typecheck` - zero errors
|
|
102
|
+
- [ ] 6.1.2 Run `bun run lint` - zero warnings
|
|
103
|
+
- [ ] 6.1.3 Run `bun test` - all tests pass
|
|
104
|
+
- [ ] 6.1.4 Verify Codanna index is updated
|
|
105
|
+
|
|
106
|
+
### 6.2 Documentation
|
|
107
|
+
- [ ] 6.2.1 Verify JSDoc comments on all public methods
|
|
108
|
+
- [ ] 6.2.2 Verify quickstart.md examples are accurate
|
|
109
|
+
- [ ] 6.2.3 Verify API contracts match implementation
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## Execution Notes
|
|
114
|
+
|
|
115
|
+
- **TDD Approach**: Write tests before implementation (Phase 5 before Phase 3-4)
|
|
116
|
+
- **File Coordination**: Tasks in Phase 3 affect `notification-queue.ts`, must run sequentially
|
|
117
|
+
- **Parallel Tasks**: Phase 5.1 and 5.2 marked [P] can run concurrently after test setup
|
|
118
|
+
- **Dependencies**: Each phase must complete before the next phase begins
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Progress Tracking
|
|
123
|
+
|
|
124
|
+
| Phase | Tasks | Completed | Status |
|
|
125
|
+
|-------|-------|------------|--------|
|
|
126
|
+
| 1. Setup | 5 | 0 | Pending |
|
|
127
|
+
| 2. Core Types | 4 | 0 | Pending |
|
|
128
|
+
| 3. Queue Service | 9 | 0 | Pending |
|
|
129
|
+
| 4. Server Integration | 8 | 0 | Pending |
|
|
130
|
+
| 5. Tests | 14 | 0 | Pending |
|
|
131
|
+
| 6. Validation | 7 | 0 | Pending |
|
|
132
|
+
| **Total** | **47** | **0** | **0%** |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
**Next Steps**: Begin with Phase 1 (Setup) to establish project structure.
|