@madeinoz67/voice-server 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,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 - use default title if not provided
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
- // Determine voice settings
199
- const voiceId = request.voice_id || request.voice_name || serverState.config.defaultVoiceId;
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
- // Process TTS if enabled
209
- if (request.voice_enabled !== false) {
210
- await processTTS(message, voiceId, voiceSettings, volume);
238
+ if (!result.success) {
239
+ return errorResponse(result.message);
211
240
  }
212
241
 
213
- return successResponse();
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
- // Use default DA voice settings
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