@medusajs/workflow-engine-redis 2.22.0-snapshot-20261021091347 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +69 -0
  2. package/README.md +102 -1
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,69 @@
1
+ # @medusajs/workflow-engine-redis
2
+
3
+ Production Workflow Engine Module: orchestrates workflow executions with checkpoints in Redis, BullMQ queues for retries, timeouts, scheduled jobs, and cleanup, and Redis pub/sub so subscribers on any instance get notified. Registered as `Modules.WORKFLOW_ENGINE` (`"workflows"`), replacing `@medusajs/workflow-engine-inmemory`.
4
+
5
+ ## Using this package
6
+
7
+ - Not loaded by default for self-hosted apps. On Medusa Cloud, `defineConfig` registers it when `REDIS_URL` is set.
8
+ - All options sit under `redis` (`RedisWorkflowsOptions`, `src/types/index.ts`):
9
+
10
+ ```ts
11
+ import { Modules } from "@medusajs/framework/utils"
12
+
13
+ module.exports = defineConfig({
14
+ modules: [
15
+ {
16
+ resolve: "@medusajs/medusa/workflow-engine-redis",
17
+ options: {
18
+ redis: {
19
+ redisUrl: process.env.WE_REDIS_URL,
20
+ workerOptions: { concurrency: 10 },
21
+ jobWorkerOptions: { concurrency: 5 },
22
+ },
23
+ },
24
+ },
25
+ ],
26
+ })
27
+ ```
28
+
29
+ - Options: `redisUrl` (required; `url` is deprecated), `redisOptions` (ioredis; `options` is deprecated), `queueName` (default `medusa-workflows`), `jobQueueName` (default `medusa-workflows-jobs`), shared `queueOptions` / `workerOptions`, per-queue `mainQueueOptions`, `mainWorkerOptions`, `jobQueueOptions`, `jobWorkerOptions`, `cleanerQueueOptions`, `cleanerWorkerOptions`, and `pubsub: { url, options }` for a separate pub/sub connection.
30
+ - Resolve with `container.resolve(Modules.WORKFLOW_ENGINE)`. Same public API as the in-memory engine: `run`, `getRunningTransaction`, `setStepSuccess`, `setStepFailure` (accepts `options.forcePermanentFailure`), `retryStep`, `cancel`, `subscribe`, `unsubscribe`, plus `listWorkflowExecutions` / `listAndCountWorkflowExecutions` with a `q` filter.
31
+
32
+ ### Data model (`src/models/workflow-execution.ts`)
33
+
34
+ - `WorkflowExecution` (`wf_exec_`): composite primary key `(workflow_id, transaction_id, run_id)`, `execution` and `context` JSON, `state`, `retention_time`. Identical to the in-memory engine's model; both write the `workflow_execution` table.
35
+ - No module links and no module events.
36
+
37
+ Docs: https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis.md, https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine.md, https://docs.medusajs.com/learn/fundamentals/workflows/long-running-workflow.md
38
+
39
+ ## Architecture
40
+
41
+ - `src/loaders/redis.ts` opens four ioredis connections (main, worker with `maxRetriesPerRequest: null`, publisher, subscriber) and registers resolved per-queue options; `src/loaders/utils.ts` registers `RedisDistributedTransactionStorage`.
42
+ - `src/utils/workflow-orchestrator-storage.ts`:
43
+ - main queue: `retry`, `step_timeout`, `transaction_timeout` jobs
44
+ - job queue: scheduled workflows (BullMQ repeat with `cron` pattern or `interval`)
45
+ - `workflows-cleaner` queue: deletes expired finished executions every 30 minutes
46
+ - Async flows (`_v`) take a 2-second `SET NX` lock on `<key>:lock` before saving; failure throws `Lock not acquired`.
47
+ - `src/services/workflow-orchestrator.ts` publishes notifications on a per-workflow channel so subscribers on other instances are notified.
48
+ - This package and `workflow-engine-inmemory` share most of their service and orchestrator code; port behavior changes to both.
49
+
50
+ ## Development
51
+
52
+ ```bash
53
+ cd packages/modules/workflow-engine-redis
54
+ yarn build
55
+ yarn test # src/loaders/__tests__, src/utils/__tests__
56
+ yarn test:integration # needs Postgres (DB_* env vars) and Redis on localhost:6379
57
+ yarn test:integration integration-tests/__tests__/race.spec.ts
58
+ yarn migration:create # after any change in src/models
59
+ ```
60
+
61
+ - Integration tests: `index.spec.ts`, `race.spec.ts`, `retry-interval.spec.ts`; fixtures in `integration-tests/__fixtures__/`. `integration-tests/utils/database.ts` deletes `bull:*` and `dtrx:*` keys in Redis at `REDIS_URL` (default `redis://localhost:6379`), and `index.spec.ts` hardcodes `redisUrl: "localhost:6379"`.
62
+
63
+ ## Gotchas
64
+
65
+ - Workers, the job queue, and the cleaner queue only exist when `worker_mode` is not `"server"`. On a server-only instance, retries and timeouts are enqueued but processed elsewhere, and `schedule()` is a no-op (`jobQueue` is undefined).
66
+ - The loader throws when no `redisUrl` / `url` is set, but connection errors are only logged.
67
+ - Shutdown: workers close in `onApplicationPrepareShutdown` (waits for running jobs), queues and Redis connections close in `onApplicationShutdown`.
68
+ - On start it removes repeatable jobs left on the main queue by pre-2.6 versions, which scheduled jobs on that queue.
69
+ - Unlike the in-memory engine, `run` does not copy `options.runId` into the workflow context.
package/README.md CHANGED
@@ -1 +1,102 @@
1
- # Workflow Orchestrator
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/workflow-engine-redis
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ Redis Workflow Engine Module for Medusa: runs workflows and tracks their executions, subscribers, retries, timeouts, and scheduled workflow jobs using Redis and BullMQ. It's the recommended Workflow Engine Module for production and replaces the default in-memory engine. It ships with `@medusajs/medusa` but isn't registered by default, so add it to `medusa-config.ts`.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/workflow-engine-redis` |
44
+ | Type | Infrastructure Module |
45
+ | Module key | `Modules.WORKFLOW_ENGINE` (`"workflows"`) |
46
+ | Registered by default | No (on Medusa Cloud, registered automatically when `REDIS_URL` is set) |
47
+ | Import from | `@medusajs/medusa/workflow-engine-redis` |
48
+
49
+ ## Installation
50
+
51
+ No installation needed. The module ships with `@medusajs/medusa`. You need a running Redis server.
52
+
53
+ ## Usage
54
+
55
+ Register the module in `medusa-config.ts`. All options go inside the `redis` object:
56
+
57
+ ```ts
58
+ import { defineConfig } from "@medusajs/framework/utils"
59
+
60
+ module.exports = defineConfig({
61
+ // ...
62
+ modules: [
63
+ {
64
+ resolve: "@medusajs/medusa/workflow-engine-redis",
65
+ options: {
66
+ redis: {
67
+ redisUrl: process.env.WE_REDIS_URL,
68
+ },
69
+ },
70
+ },
71
+ ],
72
+ })
73
+ ```
74
+
75
+ ## Configuration
76
+
77
+ Options of the `redis` object:
78
+
79
+ | Option | Type | Description | Default |
80
+ | --- | --- | --- | --- |
81
+ | `redisUrl` | `string` | Redis connection URL. Required (the module throws on startup without it or the deprecated `url`). | - |
82
+ | `redisOptions` | `RedisOptions` | [ioredis](https://github.com/redis/ioredis) client options. | - |
83
+ | `queueName` | `string` | Name of the main queue, which handles workflow retries, step timeouts, and transaction timeouts. | `"medusa-workflows"` |
84
+ | `jobQueueName` | `string` | Name of the queue that runs scheduled workflow jobs. | `"medusa-workflows-jobs"` |
85
+ | `queueOptions` | `QueueOptions` | [BullMQ](https://docs.bullmq.io) queue options (without `connection`) applied to all queues. | - |
86
+ | `workerOptions` | `WorkerOptions` | BullMQ worker options (without `connection`) applied to all workers. | - |
87
+ | `mainQueueOptions` | `QueueOptions` | Overrides `queueOptions` for the main queue. | - |
88
+ | `mainWorkerOptions` | `WorkerOptions` | Overrides `workerOptions` for the main worker. | - |
89
+ | `jobQueueOptions` | `QueueOptions` | Overrides `queueOptions` for the scheduled jobs queue. | - |
90
+ | `jobWorkerOptions` | `WorkerOptions` | Overrides `workerOptions` for the scheduled jobs worker. | - |
91
+ | `cleanerQueueOptions` | `QueueOptions` | Overrides `queueOptions` for the queue that removes expired workflow executions. | - |
92
+ | `cleanerWorkerOptions` | `WorkerOptions` | Overrides `workerOptions` for the cleaner worker. | - |
93
+ | `pubsub` | `{ url: string, options?: RedisOptions }` | Separate Redis connection for pub/sub. | Same connection as `redisUrl` and `redisOptions` |
94
+ | `url` | `string` | Deprecated. Use `redisUrl`. | - |
95
+ | `options` | `RedisOptions` | Deprecated. Use `redisOptions`. | - |
96
+
97
+ ## Resources
98
+
99
+ - [Redis Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/redis)
100
+ - [Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine)
101
+ - [How to Use the Workflow Engine Module](https://docs.medusajs.com/resources/infrastructure-modules/workflow-engine/how-to-use)
102
+ - [Workflows](https://docs.medusajs.com/learn/fundamentals/workflows)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/workflow-engine-redis",
3
- "version": "2.22.0-snapshot-20261021091347",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa Workflow Orchestrator module using Redis to track workflows executions",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -39,8 +43,8 @@
39
43
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
40
44
  },
41
45
  "devDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261021091347",
43
- "@medusajs/test-utils": "2.22.0-snapshot-20261021091347"
46
+ "@medusajs/framework": "2.22.0",
47
+ "@medusajs/test-utils": "2.22.0"
44
48
  },
45
49
  "dependencies": {
46
50
  "bullmq": "5.13.0",
@@ -48,6 +52,6 @@
48
52
  "ulid": "^2.3.0"
49
53
  },
50
54
  "peerDependencies": {
51
- "@medusajs/framework": "2.22.0-snapshot-20261021091347"
55
+ "@medusajs/framework": "2.22.0"
52
56
  }
53
57
  }