@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,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.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Queue model types
|
|
3
|
+
* FIFO notification queue for voice server
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import type { NotificationRequest } from "@/models/notification.js";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Processing status of a queued notification
|
|
10
|
+
*/
|
|
11
|
+
export type QueuedItemStatus = "pending" | "processing" | "completed" | "failed";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Queued notification item
|
|
15
|
+
*/
|
|
16
|
+
export interface QueuedNotification {
|
|
17
|
+
/** Unique identifier for this queued item */
|
|
18
|
+
id: string;
|
|
19
|
+
/** Original notification request */
|
|
20
|
+
request: NotificationRequest;
|
|
21
|
+
/** Current status */
|
|
22
|
+
status: QueuedItemStatus;
|
|
23
|
+
/** Timestamp when item was enqueued */
|
|
24
|
+
arrivedAt: Date;
|
|
25
|
+
/** Timestamp when processing started (if applicable) */
|
|
26
|
+
processingStartedAt?: Date;
|
|
27
|
+
/** Timestamp when processing completed (if applicable) */
|
|
28
|
+
completedAt?: Date;
|
|
29
|
+
/** Error message if processing failed */
|
|
30
|
+
error?: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Processing status of the queue
|
|
35
|
+
*/
|
|
36
|
+
export type QueueProcessingStatus = "idle" | "active" | "draining" | "stopped";
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Health indicator for the queue
|
|
40
|
+
*/
|
|
41
|
+
export type QueueHealth = "healthy" | "degraded" | "unavailable";
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Queue metrics
|
|
45
|
+
*/
|
|
46
|
+
export interface QueueMetrics {
|
|
47
|
+
/** Total number of items processed successfully */
|
|
48
|
+
itemsProcessed: number;
|
|
49
|
+
/** Total number of items that failed */
|
|
50
|
+
itemsFailed: number;
|
|
51
|
+
/** Average processing time in milliseconds */
|
|
52
|
+
averageProcessingTimeMs: number;
|
|
53
|
+
/** Current processing time of active item (if any) */
|
|
54
|
+
currentProcessingTimeMs?: number;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Current state of the notification queue
|
|
59
|
+
*/
|
|
60
|
+
export interface QueueState {
|
|
61
|
+
/** Current number of items in the queue */
|
|
62
|
+
depth: number;
|
|
63
|
+
/** Current processing status */
|
|
64
|
+
processingStatus: QueueProcessingStatus;
|
|
65
|
+
/** Health indicator */
|
|
66
|
+
health: QueueHealth;
|
|
67
|
+
/** Optional metrics */
|
|
68
|
+
metrics?: QueueMetrics;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Queue configuration
|
|
73
|
+
*/
|
|
74
|
+
export interface QueueConfig {
|
|
75
|
+
/** Maximum number of items allowed in the queue */
|
|
76
|
+
maxDepth: number;
|
|
77
|
+
/** Maximum time to wait for queue drain during shutdown (ms) */
|
|
78
|
+
drainTimeoutMs: number;
|
|
79
|
+
/** Queue depth threshold for degraded health status */
|
|
80
|
+
degradedThreshold: number;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Result of an enqueue operation
|
|
85
|
+
*/
|
|
86
|
+
export interface EnqueueResult {
|
|
87
|
+
/** Whether the item was successfully enqueued */
|
|
88
|
+
success: boolean;
|
|
89
|
+
/** HTTP status code */
|
|
90
|
+
statusCode: number;
|
|
91
|
+
/** Human-readable message */
|
|
92
|
+
message: string;
|
|
93
|
+
/** Position in queue (0-indexed) if successful */
|
|
94
|
+
queuePosition?: number;
|
|
95
|
+
/** Item ID if successful */
|
|
96
|
+
itemId?: string;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Result of a drain operation
|
|
101
|
+
*/
|
|
102
|
+
export interface DrainResult {
|
|
103
|
+
/** Whether drain completed successfully */
|
|
104
|
+
success: boolean;
|
|
105
|
+
/** Number of items processed during drain */
|
|
106
|
+
itemsProcessed: number;
|
|
107
|
+
/** Number of items that failed during drain */
|
|
108
|
+
itemsFailed: number;
|
|
109
|
+
/** Whether drain timed out */
|
|
110
|
+
timedOut: boolean;
|
|
111
|
+
/** Remaining items when timed out */
|
|
112
|
+
remainingItems?: number;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Create a default queue configuration
|
|
117
|
+
*/
|
|
118
|
+
export function createDefaultQueueConfig(): QueueConfig {
|
|
119
|
+
return {
|
|
120
|
+
maxDepth: 100,
|
|
121
|
+
drainTimeoutMs: 30000, // 30 seconds
|
|
122
|
+
degradedThreshold: 50,
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Create an empty queue state
|
|
128
|
+
*/
|
|
129
|
+
export function createEmptyQueueState(): QueueState {
|
|
130
|
+
return {
|
|
131
|
+
depth: 0,
|
|
132
|
+
processingStatus: "idle",
|
|
133
|
+
health: "healthy",
|
|
134
|
+
metrics: {
|
|
135
|
+
itemsProcessed: 0,
|
|
136
|
+
itemsFailed: 0,
|
|
137
|
+
averageProcessingTimeMs: 0,
|
|
138
|
+
},
|
|
139
|
+
};
|
|
140
|
+
}
|
package/src/ts/server.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Qwen TTS Voice Server
|
|
3
|
-
* Main Bun HTTP server with /notify, /pai, /health endpoints
|
|
3
|
+
* Main Bun HTTP server with /notify, /pai, /health, /queue/status endpoints
|
|
4
4
|
* MLX-audio only - Python backend removed
|
|
5
|
+
* FIFO notification queue for sequential processing
|
|
5
6
|
*/
|
|
6
7
|
|
|
7
8
|
import type { NotificationRequest, PaiNotificationRequest } from "@/models/notification.js";
|
|
@@ -17,6 +18,8 @@ import { getMLXTTSClient, type MLXTTSClientConfig } from "@/services/mlx-tts-cli
|
|
|
17
18
|
import { getVoiceLoader } from "@/services/voice-loader.js";
|
|
18
19
|
import { getRateLimiter, extractClientId } from "@/middleware/rate-limiter.js";
|
|
19
20
|
import { getCORSMiddleware } from "@/middleware/cors.js";
|
|
21
|
+
import { NotificationQueue, type TTSProcessor } from "@/services/notification-queue.js";
|
|
22
|
+
import type { QueueState } from "@/models/queue.js";
|
|
20
23
|
import { $ } from "bun";
|
|
21
24
|
|
|
22
25
|
/**
|
|
@@ -29,6 +32,10 @@ interface ServerConfig {
|
|
|
29
32
|
enableMacOSNotifications: boolean;
|
|
30
33
|
/** MLX-audio configuration */
|
|
31
34
|
mlxConfig: MLXTTSClientConfig;
|
|
35
|
+
/** Queue configuration */
|
|
36
|
+
queueMaxDepth?: number;
|
|
37
|
+
queueDrainTimeoutMs?: number;
|
|
38
|
+
queueDegradedThreshold?: number;
|
|
32
39
|
}
|
|
33
40
|
|
|
34
41
|
/**
|
|
@@ -49,6 +56,9 @@ const DEFAULT_CONFIG: ServerConfig = {
|
|
|
49
56
|
streamingInterval: parseFloat(process.env.MLX_STREAMING_INTERVAL || "0.3"),
|
|
50
57
|
timeout: 10000,
|
|
51
58
|
},
|
|
59
|
+
queueMaxDepth: parseInt(process.env.QUEUE_MAX_DEPTH || "100", 10),
|
|
60
|
+
queueDrainTimeoutMs: parseInt(process.env.QUEUE_DRAIN_TIMEOUT_MS || "30000", 10),
|
|
61
|
+
queueDegradedThreshold: parseInt(process.env.QUEUE_DEGRADED_THRESHOLD || "50", 10),
|
|
52
62
|
};
|
|
53
63
|
|
|
54
64
|
/**
|
|
@@ -59,6 +69,7 @@ interface ServerState {
|
|
|
59
69
|
config: ServerConfig;
|
|
60
70
|
cors: ReturnType<typeof getCORSMiddleware>;
|
|
61
71
|
rateLimiter: ReturnType<typeof getRateLimiter>;
|
|
72
|
+
notificationQueue: NotificationQueue;
|
|
62
73
|
}
|
|
63
74
|
|
|
64
75
|
let serverState: ServerState;
|
|
@@ -132,6 +143,34 @@ async function fallbackToMacOSSay(text: string, voiceId?: string): Promise<void>
|
|
|
132
143
|
}
|
|
133
144
|
}
|
|
134
145
|
|
|
146
|
+
/**
|
|
147
|
+
* Process TTS request with MLX-audio backend
|
|
148
|
+
* This is used by the notification queue
|
|
149
|
+
*/
|
|
150
|
+
async function processTTSWithMacOSNotification(request: NotificationRequest): Promise<void> {
|
|
151
|
+
const title = sanitizeTitle(request.title || "Notification");
|
|
152
|
+
const message = sanitizeMessage(request.message);
|
|
153
|
+
|
|
154
|
+
if (!message) {
|
|
155
|
+
throw new Error("Invalid message after sanitization");
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// Determine voice settings
|
|
159
|
+
const voiceId = request.voice_id || request.voice_name || serverState.config.defaultVoiceId;
|
|
160
|
+
const voiceSettings = request.voice_settings || DEFAULT_PROSODY;
|
|
161
|
+
const volume = request.volume ?? voiceSettings.volume ?? 1.0;
|
|
162
|
+
|
|
163
|
+
// Display macOS notification
|
|
164
|
+
if (serverState.config.enableMacOSNotifications) {
|
|
165
|
+
await displayMacOSNotification(title, message);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
// Process TTS if enabled
|
|
169
|
+
if (request.voice_enabled !== false) {
|
|
170
|
+
await processTTS(message, voiceId, voiceSettings, volume);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
135
174
|
/**
|
|
136
175
|
* Process TTS request with MLX-audio backend
|
|
137
176
|
*/
|
|
@@ -176,7 +215,7 @@ async function processTTS(
|
|
|
176
215
|
}
|
|
177
216
|
|
|
178
217
|
/**
|
|
179
|
-
* Handle POST /notify endpoint
|
|
218
|
+
* Handle POST /notify endpoint (now queues requests)
|
|
180
219
|
*/
|
|
181
220
|
async function handleNotify(request: NotificationRequest): Promise<SuccessResponse | ErrorResponse> {
|
|
182
221
|
try {
|
|
@@ -187,38 +226,45 @@ async function handleNotify(request: NotificationRequest): Promise<SuccessRespon
|
|
|
187
226
|
return errorResponse("Missing required field: message");
|
|
188
227
|
}
|
|
189
228
|
|
|
190
|
-
// Sanitize input
|
|
191
|
-
const title = sanitizeTitle(request.title || "Notification");
|
|
229
|
+
// Sanitize input
|
|
192
230
|
const message = sanitizeMessage(request.message);
|
|
193
|
-
|
|
194
231
|
if (!message) {
|
|
195
232
|
return errorResponse("Invalid input after sanitization");
|
|
196
233
|
}
|
|
197
234
|
|
|
198
|
-
//
|
|
199
|
-
const
|
|
200
|
-
const voiceSettings = request.voice_settings || DEFAULT_PROSODY;
|
|
201
|
-
const volume = request.volume ?? voiceSettings.volume ?? 1.0;
|
|
202
|
-
|
|
203
|
-
// Display macOS notification
|
|
204
|
-
if (serverState.config.enableMacOSNotifications) {
|
|
205
|
-
await displayMacOSNotification(title, message);
|
|
206
|
-
}
|
|
235
|
+
// Enqueue the notification
|
|
236
|
+
const result = await serverState.notificationQueue.enqueue(request);
|
|
207
237
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
await processTTS(message, voiceId, voiceSettings, volume);
|
|
238
|
+
if (!result.success) {
|
|
239
|
+
return errorResponse(result.message);
|
|
211
240
|
}
|
|
212
241
|
|
|
213
|
-
|
|
242
|
+
// Return 201 Accepted response
|
|
243
|
+
return {
|
|
244
|
+
status: "success",
|
|
245
|
+
message: result.message,
|
|
246
|
+
};
|
|
214
247
|
} catch (error) {
|
|
215
248
|
logger.error("Error handling /notify", error as Error);
|
|
216
249
|
return errorResponse("Internal server error");
|
|
217
250
|
}
|
|
218
251
|
}
|
|
219
252
|
|
|
253
|
+
/**
|
|
254
|
+
* Handle GET /queue/status endpoint
|
|
255
|
+
*/
|
|
256
|
+
async function handleQueueStatus(): Promise<QueueState & { status: "success" }> {
|
|
257
|
+
const queueState = serverState.notificationQueue.getQueueState();
|
|
258
|
+
return {
|
|
259
|
+
status: "success",
|
|
260
|
+
...queueState,
|
|
261
|
+
};
|
|
262
|
+
}
|
|
263
|
+
|
|
220
264
|
/**
|
|
221
265
|
* Handle POST /pai endpoint
|
|
266
|
+
* Note: This bypasses the queue for immediate PAI notifications
|
|
267
|
+
* Can be changed to use queue if desired
|
|
222
268
|
*/
|
|
223
269
|
async function handlePai(request: PaiNotificationRequest): Promise<SuccessResponse | ErrorResponse> {
|
|
224
270
|
try {
|
|
@@ -233,7 +279,7 @@ async function handlePai(request: PaiNotificationRequest): Promise<SuccessRespon
|
|
|
233
279
|
const title = sanitizeTitle(request.title);
|
|
234
280
|
const message = sanitizeMessage(request.message);
|
|
235
281
|
|
|
236
|
-
//
|
|
282
|
+
// Determine voice settings
|
|
237
283
|
const voiceId = serverState.config.defaultVoiceId;
|
|
238
284
|
const voiceSettings = DEFAULT_PROSODY;
|
|
239
285
|
const volume = 1.0;
|
|
@@ -316,11 +362,21 @@ async function parseJsonBody<T>(req: Request): Promise<T> {
|
|
|
316
362
|
export async function startServer(config: Partial<ServerConfig> = {}): Promise<void> {
|
|
317
363
|
// Initialize server state
|
|
318
364
|
const finalConfig = { ...DEFAULT_CONFIG, ...config };
|
|
365
|
+
|
|
366
|
+
// Create notification queue
|
|
367
|
+
const ttsProcessor: TTSProcessor = processTTSWithMacOSNotification;
|
|
368
|
+
const notificationQueue = new NotificationQueue(ttsProcessor, {
|
|
369
|
+
maxDepth: finalConfig.queueMaxDepth,
|
|
370
|
+
drainTimeoutMs: finalConfig.queueDrainTimeoutMs,
|
|
371
|
+
degradedThreshold: finalConfig.queueDegradedThreshold,
|
|
372
|
+
});
|
|
373
|
+
|
|
319
374
|
serverState = {
|
|
320
375
|
healthStatus: createDefaultHealthStatus(),
|
|
321
376
|
config: finalConfig,
|
|
322
377
|
cors: getCORSMiddleware(),
|
|
323
378
|
rateLimiter: getRateLimiter(),
|
|
379
|
+
notificationQueue,
|
|
324
380
|
};
|
|
325
381
|
|
|
326
382
|
const { port, host } = finalConfig;
|
|
@@ -330,6 +386,11 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
|
|
|
330
386
|
logger.info(`TTS Backend: MLX-audio`, {
|
|
331
387
|
model: finalConfig.mlxConfig.model,
|
|
332
388
|
});
|
|
389
|
+
logger.info(`Notification Queue: enabled`, {
|
|
390
|
+
maxDepth: finalConfig.queueMaxDepth,
|
|
391
|
+
drainTimeoutMs: finalConfig.queueDrainTimeoutMs,
|
|
392
|
+
degradedThreshold: finalConfig.queueDegradedThreshold,
|
|
393
|
+
});
|
|
333
394
|
|
|
334
395
|
// Initialize MLX-audio client
|
|
335
396
|
try {
|
|
@@ -400,6 +461,11 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
|
|
|
400
461
|
if (path === "/notify" && req.method === "POST") {
|
|
401
462
|
const body = await parseJsonBody<NotificationRequest>(req);
|
|
402
463
|
responseData = await handleNotify(body);
|
|
464
|
+
|
|
465
|
+
// Return 201 for successful queue operations
|
|
466
|
+
const statusCode = (responseData as SuccessResponse).status === "success" ? 201 : 400;
|
|
467
|
+
const response = Response.json(responseData, { status: statusCode });
|
|
468
|
+
return serverState.cors.addCorsHeaders(response, origin);
|
|
403
469
|
}
|
|
404
470
|
// POST /pai
|
|
405
471
|
else if (path === "/pai" && req.method === "POST") {
|
|
@@ -410,6 +476,10 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
|
|
|
410
476
|
else if (path === "/health" && req.method === "GET") {
|
|
411
477
|
responseData = await handleHealth();
|
|
412
478
|
}
|
|
479
|
+
// GET /queue/status
|
|
480
|
+
else if (path === "/queue/status" && req.method === "GET") {
|
|
481
|
+
responseData = await handleQueueStatus();
|
|
482
|
+
}
|
|
413
483
|
// 404 Not Found
|
|
414
484
|
else {
|
|
415
485
|
return Response.json(
|
|
@@ -439,6 +509,15 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
|
|
|
439
509
|
const shutdown = async () => {
|
|
440
510
|
logger.info("Shutting down server...");
|
|
441
511
|
|
|
512
|
+
// Drain notification queue
|
|
513
|
+
logger.info("Draining notification queue...");
|
|
514
|
+
const drainResult = await serverState.notificationQueue.drain();
|
|
515
|
+
logger.info("Queue drain complete", {
|
|
516
|
+
itemsProcessed: drainResult.itemsProcessed,
|
|
517
|
+
itemsFailed: drainResult.itemsFailed,
|
|
518
|
+
timedOut: drainResult.timedOut,
|
|
519
|
+
});
|
|
520
|
+
|
|
442
521
|
// Stop rate limiter
|
|
443
522
|
serverState.rateLimiter.stop();
|
|
444
523
|
|