@ssml-builder-js/azure-tts-client 2.17.0 → 2.19.0

package/src/safe.ts

@@ -13,7 +13,7 @@ import {
   getRetryAfterDelayMs,
 } from "./errors.ts";
 import type { AzureTtsClient } from "./client.ts";
-import { mergeSynthesisResults } from "./synthesis.ts";
+import { computeChunkFingerprint, mergeSynthesisResults } from "./synthesis.ts";
 import type {
   SsmlSynthesisChunk,
   SsmlSynthesisResult,
@@ -25,8 +25,12 @@ import type {
   PartialChunkSynthesisResult,
   CustomAudioMerger,
   PostMergeValidator,
+  ChunkExecutionState,
+  ResumeValidationMode,
 } from "./types.ts";
 import type { AzureTtsOutputFormat } from "./outputFormats.ts";
+import { IncompleteChunkSetError, serializeChunkError } from "./errors.ts";
+import { DeadlineController } from "./deadline.ts";
 
 export interface SsmlValidationError {
   readonly kind: "validation-error";
@@ -127,6 +131,8 @@ export interface SynthesizeSsmlSafeOptions extends AzureValidationOptions {
 export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions {
   validation?: AzureValidationOptions;
   outputFormat?: string;
+  customHeaders?: Readonly<Record<string, string>>;
+  fingerprintSchemaVersion?: string;
   signal?: AbortSignal;
   timeoutMs?: number;
   timeouts?: SynthesisTimeouts;
@@ -140,6 +146,7 @@ export interface SynthesizeSsmlChunksSafeOptions extends AzureValidationOptions
   customMerger?: CustomAudioMerger;
   outputMimeType?: string;
   postMergeValidator?: PostMergeValidator;
+  resumeValidation?: ResumeValidationMode;
 }
 
 export type SsmlSynthesisChunksSafeResult =
@@ -225,6 +232,7 @@ async function retryableSynthesis(
   options: RetryOptions | undefined,
   signal: AbortSignal | undefined,
   onRetry: (attempt: number, delayMs: number) => void,
+  deadlineAtMs?: number,
 ): Promise<SsmlSynthesisResult> {
   const retry = options
     ? {
@@ -244,6 +252,14 @@ async function retryableSynthesis(
         throw error;
       attempt += 1;
       const delayMs = retryDelayForError(retry, attempt, error);
+      const retryAfterMs = getRetryAfterDelayMs(error);
+      const remainingMs = deadlineAtMs === undefined ? undefined : Math.max(0, deadlineAtMs - Date.now());
+      if (
+        retryAfterMs !== undefined &&
+        (retryAfterMs > retry.maxDelayMs || (remainingMs !== undefined && retryAfterMs > remainingMs))
+      ) {
+        throw new Error("Speech synthesis timed out because Retry-After exceeded the available retry budget.");
+      }
       onRetry(attempt, delayMs);
       if (delayMs > 0)
         await new Promise<void>((resolve, reject) => {
@@ -291,14 +307,19 @@ export async function synthesizeSsmlSafe(
   ssml: string,
   options: SynthesizeSsmlSafeOptions = {},
 ): Promise<SsmlSynthesisSafeResult> {
-  const validationOptions = sharedValidationOptions(options.validation ?? options, options.signal);
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
+  const validationOptions = sharedValidationOptions(options.validation ?? options, deadline.signal);
   const diagnostics = await Promise.resolve(validateAzureSsml(ssml, validationOptions));
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled."),
+    );
+    deadline.dispose();
     return failure(error);
   }
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
   if (errors.length > 0) {
+    deadline.dispose();
     return failure({
       kind: "validation-error",
       message: "SSML validation failed; the Azure Speech API was not called.",
@@ -312,14 +333,17 @@ export async function synthesizeSsmlSafe(
       success: true,
       status: "success",
       value: await client.synthesizeSsml(ssml, {
-        signal: options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeouts?.perChunkMs,
-        timeouts: options.timeouts,
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: undefined } : undefined,
       }),
     };
   } catch (error) {
+    if (deadline.timedOut) return failure(toSynthesisError(new Error("Speech synthesis timed out.")));
     const synthesisError = toSynthesisError(error);
     return failure(synthesisError);
+  } finally {
+    deadline.dispose();
   }
 }
 
@@ -329,12 +353,16 @@ export async function synthesizeSsmlChunksSafe(
   chunks: readonly (SsmlSynthesisChunk | string)[],
   options: SynthesizeSsmlChunksSafeOptions = {},
 ): Promise<SsmlSynthesisChunksSafeResult> {
+  const deadline = new DeadlineController(options.timeouts?.totalJobMs, options.signal);
   const validationOptions = sharedValidationOptions(
     { ...(options.validation ?? options), timeouts: options.timeouts },
-    options.signal,
+    deadline.signal,
   );
-  if (options.signal?.aborted) {
-    const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+  if (deadline.signal.aborted) {
+    const error = toSynthesisError(
+      new Error(deadline.timedOut ? "Speech synthesis timed out." : "Speech synthesis was cancelled."),
+    );
+    deadline.dispose();
     return failure(error);
   }
   const pending = (index: number, status: SynthesisProgressEvent["status"], error?: unknown): void => {
@@ -368,8 +396,9 @@ export async function synthesizeSsmlChunksSafe(
       return diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     }),
   );
-  if (options.signal?.aborted) {
+  if (deadline.signal.aborted) {
     const error = toSynthesisError(new Error("Speech synthesis was cancelled."));
+    deadline.dispose();
     return failure(error);
   }
   const chunkDiagnostics = validations
@@ -378,6 +407,7 @@ export async function synthesizeSsmlChunksSafe(
   if (chunkDiagnostics.length > 0) {
     const error = new BatchChunkValidationError(chunkDiagnostics);
     for (const entry of chunkDiagnostics) pending(entry.chunkIndex, "failed", error);
+    deadline.dispose();
     return failure(error);
   }
 
@@ -391,9 +421,9 @@ export async function synthesizeSsmlChunksSafe(
       const value = await client.synthesizeChunks(normalizedChunks, {
         onProgress: options.onProgress,
         outputFormat: options.outputFormat,
-        signal: options.signal,
+        signal: deadline.signal,
         timeoutMs: options.timeoutMs,
-        timeouts: options.timeouts,
+        timeouts: options.timeouts ? { ...options.timeouts, totalJobMs: undefined } : undefined,
         sourceNodePath: options.sourceNodePath,
         concurrency: options.concurrency,
         retryOptions: options.retryOptions,
@@ -403,22 +433,44 @@ export async function synthesizeSsmlChunksSafe(
         customMerger: options.customMerger,
         outputMimeType: options.outputMimeType,
         postMergeValidator: options.postMergeValidator,
+        resumeValidation: options.resumeValidation,
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion,
       });
       return { ok: true, success: true, status: "success", value };
     }
+    const inputs = chunks.map((chunk) => (typeof chunk === "string" ? { ssml: chunk } : chunk));
+    const fingerprints = inputs.map((chunk) =>
+      computeChunkFingerprint(chunk.ssml, options.outputFormat, {
+        customHeaders: options.customHeaders,
+        fingerprintSchemaVersion: options.fingerprintSchemaVersion,
+      }),
+    );
     const results: Array<SsmlSynthesisResult | undefined> = new Array(chunks.length);
+    const chunkStates: ChunkExecutionState[] = inputs.map((_chunk, chunkIndex) => ({
+      chunkIndex,
+      status: "pending",
+      canResume: true,
+    }));
     const cachedChunks = new Map((options.resumeChunks ?? []).map((chunk) => [chunk.chunkIndex, chunk]));
+    const invalidCachedIndices = new Set<number>();
     for (const [index, cached] of cachedChunks) {
-      if (index >= 0 && index < chunks.length) results[index] = cached;
+      if (index < 0 || index >= chunks.length) continue;
+      if (options.resumeValidation === "disabled" || cached.fingerprint === fingerprints[index]) {
+        results[index] = cached;
+        chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result: cached };
+      } else invalidCachedIndices.add(index);
     }
     const requestedIndices = options.resumeChunkIndices
       ? new Set(options.resumeChunkIndices.filter((index) => index >= 0 && index < chunks.length))
       : undefined;
     const shouldSynthesize = (index: number): boolean =>
-      !cachedChunks.has(index) && (requestedIndices === undefined || requestedIndices.has(index));
+      (!cachedChunks.has(index) || invalidCachedIndices.has(index)) &&
+      (requestedIndices === undefined || requestedIndices.has(index) || invalidCachedIndices.has(index));
+    const jobDeadlineAt = deadline.deadlineAtMs;
     const jobScope =
       chunks.length > 1 || options.timeouts?.totalJobMs !== undefined
-        ? createSafeAbortScope(options.signal, options.timeouts?.totalJobMs)
+        ? createSafeAbortScope(deadline.signal, undefined)
         : undefined;
     fallbackJobScope = jobScope;
     const failedIndices = new Set<number>();
@@ -431,7 +483,10 @@ export async function synthesizeSsmlChunksSafe(
         const index = nextIndex++;
         if (index >= chunks.length) return;
         if (!shouldSynthesize(index)) continue;
-        if (failedIndices.size > 0 && options.cancelOnFailure !== false) return;
+        if (firstError && options.cancelOnFailure !== false) {
+          chunkStates[index] = { chunkIndex: index, status: "cancelled", isOriginalFailure: false, canResume: true };
+          return;
+        }
         const chunk = chunks[index];
         const input = typeof chunk === "string" ? { ssml: chunk } : chunk;
         const sourceNodePath = input.sourceNodePath;
@@ -442,9 +497,9 @@ export async function synthesizeSsmlChunksSafe(
           const chunkTimeout = options.timeouts?.chunkWithRetriesMs ?? options.timeouts?.perChunkMs;
           const chunkScope =
             chunkTimeout !== undefined || jobScope
-              ? createSafeAbortScope(jobScope?.signal ?? options.signal, chunkTimeout ?? options.timeoutMs)
+              ? createSafeAbortScope(jobScope?.signal ?? deadline.signal, chunkTimeout ?? options.timeoutMs)
               : undefined;
-          const chunkSignal = chunkScope?.signal ?? options.signal;
+          const chunkSignal = chunkScope?.signal ?? deadline.signal;
           let result: SsmlSynthesisResult;
           try {
             result = await retryableSynthesis(
@@ -470,9 +525,10 @@ export async function synthesizeSsmlChunksSafe(
                   nextRetryDelayMs,
                   isRetrying: true,
                 }),
+              jobDeadlineAt,
             );
           } catch (error) {
-            if (chunkScope?.timedOut())
+            if (chunkScope?.timedOut() || deadline.timedOut)
               throw new Error(`Speech synthesis timed out after ${chunkTimeout ?? options.timeoutMs} ms.`);
             throw error;
           } finally {
@@ -547,6 +603,7 @@ export async function synthesizeSsmlChunksSafe(
                 }
               : {}),
           };
+          chunkStates[index] = { chunkIndex: index, status: "succeeded", canResume: true, result: results[index] };
           completed += 1;
           options.onProgress?.({
             currentChunk: completed,
@@ -558,7 +615,18 @@ export async function synthesizeSsmlChunksSafe(
             durationMs: Date.now() - startedAt,
           });
         } catch (error) {
-          failedIndices.add(index);
+          const wasCancelled =
+            firstError !== undefined ||
+            (!deadline.timedOut && Boolean(jobScope?.signal.aborted && !jobScope?.timedOut()));
+          firstError ??= deadline.timedOut ? new Error("Speech synthesis timed out.") : error;
+          if (!wasCancelled) failedIndices.add(index);
+          chunkStates[index] = {
+            chunkIndex: index,
+            status: wasCancelled ? "cancelled" : "failed",
+            isOriginalFailure: !wasCancelled,
+            canResume: true,
+            error: serializeChunkError(error, "synthesis", !wasCancelled),
+          };
           options.onProgress?.({
             currentChunk: completed,
             totalChunks: chunks.length,
@@ -570,23 +638,44 @@ export async function synthesizeSsmlChunksSafe(
             error,
           });
           if (options.cancelOnFailure !== false) jobScope?.abort();
-          firstError ??= error;
           return;
         }
       }
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, () => worker()));
+    if (firstError && options.cancelOnFailure !== false) {
+      for (const [chunkIndex, state] of chunkStates.entries()) {
+        if (state.status === "pending" && shouldSynthesize(chunkIndex)) {
+          chunkStates[chunkIndex] = { chunkIndex, status: "cancelled", isOriginalFailure: false, canResume: true };
+        }
+      }
+    }
     if (failedIndices.size > 0) {
       const error = firstError ?? new Error("One or more SSML chunks failed to synthesize.");
+      const synthesizedChunks = results.flatMap((result, chunkIndex) =>
+        result ? [{ ...result, chunkIndex, fingerprint: fingerprints[chunkIndex] ?? "" }] : [],
+      );
       (error as { partialResult?: PartialChunkSynthesisResult }).partialResult = {
-        synthesizedChunks: results.flatMap((result, chunkIndex) => (result ? [{ ...result, chunkIndex }] : [])),
-        completedChunks: results.flatMap((result, chunkIndex) => (result ? [{ ...result, chunkIndex }] : [])),
-        pendingChunkIndices: chunks.flatMap((_chunk, chunkIndex) => (results[chunkIndex] ? [] : [chunkIndex])),
+        synthesizedChunks,
+        completedChunks: synthesizedChunks,
+        pendingChunkIndices: chunkStates.flatMap((state) =>
+          state.status === "pending" || state.status === "cancelled" || state.status === "failed"
+            ? [state.chunkIndex]
+            : [],
+        ),
         failedChunkIndices: [...failedIndices],
+        cancelledChunkIndices: chunkStates
+          .filter((state) => state.status === "cancelled")
+          .map((state) => state.chunkIndex),
+        chunkStates,
         totalChunks: chunks.length,
       };
       throw error;
     }
+    const missingChunkIndices = Array.from({ length: chunks.length }, (_value, index) =>
+      results[index] === undefined ? index : undefined,
+    ).filter((index): index is number => index !== undefined);
+    if (missingChunkIndices.length > 0) throw new IncompleteChunkSetError(chunks.length, missingChunkIndices);
     const orderedResults = results.filter((result): result is SsmlSynthesisResult => result !== undefined);
     return {
       ok: true,
@@ -594,7 +683,7 @@ export async function synthesizeSsmlChunksSafe(
       status: "success",
       value: await mergeSynthesisResults(orderedResults, {
         format: (options.outputFormat ?? "audio-16khz-128kbitrate-mono-mp3") as AzureTtsOutputFormat,
-        signal: jobScope?.signal ?? options.signal,
+        signal: jobScope?.signal ?? deadline.signal,
         customMerger: options.customMerger,
         outputMimeType: options.outputMimeType,
         postMergeValidator: options.postMergeValidator,
@@ -605,6 +694,7 @@ export async function synthesizeSsmlChunksSafe(
     return failure(synthesisError, partialResultFrom(error));
   } finally {
     fallbackJobScope?.dispose();
+    deadline.dispose();
   }
 }