@loonylabs/tti-middleware 1.8.0 → 1.9.0

package/dist/middleware/services/tti/providers/base-tti-provider.d.ts

@@ -102,10 +102,20 @@ export declare abstract class BaseTTIProvider implements ITTIProvider {
      */
     protected sleep(ms: number): Promise<void>;
     /**
-     * Wrap an operation with a timeout. If the operation doesn't resolve
-     * within timeoutMs, the returned promise rejects with a timeout error.
-     * The original operation continues running (promises can't be cancelled),
-     * but its result is ignored.
+     * Wrap an operation with a timeout and optional grace period.
+     *
+     * Normal flow (graceMs = 0):
+     *   If the operation doesn't resolve within `timeoutMs`, the returned promise
+     *   rejects immediately with a timeout error.
+     *
+     * Grace period flow (graceMs > 0):
+     *   When `timeoutMs` fires, instead of rejecting immediately, a grace period
+     *   starts. If the operation resolves successfully within `graceMs`, the result
+     *   is used and no timeout error is thrown. Only if the grace period also expires
+     *   does the promise reject — with an error reflecting the total wait time.
+     *
+     * This prevents paying for (and discarding) a Vertex AI response that arrived
+     * slightly after the timeout threshold.
      */
     private withTimeout;
     /**

package/dist/middleware/services/tti/providers/base-tti-provider.js

@@ -249,6 +249,7 @@ class BaseTTIProvider {
             jitter: retryOption.jitter ?? types_1.DEFAULT_RETRY_OPTIONS.jitter,
             timeoutMs: retryOption.timeoutMs ?? types_1.DEFAULT_RETRY_OPTIONS.timeoutMs,
             timeoutRetries: retryOption.timeoutRetries ?? types_1.DEFAULT_RETRY_OPTIONS.timeoutRetries,
+            graceMs: retryOption.graceMs ?? types_1.DEFAULT_RETRY_OPTIONS.graceMs,
         };
     }
     /**
@@ -274,25 +275,68 @@ class BaseTTIProvider {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
-     * Wrap an operation with a timeout. If the operation doesn't resolve
-     * within timeoutMs, the returned promise rejects with a timeout error.
-     * The original operation continues running (promises can't be cancelled),
-     * but its result is ignored.
+     * Wrap an operation with a timeout and optional grace period.
+     *
+     * Normal flow (graceMs = 0):
+     *   If the operation doesn't resolve within `timeoutMs`, the returned promise
+     *   rejects immediately with a timeout error.
+     *
+     * Grace period flow (graceMs > 0):
+     *   When `timeoutMs` fires, instead of rejecting immediately, a grace period
+     *   starts. If the operation resolves successfully within `graceMs`, the result
+     *   is used and no timeout error is thrown. Only if the grace period also expires
+     *   does the promise reject — with an error reflecting the total wait time.
+     *
+     * This prevents paying for (and discarding) a Vertex AI response that arrived
+     * slightly after the timeout threshold.
      */
-    withTimeout(operation, timeoutMs, operationName) {
+    withTimeout(operation, timeoutMs, graceMs, operationName) {
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                reject(new Error(`timeout: ${operationName} did not complete within ${timeoutMs}ms`));
-            }, timeoutMs);
-            operation()
-                .then((result) => {
-                clearTimeout(timer);
+            let settled = false;
+            let inGracePeriod = false;
+            let mainTimerRef;
+            let graceTimerRef = null;
+            const operationPromise = operation();
+            // Handle operation resolution — can fire at any point, including during grace
+            operationPromise.then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(mainTimerRef);
+                if (graceTimerRef)
+                    clearTimeout(graceTimerRef);
+                if (inGracePeriod) {
+                    this.log('info', `${operationName} completed during grace period`, { graceMs });
+                }
                 resolve(result);
-            })
-                .catch((error) => {
-                clearTimeout(timer);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(mainTimerRef);
+                if (graceTimerRef)
+                    clearTimeout(graceTimerRef);
                 reject(error);
             });
+            // Primary timeout
+            mainTimerRef = setTimeout(() => {
+                if (settled)
+                    return;
+                if (graceMs > 0) {
+                    inGracePeriod = true;
+                    this.log('warn', `${operationName} primary timeout after ${timeoutMs}ms, entering grace period (${graceMs}ms)`, { timeoutMs, graceMs });
+                    graceTimerRef = setTimeout(() => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        reject(new Error(`timeout: ${operationName} did not complete within ${timeoutMs + graceMs}ms (including ${graceMs}ms grace period)`));
+                    }, graceMs);
+                }
+                else {
+                    settled = true;
+                    reject(new Error(`timeout: ${operationName} did not complete within ${timeoutMs}ms`));
+                }
+            }, timeoutMs);
         });
     }
     /**
@@ -336,6 +380,7 @@ class BaseTTIProvider {
             return operation();
         }
         const timeoutMs = retryConfig.timeoutMs || 0;
+        const graceMs = retryConfig.graceMs ?? 0;
         const maxTimeoutRetries = retryConfig.timeoutRetries ?? 2;
         let lastError = null;
         let generalRetryCount = 0;
@@ -354,7 +399,7 @@ class BaseTTIProvider {
                 });
                 // Wrap with timeout if configured
                 const result = timeoutMs > 0
-                    ? await this.withTimeout(operation, timeoutMs, operationName)
+                    ? await this.withTimeout(operation, timeoutMs, graceMs, operationName)
                     : await operation();
                 const duration = Date.now() - attemptStart;
                 this.log('info', `${operationName} completed in ${duration}ms`, {

package/dist/middleware/types/index.d.ts

@@ -235,6 +235,23 @@ export interface RetryOptions {
      * long waits, while still allowing many retries for quota errors.
      */
     timeoutRetries?: number;
+    /**
+     * Grace period in milliseconds after a timeout before abandoning the attempt (default: 0).
+     *
+     * When `timeoutMs` fires, instead of immediately failing and starting a new retry,
+     * the middleware waits an additional `graceMs`. If the in-flight request resolves
+     * successfully within this window, the result is used and no retry is needed.
+     *
+     * This prevents paying for (and discarding) a successful response that arrived
+     * slightly after the timeout threshold — which is common under quota pressure when
+     * Vertex AI eventually returns a valid result after a long backoff.
+     *
+     * Example: `timeoutMs: 210000, graceMs: 60000`
+     * → waits up to 210s normally, then up to 60s more to capture a late success.
+     *
+     * Set to 0 (default) to disable — timeout retries fire immediately as before.
+     */
+    graceMs?: number;
     /**
      * @deprecated Use `backoffMultiplier` instead. Will be removed in v2.0.
      * When true, equivalent to backoffMultiplier of 1.0 with linear scaling (delayMs * attempt).

package/dist/middleware/types/index.js

@@ -39,4 +39,5 @@ exports.DEFAULT_RETRY_OPTIONS = {
     jitter: true,
     timeoutMs: 45000,
     timeoutRetries: 2,
+    graceMs: 0,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loonylabs/tti-middleware",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Provider-agnostic Text-to-Image middleware with GDPR compliance. Supports Google Cloud (Imagen, Gemini), Eden AI, and IONOS.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",