@loonylabs/tti-middleware 1.3.0 → 1.4.1

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

@@ -22,7 +22,8 @@ export declare class ProviderUnavailableError extends TTIError {
     constructor(provider: string, message?: string, cause?: Error);
 }
 export declare class GenerationFailedError extends TTIError {
-    constructor(provider: string, message: string, cause?: Error);
+    readonly modelResponse?: string;
+    constructor(provider: string, message: string, cause?: Error, modelResponse?: string);
 }
 export declare class NetworkError extends TTIError {
     constructor(provider: string, message: string, cause?: Error);
@@ -100,10 +101,26 @@ export declare abstract class BaseTTIProvider implements ITTIProvider {
      * Sleep for a specified duration
      */
     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.
+     */
+    private withTimeout;
+    /**
+     * Check if an error is a timeout error (from our withTimeout wrapper).
+     */
+    private isTimeoutError;
     /**
      * Execute a generation function with retry logic for transient errors.
      * Retries on: 429, 408, 5xx, network timeouts, TCP disconnects.
      * Does NOT retry on: 400, 401, 403, and other client errors.
+     *
+     * Each attempt is wrapped with a per-attempt timeout (configurable via
+     * retry.timeoutMs, default 45s). Timeout errors have their own retry
+     * counter (timeoutRetries, default 2) independent from the general
+     * maxRetries used for quota/server errors.
      */
     protected executeWithRetry<T>(request: TTIRequest, operation: () => Promise<T>, operationName: string): Promise<T>;
     /**

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

@@ -55,9 +55,10 @@ class ProviderUnavailableError extends TTIError {
 }
 exports.ProviderUnavailableError = ProviderUnavailableError;
 class GenerationFailedError extends TTIError {
-    constructor(provider, message, cause) {
+    constructor(provider, message, cause, modelResponse) {
         super(provider, 'GENERATION_FAILED', message, cause);
         this.name = 'GenerationFailedError';
+        this.modelResponse = modelResponse;
     }
 }
 exports.GenerationFailedError = GenerationFailedError;
@@ -246,6 +247,8 @@ class BaseTTIProvider {
             backoffMultiplier,
             maxDelayMs: retryOption.maxDelayMs ?? types_1.DEFAULT_RETRY_OPTIONS.maxDelayMs,
             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,
         };
     }
     /**
@@ -270,10 +273,43 @@ class BaseTTIProvider {
     sleep(ms) {
         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.
+     */
+    withTimeout(operation, timeoutMs, 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);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Check if an error is a timeout error (from our withTimeout wrapper).
+     */
+    isTimeoutError(error) {
+        return error.message.toLowerCase().startsWith('timeout:');
+    }
     /**
      * Execute a generation function with retry logic for transient errors.
      * Retries on: 429, 408, 5xx, network timeouts, TCP disconnects.
      * Does NOT retry on: 400, 401, 403, and other client errors.
+     *
+     * Each attempt is wrapped with a per-attempt timeout (configurable via
+     * retry.timeoutMs, default 45s). Timeout errors have their own retry
+     * counter (timeoutRetries, default 2) independent from the general
+     * maxRetries used for quota/server errors.
      */
     async executeWithRetry(request, operation, operationName) {
         const retryConfig = this.resolveRetryConfig(request);
@@ -281,29 +317,71 @@ class BaseTTIProvider {
         if (!retryConfig) {
             return operation();
         }
+        const timeoutMs = retryConfig.timeoutMs || 0;
+        const maxTimeoutRetries = retryConfig.timeoutRetries ?? 2;
         let lastError = null;
-        const maxAttempts = 1 + retryConfig.maxRetries; // initial + retries
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let generalRetryCount = 0;
+        let timeoutRetryCount = 0;
+        const maxGeneralRetries = retryConfig.maxRetries;
+        // Total attempt cap to prevent infinite loops
+        const absoluteMaxAttempts = 1 + maxGeneralRetries + maxTimeoutRetries;
+        for (let attempt = 1; attempt <= absoluteMaxAttempts; attempt++) {
+            const attemptStart = Date.now();
             try {
-                return await operation();
+                this.log('info', `${operationName} attempt ${attempt}${timeoutMs ? ` (timeout: ${timeoutMs}ms)` : ''} [retries: general=${generalRetryCount}/${maxGeneralRetries}, timeout=${timeoutRetryCount}/${maxTimeoutRetries}]`, {
+                    attempt,
+                    timeoutMs: timeoutMs || 'none',
+                    generalRetries: `${generalRetryCount}/${maxGeneralRetries}`,
+                    timeoutRetries: `${timeoutRetryCount}/${maxTimeoutRetries}`,
+                });
+                // Wrap with timeout if configured
+                const result = timeoutMs > 0
+                    ? await this.withTimeout(operation, timeoutMs, operationName)
+                    : await operation();
+                const duration = Date.now() - attemptStart;
+                this.log('info', `${operationName} completed in ${duration}ms`, {
+                    attempt,
+                    durationMs: duration,
+                });
+                return result;
             }
             catch (error) {
+                const duration = Date.now() - attemptStart;
                 lastError = error;
-                // Only retry on retryable errors
-                if (!this.isRetryableError(error)) {
+                const isTimeout = this.isTimeoutError(error);
+                // Non-retryable errors: fail immediately
+                if (!isTimeout && !this.isRetryableError(error)) {
+                    this.log('error', `${operationName} failed with non-retryable error after ${duration}ms: ${error.message}`, { attempt, durationMs: duration });
                     throw error;
                 }
-                // Check if we have retries left
-                if (attempt < maxAttempts) {
-                    const delay = this.calculateRetryDelay(attempt, retryConfig);
-                    this.log('warn', `Transient error during ${operationName}. Retry ${attempt}/${retryConfig.maxRetries} in ${delay}ms...`, { attempt, maxRetries: retryConfig.maxRetries, delayMs: delay, error: error.message });
+                // Check retry budget for this error type
+                if (isTimeout) {
+                    timeoutRetryCount++;
+                    if (timeoutRetryCount > maxTimeoutRetries) {
+                        this.log('error', `${operationName} timeout retry budget exhausted (${maxTimeoutRetries} retries, ${duration}ms on last attempt)`, { attempt, timeoutRetryCount, durationMs: duration });
+                        throw error;
+                    }
+                    // Short fixed delay before timeout retry (no exponential backoff)
+                    this.log('warn', `${operationName} timed out after ${duration}ms. Timeout retry ${timeoutRetryCount}/${maxTimeoutRetries} in 2s...`, { attempt, timeoutRetryCount, maxTimeoutRetries, durationMs: duration });
+                    await this.sleep(2000);
+                }
+                else {
+                    generalRetryCount++;
+                    if (generalRetryCount > maxGeneralRetries) {
+                        this.log('error', `${operationName} general retry budget exhausted (${maxGeneralRetries} retries): ${error.message}`, { attempt, generalRetryCount, durationMs: duration });
+                        throw error;
+                    }
+                    const delay = this.calculateRetryDelay(generalRetryCount, retryConfig);
+                    this.log('warn', `Transient error during ${operationName} after ${duration}ms. Retry ${generalRetryCount}/${maxGeneralRetries} in ${delay}ms: ${error.message}`, { attempt, generalRetryCount, maxGeneralRetries, delayMs: delay, durationMs: duration });
                     await this.sleep(delay);
                 }
             }
         }
-        // All retries exhausted
-        this.log('error', `All ${retryConfig.maxRetries} retries exhausted for ${operationName}`, {
+        // Safety: should not reach here
+        this.log('error', `All retries exhausted for ${operationName}`, {
             lastError: lastError?.message,
+            generalRetryCount,
+            timeoutRetryCount,
         });
         throw lastError;
     }

package/dist/middleware/services/tti/providers/google-cloud-provider.js

@@ -273,13 +273,14 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                 }
             }
             const parameters = helpers.toValue(parameterValue);
-            this.log('debug', 'Sending Imagen request', { endpoint, parameters: parameterValue });
+            this.log('info', 'Sending Imagen request to Vertex AI', { endpoint, parameters: parameterValue });
             const [response] = await client.predict({
                 endpoint,
                 instances: [instance],
                 parameters,
             });
             const duration = Date.now() - startTime;
+            this.log('info', `Imagen response received in ${duration}ms`, { duration, hasPredictions: !!response.predictions?.length });
             if (!response.predictions || response.predictions.length === 0) {
                 throw new base_tti_provider_1.GenerationFailedError(this.providerName, 'No images returned from Imagen API');
             }
@@ -402,11 +403,12 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
             if (request.providerOptions?.temperature !== undefined) {
                 config.temperature = request.providerOptions.temperature;
             }
-            this.log('debug', 'Sending Gemini request', {
+            this.log('info', 'Sending Gemini generateContent request to Vertex AI', {
                 model: internalModelId,
                 region,
                 hasReferenceImages: (0, base_tti_provider_1.hasReferenceImages)(request),
-                config: JSON.stringify(config, null, 2),
+                referenceImageCount: request.referenceImages?.length || 0,
+                aspectRatio: request.aspectRatio,
             });
             const response = await client.generateContent({
                 model: internalModelId,
@@ -414,6 +416,10 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
                 config,
             });
             const duration = Date.now() - startTime;
+            this.log('info', `Gemini response received in ${duration}ms`, {
+                duration,
+                hasCandidates: !!(response?.candidates || response?.response),
+            });
             return this.processGeminiResponse(response, duration);
         }
         catch (error) {
@@ -480,9 +486,12 @@ IMPORTANT: Maintain exact visual consistency with the subject in the reference -
         }
         if (images.length === 0) {
             const firstParts = candidates[0]?.content?.parts || [];
+            const fullTexts = [];
             const partTypes = firstParts.map((p) => {
-                if (p.text)
-                    return `text(${p.text.substring(0, 50)}...)`;
+                if (p.text) {
+                    fullTexts.push(p.text);
+                    return `text(${p.text.substring(0, 200)}${p.text.length > 200 ? '...' : ''})`;
+                }
                 if (p.inlineData)
                     return `inlineData(${p.inlineData.mimeType})`;
                 return 'unknown';
@@ -490,9 +499,11 @@ IMPORTANT: Maintain exact visual consistency with the subject in the reference -
             this.log('error', 'No images in Gemini response', {
                 candidateCount: candidates.length,
                 partTypes,
+                ...(fullTexts.length > 0 && { modelResponse: fullTexts.join('\n') }),
             });
+            const fullModelResponse = fullTexts.length > 0 ? fullTexts.join('\n') : undefined;
             throw new base_tti_provider_1.GenerationFailedError(this.providerName, `No images in response. Model returned: ${partTypes.join(', ')}. ` +
-                'Make sure responseModalities includes IMAGE.');
+                'Make sure responseModalities includes IMAGE.', undefined, fullModelResponse);
         }
         const usage = {
             imagesGenerated: images.length,

package/dist/middleware/services/tti/utils/debug-tti.utils.d.ts

@@ -45,6 +45,7 @@ export interface TTIDebugInfo {
         message: string;
         code?: string;
         details?: unknown;
+        modelResponse?: string;
     };
 }
 /**
@@ -145,6 +146,7 @@ export declare class TTIDebugger {
     static updateWithError(debugInfo: TTIDebugInfo, error: Error & {
         code?: string;
         cause?: unknown;
+        modelResponse?: string;
     }): TTIDebugInfo;
 }
 export default TTIDebugger;

package/dist/middleware/services/tti/utils/debug-tti.utils.js

@@ -297,6 +297,9 @@ class TTIDebugger {
             if (debugInfo.error.code) {
                 sections.push(`- **Code**: ${debugInfo.error.code}`);
             }
+            if (debugInfo.error.modelResponse) {
+                sections.push(`- **Model Response**: ${debugInfo.error.modelResponse}`);
+            }
             if (debugInfo.error.details) {
                 sections.push('- **Details**:');
                 sections.push('```json');
@@ -401,6 +404,7 @@ class TTIDebugger {
                 message: error.message,
                 code: error.code,
                 details: error.cause,
+                modelResponse: error.modelResponse,
             },
         };
     }

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

@@ -198,6 +198,21 @@ export interface RetryOptions {
      * When enabled, actual delay is randomized between 0 and the computed delay.
      */
     jitter?: boolean;
+    /**
+     * Timeout per attempt in milliseconds (default: 45000 = 45s).
+     * If the provider SDK call doesn't resolve within this time,
+     * the attempt is aborted and counted as a retryable timeout error.
+     * Set to 0 to disable timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum retries specifically for timeout errors (default: 2).
+     * Timeout retries are tracked independently from other transient errors
+     * (429, 5xx, etc.) which use the general `maxRetries` counter.
+     * This prevents a hung service from burning through all retries with
+     * long waits, while still allowing many retries for quota errors.
+     */
+    timeoutRetries?: 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

@@ -37,4 +37,6 @@ exports.DEFAULT_RETRY_OPTIONS = {
     backoffMultiplier: 2.0,
     maxDelayMs: 30000,
     jitter: true,
+    timeoutMs: 45000,
+    timeoutRetries: 2,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loonylabs/tti-middleware",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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",