@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.
@@ -0,0 +1,382 @@
1
+ /**
2
+ * Notification Queue Service
3
+ * FIFO queue for processing voice notifications sequentially
4
+ */
5
+
6
+ import type {
7
+ QueuedNotification,
8
+ QueueState,
9
+ QueueConfig,
10
+ QueueHealth,
11
+ QueueProcessingStatus,
12
+ EnqueueResult,
13
+ DrainResult,
14
+ QueueMetrics,
15
+ } from "@/models/queue.js";
16
+ import type { NotificationRequest } from "@/models/notification.js";
17
+ import { isValidNotificationRequest } from "@/models/notification.js";
18
+ import { getVoiceLoader } from "@/services/voice-loader.js";
19
+ import { logger } from "@/utils/logger.js";
20
+ import { createDefaultQueueConfig } from "@/models/queue.js";
21
+
22
+ /**
23
+ * TTS processor function type
24
+ * Processes a notification request by synthesizing and playing audio
25
+ */
26
+ export type TTSProcessor = (request: NotificationRequest) => Promise<void>;
27
+
28
+ /**
29
+ * Notification Queue Service
30
+ * Manages FIFO queue of notifications with single worker processing
31
+ */
32
+ export class NotificationQueue {
33
+ private queue: QueuedNotification[] = [];
34
+ private processingStatus: QueueProcessingStatus = "idle";
35
+ private isProcessing = false;
36
+ private metrics: QueueMetrics = {
37
+ itemsProcessed: 0,
38
+ itemsFailed: 0,
39
+ averageProcessingTimeMs: 0,
40
+ };
41
+ private processingTimes: number[] = [];
42
+ private ttsHealth: QueueHealth = "healthy";
43
+ private config: QueueConfig;
44
+ private ttsProcessor: TTSProcessor;
45
+
46
+ constructor(ttsProcessor: TTSProcessor, config?: Partial<QueueConfig>) {
47
+ this.ttsProcessor = ttsProcessor;
48
+ this.config = { ...createDefaultQueueConfig(), ...config };
49
+ logger.info("NotificationQueue initialized", {
50
+ maxDepth: this.config.maxDepth,
51
+ degradedThreshold: this.config.degradedThreshold,
52
+ });
53
+ }
54
+
55
+ /**
56
+ * Enqueue a notification request
57
+ * Returns immediately with 201 Accepted if successful
58
+ */
59
+ async enqueue(request: NotificationRequest): Promise<EnqueueResult> {
60
+ // Reject if draining or stopped
61
+ if (this.processingStatus === "draining" || this.processingStatus === "stopped") {
62
+ return {
63
+ success: false,
64
+ statusCode: 503,
65
+ message: `Queue is ${this.processingStatus}, not accepting new items`,
66
+ };
67
+ }
68
+
69
+ // Validate request before queuing
70
+ if (!isValidNotificationRequest(request)) {
71
+ return {
72
+ success: false,
73
+ statusCode: 400,
74
+ message: "Invalid notification request: missing required fields or invalid data",
75
+ };
76
+ }
77
+
78
+ // Validate voice_id
79
+ const voiceLoader = getVoiceLoader();
80
+ try {
81
+ const voiceInfo = voiceLoader.getVoiceInfo(request.voice_id || request.voice_name || "");
82
+ if (!voiceInfo) {
83
+ // Check if it's a known voice ID from the voice loader
84
+ const availableVoices = await voiceLoader.getAvailableVoices();
85
+ const voiceId = request.voice_id || request.voice_name || "";
86
+ if (!availableVoices.includes(voiceId) && voiceId !== "marrvin" && voiceId !== "marlin" && voiceId !== "daniel") {
87
+ return {
88
+ success: false,
89
+ statusCode: 400,
90
+ message: `Invalid voice_id: ${voiceId}. Available voices: ${availableVoices.join(", ")}`,
91
+ };
92
+ }
93
+ }
94
+ } catch (error) {
95
+ logger.warn("Voice validation failed, proceeding with default voice", {
96
+ error: (error as Error).message,
97
+ });
98
+ }
99
+
100
+ // Check queue depth
101
+ if (this.queue.length >= this.config.maxDepth) {
102
+ logger.warn("Queue is full, rejecting request", {
103
+ depth: this.queue.length,
104
+ maxDepth: this.config.maxDepth,
105
+ });
106
+ return {
107
+ success: false,
108
+ statusCode: 429,
109
+ message: `Queue is full (${this.queue.length}/${this.config.maxDepth} items)`,
110
+ };
111
+ }
112
+
113
+ // Create queued item
114
+ const item: QueuedNotification = {
115
+ id: this.generateId(),
116
+ request: { ...request },
117
+ status: "pending",
118
+ arrivedAt: new Date(),
119
+ };
120
+
121
+ this.queue.push(item);
122
+ logger.info("Notification queued", {
123
+ id: item.id,
124
+ position: this.queue.length - 1,
125
+ depth: this.queue.length,
126
+ });
127
+
128
+ // Start processing if not already running
129
+ this.processQueue().catch((error) => {
130
+ logger.error("Error in queue processor", error);
131
+ });
132
+
133
+ return {
134
+ success: true,
135
+ statusCode: 201,
136
+ message: "Notification accepted and queued",
137
+ queuePosition: this.queue.length - 1,
138
+ itemId: item.id,
139
+ };
140
+ }
141
+
142
+ /**
143
+ * Get current queue state
144
+ */
145
+ getQueueState(): QueueState {
146
+ const health = this.calculateHealth();
147
+ return {
148
+ depth: this.queue.length,
149
+ processingStatus: this.processingStatus,
150
+ health,
151
+ metrics: { ...this.metrics },
152
+ };
153
+ }
154
+
155
+ /**
156
+ * Drain the queue (process all remaining items)
157
+ * Called during graceful shutdown
158
+ */
159
+ async drain(): Promise<DrainResult> {
160
+ if (this.processingStatus === "draining") {
161
+ // Already draining
162
+ return await this.waitForDrain();
163
+ }
164
+
165
+ logger.info("Starting queue drain", {
166
+ itemsRemaining: this.queue.length,
167
+ timeoutMs: this.config.drainTimeoutMs,
168
+ });
169
+
170
+ this.processingStatus = "draining";
171
+
172
+ try {
173
+ // Wait for queue to empty or timeout
174
+ const result = await this.waitForDrain();
175
+
176
+ if (result.timedOut) {
177
+ logger.warn("Queue drain timed out", {
178
+ remainingItems: result.remainingItems,
179
+ });
180
+ } else {
181
+ logger.info("Queue drain complete", {
182
+ itemsProcessed: result.itemsProcessed,
183
+ itemsFailed: result.itemsFailed,
184
+ });
185
+ }
186
+
187
+ return result;
188
+ } finally {
189
+ this.processingStatus = "stopped";
190
+ this.stop();
191
+ }
192
+ }
193
+
194
+ /**
195
+ * Stop the queue (for testing or shutdown)
196
+ */
197
+ stop(): void {
198
+ this.processingStatus = "stopped";
199
+ this.isProcessing = false;
200
+ logger.debug("NotificationQueue stopped");
201
+ }
202
+
203
+ /**
204
+ * Process queue items sequentially
205
+ */
206
+ private async processQueue(): Promise<void> {
207
+ // Prevent concurrent processing
208
+ if (this.isProcessing) {
209
+ return;
210
+ }
211
+
212
+ // Check if we should be processing
213
+ if (this.processingStatus === "draining" && this.queue.length === 0) {
214
+ return;
215
+ }
216
+
217
+ this.isProcessing = true;
218
+
219
+ try {
220
+ while (this.queue.length > 0 && this.processingStatus !== "stopped") {
221
+ const item = this.queue[0];
222
+
223
+ // Skip already processed items
224
+ if (item.status !== "pending") {
225
+ this.queue.shift();
226
+ continue;
227
+ }
228
+
229
+ // Update status
230
+ this.processingStatus = "active";
231
+ item.status = "processing";
232
+ item.processingStartedAt = new Date();
233
+
234
+ logger.info("Processing queued notification", {
235
+ id: item.id,
236
+ position: 0,
237
+ });
238
+
239
+ const startTime = Date.now();
240
+
241
+ try {
242
+ // Process TTS
243
+ await this.ttsProcessor(item.request);
244
+
245
+ // Mark as completed
246
+ item.status = "completed";
247
+ item.completedAt = new Date();
248
+
249
+ const processingTime = Date.now() - startTime;
250
+ this.recordProcessingTime(processingTime);
251
+ this.metrics.itemsProcessed++;
252
+
253
+ logger.info("Notification processed successfully", {
254
+ id: item.id,
255
+ processingTimeMs: processingTime,
256
+ });
257
+
258
+ // Update TTS health
259
+ this.ttsHealth = "healthy";
260
+
261
+ } catch (error) {
262
+ // Mark as failed but continue processing
263
+ item.status = "failed";
264
+ item.completedAt = new Date();
265
+ item.error = (error as Error).message;
266
+
267
+ this.metrics.itemsFailed++;
268
+
269
+ logger.warn("Notification processing failed, skipping to next item", {
270
+ id: item.id,
271
+ error: (error as Error).message,
272
+ });
273
+
274
+ // Update TTS health if failing
275
+ this.ttsHealth = "unavailable";
276
+ }
277
+
278
+ // Remove from queue
279
+ this.queue.shift();
280
+ }
281
+
282
+ // Reset status when queue is empty
283
+ if (this.queue.length === 0) {
284
+ this.processingStatus = this.processingStatus === "draining" ? "draining" : "idle";
285
+ }
286
+ } finally {
287
+ this.isProcessing = false;
288
+ }
289
+ }
290
+
291
+ /**
292
+ * Wait for queue to drain (process all items)
293
+ */
294
+ private async waitForDrain(): Promise<DrainResult> {
295
+ const startTime = Date.now();
296
+ const initialProcessed = this.metrics.itemsProcessed;
297
+ const initialFailed = this.metrics.itemsFailed;
298
+
299
+ return new Promise<DrainResult>((resolve) => {
300
+ const checkInterval = setInterval(() => {
301
+ const elapsed = Date.now() - startTime;
302
+
303
+ if (this.queue.length === 0 || this.processingStatus === "stopped") {
304
+ clearInterval(checkInterval);
305
+ resolve({
306
+ success: true,
307
+ itemsProcessed: this.metrics.itemsProcessed - initialProcessed,
308
+ itemsFailed: this.metrics.itemsFailed - initialFailed,
309
+ timedOut: false,
310
+ });
311
+ return;
312
+ }
313
+
314
+ if (elapsed >= this.config.drainTimeoutMs) {
315
+ clearInterval(checkInterval);
316
+ resolve({
317
+ success: false,
318
+ itemsProcessed: this.metrics.itemsProcessed - initialProcessed,
319
+ itemsFailed: this.metrics.itemsFailed - initialFailed,
320
+ timedOut: true,
321
+ remainingItems: this.queue.length,
322
+ });
323
+ return;
324
+ }
325
+ }, 50);
326
+ });
327
+ }
328
+
329
+ /**
330
+ * Calculate health indicator based on queue state and TTS status
331
+ */
332
+ private calculateHealth(): QueueHealth {
333
+ // If TTS has been failing, report unavailable
334
+ if (this.ttsHealth === "unavailable") {
335
+ // Check if we've had recent successes
336
+ const recentFailures = this.metrics.itemsFailed > 0;
337
+ if (recentFailures && this.metrics.itemsProcessed === 0) {
338
+ return "unavailable";
339
+ }
340
+ }
341
+
342
+ // Check if queue depth exceeds degraded threshold
343
+ if (this.queue.length >= this.config.degradedThreshold) {
344
+ return "degraded";
345
+ }
346
+
347
+ return "healthy";
348
+ }
349
+
350
+ /**
351
+ * Record processing time for metrics
352
+ */
353
+ private recordProcessingTime(timeMs: number): void {
354
+ this.processingTimes.push(timeMs);
355
+
356
+ // Keep only last 100 measurements
357
+ if (this.processingTimes.length > 100) {
358
+ this.processingTimes.shift();
359
+ }
360
+
361
+ // Calculate average
362
+ const sum = this.processingTimes.reduce((a, b) => a + b, 0);
363
+ this.metrics.averageProcessingTimeMs = Math.round(sum / this.processingTimes.length);
364
+ }
365
+
366
+ /**
367
+ * Generate unique ID for queued item
368
+ */
369
+ private generateId(): string {
370
+ return `queue_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
371
+ }
372
+ }
373
+
374
+ /**
375
+ * Create a notification queue with default TTS processor
376
+ */
377
+ export function createNotificationQueue(
378
+ ttsProcessor: TTSProcessor,
379
+ config?: Partial<QueueConfig>
380
+ ): NotificationQueue {
381
+ return new NotificationQueue(ttsProcessor, config);
382
+ }
@@ -0,0 +1,298 @@
1
+ /**
2
+ * Integration tests for FIFO Notification Queue API
3
+ *
4
+ * Note: These tests require MLX-audio to be installed.
5
+ * They will be skipped if MLX-audio is not available.
6
+ */
7
+
8
+ import { describe, test, expect, beforeAll, afterAll } from "bun:test";
9
+
10
+ // Test server configuration
11
+ const SERVER_HOST = "127.0.0.1";
12
+ const SERVER_PORT = 8899; // Use different port for tests
13
+ const SERVER_URL = `http://${SERVER_HOST}:${SERVER_PORT}`;
14
+
15
+ let serverProcess: ReturnType<typeof Bun.spawn> | null = null;
16
+
17
+ // Check if MLX-audio is available
18
+ async function checkMLXAudio(): Promise<boolean> {
19
+ try {
20
+ const proc = Bun.spawn(["which", "mlx_tts"], {
21
+ stdout: "pipe",
22
+ stderr: "pipe",
23
+ });
24
+ await proc.exited;
25
+ return proc.exitCode === 0;
26
+ } catch {
27
+ return false;
28
+ }
29
+ }
30
+
31
+ const hasMLXAudio = await checkMLXAudio();
32
+
33
+ describe.skipIf(!hasMLXAudio)("Queue API Integration Tests (skipped - MLX-audio not available)", () => {
34
+ beforeAll(async () => {
35
+ // Start test server
36
+ serverProcess = Bun.spawn(["bun", "run", "src/ts/server.ts"], {
37
+ env: {
38
+ ...process.env,
39
+ PORT: SERVER_PORT.toString(),
40
+ NODE_ENV: "test",
41
+ ENABLE_MACOS_NOTIFICATIONS: "false", // Disable macOS notifications in tests
42
+ },
43
+ stdout: "pipe",
44
+ stderr: "pipe",
45
+ });
46
+
47
+ // Wait for server to be ready
48
+ let retries = 50;
49
+ while (retries > 0) {
50
+ try {
51
+ const response = await fetch(`${SERVER_URL}/health`);
52
+ if (response.ok) {
53
+ break;
54
+ }
55
+ } catch {
56
+ // Server not ready yet
57
+ }
58
+ await new Promise((resolve) => setTimeout(resolve, 100));
59
+ retries--;
60
+ }
61
+
62
+ if (retries === 0) {
63
+ throw new Error("Server failed to start");
64
+ }
65
+ }, 10000);
66
+
67
+ afterAll(() => {
68
+ if (serverProcess) {
69
+ serverProcess.kill();
70
+ }
71
+ });
72
+
73
+ describe("POST /notify", () => {
74
+ test("should return 201 Accepted for valid notification", async () => {
75
+ const response = await fetch(`${SERVER_URL}/notify`, {
76
+ method: "POST",
77
+ headers: { "Content-Type": "application/json" },
78
+ body: JSON.stringify({
79
+ message: "Test notification",
80
+ voice_id: "marrvin",
81
+ }),
82
+ });
83
+
84
+ expect(response.status).toBe(201);
85
+ const data = await response.json();
86
+ expect(data.status).toBe("success");
87
+ expect(data.message).toContain("accepted");
88
+ });
89
+
90
+ test("should return 400 Bad Request for missing message", async () => {
91
+ const response = await fetch(`${SERVER_URL}/notify`, {
92
+ method: "POST",
93
+ headers: { "Content-Type": "application/json" },
94
+ body: JSON.stringify({ voice_id: "marrvin" }),
95
+ });
96
+
97
+ expect(response.status).toBe(400);
98
+ const data = await response.json();
99
+ expect(data.status).toBe("error");
100
+ });
101
+
102
+ test("should return 400 Bad Request for invalid JSON", async () => {
103
+ const response = await fetch(`${SERVER_URL}/notify`, {
104
+ method: "POST",
105
+ headers: { "Content-Type": "application/json" },
106
+ body: "invalid json",
107
+ });
108
+
109
+ expect(response.status).toBe(400);
110
+ });
111
+
112
+ test("should return 201 for notification with title", async () => {
113
+ const response = await fetch(`${SERVER_URL}/notify`, {
114
+ method: "POST",
115
+ headers: { "Content-Type": "application/json" },
116
+ body: JSON.stringify({
117
+ title: "Test Title",
118
+ message: "Test notification with title",
119
+ voice_id: "marrvin",
120
+ }),
121
+ });
122
+
123
+ expect(response.status).toBe(201);
124
+ const data = await response.json();
125
+ expect(data.status).toBe("success");
126
+ });
127
+
128
+ test("should process multiple requests sequentially", async () => {
129
+ // Send multiple requests rapidly
130
+ const requests = [];
131
+ for (let i = 0; i < 5; i++) {
132
+ requests.push(
133
+ fetch(`${SERVER_URL}/notify`, {
134
+ method: "POST",
135
+ headers: { "Content-Type": "application/json" },
136
+ body: JSON.stringify({
137
+ message: `Sequential test ${i}`,
138
+ voice_id: "marrvin",
139
+ }),
140
+ })
141
+ );
142
+ }
143
+
144
+ const responses = await Promise.all(requests);
145
+
146
+ // All should return 201 Accepted
147
+ for (const response of responses) {
148
+ expect(response.status).toBe(201);
149
+ const data = await response.json();
150
+ expect(data.status).toBe("success");
151
+ }
152
+
153
+ // Wait for queue to process (with voice_enabled=false for speed)
154
+ await new Promise((resolve) => setTimeout(resolve, 500));
155
+ });
156
+ });
157
+
158
+ describe("GET /queue/status", () => {
159
+ test("should return queue status", async () => {
160
+ const response = await fetch(`${SERVER_URL}/queue/status`);
161
+
162
+ expect(response.status).toBe(200);
163
+ const data = await response.json();
164
+ expect(data.status).toBe("success");
165
+ expect(data.depth).toBeGreaterThanOrEqual(0);
166
+ expect(data.processingStatus).toMatch(/^(idle|active|draining)$/);
167
+ expect(data.health).toMatch(/^(healthy|degraded|unavailable)$/);
168
+ });
169
+
170
+ test("should include metrics in status", async () => {
171
+ const response = await fetch(`${SERVER_URL}/queue/status`);
172
+
173
+ expect(response.status).toBe(200);
174
+ const data = await response.json();
175
+ expect(data.metrics).toBeDefined();
176
+ expect(data.metrics.itemsProcessed).toBeGreaterThanOrEqual(0);
177
+ expect(data.metrics.itemsFailed).toBeGreaterThanOrEqual(0);
178
+ });
179
+
180
+ test("should reflect queue state after enqueue", async () => {
181
+ // Send a notification
182
+ await fetch(`${SERVER_URL}/notify`, {
183
+ method: "POST",
184
+ headers: { "Content-Type": "application/json" },
185
+ body: JSON.stringify({
186
+ message: "Status check test",
187
+ voice_id: "marrvin",
188
+ voice_enabled: false, // Skip TTS for faster test
189
+ }),
190
+ });
191
+
192
+ // Check status
193
+ const response = await fetch(`${SERVER_URL}/queue/status`);
194
+ expect(response.status).toBe(200);
195
+ const data = await response.json();
196
+ expect(data.status).toBe("success");
197
+ // Queue might be empty or processing depending on timing
198
+ expect(data.depth).toBeGreaterThanOrEqual(0);
199
+ });
200
+ });
201
+
202
+ describe("Queue Health Indicators", () => {
203
+ test("should show healthy when queue is empty", async () => {
204
+ // Wait for any pending items to process
205
+ await new Promise((resolve) => setTimeout(resolve, 500));
206
+
207
+ const response = await fetch(`${SERVER_URL}/queue/status`);
208
+ const data = await response.json();
209
+
210
+ expect(data.health).toBe("healthy");
211
+ });
212
+
213
+ test("should show degraded when queue has many items", async () => {
214
+ // This test would require filling the queue beyond degradedThreshold
215
+ // For now, we just verify the endpoint works
216
+ const response = await fetch(`${SERVER_URL}/queue/status`);
217
+ expect(response.status).toBe(200);
218
+ });
219
+ });
220
+
221
+ describe("CORS", () => {
222
+ test("should include CORS headers for /notify", async () => {
223
+ const response = await fetch(`${SERVER_URL}/notify`, {
224
+ method: "POST",
225
+ headers: {
226
+ Origin: "http://localhost:3000",
227
+ "Content-Type": "application/json",
228
+ },
229
+ body: JSON.stringify({
230
+ message: "CORS test",
231
+ voice_id: "marrvin",
232
+ voice_enabled: false,
233
+ }),
234
+ });
235
+
236
+ expect(response.headers.get("Access-Control-Allow-Origin")).toBeDefined();
237
+ });
238
+
239
+ test("should include CORS headers for /queue/status", async () => {
240
+ const response = await fetch(`${SERVER_URL}/queue/status`, {
241
+ headers: { Origin: "http://localhost:3000" },
242
+ });
243
+
244
+ expect(response.headers.get("Access-Control-Allow-Origin")).toBeDefined();
245
+ });
246
+
247
+ test("should handle OPTIONS preflight for /notify", async () => {
248
+ const response = await fetch(`${SERVER_URL}/notify`, {
249
+ method: "OPTIONS",
250
+ headers: {
251
+ Origin: "http://localhost:3000",
252
+ "Access-Control-Request-Method": "POST",
253
+ },
254
+ });
255
+
256
+ expect(response.status).toBe(204);
257
+ });
258
+ });
259
+
260
+ describe("Response Time", () => {
261
+ test("should return 201 within 100ms", async () => {
262
+ const start = Date.now();
263
+
264
+ const response = await fetch(`${SERVER_URL}/notify`, {
265
+ method: "POST",
266
+ headers: { "Content-Type": "application/json" },
267
+ body: JSON.stringify({
268
+ message: "Response time test",
269
+ voice_id: "marrvin",
270
+ voice_enabled: false,
271
+ }),
272
+ });
273
+
274
+ const elapsed = Date.now() - start;
275
+
276
+ expect(response.status).toBe(201);
277
+ expect(elapsed).toBeLessThan(100);
278
+ });
279
+
280
+ test("should return /queue/status within 50ms", async () => {
281
+ const start = Date.now();
282
+
283
+ const response = await fetch(`${SERVER_URL}/queue/status`);
284
+
285
+ const elapsed = Date.now() - start;
286
+
287
+ expect(response.status).toBe(200);
288
+ expect(elapsed).toBeLessThan(50);
289
+ });
290
+ });
291
+ });
292
+
293
+ // If MLX-audio is not available, add a placeholder test
294
+ describe.if(hasMLXAudio)("Integration tests", () => {
295
+ test("placeholder - MLX-audio is available", () => {
296
+ expect(true).toBe(true);
297
+ });
298
+ });