chore(): Default caching configuration and gracefull redis error handling (#13663)

* chore(): Default caching configuration and gracefull redis error handling

* Create odd-moons-crash.md

* chore(): Default caching configuration and gracefull redis error handling

* fixes

* address feedback

* revert(): Test utils imit module fix

* reconnect

* reconnect

* reconnect

.changeset/odd-moons-crash.md

@@ -0,0 +1,6 @@
+---
+"@medusajs/caching-redis": patch
+"@medusajs/utils": patch
+---
+
+chore(): Default caching configuration and gracefull redis error handling

packages/core/utils/src/common/__tests__/define-config.spec.ts

@@ -1048,6 +1048,7 @@ describe("defineConfig", function () {
 
     process.env.EXECUTION_CONTEXT = "medusa-cloud"
     process.env.REDIS_URL = "redis://localhost:6379"
+    process.env.CACHE_REDIS_URL = "redis://localhost:6379"
     process.env.S3_FILE_URL = "https://s3.amazonaws.com/medusa-cloud-test"
     process.env.S3_PREFIX = "test"
     process.env.S3_REGION = "us-east-1"
@@ -1086,6 +1087,21 @@ describe("defineConfig", function () {
             },
             "resolve": "@medusajs/medusa/cache-redis",
           },
+          "caching": {
+            "options": {
+              "providers": [
+                {
+                  "id": "caching-redis",
+                  "is_default": true,
+                  "options": {
+                    "redisUrl": "redis://localhost:6379",
+                  },
+                  "resolve": "@medusajs/medusa/caching-redis",
+                },
+              ],
+            },
+            "resolve": "@medusajs/caching",
+          },
           "cart": {
             "resolve": "@medusajs/medusa/cart",
           },
@@ -1255,6 +1271,7 @@ describe("defineConfig", function () {
 
     process.env.EXECUTION_CONTEXT = "medusa-cloud"
     process.env.REDIS_URL = "redis://localhost:6379"
+    process.env.CACHE_REDIS_URL = "redis://localhost:6379"
     process.env.S3_FILE_URL = "https://s3.amazonaws.com/medusa-cloud-test"
     process.env.S3_PREFIX = "test"
     process.env.S3_REGION = "us-east-1"
@@ -1294,6 +1311,21 @@ describe("defineConfig", function () {
             },
             "resolve": "@medusajs/medusa/cache-redis",
           },
+          "caching": {
+            "options": {
+              "providers": [
+                {
+                  "id": "caching-redis",
+                  "is_default": true,
+                  "options": {
+                    "redisUrl": "redis://localhost:6379",
+                  },
+                  "resolve": "@medusajs/medusa/caching-redis",
+                },
+              ],
+            },
+            "resolve": "@medusajs/caching",
+          },
           "cart": {
             "resolve": "@medusajs/medusa/cart",
           },
@@ -1473,6 +1505,7 @@ describe("defineConfig", function () {
 
     process.env.EXECUTION_CONTEXT = "medusa-cloud"
     process.env.REDIS_URL = "redis://localhost:6379"
+    process.env.CACHE_REDIS_URL = "redis://localhost:6379"
     process.env.S3_FILE_URL = "https://s3.amazonaws.com/medusa-cloud-test"
     process.env.S3_PREFIX = "test"
     process.env.S3_REGION = "us-east-1"
@@ -1518,6 +1551,21 @@ describe("defineConfig", function () {
             },
             "resolve": "@medusajs/medusa/cache-redis",
           },
+          "caching": {
+            "options": {
+              "providers": [
+                {
+                  "id": "caching-redis",
+                  "is_default": true,
+                  "options": {
+                    "redisUrl": "redis://localhost:6379",
+                  },
+                  "resolve": "@medusajs/medusa/caching-redis",
+                },
+              ],
+            },
+            "resolve": "@medusajs/caching",
+          },
           "cart": {
             "resolve": "@medusajs/medusa/cart",
           },

packages/core/utils/src/common/define-config.ts

@@ -303,6 +303,24 @@ function resolveModules(
     },
   ]
 
+  if (process.env.CACHE_REDIS_URL) {
+    cloudModules.push({
+      resolve: MODULE_PACKAGE_NAMES[Modules.CACHING],
+      options: {
+        providers: [
+          {
+            id: "caching-redis",
+            resolve: "@medusajs/medusa/caching-redis",
+            is_default: true,
+            options: {
+              redisUrl: process.env.CACHE_REDIS_URL,
+            },
+          },
+        ],
+      },
+    })
+  }
+
   /**
    * The default set of modules to always use. The end user can swap
    * the modules by providing an alternate implementation via their

packages/medusa-test-utils/src/init-modules.ts

@@ -64,12 +64,12 @@ export async function initModules({
 
   async function shutdown() {
     const promises: Promise<void>[] = []
-    promises.push(medusaApp.onApplicationPrepareShutdown())
-    promises.push(medusaApp.onApplicationShutdown())
 
     if (shouldDestroyConnectionAutomatically) {
       promises.push((sharedPgConnection as any).context?.destroy())
       promises.push((sharedPgConnection as any).destroy())
+      promises.push(medusaApp.onApplicationPrepareShutdown())
+      promises.push(medusaApp.onApplicationShutdown())
     } else {
       if (!preventConnectionDestroyWarning) {
         logger.info(

packages/modules/providers/caching-redis/src/loaders/connection.ts

@@ -4,7 +4,7 @@ import type {
   ModulesSdkTypes,
 } from "@medusajs/framework/types"
 import { RedisCacheModuleOptions } from "@types"
-import Redis from "ioredis"
+import Redis, { type RedisOptions } from "ioredis"
 
 export default async (
   {
@@ -23,36 +23,56 @@ export default async (
 
   const moduleOptions = (options ??
     moduleDeclaration?.options ??
-    {}) as RedisCacheModuleOptions & {
+    {}) as RedisCacheModuleOptions
-    redisUrl?: string
-  }
 
-  if (!moduleOptions.redisUrl) {
+  const { redisUrl, ...redisOptions_ } = moduleOptions
+  if (!redisUrl) {
     throw new Error("[caching-redis] redisUrl is required")
   }
 
   let redisClient: Redis
 
-  try {
+  const redisOptions: RedisOptions = {
-    redisClient = new Redis(moduleOptions.redisUrl!, {
     connectTimeout: 10000,
+    commandTimeout: 5000,
     lazyConnect: true,
-      retryDelayOnFailover: 100,
+    maxRetriesPerRequest: 3,
+    enableOfflineQueue: true,
     connectionName: "medusa-cache-redis",
-      ...moduleOptions,
+    ...redisOptions_,
+  }
+
+  redisClient = new Redis(redisUrl!, redisOptions)
+
+  // Handle connection errors gracefully
+  redisClient.on("error", (error) => {
+    logger_.warn(`Redis cache connection error: ${error.message}`)
   })
 
-    // Test connection
+  redisClient.on("connect", () => {
-    await redisClient.ping()
     logger_.info("Redis cache connection established successfully")
-  } catch (error) {
-    logger_.error(`Failed to connect to Redis cache: ${error.message}`)
-    redisClient = new Redis(moduleOptions.redisUrl!, {
-      connectTimeout: 10000,
-      lazyConnect: true,
-      retryDelayOnFailover: 100,
-      ...moduleOptions,
   })
+
+  redisClient.on("ready", () => {
+    logger_.info("Redis cache is ready to accept commands")
+  })
+
+  redisClient.on("close", () => {
+    logger_.warn("Redis cache connection closed")
+  })
+
+  redisClient.on("reconnecting", () => {
+    logger_.info("Redis cache attempting to reconnect...")
+  })
+
+  try {
+    // Test connection with timeout
+    await redisClient.ping()
+    logger_.info("Redis cache connection test successful")
+  } catch (error) {
+    logger_.warn(
+      `Redis cache connection test failed: ${error.message}, but continuing with lazy connection`
+    )
   }
 
   container.register({
@@ -62,5 +82,8 @@ export default async (
     prefix: {
       resolve: () => moduleOptions.prefix ?? "mc:",
     },
+    logger: {
+      resolve: () => logger_,
+    },
   })
 }

packages/modules/providers/caching-redis/src/services/redis-cache.ts

@@ -1,3 +1,4 @@
+import { Logger } from "@medusajs/framework/types"
 import { RedisCacheModuleOptions } from "@types"
 import { Redis } from "ioredis"
 import { createGunzip, createGzip } from "zlib"
@@ -10,13 +11,20 @@ export class RedisCachingProvider {
   protected defaultTTL: number
   protected compressionThreshold: number
   protected hasher: (key: string) => string
+  protected logger: Logger
 
   constructor(
     {
       redisClient,
+      logger,
       prefix,
       hasher,
-    }: { redisClient: Redis; prefix: string; hasher: (key: string) => string },
+    }: {
+      redisClient: Redis
+      prefix: string
+      hasher: (key: string) => string
+      logger: Logger
+    },
     options?: RedisCacheModuleOptions
   ) {
     this.redisClient = redisClient
@@ -24,6 +32,29 @@ export class RedisCachingProvider {
     this.defaultTTL = options?.ttl ?? 3600 // 1 hour default
     this.compressionThreshold = options?.compressionThreshold ?? 2048 // 2KB default
     this.hasher = hasher
+    this.logger = logger
+  }
+
+  private isConnectionError(error: any): boolean {
+    return (
+      error.code === "ECONNREFUSED" ||
+      error.code === "ENOTFOUND" ||
+      error.code === "ETIMEDOUT" ||
+      error.code === "ECONNRESET" ||
+      error.code === "EPIPE" ||
+      error.message?.includes("Connection is closed") ||
+      error.message?.includes("connect ECONNREFUSED") ||
+      error.message?.includes("connect ETIMEDOUT") ||
+      error.message?.includes("Command timed out") ||
+      error.message?.includes("Maximum number of retries exceeded") ||
+      ["connecting", "reconnecting", "disconnecting", "wait", "end"].includes(
+        this.redisClient.status
+      )
+    )
+  }
+
+  private isConnectionHealthy(): boolean {
+    return this.redisClient.status === "ready"
   }
 
   #getKeyName(key: string): string {
@@ -252,7 +283,12 @@ export class RedisCachingProvider {
   }
 
   async get({ key, tags }: { key?: string; tags?: string[] }): Promise<any> {
+    if (!this.isConnectionHealthy()) {
+      return null
+    }
+
     if (key) {
+      try {
         const keyName = this.#getKeyName(key)
         const buffer = await this.redisClient.hgetBuffer(keyName, "data")
         if (!buffer) {
@@ -261,9 +297,19 @@ export class RedisCachingProvider {
 
         const finalData = await this.#decompressData(buffer)
         return JSON.parse(finalData)
+      } catch (error) {
+        if (this.isConnectionError(error)) {
+          this.logger.warn(
+            "Redis connection error during get operation, returning null to trigger fallback to original data source"
+          )
+          return null
+        }
+        throw error
+      }
     }
 
     if (tags?.length) {
+      try {
         // Get all keys associated with the tags
         const pipeline = this.redisClient.pipeline()
         tags.forEach((tag) => {
@@ -293,7 +339,8 @@ export class RedisCachingProvider {
         const valueResults = await valuePipeline.exec()
         const results: any[] = []
 
-      const decompressionPromises = (valueResults || []).map(async (result) => {
+        const decompressionPromises = (valueResults || []).map(
+          async (result) => {
             if (result && result[1]) {
               const buffer = result[1] as Buffer
               try {
@@ -301,17 +348,27 @@ export class RedisCachingProvider {
                 return JSON.parse(finalData)
               } catch (e) {
                 // If JSON parsing fails, skip this entry (corrupted data)
-            console.warn(`Skipping corrupted cache entry: ${e.message}`)
+                this.logger.warn(`Skipping corrupted cache entry: ${e.message}`)
                 return null
               }
             }
             return null
-      })
+          }
+        )
 
         const decompressionResults = await Promise.all(decompressionPromises)
         results.push(...decompressionResults.filter(Boolean))
 
         return results
+      } catch (error) {
+        if (this.isConnectionError(error)) {
+          this.logger.warn(
+            "Redis connection error during get operation, returning empty array to trigger fallback to original data source"
+          )
+          return null
+        }
+        throw error
+      }
     }
 
     return null
@@ -332,6 +389,7 @@ export class RedisCachingProvider {
       autoInvalidate?: boolean
     }
   }): Promise<void> {
+    try {
       const keyName = this.#getKeyName(key)
       const serializedData = JSON.stringify(data)
       const effectiveTTL = ttl ?? this.defaultTTL
@@ -379,6 +437,15 @@ export class RedisCachingProvider {
       }
 
       await setPipeline.exec()
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        this.logger.warn(
+          "Redis connection error during set operation, relying on IORedis retry mechanism"
+        )
+        return
+      }
+      throw error
+    }
   }
 
   async clear({
@@ -392,6 +459,7 @@ export class RedisCachingProvider {
       autoInvalidate?: boolean
     }
   }): Promise<void> {
+    try {
       if (key) {
         const keyName = this.#getKeyName(key)
         const tagsKey = this.#getTagsKey(key)
@@ -558,7 +626,8 @@ export class RedisCachingProvider {
                   const entryOptions = JSON.parse(optionsResult[1] as string)
 
                   // Delete if entry has autoInvalidate=true or no setting (default true)
-                const shouldAutoInvalidate = entryOptions.autoInvalidate ?? true
+                  const shouldAutoInvalidate =
+                    entryOptions.autoInvalidate ?? true
 
                   if (shouldAutoInvalidate) {
                     keysToDelete.push(key)
@@ -607,7 +676,9 @@ export class RedisCachingProvider {
                       if (tagIds.length) {
                         const entryTags = await this.#resolveTagIds(tagIds)
                         entryTags.forEach((tag) => {
-                        const tagKey = this.#getTagKey(tag, { isHashed: true })
+                          const tagKey = this.#getTagKey(tag, {
+                            isHashed: true,
+                          })
                           tagCleanupPipeline.srem(tagKey, key)
                         })
                         tagCleanupPipeline.unlink(tagsKey) // Delete the tags key
@@ -656,9 +727,19 @@ export class RedisCachingProvider {
           }
         }
       }
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        this.logger.warn(
+          "Redis connection error during clear operation, relying on IORedis retry mechanism"
+        )
+        return
+      }
+      throw error
+    }
   }
 
   async flush(): Promise<void> {
+    try {
       // Use SCAN to find ALL keys with our prefix and delete them
       // This includes main cache keys, tag keys (tag:*), and tags keys (tags:*)
       const pattern = `${this.keyNamePrefix}*`
@@ -679,5 +760,14 @@ export class RedisCachingProvider {
           await this.redisClient.unlink(...keys)
         }
       } while (cursor !== "0")
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        this.logger.warn(
+          "Redis connection error during flush operation, relying on IORedis retry mechanism"
+        )
+        return
+      }
+      throw error
+    }
   }
 }

packages/modules/providers/caching-redis/src/types/index.ts

@@ -1,20 +1,13 @@
-export interface RedisCacheModuleOptions {
+import { RedisOptions } from "ioredis"
+export interface RedisCacheModuleOptions extends RedisOptions {
+  /**
+   * Redis connection string
+   */
+  redisUrl?: string
   /**
    * TTL in milliseconds
    */
   ttl?: number
-  /**
-   * Connection timeout in milliseconds
-   */
-  connectTimeout?: number
-  /**
-   * Lazyload connections
-   */
-  lazyConnect?: boolean
-  /**
-   * Connection retries
-   */
-  retryDelayOnFailover?: number
   /**
    * Key prefix for all cache keys
    */

packages/modules/workflow-engine-redis/src/loaders/redis.ts

@@ -42,11 +42,11 @@ export default async (
       maxRetriesPerRequest: null,
     })
     logger?.info(
-      `Connection to Redis in module 'workflow-engine-redis' established`
+      `[Workflow-engine-redis] Connection to Redis in module 'workflow-engine-redis' established`
     )
   } catch (err) {
     logger?.error(
-      `An error occurred while connecting to Redis in module 'workflow-engine-redis': ${err}`
+      `[Workflow-engine-redis] An error occurred while connecting to Redis in module 'workflow-engine-redis': ${err}`
     )
   }
 
@@ -54,11 +54,11 @@ export default async (
     redisPublisher = await getConnection(cnnPubSub.url, cnnPubSub.options)
     redisSubscriber = await getConnection(cnnPubSub.url, cnnPubSub.options)
     logger?.info(
-      `Connection to Redis PubSub in module 'workflow-engine-redis' established`
+      `[Workflow-engine-redis] Connection to Redis PubSub in module 'workflow-engine-redis' established`
     )
   } catch (err) {
     logger?.error(
-      `An error occurred while connecting to Redis PubSub in module 'workflow-engine-redis': ${err}`
+      `[Workflow-engine-redis] An error occurred while connecting to Redis PubSub in module 'workflow-engine-redis': ${err}`
     )
   }
 

packages/modules/workflow-engine-redis/src/utils/workflow-orchestrator-storage.ts

@@ -128,6 +128,7 @@ export class RedisDistributedTransactionStorage
   }
 
   async onApplicationStart() {
+    await this.ensureRedisConnection()
     const allowedJobs = [
       JobType.RETRY,
       JobType.STEP_TIMEOUT,
@@ -212,6 +213,64 @@ export class RedisDistributedTransactionStorage
     this.workflowOrchestratorService_ = workflowOrchestratorService
   }
 
+  private async ensureRedisConnection(): Promise<void> {
+    const reconnectTasks: Promise<void>[] = []
+
+    if (this.redisClient.status !== "ready") {
+      this.logger_.warn(
+        `[Workflow-engine-redis] Redis connection is not ready (status: ${this.redisClient.status}). Attempting to reconnect...`
+      )
+      reconnectTasks.push(
+        this.redisClient
+          .connect()
+          .then(() => {
+            this.logger_.info(
+              "[Workflow-engine-redis] Redis connection reestablished successfully"
+            )
+          })
+          .catch((error) => {
+            this.logger_.error(
+              "[Workflow-engine-redis] Failed to reconnect to Redis",
+              error
+            )
+            throw new MedusaError(
+              MedusaError.Types.DB_ERROR,
+              `Redis connection failed: ${error.message}`
+            )
+          })
+      )
+    }
+
+    if (this.redisWorkerConnection.status !== "ready") {
+      this.logger_.warn(
+        `[Workflow-engine-redis] Redis worker connection is not ready (status: ${this.redisWorkerConnection.status}). Attempting to reconnect...`
+      )
+      reconnectTasks.push(
+        this.redisWorkerConnection
+          .connect()
+          .then(() => {
+            this.logger_.info(
+              "[Workflow-engine-redis] Redis worker connection reestablished successfully"
+            )
+          })
+          .catch((error) => {
+            this.logger_.error(
+              "[Workflow-engine-redis] Failed to reconnect to Redis worker connection",
+              error
+            )
+            throw new MedusaError(
+              MedusaError.Types.DB_ERROR,
+              `Redis worker connection failed: ${error.message}`
+            )
+          })
+      )
+    }
+
+    if (reconnectTasks.length > 0) {
+      await promiseAll(reconnectTasks)
+    }
+  }
+
   private async saveToDb(data: TransactionCheckpoint, retentionTime?: number) {
     const isNotStarted = data.flow.state === TransactionState.NOT_STARTED
     const isFinished = [