@brickkit/redis-world 0.11.0 → 0.13.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.
@@ -0,0 +1,242 @@
1
+ import { MessageId, Queue, ValidQueueName, World } from "@workflow/world";
2
+ import { Redis, RedisOptions } from "ioredis";
3
+ /** How long finished runs are kept, using `age` and `count` limits. */
4
+ interface KeepRuns {
5
+ /** Delete runs that finished more than this many seconds ago. */
6
+ age?: number;
7
+ /** Keep at most this many of the newest runs; delete the rest. */
8
+ count?: number;
9
+ }
10
+ /**
11
+ * Retention for run data (the run, its event log, steps, hooks, and streams),
12
+ * per terminal status. A status without a policy is kept forever.
13
+ */
14
+ interface RunRetention {
15
+ completed?: KeepRuns;
16
+ failed?: KeepRuns;
17
+ cancelled?: KeepRuns;
18
+ /** How often each worker looks for expired runs (ms). Default: 60000 */
19
+ sweepIntervalMs?: number;
20
+ /** Runs deleted per status per sweep. Default: 200 */
21
+ batchSize?: number;
22
+ }
23
+ /** The options every Redis-backed world shares, whatever its queue. */
24
+ interface RedisBackedWorldConfig {
25
+ /**
26
+ * Redis connection URL or connection options
27
+ * Examples:
28
+ * - 'redis://localhost:6379'
29
+ * - 'rediss://username:password@host:6380/0'
30
+ * - { host: 'localhost', port: 6379 }
31
+ */
32
+ redis: string | RedisOptions;
33
+ /**
34
+ * Number of concurrent workers processing jobs
35
+ * Default: 10
36
+ */
37
+ queueConcurrency?: number;
38
+ /**
39
+ * Optional key prefix for all Redis keys
40
+ * Useful for multi-tenancy or namespace isolation
41
+ * Default: 'workflow:'
42
+ */
43
+ keyPrefix?: string;
44
+ /**
45
+ * Backoff strategy for retries: 'fixed' replays at the same interval,
46
+ * 'exponential' doubles the delay on each attempt.
47
+ * Default: 'exponential'
48
+ */
49
+ backoffType?: "fixed" | "exponential";
50
+ /**
51
+ * Base delay for backoff (ms). For exponential backoff this is multiplied
52
+ * by 2^(attempt - 1), up to `maxBackoffMs`.
53
+ * Default: 1000
54
+ */
55
+ backoffDelayMs?: number;
56
+ /**
57
+ * The longest a retry is delayed (ms). With the default number of attempts an
58
+ * uncapped exponential backoff would wait hours between late attempts.
59
+ * Default: 30000 (30s)
60
+ */
61
+ maxBackoffMs?: number;
62
+ /**
63
+ * Base URL the queue worker uses to dispatch jobs back to the user's HTTP
64
+ * server, which must serve `world.createQueueHandler(...)` at
65
+ * `/.well-known/workflow/v1/flow` (steps travel on the same route). A route
66
+ * registered with `world.registerRoute`, or an in-process handler registered
67
+ * with `world.registerHandler`, takes precedence.
68
+ * Default: process.env.WORKFLOW_BASE_URL || `http://localhost:${process.env.PORT ?? 3000}`
69
+ */
70
+ baseUrl?: string;
71
+ /**
72
+ * Per-job HTTP request timeout (ms). Long-running workflow steps may need a
73
+ * higher value.
74
+ * Default: 300_000 (5 minutes)
75
+ */
76
+ httpTimeoutMs?: number;
77
+ /** Maximum events a run may accumulate, reported as `EventResult.maxEvents`.
78
+ * Default: `WORKFLOW_MAX_EVENTS` || 25_000 */
79
+ maxEventsPerRun?: number;
80
+ /**
81
+ * Batch commands issued in the same event-loop tick into one write. A win
82
+ * once several runs are in flight (~1.75x at 256 concurrent) and a marginal
83
+ * loss for a single serial caller.
84
+ * Default: true
85
+ */
86
+ enableAutoPipelining?: boolean;
87
+ /**
88
+ * How long finished runs are kept, per terminal status: `age` in seconds,
89
+ * `count` of newest runs to keep. A reaper on each worker deletes the run, its event log, steps, hooks
90
+ * and streams once it passes. A status without a policy is kept forever.
91
+ * Default: undefined (nothing expires)
92
+ *
93
+ * @example
94
+ * retention: {
95
+ * completed: { age: 24 * 60 * 60, count: 1000 },
96
+ * failed: { age: 7 * 24 * 60 * 60 },
97
+ * }
98
+ */
99
+ retention?: RunRetention;
100
+ /**
101
+ * Delivery budget per message (see each world for what happens past it).
102
+ * At least 49: the runtime records a run as failed (`MAX_DELIVERIES_EXCEEDED`)
103
+ * on delivery 49, and a message retired earlier strands its run in `running`.
104
+ * Default: 73
105
+ */
106
+ maxAttempts?: number;
107
+ /**
108
+ * Optional TTL (ms) for queue deduplication when `idempotencyKey`
109
+ * is supplied to `queue()`. By default no TTL is applied: the dedup key
110
+ * lives until the job is acknowledged, so duplicate enqueues are dropped
111
+ * for the entire lifetime of the pending/delayed job (the semantics the
112
+ * workflow runtime relies on when re-enqueuing pending steps on replay).
113
+ * Only set this if you need the dedup guard to expire on wall-clock time;
114
+ * it must be much larger than the longest expected queue delay/backlog,
115
+ * otherwise duplicate step executions become possible.
116
+ * Default: undefined (dedup key released on job completion)
117
+ */
118
+ idempotencyTtlMs?: number;
119
+ }
120
+ interface RedisWorldConfig extends RedisBackedWorldConfig {
121
+ /** Worker liveness TTL in milliseconds. Default 90000; minimum 300.
122
+ * Set above the longest event-loop pause. Renewed every TTL / 3. */
123
+ heartbeatTtlMs?: number;
124
+ /**
125
+ * Delivery budget before retries continue at maxBackoffMs. Messages are never
126
+ * silently retired. At least 49. Default: 73
127
+ */
128
+ maxAttempts?: number;
129
+ }
130
+ /**
131
+ * The config the `WORKFLOW_REDIS_*` variables give. `createWorld` lays the
132
+ * config it is passed over this, so an option left out still comes from env.
133
+ */
134
+ declare function configFromEnv(): {
135
+ redis: string;
136
+ queueConcurrency: number | undefined;
137
+ keyPrefix: string | undefined;
138
+ };
139
+ declare const DEFAULTS: {
140
+ readonly queueConcurrency: 10;
141
+ readonly keyPrefix: "workflow:";
142
+ readonly backoffType: "exponential";
143
+ readonly backoffDelayMs: 1000;
144
+ readonly maxBackoffMs: 30000;
145
+ readonly httpTimeoutMs: 300000;
146
+ readonly maxAttempts: 73;
147
+ readonly enableAutoPipelining: true;
148
+ };
149
+ /** A world config with every shared default filled in. */
150
+ type ResolvedConfig<C extends RedisBackedWorldConfig> = C & { -readonly [K in keyof typeof DEFAULTS]-?: NonNullable<RedisBackedWorldConfig[K]>; };
151
+ /** Fills the shared defaults and checks the shared limits, for every queue. */
152
+ declare function resolveConfig<C extends RedisBackedWorldConfig>(config: C): ResolvedConfig<C>;
153
+ interface QueueStats {
154
+ waiting: number;
155
+ active: number;
156
+ delayed: number;
157
+ /** Finished delivery records the queue still holds; redis-world keeps none. */
158
+ completed: number;
159
+ failed: number;
160
+ }
161
+ /** A message as a queue backend stores it. */
162
+ interface QueuedMessage {
163
+ messageId: MessageId;
164
+ queueName: ValidQueueName;
165
+ /** The payload, already serialized; forwarded verbatim as the request body. */
166
+ message: string;
167
+ /** Extra headers the producer asked to forward; the `x-vqs-*` ones override them. */
168
+ headers?: Record<string, string>;
169
+ /** The route registered for this prefix when it was queued (`registerRoute`). */
170
+ route?: string;
171
+ }
172
+ /** One delivery of a stored message, with the counters the backend keeps. */
173
+ interface Delivery extends QueuedMessage {
174
+ /** Failed deliveries plus this one, crashes included; reschedules don't count. */
175
+ attempt: number;
176
+ /** Every delivery that reached a handler, reschedules included. */
177
+ deliveryCount: number;
178
+ /** When the message was first queued (epoch ms). */
179
+ createdAt: number;
180
+ }
181
+ /**
182
+ * Delivers a message to its handler. Resolves to the seconds after which the
183
+ * same message is to be delivered again without consuming an attempt, or
184
+ * `undefined` to acknowledge it. Throws when the delivery failed and must be
185
+ * retried.
186
+ */
187
+ type Deliver = (delivery: Delivery) => Promise<number | undefined>;
188
+ /** The part of a world's queue that differs between Redis queue implementations. */
189
+ interface QueueBackend {
190
+ /** Store a message. Resolves to the id of the queued message: on an
191
+ * `idempotencyKey` hit, the one already queued. */
192
+ enqueue(message: QueuedMessage, opts: {
193
+ idempotencyKey?: string;
194
+ delaySeconds?: number;
195
+ }): Promise<MessageId>;
196
+ /** Start delivering stored messages through `deliver`. */
197
+ start(deliver: Deliver): Promise<void>;
198
+ close(): Promise<void>;
199
+ getQueueStats(): Promise<QueueStats>;
200
+ }
201
+ type WorldQueue = Queue & {
202
+ start(): Promise<void>;
203
+ close(): Promise<void>;
204
+ getQueueStats(): Promise<QueueStats>;
205
+ };
206
+ interface WorldQueueOptions {
207
+ /**
208
+ * Whether a run has moved past `pending`. The first message of a run is not
209
+ * queued again once it has, see `initialMessageKey`.
210
+ */
211
+ runHasStarted?: (runId: string) => Promise<boolean>;
212
+ }
213
+ /**
214
+ * The Workflow SDK `Queue` on top of a backend: message ids, the first-message
215
+ * guard, the payload transport, HTTP or in-process delivery with the `x-vqs-*`
216
+ * headers, and the handler that answers those deliveries.
217
+ */
218
+ declare function createWorldQueue(backend: QueueBackend, config: Pick<ResolvedConfig<RedisBackedWorldConfig>, "baseUrl" | "httpTimeoutMs">, options: WorldQueueOptions & {
219
+ debug: (...args: unknown[]) => void;
220
+ }): WorldQueue;
221
+ /** The delay before retrying a failed delivery: the configured curve, capped. */
222
+ declare function retryDelayMs(attempt: number, config: Pick<ResolvedConfig<RedisBackedWorldConfig>, "backoffType" | "backoffDelayMs" | "maxBackoffMs">): number;
223
+ type RedisBackedWorld = World & {
224
+ start(): Promise<void>;
225
+ getQueueStats(): Promise<QueueStats>;
226
+ /** Run one retention sweep now; returns the runs deleted. 0 without `retention`. */
227
+ sweepRetention(): Promise<number>;
228
+ };
229
+ /**
230
+ * A world on Redis: storage, streams and retention are the same for every
231
+ * queue; `createQueue` supplies the queue. `config` is laid over `env`, so an
232
+ * option the caller leaves out still comes from the environment.
233
+ */
234
+ declare function createRedisBackedWorld<C extends RedisBackedWorldConfig>(config: Partial<C>, world: {
235
+ env: C;
236
+ createQueue(redis: Redis, config: ResolvedConfig<C>, options: WorldQueueOptions): WorldQueue;
237
+ /** Log prefix for run recovery on start. */
238
+ label: string;
239
+ debug: (...args: unknown[]) => void;
240
+ }): RedisBackedWorld;
241
+ export { RunRetention as _, QueueStats as a, WorldQueueOptions as c, RedisBackedWorldConfig as d, RedisWorldConfig as f, KeepRuns as g, resolveConfig as h, QueueBackend as i, createWorldQueue as l, configFromEnv as m, createRedisBackedWorld as n, QueuedMessage as o, ResolvedConfig as p, Deliver as r, WorldQueue as s, RedisBackedWorld as t, retryDelayMs as u };
242
+ //# sourceMappingURL=world-BDW_evdb.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"world-BDW_evdb.d.ts","names":[],"sources":["../src/reaper.ts","../src/config.ts","../src/world-queue.ts","../src/world.ts"],"mappings":";;;UAIiB;;EAEf;;EAEA;;;;;;UAOe;EACf,YAAY;EACZ,SAAS;EACT,YAAY;;EAEZ;;EAEA;;;UClBe;;;;;;;;EAQf,gBAAgB;;;;;EAMhB;;;;;;EAOA;;;;;;EAOA;;;;;;EAOA;;;;;;EAOA;;;;;;;;;EAUA;;;;;;EAOA;;;EAIA;;;;;;;EAQA;;;;;;;;;;;;;EAcA,YAAY;;;;;;;EAQZ;;;;;;;;;;;;EAaA;;UAGe,yBAAyB;;;EAGxC;;;;;EAMA;;;;;;iBAOc;EAEZ;EAIA;EAKA;;cAIE;WACJ;WACA;WACA;WACA;WACA;WACA;WACA;WACA;;;KAIU,eAAe,UAAU,0BAA0B,iBAClD,kBAAkB,aAAa,YACxC,uBAAuB;;iBAKX,cAAc,UAAU,wBACtC,QAAQ,IACP,eAAe;UCnJD;EACf;EACA;EACA;;EAEA;EACA;;;UAIe;EACf,WAAW;EACX,WAAW;;EAEX;;EAEA,UAAU;;EAEV;;;UAIe,iBAAiB;;EAEhC;;EAEA;;EAEA;;;;;;;;KASU,WAAW,UAAU,aAAa;;UAG7B;;;EAGf,QACE,SAAS,eACT;IAAQ;IAAyB;MAChC,QAAQ;;EAEX,MAAM,SAAS,UAAU;EACzB,SAAS;EACT,iBAAiB,QAAQ;;KAGf,aAAa;EACvB,SAAS;EACT,SAAS;EACT,iBAAiB,QAAQ;;UAGV;;;;;EAKf,iBAAiB,kBAAkB;;;;;;;iBAoBrB,iBACd,SAAS,cACT,QAAQ,KACN,eAAe,uDAGjB,SAAS;EAAsB,WAAW;IACzC;;iBA2Ka,aACd,iBACA,QAAQ,KACN,eAAe;KChQP,mBAAmB;EAC7B,SAAS;EACT,iBAAiB,QAAQ;;EAEzB,kBAAkB;;;;;;;iBAQJ,uBAAuB,UAAU,wBAC/C,QAAQ,QAAQ,IAChB;EACE,KAAK;EACL,YACE,OAAO,OACP,QAAQ,eAAe,IACvB,SAAS,oBACR;;EAEH;EACA,WAAW;IAEZ"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brickkit/redis-world",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "Plain Redis World for Workflow SDK v5 with a reliable list queue and durable storage",
5
5
  "homepage": "https://brickkit.dev",
