@madeinoz67/voice-server 0.1.9 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/CLAUDE.md +5 -0
- package/cliff.toml +3 -1
- package/docs/api.md +4 -0
- package/docs/assets/queue-error-handling-flow.png +0 -0
- package/docs/assets/queue-request-flow-success.png +0 -0
- package/docs/assets/queue-states.png +0 -0
- package/docs/assets/queue-system-overview.png +0 -0
- package/docs/assets/voice-server-architecture.png +0 -0
- package/docs/fifo-queue.md +175 -0
- package/docs/queue-architecture.md +182 -0
- package/mkdocs.yml +3 -0
- package/package.json +1 -1
- package/specs/002-fifo-notify-queue/checklists/requirements.md +50 -0
- package/specs/002-fifo-notify-queue/contracts/api.yaml +283 -0
- package/specs/002-fifo-notify-queue/data-model.md +379 -0
- package/specs/002-fifo-notify-queue/plan.md +320 -0
- package/specs/002-fifo-notify-queue/quickstart.md +273 -0
- package/specs/002-fifo-notify-queue/research.md +374 -0
- package/specs/002-fifo-notify-queue/spec.md +125 -0
- package/specs/002-fifo-notify-queue/tasks.md +136 -0
- package/src/ts/models/queue.ts +140 -0
- package/src/ts/server.ts +98 -19
- package/src/ts/services/mlx-tts-client.ts +75 -20
- package/src/ts/services/notification-queue.ts +382 -0
- package/tests/integration/queue-api.test.ts +298 -0
- package/tests/unit/services/notification-queue.test.ts +622 -0
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
# Implementation Plan: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Branch**: `002-fifo-notify-queue` | **Date**: 2026-02-09 | **Spec**: [spec.md](./spec.md)
|
|
4
|
+
**Input**: Feature specification from `/specs/002-fifo-notify-queue/spec.md`
|
|
5
|
+
|
|
6
|
+
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
7
|
+
|
|
8
|
+
## Summary
|
|
9
|
+
|
|
10
|
+
Implement a FIFO (first-in-first-out) queue for the voice server's `/notify` endpoint to prevent audio overlap when multiple agents send notifications simultaneously. The queue accepts requests immediately with a 201 Accepted response, then processes notifications sequentially in the background. Includes a `/queue/status` monitoring endpoint and graceful shutdown with queue draining.
|
|
11
|
+
|
|
12
|
+
**Key Requirements**:
|
|
13
|
+
- FIFO ordering for all notifications
|
|
14
|
+
- 201 Accepted response within 100ms
|
|
15
|
+
- Max 100 item queue depth with 429 on overflow
|
|
16
|
+
- Invalid requests rejected immediately (400 Bad Request)
|
|
17
|
+
- Graceful shutdown drains queue before exit
|
|
18
|
+
|
|
19
|
+
## Technical Context
|
|
20
|
+
|
|
21
|
+
**Language/Version**: TypeScript 5.x (Bun runtime)
|
|
22
|
+
**Primary Dependencies**: Bun native APIs, MLX-audio CLI (existing)
|
|
23
|
+
**Storage**: In-memory array (no persistence per spec)
|
|
24
|
+
**Testing**: Bun test runner (built-in)
|
|
25
|
+
**Target Platform**: macOS only (Constitution Principle IV)
|
|
26
|
+
**Project Type**: Single (monorepo with server code in `src/ts/`)
|
|
27
|
+
**Performance Goals**:
|
|
28
|
+
- 201 Accepted response < 100ms
|
|
29
|
+
- Queue status response < 50ms
|
|
30
|
+
- Max 100 queued items
|
|
31
|
+
- Sequential audio playback (no overlap)
|
|
32
|
+
**Constraints**:
|
|
33
|
+
- In-memory queue only (no persistence)
|
|
34
|
+
- Single worker for FIFO ordering
|
|
35
|
+
- Queue depth ≤ 100 items
|
|
36
|
+
- Shutdown drain timeout ≤ 30 seconds
|
|
37
|
+
**Scale/Scope**:
|
|
38
|
+
- Local voice server (single instance)
|
|
39
|
+
- 2-7 rapid notifications per PAI Algorithm operation
|
|
40
|
+
- Average 3-10 second TTS processing time per notification
|
|
41
|
+
|
|
42
|
+
## Constitution Check
|
|
43
|
+
|
|
44
|
+
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
45
|
+
|
|
46
|
+
### Principle I: Drop-in Compatibility
|
|
47
|
+
✅ **PASS** - `/notify` endpoint maintains exact contract. 201 Accepted is compatible with existing PAI system expectations. No breaking changes to request/response formats.
|
|
48
|
+
|
|
49
|
+
### Principle II: Local-First Architecture
|
|
50
|
+
✅ **PASS** - Queue is in-memory, no external API dependencies. MLX-audio remains primary TTS backend.
|
|
51
|
+
|
|
52
|
+
### Principle III: Graceful Degradation
|
|
53
|
+
✅ **PASS** - Queue skip-on-failure pattern continues processing even when individual items fail. Existing fallback to macOS `say` preserved.
|
|
54
|
+
|
|
55
|
+
### Principle IV: Platform Honesty
|
|
56
|
+
✅ **PASS** - No cross-platform abstractions. Uses macOS-native commands (`afplay`, `osascript`) directly.
|
|
57
|
+
|
|
58
|
+
### Principle V: Test-First Validation
|
|
59
|
+
✅ **PASS** - Unit and integration tests planned for all queue operations, API endpoints, and error conditions. TDD approach followed.
|
|
60
|
+
|
|
61
|
+
### Principle VI: Codanna Workflow
|
|
62
|
+
✅ **PASS** - All new TypeScript files in `src/ts/services/` and `src/ts/models/` will be indexed. Codanna used for symbol lookup and impact analysis.
|
|
63
|
+
|
|
64
|
+
### Principle VII: Documentation Standards
|
|
65
|
+
✅ **PASS** - This plan follows Markdown formatting requirements. API documentation in OpenAPI format. Code will have JSDoc comments.
|
|
66
|
+
|
|
67
|
+
**Overall Gate Status**: ✅ **PASS** - All constitutional principles satisfied.
|
|
68
|
+
|
|
69
|
+
## Project Structure
|
|
70
|
+
|
|
71
|
+
### Documentation (this feature)
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
specs/002-fifo-notify-queue/
|
|
75
|
+
├── plan.md # This file (/speckit.plan command output)
|
|
76
|
+
├── research.md # Phase 0 output (/speckit.plan command)
|
|
77
|
+
├── data-model.md # Phase 1 output (/speckit.plan command)
|
|
78
|
+
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
|
79
|
+
├── contracts/ # Phase 1 output (/speckit.plan command)
|
|
80
|
+
│ └── api.yaml # OpenAPI specification
|
|
81
|
+
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Source Code (repository root)
|
|
85
|
+
|
|
86
|
+
```text
|
|
87
|
+
src/ts/
|
|
88
|
+
├── services/
|
|
89
|
+
│ ├── notification-queue.ts # NEW: Queue implementation
|
|
90
|
+
│ ├── mlx-tts-client.ts # EXISTING: No changes needed
|
|
91
|
+
│ ├── pronunciation.ts # EXISTING: No changes needed
|
|
92
|
+
│ ├── prosody-translator.ts # EXISTING: No changes needed
|
|
93
|
+
│ └── voice-loader.ts # EXISTING: No changes needed
|
|
94
|
+
├── models/
|
|
95
|
+
│ ├── queue.ts # NEW: Queue types
|
|
96
|
+
│ ├── notification.ts # EXISTING: No changes needed
|
|
97
|
+
│ ├── health.ts # EXISTING: Extended with queue fields
|
|
98
|
+
│ ├── tts.ts # EXISTING: No changes needed
|
|
99
|
+
│ └── voice-config.ts # EXISTING: No changes needed
|
|
100
|
+
├── middleware/
|
|
101
|
+
│ ├── cors.ts # EXISTING: No changes needed
|
|
102
|
+
│ └── rate-limiter.ts # EXISTING: No changes needed
|
|
103
|
+
├── utils/
|
|
104
|
+
│ ├── logger.ts # EXISTING: No changes needed
|
|
105
|
+
│ └── text-sanitizer.ts # EXISTING: No changes needed
|
|
106
|
+
└── server.ts # MODIFY: Add queue integration, /queue/status endpoint
|
|
107
|
+
|
|
108
|
+
tests/
|
|
109
|
+
├── unit/
|
|
110
|
+
│ └── services/
|
|
111
|
+
│ └── notification-queue.test.ts # NEW: Queue unit tests
|
|
112
|
+
└── integration/
|
|
113
|
+
└── queue-api.test.ts # NEW: Queue API integration tests
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
**Structure Decision**: Single project structure (Option 1). This is a backend service with HTTP API, no frontend component. All code resides in `src/ts/` following existing patterns.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Phase 0: Research ✓ Complete
|
|
121
|
+
|
|
122
|
+
**Status**: Complete
|
|
123
|
+
|
|
124
|
+
**Research Output**: [research.md](./research.md)
|
|
125
|
+
|
|
126
|
+
**Key Decisions**:
|
|
127
|
+
1. **Queue Implementation**: Array-based in-memory queue with async/await processing
|
|
128
|
+
2. **Concurrency**: Single async worker with Promise-based processing
|
|
129
|
+
3. **Graceful Shutdown**: Await queue drain with 30-second timeout
|
|
130
|
+
4. **Error Handling**: Skip failed items, continue processing
|
|
131
|
+
5. **Health Monitoring**: Extend existing HealthStatus model with queue fields
|
|
132
|
+
6. **Rate Limiting**: Apply before queue admission, separate 429 for queue full
|
|
133
|
+
|
|
134
|
+
**Open Questions Resolved**:
|
|
135
|
+
- ✅ Shutdown behavior: Drain queue before exit (30s timeout)
|
|
136
|
+
- ✅ Queue status returns: 200 OK with health indicator
|
|
137
|
+
- ✅ Invalid requests: Reject immediately (400) before queuing
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Phase 1: Design & Contracts ✓ Complete
|
|
142
|
+
|
|
143
|
+
**Status**: Complete
|
|
144
|
+
|
|
145
|
+
### Data Model
|
|
146
|
+
|
|
147
|
+
**Output**: [data-model.md](./data-model.md)
|
|
148
|
+
|
|
149
|
+
**Entities Defined**:
|
|
150
|
+
- `QueuedNotification` - Queued item with message, voice settings, status
|
|
151
|
+
- `QueueState` - Current queue depth, processing status, health indicator
|
|
152
|
+
- `QueueConfig` - Configuration for max depth, drain timeout, degraded threshold
|
|
153
|
+
|
|
154
|
+
**Type Dependencies**:
|
|
155
|
+
- Uses existing `NotificationRequest`, `ProsodySettings` from `models/notification.ts` and `models/voice-config.ts`
|
|
156
|
+
- Extends `HealthStatus` from `models/health.ts` with queue fields
|
|
157
|
+
|
|
158
|
+
### API Contracts
|
|
159
|
+
|
|
160
|
+
**Output**: [contracts/api.yaml](./contracts/api.yaml)
|
|
161
|
+
|
|
162
|
+
**Endpoints Specified**:
|
|
163
|
+
1. `POST /notify` - Queue notification (201/400/429/500)
|
|
164
|
+
2. `GET /queue/status` - Get queue state (200 always)
|
|
165
|
+
|
|
166
|
+
**Request/Response Schemas**:
|
|
167
|
+
- `NotificationRequest` - Queue request body
|
|
168
|
+
- `SuccessResponse` - Success response
|
|
169
|
+
- `ErrorResponse` - Error response
|
|
170
|
+
- `QueueStateResponse` - Queue status response
|
|
171
|
+
|
|
172
|
+
### Quickstart Guide
|
|
173
|
+
|
|
174
|
+
**Output**: [quickstart.md](./quickstart.md)
|
|
175
|
+
|
|
176
|
+
**Covers**:
|
|
177
|
+
- Development setup
|
|
178
|
+
- API usage examples
|
|
179
|
+
- Testing queue behavior
|
|
180
|
+
- Troubleshooting
|
|
181
|
+
- Configuration options
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Phase 2: Tasks (NOT CREATED YET)
|
|
186
|
+
|
|
187
|
+
**Status**: Pending `/speckit.tasks` command
|
|
188
|
+
|
|
189
|
+
**Note**: Run `/speckit.tasks` to generate `tasks.md` with dependency-ordered implementation tasks.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## Testing Strategy (Per Constitution Principle V)
|
|
194
|
+
|
|
195
|
+
### Unit Tests
|
|
196
|
+
|
|
197
|
+
**File**: `tests/unit/services/notification-queue.test.ts`
|
|
198
|
+
|
|
199
|
+
Coverage:
|
|
200
|
+
- Queue enqueue/dequeue operations
|
|
201
|
+
- FIFO ordering verification
|
|
202
|
+
- Max depth enforcement
|
|
203
|
+
- Processing state management
|
|
204
|
+
- Error handling (skip failed items)
|
|
205
|
+
- Graceful shutdown with drain
|
|
206
|
+
|
|
207
|
+
### Integration Tests
|
|
208
|
+
|
|
209
|
+
**File**: `tests/integration/queue-api.test.ts`
|
|
210
|
+
|
|
211
|
+
Coverage:
|
|
212
|
+
- `POST /notify` returns 201 Accepted
|
|
213
|
+
- Multiple requests process sequentially (no audio overlap)
|
|
214
|
+
- Queue overflow returns 429
|
|
215
|
+
- Invalid requests return 400
|
|
216
|
+
- `GET /queue/status` returns correct state
|
|
217
|
+
- Health indicator reflects TTS availability
|
|
218
|
+
|
|
219
|
+
### Test Doubles
|
|
220
|
+
|
|
221
|
+
- Mock `processTTS()` function for unit tests
|
|
222
|
+
- Mock MLX TTS client for integration tests
|
|
223
|
+
- Fake timers for timing-sensitive tests
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Constitution Re-Check (Post-Design)
|
|
228
|
+
|
|
229
|
+
*Re-evaluated after Phase 1 design*
|
|
230
|
+
|
|
231
|
+
✅ **All Principles Pass** - No violations, no complexity tracking required.
|
|
232
|
+
|
|
233
|
+
Design decisions uphold all constitutional principles:
|
|
234
|
+
- Drop-in compatibility maintained (201 Accepted is standard HTTP pattern)
|
|
235
|
+
- Local-first architecture (in-memory queue)
|
|
236
|
+
- Graceful degradation (skip-on-failure)
|
|
237
|
+
- Platform honesty (macOS-only)
|
|
238
|
+
- Test-first validation (comprehensive tests planned)
|
|
239
|
+
- Codanna workflow (new files will be indexed)
|
|
240
|
+
- Documentation standards (OpenAPI, JSDoc, Markdown)
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## Implementation Notes
|
|
245
|
+
|
|
246
|
+
### Queue Processing Flow
|
|
247
|
+
|
|
248
|
+
```
|
|
249
|
+
HTTP Request → Validate → Enqueue → Return 201
|
|
250
|
+
↓
|
|
251
|
+
Background Worker
|
|
252
|
+
↓
|
|
253
|
+
Process TTS → Play Audio
|
|
254
|
+
↓
|
|
255
|
+
Next Item (if any)
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Graceful Shutdown Flow
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
SIGTERM/SIGINT → Set draining flag → Stop accepting requests
|
|
262
|
+
↓
|
|
263
|
+
Wait for queue empty (30s timeout)
|
|
264
|
+
↓
|
|
265
|
+
Exit process
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### Error Handling Flow
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
TTS Failure → Log error → Skip to next item → Continue processing
|
|
272
|
+
Queue Full → Return 429 → Client may retry
|
|
273
|
+
Invalid Request → Return 400 → Never queued
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Dependencies
|
|
279
|
+
|
|
280
|
+
### Internal Dependencies
|
|
281
|
+
|
|
282
|
+
- `src/ts/models/notification.ts` - Request/response types
|
|
283
|
+
- `src/ts/models/voice-config.ts` - ProsodySettings type
|
|
284
|
+
- `src/ts/models/health.ts` - HealthStatus extension
|
|
285
|
+
- `src/ts/services/mlx-tts-client.ts` - TTS synthesis
|
|
286
|
+
- `src/ts/utils/logger.ts` - Logging
|
|
287
|
+
- `src/ts/utils/text-sanitizer.ts` - Input validation
|
|
288
|
+
- `src/ts/services/voice-loader.ts` - Voice ID validation
|
|
289
|
+
|
|
290
|
+
### External Dependencies
|
|
291
|
+
|
|
292
|
+
- Bun runtime (native Promise, Array, crypto APIs)
|
|
293
|
+
- MLX-audio CLI (existing TTS backend)
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Success Criteria Verification
|
|
298
|
+
|
|
299
|
+
**From Spec**:
|
|
300
|
+
|
|
301
|
+
| Criterion | Verification |
|
|
302
|
+
|-----------|--------------|
|
|
303
|
+
| SC-001: Sequential playback | Integration test sends 10 concurrent requests, verifies no audio overlap |
|
|
304
|
+
| SC-002: 201 in < 100ms | Unit test measures response time for enqueue operation |
|
|
305
|
+
| SC-003: Status < 50ms | Unit test measures `/queue/status` response time |
|
|
306
|
+
| SC-004: 429 on overflow | Integration test fills queue to 100, verifies 429 on 101st request |
|
|
307
|
+
| SC-005: 400 on invalid | Unit tests for each validation failure scenario |
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## Next Steps
|
|
312
|
+
|
|
313
|
+
1. **Run `/speckit.tasks`** - Generate implementation task list
|
|
314
|
+
2. **Update agent context** - Run `.specify/scripts/bash/update-agent-context.sh claude`
|
|
315
|
+
3. **Begin implementation** - Follow tasks in dependency order
|
|
316
|
+
4. **Update Codanna index** - After adding new TypeScript files
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
**Plan Status**: ✅ Phase 0 & 1 Complete | Phase 2 Pending `/speckit.tasks`
|
|
@@ -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
|