@loonylabs/tti-middleware 1.1.1 → 1.2.0

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

@@ -84,24 +84,36 @@ export declare abstract class BaseTTIProvider implements ITTIProvider {
      * Validate that the request is valid
      */
     protected validateRequest(request: TTIRequest): void;
+    /** Resolved retry config type (without deprecated fields) */
+    protected static readonly RESOLVED_RETRY_DEFAULTS: Required<Omit<RetryOptions, "incrementalBackoff">>;
     /**
      * Resolve retry configuration from request
      */
-    protected resolveRetryConfig(request: TTIRequest): Required<RetryOptions> | null;
+    protected resolveRetryConfig(request: TTIRequest): Required<Omit<RetryOptions, 'incrementalBackoff'>> | null;
     /**
-     * Calculate delay for a specific retry attempt
+     * Calculate delay for a specific retry attempt using exponential backoff.
+     * Formula: min(delayMs * backoffMultiplier^(attempt-1), maxDelayMs)
+     * With optional jitter: random value between 0 and computed delay.
      */
-    protected calculateRetryDelay(attempt: number, config: Required<RetryOptions>): number;
+    protected calculateRetryDelay(attempt: number, config: Required<Omit<RetryOptions, 'incrementalBackoff'>>): number;
     /**
      * Sleep for a specified duration
      */
     protected sleep(ms: number): Promise<void>;
     /**
-     * Execute a generation function with retry logic for rate limits
+     * 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.
      */
     protected executeWithRetry<T>(request: TTIRequest, operation: () => Promise<T>, operationName: string): Promise<T>;
     /**
-     * Check if an error is a rate limit error (429)
+     * Check if an error is retryable (transient).
+     * Retryable: 429, 408, 500, 502, 503, 504, network errors, timeouts.
+     * Not retryable: 400, 401, 403, and other client errors.
+     */
+    protected isRetryableError(error: Error): boolean;
+    /**
+     * @deprecated Use isRetryableError() instead
      */
     protected isRateLimitError(error: Error): boolean;
     /**

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

@@ -220,9 +220,6 @@ class BaseTTIProvider {
             }
         }
     }
-    // ============================================================
-    // RETRY LOGIC
-    // ============================================================
     /**
      * Resolve retry configuration from request
      */
@@ -236,23 +233,36 @@ class BaseTTIProvider {
         if (retryOption === undefined || retryOption === true) {
             return { ...types_1.DEFAULT_RETRY_OPTIONS };
         }
+        // Handle deprecated incrementalBackoff
+        let backoffMultiplier = retryOption.backoffMultiplier ?? types_1.DEFAULT_RETRY_OPTIONS.backoffMultiplier;
+        if (retryOption.incrementalBackoff !== undefined && retryOption.backoffMultiplier === undefined) {
+            // Legacy: incrementalBackoff=true mapped to linear scaling (multiplier 1.0)
+            backoffMultiplier = retryOption.incrementalBackoff ? 1.0 : 1.0;
+        }
         // Custom configuration: merge with defaults
         return {
             maxRetries: retryOption.maxRetries ?? types_1.DEFAULT_RETRY_OPTIONS.maxRetries,
             delayMs: retryOption.delayMs ?? types_1.DEFAULT_RETRY_OPTIONS.delayMs,
-            incrementalBackoff: retryOption.incrementalBackoff ?? types_1.DEFAULT_RETRY_OPTIONS.incrementalBackoff,
+            backoffMultiplier,
+            maxDelayMs: retryOption.maxDelayMs ?? types_1.DEFAULT_RETRY_OPTIONS.maxDelayMs,
+            jitter: retryOption.jitter ?? types_1.DEFAULT_RETRY_OPTIONS.jitter,
         };
     }
     /**
-     * Calculate delay for a specific retry attempt
+     * Calculate delay for a specific retry attempt using exponential backoff.
+     * Formula: min(delayMs * backoffMultiplier^(attempt-1), maxDelayMs)
+     * With optional jitter: random value between 0 and computed delay.
      */
     calculateRetryDelay(attempt, config) {
-        if (config.incrementalBackoff) {
-            // Incremental: 1s, 2s, 3s, ...
-            return config.delayMs * attempt;
+        // Exponential backoff: delayMs * multiplier^(attempt-1)
+        const exponentialDelay = config.delayMs * Math.pow(config.backoffMultiplier, attempt - 1);
+        // Cap at maxDelayMs
+        const cappedDelay = Math.min(exponentialDelay, config.maxDelayMs);
+        // Apply jitter: random value between 0 and cappedDelay
+        if (config.jitter) {
+            return Math.round(Math.random() * cappedDelay);
         }
-        // Static: always same delay
-        return config.delayMs;
+        return Math.round(cappedDelay);
     }
     /**
      * Sleep for a specified duration
@@ -261,7 +271,9 @@ class BaseTTIProvider {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
-     * Execute a generation function with retry logic for rate limits
+     * 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.
      */
     async executeWithRetry(request, operation, operationName) {
         const retryConfig = this.resolveRetryConfig(request);
@@ -277,33 +289,77 @@ class BaseTTIProvider {
             }
             catch (error) {
                 lastError = error;
-                // Check if this is a rate limit error (429)
-                const isRateLimitError = this.isRateLimitError(error);
-                // Only retry on rate limit errors
-                if (!isRateLimitError) {
+                // Only retry on retryable errors
+                if (!this.isRetryableError(error)) {
                     throw error;
                 }
                 // Check if we have retries left
                 if (attempt < maxAttempts) {
                     const delay = this.calculateRetryDelay(attempt, retryConfig);
-                    this.log('warn', `Rate limit hit during ${operationName}. Retry ${attempt}/${retryConfig.maxRetries} in ${delay}ms...`, { attempt, maxRetries: retryConfig.maxRetries, delayMs: delay });
+                    this.log('warn', `Transient error during ${operationName}. Retry ${attempt}/${retryConfig.maxRetries} in ${delay}ms...`, { attempt, maxRetries: retryConfig.maxRetries, delayMs: delay, error: error.message });
                     await this.sleep(delay);
                 }
             }
         }
         // All retries exhausted
+        this.log('error', `All ${retryConfig.maxRetries} retries exhausted for ${operationName}`, {
+            lastError: lastError?.message,
+        });
         throw lastError;
     }
     /**
-     * Check if an error is a rate limit error (429)
+     * Check if an error is retryable (transient).
+     * Retryable: 429, 408, 500, 502, 503, 504, network errors, timeouts.
+     * Not retryable: 400, 401, 403, and other client errors.
      */
-    isRateLimitError(error) {
+    isRetryableError(error) {
         const message = error.message.toLowerCase();
-        return (message.includes('429') ||
-            message.includes('rate limit') ||
+        // Non-retryable client errors (check first to avoid false positives)
+        if (message.includes('401') ||
+            message.includes('403') ||
+            message.includes('400') ||
+            message.includes('authentication') ||
+            message.includes('unauthorized') ||
+            message.includes('forbidden')) {
+            return false;
+        }
+        // Retryable HTTP status codes
+        if (message.includes('429') ||
+            message.includes('408') ||
+            message.includes('500') ||
+            message.includes('502') ||
+            message.includes('503') ||
+            message.includes('504')) {
+            return true;
+        }
+        // Retryable by error description
+        if (message.includes('rate limit') ||
             message.includes('quota exceeded') ||
             message.includes('too many requests') ||
-            message.includes('resource exhausted'));
+            message.includes('resource exhausted')) {
+            return true;
+        }
+        // Network / timeout errors
+        if (message.includes('timeout') ||
+            message.includes('etimedout') ||
+            message.includes('esockettimedout') ||
+            message.includes('econnreset') ||
+            message.includes('econnrefused') ||
+            message.includes('enotfound') ||
+            message.includes('econnaborted') ||
+            message.includes('epipe') ||
+            message.includes('ehostunreach') ||
+            message.includes('enetunreach') ||
+            message.includes('socket hang up')) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * @deprecated Use isRetryableError() instead
+     */
+    isRateLimitError(error) {
+        return this.isRetryableError(error);
     }
     /**
      * Convert errors to TTIError instances with proper classification
@@ -354,6 +410,11 @@ class BaseTTIProvider {
 }
 exports.BaseTTIProvider = BaseTTIProvider;
 // ============================================================
+// RETRY LOGIC
+// ============================================================
+/** Resolved retry config type (without deprecated fields) */
+BaseTTIProvider.RESOLVED_RETRY_DEFAULTS = types_1.DEFAULT_RETRY_OPTIONS;
+// ============================================================
 // HELPER FUNCTIONS
 // ============================================================
 /**

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

@@ -449,8 +449,8 @@ class GoogleCloudTTIProvider extends base_tti_provider_1.BaseTTIProvider {
     }
     buildCharacterConsistencyPrompt(userPrompt, subjectDescription, referenceCount) {
         const referenceText = referenceCount === 1 ? 'the reference image' : `the ${referenceCount} reference images`;
-        return `Using ${referenceText} as a reference for the subject "${subjectDescription}", generate a new image where: ${userPrompt}
-
+        return `Using ${referenceText} as a reference for the subject "${subjectDescription}", generate a new image where: ${userPrompt}
+
 IMPORTANT: Maintain exact visual consistency with the subject in the reference - same style, colors, proportions, and distinctive features. The subject should be immediately recognizable as the same one from the reference.`;
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

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

@@ -165,11 +165,16 @@ export interface TTIResponse {
 }
 export type TTIErrorCode = 'INVALID_CONFIG' | 'QUOTA_EXCEEDED' | 'PROVIDER_UNAVAILABLE' | 'GENERATION_FAILED' | 'NETWORK_ERROR' | 'UNAUTHORIZED' | 'CAPABILITY_NOT_SUPPORTED';
 /**
- * Configuration for retry behavior on rate limits (429 errors)
+ * Configuration for retry behavior on transient errors.
+ *
+ * Retryable errors: 429 (rate limit), 408 (timeout), 5xx (server errors),
+ * network timeouts, and TCP disconnects.
+ *
+ * Non-retryable errors: 400, 401, 403, and other client errors.
  */
 export interface RetryOptions {
     /**
-     * Maximum number of retry attempts (default: 2)
+     * Maximum number of retry attempts (default: 3)
      * Total attempts = 1 (initial) + maxRetries
      */
     maxRetries?: number;
@@ -178,17 +183,32 @@ export interface RetryOptions {
      */
     delayMs?: number;
     /**
-     * Use incremental backoff: delay increases by delayMs each retry
-     * false: always wait delayMs (e.g., 1s, 1s, 1s)
-     * true: wait delayMs * attempt (e.g., 1s, 2s, 3s)
-     * Default: false
+     * Backoff multiplier for exponential backoff (default: 2.0)
+     * Delay formula: delayMs * (backoffMultiplier ^ (attempt - 1))
+     * Set to 1.0 for constant delay.
+     */
+    backoffMultiplier?: number;
+    /**
+     * Maximum delay in milliseconds (default: 30000)
+     * Caps the computed delay to prevent excessively long waits.
+     */
+    maxDelayMs?: number;
+    /**
+     * Enable jitter to randomize delay and prevent thundering herd (default: true)
+     * When enabled, actual delay is randomized between 0 and the computed delay.
+     */
+    jitter?: boolean;
+    /**
+     * @deprecated Use `backoffMultiplier` instead. Will be removed in v2.0.
+     * When true, equivalent to backoffMultiplier of 1.0 with linear scaling (delayMs * attempt).
      */
     incrementalBackoff?: boolean;
 }
 /**
- * Default retry configuration
+ * Default retry configuration following Google Cloud best practices.
+ * @see https://cloud.google.com/storage/docs/retry-strategy
  */
-export declare const DEFAULT_RETRY_OPTIONS: Required<RetryOptions>;
+export declare const DEFAULT_RETRY_OPTIONS: Required<Omit<RetryOptions, 'incrementalBackoff'>>;
 /**
  * Interface that all TTI providers must implement
  */

package/dist/middleware/types/index.js

@@ -28,10 +28,13 @@ exports.LOG_LEVEL_PRIORITY = {
     silent: 4,
 };
 /**
- * Default retry configuration
+ * Default retry configuration following Google Cloud best practices.
+ * @see https://cloud.google.com/storage/docs/retry-strategy
  */
 exports.DEFAULT_RETRY_OPTIONS = {
-    maxRetries: 2,
+    maxRetries: 3,
     delayMs: 1000,
-    incrementalBackoff: false,
+    backoffMultiplier: 2.0,
+    maxDelayMs: 30000,
+    jitter: true,
 };

package/package.json

@@ -1,90 +1,90 @@
-{
-  "name": "@loonylabs/tti-middleware",
-  "version": "1.1.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",
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md",
-    ".env.example"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "npm run test:unit",
-    "test:unit": "jest --testPathPattern=tests/unit",
-    "test:unit:watch": "jest --testPathPattern=tests/unit --watch",
-    "test:unit:coverage": "jest --testPathPattern=tests/unit --coverage",
-    "test:integration": "cross-env TTI_INTEGRATION_TESTS=true jest --testPathPattern=tests/integration",
-    "test:ci": "jest --runInBand --ci --coverage --testPathPattern=tests/unit",
-    "test:live": "TTI_INTEGRATION_TESTS=true jest tests/integration/*.integration.test.ts --testTimeout=120000",
-    "test:manual": "ts-node scripts/manual-test-edenai.ts",
-    "test:manual:google-cloud": "ts-node scripts/manual-test-google-cloud.ts",
-    "lint": "eslint src/**/*.ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run clean && npm run build && npm run test"
-  },
-  "keywords": [
-    "tti",
-    "text-to-image",
-    "image-generation",
-    "ai",
-    "vertex-ai",
-    "google-cloud",
-    "gemini",
-    "imagen",
-    "middleware",
-    "provider-agnostic",
-    "typescript",
-    "gdpr",
-    "dsgvo",
-    "character-consistency"
-  ],
-  "author": "loonylabs-dev",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/loonylabs-dev/tti-middleware.git"
-  },
-  "bugs": {
-    "url": "https://github.com/loonylabs-dev/tti-middleware/issues"
-  },
-  "homepage": "https://github.com/loonylabs-dev/tti-middleware#readme",
-  "peerDependencies": {
-    "@google-cloud/aiplatform": ">=3.0.0",
-    "@google/genai": ">=0.14.0"
-  },
-  "peerDependenciesMeta": {
-    "@google-cloud/aiplatform": {
-      "optional": true
-    },
-    "@google/genai": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@google-cloud/aiplatform": "^3.29.0",
-    "@google/genai": "^0.14.0",
-    "@types/jest": "^29.5.8",
-    "@types/node": "^20.10.0",
-    "@typescript-eslint/eslint-plugin": "^6.13.0",
-    "@typescript-eslint/parser": "^6.13.0",
-    "cross-env": "^10.1.0",
-    "dotenv": "^17.2.3",
-    "eslint": "^8.54.0",
-    "jest": "^29.7.0",
-    "prettier": "^3.1.0",
-    "ts-jest": "^29.1.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.3.2"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@loonylabs/tti-middleware",
+  "version": "1.2.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",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run test:unit",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "test:unit:watch": "jest --testPathPattern=tests/unit --watch",
+    "test:unit:coverage": "jest --testPathPattern=tests/unit --coverage",
+    "test:integration": "cross-env TTI_INTEGRATION_TESTS=true jest --testPathPattern=tests/integration",
+    "test:ci": "jest --runInBand --ci --coverage --testPathPattern=tests/unit",
+    "test:live": "TTI_INTEGRATION_TESTS=true jest tests/integration/*.integration.test.ts --testTimeout=120000",
+    "test:manual": "ts-node scripts/manual-test-edenai.ts",
+    "test:manual:google-cloud": "ts-node scripts/manual-test-google-cloud.ts",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "clean": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm run test"
+  },
+  "keywords": [
+    "tti",
+    "text-to-image",
+    "image-generation",
+    "ai",
+    "vertex-ai",
+    "google-cloud",
+    "gemini",
+    "imagen",
+    "middleware",
+    "provider-agnostic",
+    "typescript",
+    "gdpr",
+    "dsgvo",
+    "character-consistency"
+  ],
+  "author": "loonylabs-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/loonylabs-dev/tti-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loonylabs-dev/tti-middleware/issues"
+  },
+  "homepage": "https://github.com/loonylabs-dev/tti-middleware#readme",
+  "peerDependencies": {
+    "@google-cloud/aiplatform": ">=3.0.0",
+    "@google/genai": ">=0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/aiplatform": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google-cloud/aiplatform": "^3.29.0",
+    "@google/genai": "^0.14.0",
+    "@types/jest": "^29.5.8",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "cross-env": "^10.1.0",
+    "dotenv": "^17.2.3",
+    "eslint": "^8.54.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}