feat(redis): add cleanerQueueName option for workflow management

[habualoush]

Overview

This PR introduces a configurable cleanerQueueName parameter to the Redis Workflow Engine module, replacing the hardcoded "workflows-cleaner" with a flexible, configurable option that defaults to "medusa-workflows-cleaner".

---

Summary

What — Changes Introduced

• Added cleanerQueueName as a configurable option in RedisWorkflowsOptions
• Updated the loader to pass cleanerQueueName through dependency injection
• Modified RedisDistributedTransactionStorage to use the configurable name with sensible default
• Updated all related tests to reflect the new naming convention
• Maintains backward compatibility with proper fallback defaults

Why — Motivation

• Naming Consistency: Other queues use medusa- prefix; cleaner queue now follows same convention
• User Flexibility: Multi-tenant setups can customize queue names for namespace isolation
• Design Alignment: All queue names are now configurable following established patterns
• Maintainability: Improves code consistency across the workflow engine module

How — Implementation Details

Files Changed

1. src/types/index.ts — Added type definition for cleanerQueueName
2. src/loaders/redis.ts — Added loader logic to handle the new parameter
3. src/utils/workflow-orchestrator-storage.ts — Updated constructor to use configurable name
4. src/utils/__tests__/workflow-orchestrator-storage.spec.ts — Updated test expectations

Code Changes

Before:

this.cleanerQueueName = "workflows-cleaner"

After:

this.cleanerQueueName = redisCleanerQueueName ?? "medusa-workflows-cleaner"

---

Testing

How to Test

cd packages/modules/workflow-engine-redis
yarn test

Manual Verification

1. Start a Medusa application with workflow engine enabled
2. Monitor Redis to confirm cleaner queue is named medusa-workflows-cleaner
3. Verify cleanup tasks execute on schedule

Custom Configuration Test

export const workflowOrchestrator = {
  module: "@medusajs/workflow-engine-redis",
  options: {
    redisUrl: "redis://localhost:6379",
    cleanerQueueName: "custom-cleanup-queue"
  }
}

---

Usage Examples

Default Behavior

export const workflowOrchestrator = {
  module: "@medusajs/workflow-engine-redis",
  options: {
    redisUrl: "redis://localhost:6379"
  }
}
// Queue will be named: "medusa-workflows-cleaner"

Custom Queue Name

export const workflowOrchestrator = {
  module: "@medusajs/workflow-engine-redis",
  options: {
    redisUrl: "redis://localhost:6379",
    queueName: "my-app-workflows",
    jobQueueName: "my-app-scheduled-jobs",
    cleanerQueueName: "my-app-cleanup-tasks"
  }
}

Multi-Tenant Setup

const getTenantConfig = (tenantId: string) => ({
  redisUrl: "redis://localhost:6379",
  queueName: `${tenantId}-workflows`,
  jobQueueName: `${tenantId}-scheduled-jobs`,
  cleanerQueueName: `${tenantId}-cleanup-tasks`
})

---

Checklist

• Tests are updated and passing
• Code follows existing patterns in the module
• No breaking changes (backward compatible)
• Documentation (JSDoc) added
• Changeset added
• Related issues linked (if applicable)

---

Notes

• This change is backward compatible — existing code without cleanerQueueName will use the new default
• The new default name "medusa-workflows-cleaner" follows the established naming convention
• All three queue names now follow the same configuration pattern

---

Note

Introduces a configurable cleaner queue name and propagates it through the Redis workflow engine, aligning naming with other queues and enabling overrides.

• Adds cleanerQueueName to RedisWorkflowsOptions in types/index.ts (default medusa-workflows-cleaner)
• Updates loaders/redis.ts to resolve cleanerQueueName and register redisCleanerQueueName with per-queue options
• Modifies RedisDistributedTransactionStorage to consume redisCleanerQueueName instead of hardcoded "workflows-cleaner"
• Updates tests in utils/__tests__/workflow-orchestrator-storage.spec.ts to expect the new default name and DI path

^{Written by Cursor Bugbot for commit 2adf71c. This will update automatically on new commits. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2adf71c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

@habualoush is attempting to deploy a commit to the medusajs Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[cursor]

Old cleaner queue orphaned without cleanup migration

Low Severity

Changing the default cleaner queue name from "workflows-cleaner" to "medusa-workflows-cleaner" orphans the old queue in Redis. The old queue has a repeatable job that adds tasks every 30 minutes, but no worker processes them after upgrade. This causes gradual Redis memory growth. The codebase has precedent for migration cleanup at lines 191-193 for a similar scenario, but equivalent cleanup for the old cleaner queue name is missing.