@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.
- package/CHANGELOG.md +9 -72
- package/CLAUDE.md +5 -0
- package/bun.lock +13 -13
- package/cliff.toml +10 -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/homebrew.mxcl.voice-server.plist +33 -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,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
|