6
6
  "keywords": [
@@ -32,6 +32,10 @@
32
32
  "./cli": {
33
33
  "types": "./dist/cli.d.ts",
34
34
  "default": "./dist/cli.js"
35
+ },
36
+ "./internal": {
37
+ "types": "./dist/internal.d.ts",
38
+ "default": "./dist/internal.js"
35
39
  }
36
40
  },
37
41
  "publishConfig": {
@@ -47,23 +51,23 @@
47
51
  "test:e2e": "bun run build && vitest run --config vitest.e2e.config.ts"
48
52
  },
49
53
  "dependencies": {
50
- "@workflow/errors": "5.0.4",
54
+ "@workflow/errors": "5.1.0",
51
55
  "@workflow/utils": "5.0.2",
52
- "@workflow/world": "5.0.4",
56
+ "@workflow/world": "5.1.0",
53
57
  "ioredis": "^6.0.0",
54
58
  "ulid": "^3.0.2"
55
59
  },
56
60
  "devDependencies": {
57
- "@hono/node-server": "^2.1.5",
58
- "@testcontainers/redis": "^12.1.0",
59
- "@types/node": "^26.6.5",
60
- "@workflow/cli": "5.0.5",
61
- "@workflow/core": "5.2.2",
62
- "@workflow/world-testing": "5.0.5",
63
- "hono": "^4.13.13",
64
- "tsdown": "^0.23.1",
65
- "typescript": "^5.7.0",
66
- "vitest": "^4.1.11",
67
- "workflow": "5.2.2"
61
+ "@hono/node-server": "^2.1.6",
62
+ "@testcontainers/redis": "^12.2.1",
63
+ "@types/node": "^26.6.6",
64
+ "@workflow/cli": "5.0.7",
65
+ "@workflow/core": "5.3.0",
66
+ "@workflow/world-testing": "5.0.7",
67
+ "hono": "^4.13.16",
68
+ "tsdown": "^0.23.5",
69
+ "typescript": "^7.0.2",
70
+ "vitest": "^4.1.12",
71
+ "workflow": "5.3.0"
68
72
  }
69
73
  }
package/dist/cli.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"cli.js","names":[],"sources":["../src/internal/env.ts","../src/cli.ts"],"sourcesContent":["/**\n * Load an env file when present without making a `.env` file mandatory.\n *\n * Node 24 provides the parser natively, so published worlds do not need a\n * runtime dependency solely to load local development configuration.\n */\nexport function loadOptionalEnvFile(path?: string): void {\n try {\n if (path === undefined) {\n process.loadEnvFile();\n } else {\n process.loadEnvFile(path);\n }\n } catch (error: unknown) {\n if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n throw error;\n }\n }\n}\n","import { loadOptionalEnvFile } from \"./internal/env.js\";\nimport { Redis } from \"ioredis\";\n\nasync function setupRedis() {\n // Load .env file if it exists.\n loadOptionalEnvFile();\n\n const connectionString =\n process.env.WORKFLOW_REDIS_URL ||\n process.env.REDIS_URL ||\n \"redis://localhost:6379\";\n\n const keyPrefix = process.env.WORKFLOW_REDIS_KEY_PREFIX || \"workflow:\";\n\n console.log(\"Setting up Redis for Workflow...\");\n console.log(\n `Connection: ${connectionString.replace(/^(\\w+:\\/\\/)([^@]+)@/, \"$1[redacted]@\")}`,\n );\n console.log(`Key Prefix: ${keyPrefix}`);\n\n let redis: Redis | undefined;\n let exitCode = 0;\n\n try {\n redis = new Redis(connectionString);\n\n // Test connection\n await redis.ping();\n console.log(\"Successfully connected to Redis!\");\n\n // Get Redis info\n const info = await redis.info(\"server\");\n const version = info.match(/redis_version:([^\\r\\n]+)/)?.[1];\n if (version) {\n console.log(`Redis version: ${version}`);\n }\n\n // Check if any workflow keys exist\n const existingKeys = await redis.keys(`${keyPrefix}*`);\n if (existingKeys.length > 0) {\n console.log(\n `\\nWarning: found ${existingKeys.length} existing workflow keys with prefix \"${keyPrefix}\"`,\n );\n console.log(\n \"\\nTo flush existing workflow data, run with FLUSH=true environment variable:\",\n );\n console.log(\" FLUSH=true npx brickkit-redis-world-setup\");\n\n if (process.env.FLUSH === \"true\") {\n console.log(\"\\nFlushing existing workflow data...\");\n const pipeline = redis.pipeline();\n for (const key of existingKeys) {\n pipeline.del(key);\n }\n await pipeline.exec();\n console.log(`Deleted ${existingKeys.length} keys`);\n }\n } else {\n console.log(`\\nNo existing workflow data found (clean slate)`);\n }\n\n console.log(\"\\nRedis is ready for Workflow DevKit!\");\n console.log(\"\\nThe following Redis data structures will be used:\");\n console.log(\n ` - Hashes: ${keyPrefix}run:*, ${keyPrefix}step:*, ${keyPrefix}event:*, ${keyPrefix}hook:*`,\n );\n console.log(\n ` - Sorted Sets: ${keyPrefix}runs:*, ${keyPrefix}steps:*, ${keyPrefix}events:*`,\n );\n console.log(` - Streams: ${keyPrefix}stream:*`);\n console.log(\n ` - Redis queue: ${keyPrefix}queue:flows, processing lists and delayed set`,\n );\n } catch (error) {\n exitCode = 1;\n console.error(\"Failed to setup Redis:\", error);\n } finally {\n await redis?.quit().catch(() => {});\n }\n\n process.exit(exitCode);\n}\n\n// Check if running as main module\nif (import.meta.url === `file://${process.argv[1]}`) {\n setupRedis();\n}\n\nexport { setupRedis };\n"],"mappings":";;;;;;;;AAMA,SAAgB,oBAAoB,MAAqB;CACvD,IAAI;EACF,IAAI,SAAS,KAAA,GACX,QAAQ,YAAY;OAEpB,QAAQ,YAAY,IAAI;CAE5B,SAAS,OAAgB;EACvB,IAAK,MAAgC,SAAS,UAC5C,MAAM;CAEV;AACF;;;ACfA,eAAe,aAAa;CAE1B,oBAAoB;CAEpB,MAAM,mBACJ,QAAQ,IAAI,sBACZ,QAAQ,IAAI,aACZ;CAEF,MAAM,YAAY,QAAQ,IAAI,6BAA6B;CAE3D,QAAQ,IAAI,kCAAkC;CAC9C,QAAQ,IACN,eAAe,iBAAiB,QAAQ,uBAAuB,eAAe,GAChF;CACA,QAAQ,IAAI,eAAe,WAAW;CAEtC,IAAI;CACJ,IAAI,WAAW;CAEf,IAAI;EACF,QAAQ,IAAI,MAAM,gBAAgB;EAGlC,MAAM,MAAM,KAAK;EACjB,QAAQ,IAAI,kCAAkC;EAI9C,MAAM,WAAU,MADG,MAAM,KAAK,QAAQ,EAAA,CACjB,MAAM,0BAA0B,CAAC,GAAG;EACzD,IAAI,SACF,QAAQ,IAAI,kBAAkB,SAAS;EAIzC,MAAM,eAAe,MAAM,MAAM,KAAK,GAAG,UAAU,EAAE;EACrD,IAAI,aAAa,SAAS,GAAG;GAC3B,QAAQ,IACN,oBAAoB,aAAa,OAAO,uCAAuC,UAAU,EAC3F;GACA,QAAQ,IACN,8EACF;GACA,QAAQ,IAAI,6CAA6C;GAEzD,IAAI,QAAQ,IAAI,UAAU,QAAQ;IAChC,QAAQ,IAAI,sCAAsC;IAClD,MAAM,WAAW,MAAM,SAAS;IAChC,KAAK,MAAM,OAAO,cAChB,SAAS,IAAI,GAAG;IAElB,MAAM,SAAS,KAAK;IACpB,QAAQ,IAAI,WAAW,aAAa,OAAO,MAAM;GACnD;EACF,OACE,QAAQ,IAAI,iDAAiD;EAG/D,QAAQ,IAAI,uCAAuC;EACnD,QAAQ,IAAI,qDAAqD;EACjE,QAAQ,IACN,eAAe,UAAU,SAAS,UAAU,UAAU,UAAU,WAAW,UAAU,OACvF;EACA,QAAQ,IACN,oBAAoB,UAAU,UAAU,UAAU,WAAW,UAAU,SACzE;EACA,QAAQ,IAAI,gBAAgB,UAAU,SAAS;EAC/C,QAAQ,IACN,oBAAoB,UAAU,8CAChC;CACF,SAAS,OAAO;EACd,WAAW;EACX,QAAQ,MAAM,0BAA0B,KAAK;CAC/C,UAAU;EACR,MAAM,OAAO,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;CACpC;CAEA,QAAQ,KAAK,QAAQ;AACvB;AAGA,IAAI,YAAY,QAAQ,UAAU,QAAQ,KAAK,MAC7C,WAAW"}