@antelopejs/interface-redis-scheduler 0.0.9 → 0.0.10
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.
- package/README.md +22 -20
- package/dist/index.js +14 -21
- package/dist/index.js.map +1 -1
- package/dist/tests/index.test.js +128 -124
- package/dist/tests/index.test.js.map +1 -1
- package/docs/1.introduction.md +97 -73
- package/docs/assets/task-delivery.svg +3 -3
- package/docs/tsconfig.json +7 -0
- package/package.json +9 -6
- package/skills/redis-scheduler-interface/SKILL.md +49 -29
- package/skills/redis-scheduler-interface/cases.json +57 -0
package/README.md
CHANGED
|
@@ -1,26 +1,26 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@antelopejs/interface-redis-scheduler`
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<a href="https://www.npmjs.com/package/@antelopejs/interface-redis-scheduler"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-redis-scheduler?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-redis-scheduler?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
-
<a href="https://discord.gg/
|
|
7
|
-
<a href="https://interfaces.antelopejs.com/docs/redis-scheduler"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
4
|
+
<a href="https://www.npmjs.com/package/@antelopejs/interface-redis-scheduler"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-redis-scheduler?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
5
|
+
<a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-redis-scheduler?style=for-the-badge&labelColor=000000&color=000000"></a>
|
|
6
|
+
<a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
7
|
+
<a href="https://interfaces.antelopejs.com/docs/redis-scheduler"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
8
8
|
</div>
|
|
9
9
|
|
|
10
|
-
Task scheduling on Redis for AntelopeJS
|
|
10
|
+
Task scheduling on Redis for AntelopeJS. You schedule a task for a given time, and a listener in your application runs it when it is due, with up to three retries on failure.
|
|
11
11
|
|
|
12
12
|
## What it offers
|
|
13
13
|
|
|
14
14
|
- `setHandler` registers the function that runs one kind of task.
|
|
15
|
-
- `addTask` schedules a task for a Unix timestamp in milliseconds
|
|
16
|
-
- `enableListener` starts task processing
|
|
17
|
-
- Tasks live in a Redis sorted set, so they survive restarts and every instance of the application sees the same queue.
|
|
15
|
+
- `addTask` schedules a task for a Unix timestamp in milliseconds. `removeTask` removes the queued entry before it runs.
|
|
16
|
+
- `enableListener` starts task processing. `disableListener` closes only the notification subscriber, not the pending timer.
|
|
17
|
+
- Tasks live in a Redis sorted set, so they survive application restarts and every instance of the application sees the same queue. Each due task goes to one listener.
|
|
18
18
|
|
|
19
19
|
## Implementations
|
|
20
20
|
|
|
21
|
-
| Module | Notes
|
|
22
|
-
| ---------------------------------------------------------- |
|
|
23
|
-
| [`@antelopejs/redis`](https://github.com/AntelopeJS/redis) | Also implements `@antelopejs/interface-redis
|
|
21
|
+
| Module | Notes |
|
|
22
|
+
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| [`@antelopejs/redis`](https://github.com/AntelopeJS/redis) | Also implements `@antelopejs/interface-redis`, which supplies the Redis client the scheduler uses |
|
|
24
24
|
|
|
25
25
|
## Install
|
|
26
26
|
|
|
@@ -68,9 +68,9 @@ export async function stop() {
|
|
|
68
68
|
}
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
-
Register a handler before you schedule tasks for it
|
|
71
|
+
Register a handler before you schedule tasks for it. `addTask` rejects for a handler name that this process has not registered.
|
|
72
72
|
|
|
73
|
-
`disableListener()` is not a full shutdown or pause
|
|
73
|
+
`disableListener()` is not a full shutdown or pause. A pending timer and running handlers can continue to process tasks. Read the [lifecycle and delivery limits](./docs/1.introduction.md#disablelistener) before you use it for shutdown.
|
|
74
74
|
|
|
75
75
|
## Documentation
|
|
76
76
|
|
|
@@ -78,14 +78,16 @@ Register a handler before you schedule tasks for it: `addTask` throws for an unk
|
|
|
78
78
|
|
|
79
79
|
## Compatibility
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
The module declares these peer dependencies:
|
|
82
82
|
|
|
83
|
-
<!-- docs-compat:
|
|
83
|
+
<!-- antelopejs-docs-compat:start -->
|
|
84
84
|
|
|
85
|
-
| Package |
|
|
86
|
-
| ----------------------------- | ---------------- |
|
|
87
|
-
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
88
|
-
| `@antelopejs/interface-redis` | `>=0.0.9 <1.0.0` |
|
|
85
|
+
| Package | Supported | Tested with |
|
|
86
|
+
| ----------------------------- | ---------------- | ----------- |
|
|
87
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.2.4` |
|
|
88
|
+
| `@antelopejs/interface-redis` | `>=0.0.9 <1.0.0` | `0.0.9` |
|
|
89
|
+
|
|
90
|
+
<!-- antelopejs-docs-compat:end -->
|
|
89
91
|
|
|
90
92
|
## Contributing
|
|
91
93
|
|
package/dist/index.js
CHANGED
|
@@ -57,9 +57,6 @@ function setHandler(handlerName, handler) {
|
|
|
57
57
|
}
|
|
58
58
|
/** Redis subscriber client for receiving task updates */
|
|
59
59
|
let subscriber;
|
|
60
|
-
const SubscriberMessageHandlers = {
|
|
61
|
-
[SchedulerUpdateMessage]: () => void updateTimer(),
|
|
62
|
-
};
|
|
63
60
|
function createTaskMember(handlerName, taskInfo) {
|
|
64
61
|
return `${handlerName}:${taskInfo}`;
|
|
65
62
|
}
|
|
@@ -90,11 +87,9 @@ async function enableListener() {
|
|
|
90
87
|
if (channel !== SchedulerChannel) {
|
|
91
88
|
return;
|
|
92
89
|
}
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
return;
|
|
90
|
+
if (message === SchedulerUpdateMessage) {
|
|
91
|
+
void updateTimer();
|
|
96
92
|
}
|
|
97
|
-
handler();
|
|
98
93
|
});
|
|
99
94
|
void updateTimer();
|
|
100
95
|
}
|
|
@@ -235,21 +230,19 @@ async function runTasks() {
|
|
|
235
230
|
locked = true;
|
|
236
231
|
const client = await (0, interface_redis_1.GetClient)();
|
|
237
232
|
const tasks = await takeDueTasks(client);
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
await handlers.get(m[2])?.(m[3]);
|
|
244
|
-
}
|
|
233
|
+
for (const task of tasks) {
|
|
234
|
+
const m = task.match(RetryPattern);
|
|
235
|
+
try {
|
|
236
|
+
if (m && handlers.has(m[2])) {
|
|
237
|
+
await handlers.get(m[2])?.(m[3]);
|
|
245
238
|
}
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
}
|
|
239
|
+
}
|
|
240
|
+
catch (err) {
|
|
241
|
+
logging_1.Logging.Error(err);
|
|
242
|
+
if (m) {
|
|
243
|
+
const retryCount = m[1] ? parseInt(m[1], 10) : 0;
|
|
244
|
+
if (retryCount < MaxRetries) {
|
|
245
|
+
await client.zadd(RedisKey, Date.now() + RetryDelayMs, `RETRY-${retryCount + 1}:${m[2]}:${m[3]}`);
|
|
253
246
|
}
|
|
254
247
|
}
|
|
255
248
|
}
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAyDA,gCAEC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAyDA,gCAEC;AA4BD,wCAcC;AAkBD,0CAEC;AA8BD,0BAcC;AA0BD,gCAMC;AAWD,kCAyBC;AAkBD,4BA0BC;AApRD,iEAAwD;AACxD,gEAA6D;AAC7D,+DAA8D;AAQ9D,8DAA8D;AAC9D,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AACvC,MAAM,gBAAgB,GAAG,eAAe,CAAC;AACzC,MAAM,sBAAsB,GAAG,QAAQ,CAAC;AACxC,MAAM,UAAU,GAAG,CAAC,CAAC;AACrB,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,eAAe,GAAG,QAAQ,CAAC;AACjC,MAAM,YAAY,GAAG,iCAAiC,CAAC;AAEvD,8CAA8C;AAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;AAChD,wDAAwD;AACxD,MAAM,KAAK,GAAG,IAAI,iCAAgB,EAE/B,CAAC;AACJ,KAAK,CAAC,UAAU,CAAC,CAAC,WAAmB,EAAE,OAAoB,EAAE,EAAE;IAC7D,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACrC,CAAC,EAAE,IAAI,CAAC,CAAC;AACT,KAAK,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,EAAE;IACjC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,UAAU,CAAC,WAAmB,EAAE,OAAoB;IAClE,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED,yDAAyD;AACzD,IAAI,UAAiB,CAAC;AAEtB,SAAS,gBAAgB,CAAC,WAAmB,EAAE,QAAgB;IAC7D,OAAO,GAAG,WAAW,IAAI,QAAQ,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACI,KAAK,UAAU,cAAc;IAClC,UAAU,GAAG,CAAC,MAAM,IAAA,2BAAS,GAAE,CAAC,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;IAC3B,MAAM,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QAC5C,IAAI,OAAO,KAAK,gBAAgB,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QACD,IAAI,OAAO,KAAK,sBAAsB,EAAE,CAAC;YACvC,KAAK,WAAW,EAAE,CAAC;QACrB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,KAAK,WAAW,EAAE,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,eAAe;IACnC,MAAM,UAAU,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACI,KAAK,UAAU,OAAO,CAC3B,WAAmB,EACnB,OAAe,EACf,QAAgB;IAEhB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,kCAAkC,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,KAAK,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,sBAAsB,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,UAAU,UAAU,CAAC,WAAmB,EAAE,QAAgB;IACpE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,kCAAkC,WAAW,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,gDAAgD;AAChD,IAAI,MAAM,GAAG,KAAK,CAAC;AACnB,+CAA+C;AAC/C,IAAI,KAAqB,CAAC;AAE1B;;;GAGG;AACI,KAAK,UAAU,WAAW;IAC/B,IAAI,MAAM,EAAE,CAAC;QACX,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACvB,MAAM,QAAQ,EAAE,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,EACrB,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,kBAAkB,GAAG;;;;CAI1B,CAAC;AAEF,KAAK,UAAU,YAAY,CAAC,MAAa;IACvC,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7E,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,QAAQ;IAC5B,MAAM,GAAG,IAAI,CAAC;IACd,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5B,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,iBAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjD,IAAI,UAAU,GAAG,UAAU,EAAE,CAAC;oBAC5B,MAAM,MAAM,CAAC,IAAI,CACf,QAAQ,EACR,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,EACzB,SAAS,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAC1C,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,GAAG,KAAK,CAAC;IACf,MAAM,WAAW,EAAE,CAAC;AACtB,CAAC"}
|
package/dist/tests/index.test.js
CHANGED
|
@@ -9,24 +9,112 @@ async function cleanupRedis() {
|
|
|
9
9
|
await client.del(RedisKey);
|
|
10
10
|
}
|
|
11
11
|
describe("Redis Scheduler - setHandler", () => {
|
|
12
|
-
it("should register a handler", async () =>
|
|
13
|
-
|
|
12
|
+
it("should register a handler", async () => {
|
|
13
|
+
let called = false;
|
|
14
|
+
(0, index_1.setHandler)("test-register", () => {
|
|
15
|
+
called = true;
|
|
16
|
+
});
|
|
17
|
+
(0, chai_1.expect)(called).to.equal(false);
|
|
18
|
+
});
|
|
19
|
+
it("should reject handler names containing :", async () => {
|
|
20
|
+
(0, chai_1.expect)(() => (0, index_1.setHandler)("invalid:name", () => { })).to.throw("may not contain");
|
|
21
|
+
});
|
|
14
22
|
});
|
|
15
23
|
describe("Redis Scheduler - addTask", () => {
|
|
16
|
-
it("should add a task to the sorted set", async () =>
|
|
17
|
-
|
|
24
|
+
it("should add a task to the sorted set", async () => {
|
|
25
|
+
await cleanupRedis();
|
|
26
|
+
(0, index_1.setHandler)("test-add", () => { });
|
|
27
|
+
const dueTime = Date.now() + 60000;
|
|
28
|
+
await (0, index_1.addTask)("test-add", dueTime, "task-data");
|
|
29
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
30
|
+
const members = await client.zrange(RedisKey, 0, -1);
|
|
31
|
+
(0, chai_1.expect)(members).to.include("test-add:task-data");
|
|
32
|
+
await cleanupRedis();
|
|
33
|
+
});
|
|
34
|
+
it("should throw for unknown handler", async () => {
|
|
35
|
+
(0, chai_1.expect)(await rejectionMessage((0, index_1.addTask)("nonexistent-handler", Date.now(), "data"))).to.include("Unknown SchedulerUtil handler");
|
|
36
|
+
});
|
|
18
37
|
});
|
|
19
38
|
describe("Redis Scheduler - removeTask", () => {
|
|
20
|
-
it("should remove a task from the sorted set", async () =>
|
|
21
|
-
|
|
39
|
+
it("should remove a task from the sorted set", async () => {
|
|
40
|
+
await cleanupRedis();
|
|
41
|
+
(0, index_1.setHandler)("test-remove", () => { });
|
|
42
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
43
|
+
await client.zadd(RedisKey, Date.now() + 60000, "test-remove:remove-data");
|
|
44
|
+
await (0, index_1.removeTask)("test-remove", "remove-data");
|
|
45
|
+
const members = await client.zrange(RedisKey, 0, -1);
|
|
46
|
+
(0, chai_1.expect)(members).to.not.include("test-remove:remove-data");
|
|
47
|
+
await cleanupRedis();
|
|
48
|
+
});
|
|
49
|
+
it("should throw for unknown handler", async () => {
|
|
50
|
+
(0, chai_1.expect)(await rejectionMessage((0, index_1.removeTask)("nonexistent-handler", "data"))).to.include("Unknown SchedulerUtil handler");
|
|
51
|
+
});
|
|
22
52
|
});
|
|
23
53
|
describe("Redis Scheduler - enableListener / disableListener", () => {
|
|
24
|
-
it("should enable and disable the listener", async () =>
|
|
25
|
-
|
|
54
|
+
it("should enable and disable the listener", async () => {
|
|
55
|
+
await cleanupRedis();
|
|
56
|
+
const executed = new Promise((resolve) => {
|
|
57
|
+
(0, index_1.setHandler)("test-listener", resolve);
|
|
58
|
+
});
|
|
59
|
+
await (0, index_1.enableListener)();
|
|
60
|
+
try {
|
|
61
|
+
await (0, index_1.addTask)("test-listener", Date.now() - 1000, "notified");
|
|
62
|
+
(0, chai_1.expect)(await executed).to.equal("notified");
|
|
63
|
+
}
|
|
64
|
+
finally {
|
|
65
|
+
await (0, index_1.disableListener)();
|
|
66
|
+
}
|
|
67
|
+
await cleanupRedis();
|
|
68
|
+
});
|
|
69
|
+
it("should use lazyConnect when duplicating client", async () => {
|
|
70
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
71
|
+
const originalDuplicate = client.duplicate.bind(client);
|
|
72
|
+
let duplicateOptions;
|
|
73
|
+
client.duplicate = (override) => {
|
|
74
|
+
duplicateOptions = override;
|
|
75
|
+
return originalDuplicate(override);
|
|
76
|
+
};
|
|
77
|
+
try {
|
|
78
|
+
await (0, index_1.enableListener)();
|
|
79
|
+
(0, chai_1.expect)(duplicateOptions).to.deep.include({ lazyConnect: true });
|
|
80
|
+
await (0, index_1.disableListener)();
|
|
81
|
+
}
|
|
82
|
+
finally {
|
|
83
|
+
client.duplicate = originalDuplicate;
|
|
84
|
+
}
|
|
85
|
+
});
|
|
26
86
|
});
|
|
27
87
|
describe("Redis Scheduler - runTasks", () => {
|
|
28
|
-
it("should execute due tasks", async () =>
|
|
29
|
-
|
|
88
|
+
it("should execute due tasks", async () => {
|
|
89
|
+
await cleanupRedis();
|
|
90
|
+
const results = [];
|
|
91
|
+
(0, index_1.setHandler)("test-run", (taskInfo) => {
|
|
92
|
+
results.push(taskInfo);
|
|
93
|
+
});
|
|
94
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
95
|
+
await client.zadd(RedisKey, Date.now() - 1000, "test-run:payload1");
|
|
96
|
+
await client.zadd(RedisKey, Date.now() - 500, "test-run:payload2");
|
|
97
|
+
await (0, index_1.runTasks)();
|
|
98
|
+
(0, chai_1.expect)(results).to.include("payload1");
|
|
99
|
+
(0, chai_1.expect)(results).to.include("payload2");
|
|
100
|
+
const remaining = await client.zrange(RedisKey, 0, -1);
|
|
101
|
+
(0, chai_1.expect)(remaining).to.have.length(0);
|
|
102
|
+
await cleanupRedis();
|
|
103
|
+
});
|
|
104
|
+
it("should not execute future tasks", async () => {
|
|
105
|
+
await cleanupRedis();
|
|
106
|
+
const results = [];
|
|
107
|
+
(0, index_1.setHandler)("test-future", (taskInfo) => {
|
|
108
|
+
results.push(taskInfo);
|
|
109
|
+
});
|
|
110
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
111
|
+
await client.zadd(RedisKey, Date.now() + 60000, "test-future:future-data");
|
|
112
|
+
await (0, index_1.runTasks)();
|
|
113
|
+
(0, chai_1.expect)(results).to.have.length(0);
|
|
114
|
+
const remaining = await client.zrange(RedisKey, 0, -1);
|
|
115
|
+
(0, chai_1.expect)(remaining).to.have.length(1);
|
|
116
|
+
await cleanupRedis();
|
|
117
|
+
});
|
|
30
118
|
it("should keep a task rescheduled while due tasks are collected", async () => {
|
|
31
119
|
await cleanupRedis();
|
|
32
120
|
const results = [];
|
|
@@ -87,126 +175,42 @@ describe("Redis Scheduler - runTasks", () => {
|
|
|
87
175
|
});
|
|
88
176
|
});
|
|
89
177
|
function isMockClient(client) {
|
|
90
|
-
|
|
178
|
+
if (!("data" in client)) {
|
|
179
|
+
return false;
|
|
180
|
+
}
|
|
181
|
+
const { data } = client;
|
|
182
|
+
return (typeof data === "object" &&
|
|
183
|
+
data !== null &&
|
|
184
|
+
"get" in data &&
|
|
185
|
+
typeof data.get === "function" &&
|
|
186
|
+
"has" in data &&
|
|
187
|
+
typeof data.has === "function");
|
|
91
188
|
}
|
|
92
189
|
describe("Redis Scheduler - retry logic", () => {
|
|
93
|
-
it("should retry failed tasks up to 3 times", async () =>
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
190
|
+
it("should retry failed tasks up to 3 times", async () => {
|
|
191
|
+
await cleanupRedis();
|
|
192
|
+
let callCount = 0;
|
|
193
|
+
(0, index_1.setHandler)("test-retry", () => {
|
|
194
|
+
callCount++;
|
|
195
|
+
throw new Error("intentional failure");
|
|
196
|
+
});
|
|
197
|
+
const client = await (0, interface_redis_1.GetClient)();
|
|
198
|
+
await client.zadd(RedisKey, Date.now() - 1000, "test-retry:retry-data");
|
|
199
|
+
await (0, index_1.runTasks)();
|
|
200
|
+
(0, chai_1.expect)(callCount).to.equal(1);
|
|
201
|
+
const retryMembers = await client.zrange(RedisKey, 0, -1);
|
|
202
|
+
(0, chai_1.expect)(retryMembers).to.have.length(1);
|
|
203
|
+
(0, chai_1.expect)(retryMembers[0]).to.match(/^RETRY-1:test-retry:retry-data$/);
|
|
204
|
+
await cleanupRedis();
|
|
99
205
|
});
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
async function RejectColonInNameTest() {
|
|
103
|
-
try {
|
|
104
|
-
(0, index_1.setHandler)("invalid:name", () => { });
|
|
105
|
-
chai_1.expect.fail("should have thrown");
|
|
106
|
-
}
|
|
107
|
-
catch (err) {
|
|
108
|
-
(0, chai_1.expect)(err.message).to.include("may not contain");
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
async function AddTaskTest() {
|
|
112
|
-
await cleanupRedis();
|
|
113
|
-
(0, index_1.setHandler)("test-add", () => { });
|
|
114
|
-
const dueTime = Date.now() + 60000;
|
|
115
|
-
await (0, index_1.addTask)("test-add", dueTime, "task-data");
|
|
116
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
117
|
-
const members = await client.zrange(RedisKey, 0, -1);
|
|
118
|
-
(0, chai_1.expect)(members).to.include("test-add:task-data");
|
|
119
|
-
await cleanupRedis();
|
|
120
|
-
}
|
|
121
|
-
async function AddTaskUnknownHandlerTest() {
|
|
122
|
-
try {
|
|
123
|
-
await (0, index_1.addTask)("nonexistent-handler", Date.now(), "data");
|
|
124
|
-
chai_1.expect.fail("should have thrown");
|
|
125
|
-
}
|
|
126
|
-
catch (err) {
|
|
127
|
-
(0, chai_1.expect)(err.message).to.include("Unknown SchedulerUtil handler");
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
async function RemoveTaskTest() {
|
|
131
|
-
await cleanupRedis();
|
|
132
|
-
(0, index_1.setHandler)("test-remove", () => { });
|
|
133
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
134
|
-
await client.zadd(RedisKey, Date.now() + 60000, "test-remove:remove-data");
|
|
135
|
-
await (0, index_1.removeTask)("test-remove", "remove-data");
|
|
136
|
-
const members = await client.zrange(RedisKey, 0, -1);
|
|
137
|
-
(0, chai_1.expect)(members).to.not.include("test-remove:remove-data");
|
|
138
|
-
await cleanupRedis();
|
|
139
|
-
}
|
|
140
|
-
async function RemoveTaskUnknownHandlerTest() {
|
|
206
|
+
});
|
|
207
|
+
async function rejectionMessage(promise) {
|
|
141
208
|
try {
|
|
142
|
-
await
|
|
143
|
-
chai_1.expect.fail("should have thrown");
|
|
209
|
+
await promise;
|
|
144
210
|
}
|
|
145
211
|
catch (err) {
|
|
146
|
-
|
|
212
|
+
return err instanceof Error ? err.message : undefined;
|
|
147
213
|
}
|
|
148
|
-
|
|
149
|
-
async function EnableDisableListenerTest() {
|
|
150
|
-
await (0, index_1.enableListener)();
|
|
151
|
-
await (0, index_1.disableListener)();
|
|
152
|
-
}
|
|
153
|
-
async function EnableListenerUsesLazyConnectTest() {
|
|
154
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
155
|
-
const originalDuplicate = client.duplicate.bind(client);
|
|
156
|
-
let duplicateOptions;
|
|
157
|
-
client.duplicate = ((override) => {
|
|
158
|
-
duplicateOptions = override;
|
|
159
|
-
return originalDuplicate(override);
|
|
160
|
-
});
|
|
161
|
-
await (0, index_1.enableListener)();
|
|
162
|
-
(0, chai_1.expect)(duplicateOptions).to.deep.include({ lazyConnect: true });
|
|
163
|
-
await (0, index_1.disableListener)();
|
|
164
|
-
client.duplicate = originalDuplicate;
|
|
165
|
-
}
|
|
166
|
-
async function RunDueTasksTest() {
|
|
167
|
-
await cleanupRedis();
|
|
168
|
-
const results = [];
|
|
169
|
-
(0, index_1.setHandler)("test-run", (taskInfo) => {
|
|
170
|
-
results.push(taskInfo);
|
|
171
|
-
});
|
|
172
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
173
|
-
await client.zadd(RedisKey, Date.now() - 1000, "test-run:payload1");
|
|
174
|
-
await client.zadd(RedisKey, Date.now() - 500, "test-run:payload2");
|
|
175
|
-
await (0, index_1.runTasks)();
|
|
176
|
-
(0, chai_1.expect)(results).to.include("payload1");
|
|
177
|
-
(0, chai_1.expect)(results).to.include("payload2");
|
|
178
|
-
const remaining = await client.zrange(RedisKey, 0, -1);
|
|
179
|
-
(0, chai_1.expect)(remaining).to.have.length(0);
|
|
180
|
-
await cleanupRedis();
|
|
181
|
-
}
|
|
182
|
-
async function SkipFutureTasksTest() {
|
|
183
|
-
await cleanupRedis();
|
|
184
|
-
const results = [];
|
|
185
|
-
(0, index_1.setHandler)("test-future", (taskInfo) => {
|
|
186
|
-
results.push(taskInfo);
|
|
187
|
-
});
|
|
188
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
189
|
-
await client.zadd(RedisKey, Date.now() + 60000, "test-future:future-data");
|
|
190
|
-
await (0, index_1.runTasks)();
|
|
191
|
-
(0, chai_1.expect)(results).to.have.length(0);
|
|
192
|
-
const remaining = await client.zrange(RedisKey, 0, -1);
|
|
193
|
-
(0, chai_1.expect)(remaining).to.have.length(1);
|
|
194
|
-
await cleanupRedis();
|
|
195
|
-
}
|
|
196
|
-
async function RetryFailedTasksTest() {
|
|
197
|
-
await cleanupRedis();
|
|
198
|
-
let callCount = 0;
|
|
199
|
-
(0, index_1.setHandler)("test-retry", () => {
|
|
200
|
-
callCount++;
|
|
201
|
-
throw new Error("intentional failure");
|
|
202
|
-
});
|
|
203
|
-
const client = await (0, interface_redis_1.GetClient)();
|
|
204
|
-
await client.zadd(RedisKey, Date.now() - 1000, "test-retry:retry-data");
|
|
205
|
-
await (0, index_1.runTasks)();
|
|
206
|
-
(0, chai_1.expect)(callCount).to.equal(1);
|
|
207
|
-
const retryMembers = await client.zrange(RedisKey, 0, -1);
|
|
208
|
-
(0, chai_1.expect)(retryMembers).to.have.length(1);
|
|
209
|
-
(0, chai_1.expect)(retryMembers[0]).to.match(/^RETRY-1:test-retry:retry-data$/);
|
|
210
|
-
await cleanupRedis();
|
|
214
|
+
return undefined;
|
|
211
215
|
}
|
|
212
216
|
//# sourceMappingURL=index.test.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":";;AAAA,+BAA8B;AAC9B,iEAAwD;AACxD,oCAOkB;AAElB,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AAEvC,KAAK,UAAU,YAAY;IACzB,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE,
|
|
1
|
+
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":";;AAAA,+BAA8B;AAC9B,iEAAwD;AACxD,oCAOkB;AAElB,MAAM,QAAQ,GAAG,qBAAqB,CAAC;AAEvC,KAAK,UAAU,YAAY;IACzB,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;IACjC,MAAM,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;QACzC,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAA,kBAAU,EAAC,eAAe,EAAE,GAAG,EAAE;YAC/B,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,IAAA,aAAM,EAAC,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,IAAA,aAAM,EAAC,GAAG,EAAE,CAAC,IAAA,kBAAU,EAAC,cAAc,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CACzD,iBAAiB,CAClB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACnD,MAAM,YAAY,EAAE,CAAC;QACrB,IAAA,kBAAU,EAAC,UAAU,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEjC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACnC,MAAM,IAAA,eAAO,EAAC,UAAU,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACrD,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAEjD,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAChD,IAAA,aAAM,EACJ,MAAM,gBAAgB,CACpB,IAAA,eAAO,EAAC,qBAAqB,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CACnD,CACF,CAAC,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,YAAY,EAAE,CAAC;QACrB,IAAA,kBAAU,EAAC,aAAa,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAEpC,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,yBAAyB,CAAC,CAAC;QAE3E,MAAM,IAAA,kBAAU,EAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QAE/C,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACrD,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAE1D,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAChD,IAAA,aAAM,EACJ,MAAM,gBAAgB,CAAC,IAAA,kBAAU,EAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAClE,CAAC,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oDAAoD,EAAE,GAAG,EAAE;IAClE,EAAE,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;YAC/C,IAAA,kBAAU,EAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,MAAM,IAAA,sBAAc,GAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,IAAA,eAAO,EAAC,eAAe,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC;YAC9D,IAAA,aAAM,EAAC,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9C,CAAC;gBAAS,CAAC;YACT,MAAM,IAAA,uBAAe,GAAE,CAAC;QAC1B,CAAC;QAED,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,iBAAiB,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,gBAAwD,CAAC;QAE7D,MAAM,CAAC,SAAS,GAAG,CAAC,QAAQ,EAAE,EAAE;YAC9B,gBAAgB,GAAG,QAAQ,CAAC;YAC5B,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,IAAA,sBAAc,GAAE,CAAC;YACvB,IAAA,aAAM,EAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YAChE,MAAM,IAAA,uBAAe,GAAE,CAAC;QAC1B,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,SAAS,GAAG,iBAAiB,CAAC;QACvC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,EAAE,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE;QACxC,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAA,kBAAU,EAAC,UAAU,EAAE,CAAC,QAAgB,EAAE,EAAE;YAC1C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,mBAAmB,CAAC,CAAC;QACpE,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAEnE,MAAM,IAAA,gBAAQ,GAAE,CAAC;QAEjB,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACvC,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAEvC,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACvD,IAAA,aAAM,EAAC,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAEpC,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAA,kBAAU,EAAC,aAAa,EAAE,CAAC,QAAgB,EAAE,EAAE;YAC7C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,yBAAyB,CAAC,CAAC;QAE3E,MAAM,IAAA,gBAAQ,GAAE,CAAC;QAEjB,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAElC,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACvD,IAAA,aAAM,EAAC,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAEpC,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAA,kBAAU,EAAC,iBAAiB,EAAE,CAAC,QAAgB,EAAE,EAAE;YACjD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,yBAAyB,CAAC,CAAC;QAE1E,MAAM,OAAO,CAAC,GAAG,CAAC;YAChB,IAAA,gBAAQ,GAAE;YACV,IAAA,eAAO,EAAC,iBAAiB,EAAE,KAAK,EAAE,SAAS,CAAC;SAC7C,CAAC,CAAC;QAEH,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QAC3C,IAAA,aAAM,EAAC,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CACvE,MAAM,CAAC,KAAK,CAAC,CACd,CAAC;QAEF,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;QAC7D,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAA,kBAAU,EAAC,mBAAmB,EAAE,CAAC,QAAgB,EAAE,EAAE;YACnD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC9B,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,2BAA2B,CAAC,CAAC;QAC9D,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QACxB,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,MAAM,aAAa,GAAG,CAAC,GAAW,EAAE,EAAE;YACpC,IAAI,CAAC,MAAM,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAChC,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG;YACV,GAAG,KAAK;YACR,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClD,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACnD,CAAC;QAEF,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,IAAA,gBAAQ,GAAE,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;QACpB,CAAC;QAED,IAAA,aAAM,EAAC,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAA,aAAM,EAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAA,aAAM,EAAC,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClC,IAAA,aAAM,EAAC,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CACzE,MAAM,CAAC,GAAG,CAAC,CACZ,CAAC;QAEF,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAOH,SAAS,YAAY,CACnB,MAAS;IAET,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IACxB,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,KAAK,IAAI,IAAI;QACb,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU;QAC9B,KAAK,IAAI,IAAI;QACb,OAAO,IAAI,CAAC,GAAG,KAAK,UAAU,CAC/B,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,+BAA+B,EAAE,GAAG,EAAE;IAC7C,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,MAAM,YAAY,EAAE,CAAC;QACrB,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAA,kBAAU,EAAC,YAAY,EAAE,GAAG,EAAE;YAC5B,SAAS,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,IAAA,2BAAS,GAAE,CAAC;QACjC,MAAM,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,uBAAuB,CAAC,CAAC;QAExE,MAAM,IAAA,gBAAQ,GAAE,CAAC;QACjB,IAAA,aAAM,EAAC,SAAS,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAE9B,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC1D,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvC,IAAA,aAAM,EAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAEpE,MAAM,YAAY,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,gBAAgB,CAC7B,OAAyB;IAEzB,IAAI,CAAC;QACH,MAAM,OAAO,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
|
package/docs/1.introduction.md
CHANGED
|
@@ -1,37 +1,45 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
title: Redis scheduler
|
|
3
|
+
description: Schedule tasks in a Redis sorted set and run them with a listener, with the delivery, retry, and shutdown rules of each export.
|
|
4
|
+
mode: reference
|
|
5
|
+
---
|
|
2
6
|
|
|
3
7
|
## Overview
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
`@antelopejs/interface-redis-scheduler` stores tasks in a Redis sorted set, with each due timestamp as the score. A local timer checks for due tasks, and Redis pub/sub tells listeners when the schedule changes. A handler that throws is retried. The scheduler does not give exactly-once delivery.
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
The scheduler code runs in your own module. It reaches Redis through `GetClient()` from `@antelopejs/interface-redis`, so the project must load a module that implements that interface, such as `@antelopejs/redis`. Where Redis keeps its data, and whether queued entries survive a Redis restart, depends on that module's connection settings and the Redis server's persistence configuration.
|
|
12
|
+
|
|
13
|
+
A listener takes due tasks with one Lua script that reads and removes them in a single step. Several listeners can share one queue, and each due entry goes to one of them. The entry leaves Redis before its handler runs, so a process failure after the removal and before the handler completes loses the task. Make handlers idempotent, because a retry runs the handler again after a failure that may already have had effects.
|
|
14
|
+
|
|
15
|
+
A listener that takes an entry whose handler name it has not registered removes the entry and does not run it, retry it, or log it. Register every handler in every process that calls `enableListener()`.
|
|
8
16
|
|
|
9
17
|
## Schedule a task safely
|
|
10
18
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
19
|
+
A task runs as expected when these four conditions hold:
|
|
20
|
+
|
|
21
|
+
1. Every process that adds, removes, or runs tasks of a type registers that type with [`setHandler`](#sethandler).
|
|
22
|
+
2. Each listener starts with [`enableListener`](#enablelistener) after its handlers are registered.
|
|
23
|
+
3. The application saves the serialized payload, then calls [`addTask`](#addtask) with a due time in milliseconds.
|
|
24
|
+
4. [`removeTask`](#removetask) receives that saved payload. A payload rebuilt with a new timestamp does not match.
|
|
15
25
|
|
|
16
|
-
{width="480"}
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
The scheduler fits work whose loss or repetition your application can tolerate or reconcile. It has no exactly-once execution, no durable record of which process runs a task, and no API that stops or drains processing. Read [retry logic](#retry-logic), [shutdown limits](#disablelistener), and [known limitations](#known-limitations) before you depend on it.
|
|
19
29
|
|
|
20
|
-
## Getting
|
|
30
|
+
## Getting started
|
|
21
31
|
|
|
22
|
-
Install the package in your
|
|
32
|
+
Install the package in your module:
|
|
23
33
|
|
|
24
34
|
```bash
|
|
25
35
|
npm install @antelopejs/interface-redis-scheduler
|
|
26
36
|
```
|
|
27
37
|
|
|
28
|
-
> **Note:**
|
|
38
|
+
> **Note:** `@antelopejs/interface-redis` is a peer dependency. Install it too, and load a module that implements it, such as `@antelopejs/redis`, so the scheduler can connect to Redis.
|
|
29
39
|
|
|
30
40
|
## Try one scheduled task
|
|
31
41
|
|
|
32
|
-
|
|
33
|
-
with no other scheduler listener. It logs a reminder after about one minute;
|
|
34
|
-
it does not send an email or charge a payment.
|
|
42
|
+
This example runs in an initialized application against a disposable Redis database with no other scheduler listener. It logs a reminder after about one minute. It does not send an email or charge a payment.
|
|
35
43
|
|
|
36
44
|
```typescript
|
|
37
45
|
import {
|
|
@@ -52,26 +60,29 @@ const taskInfo = JSON.stringify({
|
|
|
52
60
|
await addTask("docs-reminder", Date.now() + 60_000, taskInfo);
|
|
53
61
|
```
|
|
54
62
|
|
|
55
|
-
|
|
56
|
-
in milliseconds, not a delay. Save `taskInfo` if you may later remove the queued
|
|
57
|
-
entry; [removal is not a cancellation guarantee](#removetask). The public API does
|
|
58
|
-
not fully stop timers, so end this disposable process when finished.
|
|
63
|
+
The process must stay alive for the reminder to appear. The due time is a Unix timestamp in milliseconds, not a delay. Save `taskInfo` if you may later remove the queued entry, and note that [removal does not guarantee cancellation](#removetask). The API cannot fully stop the timers, so end this disposable process when you are done.
|
|
59
64
|
|
|
60
|
-
## Core
|
|
65
|
+
## Core concepts
|
|
61
66
|
|
|
62
|
-
The scheduler
|
|
67
|
+
The scheduler has three parts:
|
|
63
68
|
|
|
64
|
-
- **Handlers** process tasks of
|
|
65
|
-
- **Tasks** are
|
|
66
|
-
- **
|
|
69
|
+
- **Handlers** process tasks of one type. Register them with `setHandler()` before you schedule tasks of that type.
|
|
70
|
+
- **Tasks** are entries in a Redis sorted set, scored by their due time. When a task is due, a listener calls the matching handler.
|
|
71
|
+
- **Listeners** watch the sorted set and run tasks when they fall due. Start one with `enableListener()`.
|
|
67
72
|
|
|
68
73
|
## `setHandler`
|
|
69
74
|
|
|
70
|
-
|
|
75
|
+
`setHandler` registers the handler for one task type. The name identifies the type, and the callback receives the task data as a string. The registration is local to the process and makes no Redis call. `sendEmail` below stands for a function in your application. It is not a scheduler export.
|
|
71
76
|
|
|
72
77
|
```typescript
|
|
73
78
|
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
74
79
|
|
|
80
|
+
declare function sendEmail(message: {
|
|
81
|
+
to: string;
|
|
82
|
+
subject: string;
|
|
83
|
+
body: string;
|
|
84
|
+
}): Promise<void>;
|
|
85
|
+
|
|
75
86
|
setHandler("send-email", async (taskInfo) => {
|
|
76
87
|
const emailData = JSON.parse(taskInfo);
|
|
77
88
|
await sendEmail({
|
|
@@ -82,7 +93,7 @@ setHandler("send-email", async (taskInfo) => {
|
|
|
82
93
|
});
|
|
83
94
|
```
|
|
84
95
|
|
|
85
|
-
|
|
96
|
+
A handler name must not contain the `:` character, because the scheduler uses it as a delimiter. Otherwise `setHandler` throws an `Error` with the message ``SchedulerUtil handler name may not contain `:` ``.
|
|
86
97
|
|
|
87
98
|
### Parameters
|
|
88
99
|
|
|
@@ -93,28 +104,27 @@ Handler names must not contain the `:` character, as the scheduler uses it inter
|
|
|
93
104
|
|
|
94
105
|
## `enableListener`
|
|
95
106
|
|
|
96
|
-
|
|
107
|
+
`enableListener` starts task processing in this process. It opens a dedicated Redis subscriber connection, which receives the update messages that `addTask` publishes. It then arms a timer for the next due task, or runs the tasks that are already due.
|
|
97
108
|
|
|
98
109
|
```typescript
|
|
99
110
|
import { enableListener } from "@antelopejs/interface-redis-scheduler";
|
|
100
111
|
|
|
101
112
|
async function startApp() {
|
|
102
|
-
// Register all handlers first
|
|
113
|
+
// Register all handlers first.
|
|
103
114
|
// ...
|
|
104
115
|
|
|
105
|
-
// Then start the listener
|
|
106
116
|
await enableListener();
|
|
107
117
|
console.log("Scheduler is active");
|
|
108
118
|
}
|
|
109
119
|
```
|
|
110
120
|
|
|
111
|
-
> **Important:** Register all task handlers before
|
|
121
|
+
> **Important:** Register all task handlers before you call `enableListener()`. The listener starts processing due tasks right away.
|
|
112
122
|
|
|
113
123
|
## `disableListener`
|
|
114
124
|
|
|
115
|
-
`disableListener()` returns `Promise<void>` and only calls `quit()` on the notification subscriber. Call it only after `enableListener()` has completed
|
|
125
|
+
`disableListener()` returns `Promise<void>` and only calls `quit()` on the notification subscriber. Call it only after `enableListener()` has completed. Before that, the subscriber does not exist and the call rejects.
|
|
116
126
|
|
|
117
|
-
> **Warning:** It does not clear the pending timer, cancel running handlers, or wait for
|
|
127
|
+
> **Warning:** It does not clear the pending timer, cancel running handlers, or wait for tasks to complete. A timer that is already armed can still run tasks and arm another timer through `updateTimer()`. Do not use this function as a pause, a drain, or a guarantee that no more tasks run. The public API has no operation that stops the timer.
|
|
118
128
|
|
|
119
129
|
```typescript
|
|
120
130
|
import { disableListener } from "@antelopejs/interface-redis-scheduler";
|
|
@@ -127,13 +137,13 @@ async function stopApp() {
|
|
|
127
137
|
|
|
128
138
|
## `addTask`
|
|
129
139
|
|
|
130
|
-
|
|
140
|
+
`addTask` schedules a task for a given time. It adds the task to the Redis sorted set with the due time as its score, then publishes an update message so listeners refresh their timers. While this process runs a batch of tasks, `addTask` does not publish. That process picks up the new task when its batch ends.
|
|
131
141
|
|
|
132
142
|
```typescript
|
|
133
143
|
import { addTask } from "@antelopejs/interface-redis-scheduler";
|
|
134
144
|
|
|
135
145
|
async function scheduleReminder(recipient: string) {
|
|
136
|
-
//
|
|
146
|
+
// Due in 3 days.
|
|
137
147
|
const dueTime = Date.now() + 3 * 24 * 60 * 60 * 1000;
|
|
138
148
|
|
|
139
149
|
const taskInfo = JSON.stringify({
|
|
@@ -148,21 +158,21 @@ async function scheduleReminder(recipient: string) {
|
|
|
148
158
|
}
|
|
149
159
|
```
|
|
150
160
|
|
|
151
|
-
|
|
161
|
+
`addTask` rejects with `Unknown SchedulerUtil handler: <name>` when this process has not registered the handler name.
|
|
152
162
|
|
|
153
|
-
The pair `handlerName`
|
|
163
|
+
The pair of `handlerName` and `taskInfo` identifies the queued entry. Adding the same pair again changes its due time and does not create a second task. To keep two otherwise identical jobs apart, put a stable job ID in the payload.
|
|
154
164
|
|
|
155
165
|
### Parameters
|
|
156
166
|
|
|
157
|
-
| Parameter | Type | Description
|
|
158
|
-
| ------------- | -------- |
|
|
159
|
-
| `handlerName` | `string` | The registered handler name that processes this task
|
|
160
|
-
| `dueTime` | `number` | Unix timestamp in milliseconds when the task
|
|
161
|
-
| `taskInfo` | `string` | Data passed to the handler
|
|
167
|
+
| Parameter | Type | Description |
|
|
168
|
+
| ------------- | -------- | --------------------------------------------------------- |
|
|
169
|
+
| `handlerName` | `string` | The registered handler name that processes this task |
|
|
170
|
+
| `dueTime` | `number` | Unix timestamp in milliseconds when the task is due |
|
|
171
|
+
| `taskInfo` | `string` | Data passed to the handler, usually a JSON-encoded string |
|
|
162
172
|
|
|
163
173
|
## `removeTask`
|
|
164
174
|
|
|
165
|
-
|
|
175
|
+
`removeTask` removes the original queued entry if it is still present. Pass the saved `taskInfo` string that `scheduleReminder` returned. Do not rebuild the JSON.
|
|
166
176
|
|
|
167
177
|
```typescript
|
|
168
178
|
import { removeTask } from "@antelopejs/interface-redis-scheduler";
|
|
@@ -172,11 +182,11 @@ async function removeQueuedReminder(savedTaskInfo: string) {
|
|
|
172
182
|
}
|
|
173
183
|
```
|
|
174
184
|
|
|
175
|
-
|
|
185
|
+
`removeTask` rejects with `Unknown SchedulerUtil handler: <name>` when this process has not registered the handler name.
|
|
176
186
|
|
|
177
|
-
> **Warning:** The `taskInfo` must
|
|
187
|
+
> **Warning:** The `taskInfo` must match the original string exactly. If the serialized JSON differs in key order or whitespace, nothing is removed and no error is raised.
|
|
178
188
|
|
|
179
|
-
Removal targets the original queued
|
|
189
|
+
Removal targets the original queued entry only. It does not stop a running handler, and it does not remove a retry stored with a `RETRY-` prefix. If a cancellation must survive races and retries, make the handler check cancellation state that your application owns before it applies effects.
|
|
180
190
|
|
|
181
191
|
### Parameters
|
|
182
192
|
|
|
@@ -185,64 +195,62 @@ Removal targets the original queued member only. It does not stop a running hand
|
|
|
185
195
|
| `handlerName` | `string` | The handler name associated with the task |
|
|
186
196
|
| `taskInfo` | `string` | The exact task info string used when adding the task |
|
|
187
197
|
|
|
188
|
-
## Retry
|
|
189
|
-
|
|
190
|
-
The scheduler automatically retries failed tasks. When a handler throws an error, the scheduler reschedules the task with a retry counter.
|
|
198
|
+
## Retry logic
|
|
191
199
|
|
|
192
|
-
|
|
193
|
-
- **Retry delay:** 5 seconds between each attempt
|
|
194
|
-
- **Behavior on exhaustion:** After 3 failed retries, the task is discarded; failures are reported through `Logging.Error`
|
|
200
|
+
The scheduler retries failed tasks with no extra code. When a handler throws or its promise rejects, the scheduler logs the error with `Logging.Error` and queues the task again with a retry counter.
|
|
195
201
|
|
|
196
|
-
|
|
202
|
+
- **Maximum retries.** 3 retries after the first attempt, so 4 attempts in total.
|
|
203
|
+
- **Retry delay.** Each retry is due 5 seconds after the attempt that failed.
|
|
204
|
+
- **Exhaustion.** After the third retry fails, the scheduler logs the error and discards the task.
|
|
197
205
|
|
|
198
206
|
```typescript
|
|
199
207
|
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
200
208
|
|
|
201
|
-
|
|
209
|
+
declare function refreshSummary(data: unknown): Promise<void>;
|
|
210
|
+
|
|
211
|
+
// If this handler throws, the scheduler retries up to 3 times.
|
|
202
212
|
setHandler("refresh-summary", async (taskInfo) => {
|
|
203
213
|
const data = JSON.parse(taskInfo);
|
|
204
214
|
await refreshSummary(data);
|
|
205
|
-
// On failure: retry after 5s, then 5s, then 5s, then discard
|
|
215
|
+
// On failure: retry after 5s, then 5s, then 5s, then discard.
|
|
206
216
|
});
|
|
207
217
|
```
|
|
208
218
|
|
|
209
|
-
`refreshSummary` is an application function that recomputes a replaceable summary.
|
|
210
|
-
Choose retryable, idempotent work; a retry is not proof that the previous attempt
|
|
211
|
-
had no effect. Do not use this sketch as a durable payment-processing queue.
|
|
219
|
+
`refreshSummary` is an application function that recomputes a replaceable summary. Choose work that is safe to retry and idempotent, because a retry does not prove that the failed attempt had no effect. Do not use this pattern as a durable payment-processing queue.
|
|
212
220
|
|
|
213
|
-
## Redis
|
|
221
|
+
## Redis storage
|
|
214
222
|
|
|
215
|
-
The scheduler uses
|
|
223
|
+
The scheduler uses one Redis sorted set with the key `SchedulerUtil.Tasks`. Each entry has the form `handlerName:taskInfo`, and its score is the due timestamp in milliseconds.
|
|
216
224
|
|
|
217
|
-
|
|
225
|
+
A retried task has the form `RETRY-{count}:handlerName:taskInfo`, where `{count}` is the number of the retry, from 1 to 3.
|
|
218
226
|
|
|
219
|
-
The scheduler also uses a Redis pub/sub channel named `SchedulerUtil`
|
|
227
|
+
The scheduler also uses a Redis pub/sub channel named `SchedulerUtil`. `addTask` publishes the message `update` on it, and each listener that receives it refreshes its timer. The messages do not assign tasks to a listener. The Lua script that takes due tasks does that.
|
|
220
228
|
|
|
221
229
|
## `updateTimer`
|
|
222
230
|
|
|
223
|
-
|
|
231
|
+
`updateTimer` reads the first queued task. If that task is already due, `updateTimer` runs the due tasks. Otherwise it arms a timer for the task's due time, capped at 24 hours. A listener calls `updateTimer` when it starts, when it receives an update message, and after each batch of tasks. While this process runs a batch, `updateTimer` returns without doing anything. You do not need to call it in normal usage.
|
|
224
232
|
|
|
225
233
|
```typescript
|
|
226
234
|
import { updateTimer } from "@antelopejs/interface-redis-scheduler";
|
|
227
235
|
|
|
228
|
-
// Force a timer refresh (advanced usage)
|
|
236
|
+
// Force a timer refresh (advanced usage).
|
|
229
237
|
await updateTimer();
|
|
230
238
|
```
|
|
231
239
|
|
|
232
240
|
## `runTasks`
|
|
233
241
|
|
|
234
|
-
|
|
242
|
+
`runTasks` takes every task that is due and runs it. It removes the due tasks from Redis in one step, then calls their handlers one after another, earliest due time first. A task whose handler is not registered in this process is dropped. The retry logic applies to each handler that fails. When the batch ends, `runTasks` calls `updateTimer`. The timer calls `runTasks` when it fires, so you do not need to call it in normal usage.
|
|
235
243
|
|
|
236
244
|
```typescript
|
|
237
245
|
import { runTasks } from "@antelopejs/interface-redis-scheduler";
|
|
238
246
|
|
|
239
|
-
//
|
|
247
|
+
// Run the due tasks now (advanced usage).
|
|
240
248
|
await runTasks();
|
|
241
249
|
```
|
|
242
250
|
|
|
243
|
-
## Complete
|
|
251
|
+
## Complete example
|
|
244
252
|
|
|
245
|
-
This
|
|
253
|
+
This sketch registers handlers, starts the listener, schedules tasks, and closes the subscriber. `sendEmail`, `deleteSession`, and `refreshSummary` in these examples stand for application functions you supply. They are not scheduler exports. The example needs a configured Redis implementation and does not start a service from this page.
|
|
246
254
|
|
|
247
255
|
```typescript
|
|
248
256
|
import {
|
|
@@ -253,7 +261,14 @@ import {
|
|
|
253
261
|
removeTask,
|
|
254
262
|
} from "@antelopejs/interface-redis-scheduler";
|
|
255
263
|
|
|
256
|
-
|
|
264
|
+
declare function sendEmail(
|
|
265
|
+
to: string,
|
|
266
|
+
subject: string,
|
|
267
|
+
body: string,
|
|
268
|
+
): Promise<void>;
|
|
269
|
+
declare function deleteSession(sessionId: string): Promise<void>;
|
|
270
|
+
|
|
271
|
+
// 1. Register task handlers.
|
|
257
272
|
setHandler("send-email", async (taskInfo) => {
|
|
258
273
|
const data = JSON.parse(taskInfo);
|
|
259
274
|
await sendEmail(data.to, data.subject, data.body);
|
|
@@ -264,14 +279,14 @@ setHandler("cleanup-session", async (taskInfo) => {
|
|
|
264
279
|
await deleteSession(sessionId);
|
|
265
280
|
});
|
|
266
281
|
|
|
267
|
-
// 2. Start the listener
|
|
282
|
+
// 2. Start the listener.
|
|
268
283
|
async function start() {
|
|
269
284
|
await enableListener();
|
|
270
285
|
}
|
|
271
286
|
|
|
272
|
-
// 3. Schedule tasks from your application logic
|
|
287
|
+
// 3. Schedule tasks from your application logic.
|
|
273
288
|
async function onUserSignup(userId: string, email: string) {
|
|
274
|
-
// Send a welcome email in 1 hour
|
|
289
|
+
// Send a welcome email in 1 hour.
|
|
275
290
|
const dueTime = Date.now() + 60 * 60 * 1000;
|
|
276
291
|
await addTask(
|
|
277
292
|
"send-email",
|
|
@@ -285,13 +300,22 @@ async function onUserSignup(userId: string, email: string) {
|
|
|
285
300
|
}
|
|
286
301
|
|
|
287
302
|
async function onUserLogout(sessionId: string) {
|
|
288
|
-
// Clean up session data in 24 hours
|
|
303
|
+
// Clean up session data in 24 hours.
|
|
289
304
|
const dueTime = Date.now() + 24 * 60 * 60 * 1000;
|
|
290
305
|
await addTask("cleanup-session", dueTime, JSON.stringify({ sessionId }));
|
|
291
306
|
}
|
|
292
307
|
|
|
293
|
-
// 4. Close notifications on shutdown
|
|
308
|
+
// 4. Close notifications on shutdown. Pending timers and handlers may continue.
|
|
294
309
|
async function shutdown() {
|
|
295
310
|
await disableListener();
|
|
296
311
|
}
|
|
297
312
|
```
|
|
313
|
+
|
|
314
|
+
## Known limitations
|
|
315
|
+
|
|
316
|
+
These behaviours are tracked as open issues:
|
|
317
|
+
|
|
318
|
+
- Two batches can run at the same time on one listener, so two handlers of one process can overlap ([#39](https://github.com/AntelopeJS/interface-redis-scheduler/issues/39)).
|
|
319
|
+
- When `runTasks` rejects, for example because Redis fails while it takes due tasks or writes a retry, the process keeps its internal lock. That listener's `updateTimer` then returns without arming a timer ([#27](https://github.com/AntelopeJS/interface-redis-scheduler/issues/27)).
|
|
320
|
+
- When writing a retry fails in the middle of a batch, the batch's remaining tasks are lost. They were already removed from Redis ([#29](https://github.com/AntelopeJS/interface-redis-scheduler/issues/29)).
|
|
321
|
+
- When `removeTask` deletes the first queued task while `updateTimer` reads it, no timer is armed, and the remaining tasks wait for the next update message ([#38](https://github.com/AntelopeJS/interface-redis-scheduler/issues/38)).
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
<svg xmlns="http://www.w3.org/2000/svg" width="480" height="760" viewBox="0 0 480 760" role="img" aria-labelledby="title desc">
|
|
2
2
|
<title id="title">Task delivery and the in-flight gap</title>
|
|
3
|
-
<desc id="desc">A timer reads due tasks from a sorted set
|
|
3
|
+
<desc id="desc">A timer reads and removes due tasks from a sorted set in one Lua script before calling handlers. Successful handlers finish. Thrown errors requeue after five seconds, up to three retries. A crash after removal can lose work; pub/sub only refreshes timers.</desc>
|
|
4
4
|
<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0 8 4 0 8" fill="#627d98"/></marker></defs>
|
|
5
5
|
<rect width="480" height="760" rx="16" fill="#f4f7fb"/>
|
|
6
6
|
<g font-family="system-ui, sans-serif" fill="#17324d" font-size="18">
|
|
7
|
-
<text x="24" y="36" font-size="24" font-weight="700">Remove first. Run the handler.</text><text x="24" y="70">
|
|
7
|
+
<text x="24" y="36" font-size="24" font-weight="700">Remove first. Run the handler.</text><text x="24" y="70">Every listener registers every handler</text><text x="24" y="99">Application-owned recovery</text>
|
|
8
8
|
<rect x="24" y="126" width="400" height="86" rx="10" fill="#e2edf8" stroke="#b0c9e0"/><text x="44" y="160" font-size="22" font-weight="700">Queued in Redis</text><text x="44" y="190">Score = due time (milliseconds)</text>
|
|
9
9
|
<path d="M224 212V246" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
10
|
-
<rect x="24" y="258" width="400" height="86" rx="10" fill="#fff0cf"/><text x="44" y="292" font-size="22" font-weight="700">Read + remove due tasks</text><text x="44" y="322">
|
|
10
|
+
<rect x="24" y="258" width="400" height="86" rx="10" fill="#fff0cf"/><text x="44" y="292" font-size="22" font-weight="700">Read + remove due tasks</text><text x="44" y="322">One Lua script, one listener per task</text>
|
|
11
11
|
<path d="M224 344V378" stroke="#627d98" stroke-width="2" marker-end="url(#arrow)"/>
|
|
12
12
|
<rect x="24" y="390" width="400" height="86" rx="10" fill="#17324d"/><text x="44" y="424" fill="#fff" font-size="22" font-weight="700">Run handler</text><text x="44" y="454" fill="#d5e5f3">Success → done</text>
|
|
13
13
|
<path d="M424 433H448V169H424" fill="none" stroke="#627d98" stroke-width="2" stroke-dasharray="5 5" marker-end="url(#arrow)"/>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-redis-scheduler",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.10",
|
|
4
4
|
"description": "AntelopeJS interface for scheduling tasks on Redis, with retries on failure",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -49,11 +49,11 @@
|
|
|
49
49
|
"prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
|
|
50
50
|
"checks": "antelopejs-checks",
|
|
51
51
|
"size": "antelopejs-check-size",
|
|
52
|
-
"ratchet": "antelopejs-ratchet",
|
|
53
52
|
"sync": "antelopejs-sync",
|
|
54
|
-
"ratchet:update": "antelopejs-ratchet --update",
|
|
55
53
|
"sync:check": "antelopejs-sync --check",
|
|
56
|
-
"typecheck": "tsc --noEmit"
|
|
54
|
+
"typecheck": "tsc --noEmit",
|
|
55
|
+
"suppressions": "antelopejs-suppressions",
|
|
56
|
+
"suppressions:update": "antelopejs-suppressions --update"
|
|
57
57
|
},
|
|
58
58
|
"dependencies": {
|
|
59
59
|
"ioredis": "^5.10.1"
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"@antelopejs/core": "^1.16.0",
|
|
63
63
|
"@antelopejs/interface-core": "^0.2.4",
|
|
64
64
|
"@antelopejs/interface-redis": "^0.0.9",
|
|
65
|
-
"@antelopejs/tooling-configs": "^0.2.
|
|
65
|
+
"@antelopejs/tooling-configs": "^0.2.18",
|
|
66
66
|
"@types/chai": "^4.3.20",
|
|
67
67
|
"@types/mocha": "^10.0.10",
|
|
68
68
|
"@types/node": "^22.19.15",
|
|
@@ -87,6 +87,9 @@
|
|
|
87
87
|
"test": "src/antelope.test.ts",
|
|
88
88
|
"skills": [
|
|
89
89
|
"./skills"
|
|
90
|
-
]
|
|
90
|
+
],
|
|
91
|
+
"docs": {
|
|
92
|
+
"standard": true
|
|
93
|
+
}
|
|
91
94
|
}
|
|
92
95
|
}
|
|
@@ -1,20 +1,25 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: redis-scheduler-interface
|
|
3
|
-
description: Distributed Redis-backed task scheduling for AntelopeJS
|
|
3
|
+
description: Distributed Redis-backed task scheduling for AntelopeJS. Register named handlers, schedule tasks at a due timestamp in a Redis sorted set, and execute them with automatic retries; listeners across instances claim due tasks atomically, and pub/sub only re-arms their timers. Use when code imports '@antelopejs/interface-redis-scheduler', when a task involves scheduling delayed/deferred jobs, reminders, or background work in an AntelopeJS module, or when symbols like setHandler, addTask, removeTask, enableListener, disableListener, or the SchedulerUtil.Tasks Redis key appear.
|
|
4
4
|
category: antelopejs-interface
|
|
5
5
|
tags: [antelopejs, redis, scheduler, tasks, background-jobs]
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Redis Scheduler Interface
|
|
9
9
|
|
|
10
|
-
Distributed task scheduler on top of Redis
|
|
11
|
-
(`SchedulerUtil.Tasks`) scored by their due timestamp
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
10
|
+
Distributed task scheduler on top of Redis. Tasks live in one sorted set
|
|
11
|
+
(`SchedulerUtil.Tasks`), scored by their due timestamp. A listener takes the
|
|
12
|
+
due tasks with one Lua script that reads and removes them in a single step, so
|
|
13
|
+
each due entry goes to exactly one listener, and several listeners can share
|
|
14
|
+
the queue. The `SchedulerUtil` pub/sub channel only carries an `update`
|
|
15
|
+
message that tells listeners to re-arm their timers; it does not decide who
|
|
16
|
+
runs a task.
|
|
17
|
+
|
|
18
|
+
Mental model: this is a consumer-side utility, not a proxied service. All
|
|
19
|
+
exported functions run in your own module. Redis access goes through
|
|
20
|
+
`GetClient()` from `@antelopejs/interface-redis` (`setHandler` itself is local
|
|
21
|
+
and makes no Redis call). There is no provider to write with
|
|
22
|
+
`ImplementInterface`. A Redis interface implementation (for example the
|
|
18
23
|
`@antelopejs/redis` module) must be loaded in the app.
|
|
19
24
|
|
|
20
25
|
## Imports
|
|
@@ -31,8 +36,8 @@ import {
|
|
|
31
36
|
} from "@antelopejs/interface-redis-scheduler";
|
|
32
37
|
```
|
|
33
38
|
|
|
34
|
-
|
|
35
|
-
execution loop
|
|
39
|
+
`updateTimer` and `runTasks` are also exported, but they belong to the internal
|
|
40
|
+
execution loop. Call them only in tests or advanced scenarios.
|
|
36
41
|
|
|
37
42
|
## Consumption example
|
|
38
43
|
|
|
@@ -66,28 +71,43 @@ await disableListener();
|
|
|
66
71
|
|
|
67
72
|
## Gotchas
|
|
68
73
|
|
|
69
|
-
- Handler names must not contain
|
|
74
|
+
- Handler names must not contain `:`, which delimits the sorted-set member
|
|
70
75
|
format `handlerName:taskInfo`. `setHandler` throws otherwise.
|
|
71
|
-
- `addTask` and `removeTask`
|
|
72
|
-
current process.
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
76
|
+
- `addTask` and `removeTask` reject with `Unknown SchedulerUtil handler: <name>`
|
|
77
|
+
for a handler name not registered in the current process. Call `setHandler`
|
|
78
|
+
before you schedule.
|
|
79
|
+
- Register every handler in every listener process. A listener that claims a
|
|
80
|
+
due entry whose handler it has not registered drops the entry: it does not
|
|
81
|
+
run it, retry it or log it.
|
|
82
|
+
- Register all handlers before `enableListener()`. The listener checks for due
|
|
83
|
+
tasks as soon as it starts.
|
|
84
|
+
- A claimed entry is removed from Redis before its handler runs. If the
|
|
85
|
+
process stops during the run, the task is lost. There is no exactly-once
|
|
86
|
+
execution.
|
|
87
|
+
- A batch runs its handlers one after another, earliest due time first.
|
|
88
|
+
- `taskInfo` is a plain string. Serialize and parse it (typically JSON)
|
|
89
|
+
yourself.
|
|
90
|
+
- `removeTask` needs the exact original `taskInfo` string. A JSON payload with
|
|
91
|
+
a different key order or whitespace does not match, and nothing is removed.
|
|
92
|
+
- A handler that throws or rejects is retried up to 3 times. Each retry is due
|
|
93
|
+
5 seconds after the attempt that failed, and its member becomes
|
|
94
|
+
`RETRY-{n}:handlerName:taskInfo`. After the third retry fails, the task is
|
|
95
|
+
discarded. Every failure is logged through interface-core `Logging.Error`.
|
|
96
|
+
- The listener's timer waits at most 24 hours before it checks again.
|
|
81
97
|
- `enableListener` duplicates the shared Redis client into a dedicated
|
|
82
|
-
subscriber connection
|
|
83
|
-
- `disableListener` only quits the subscriber connection
|
|
84
|
-
pending
|
|
85
|
-
|
|
98
|
+
subscriber connection. `disableListener` quits that subscriber.
|
|
99
|
+
- `disableListener` only quits the subscriber connection. It does not clear
|
|
100
|
+
the pending timer, cancel running handlers, or wait for tasks to complete.
|
|
101
|
+
An armed timer keeps running due tasks and arming the next timer through
|
|
102
|
+
`updateTimer()`, so tasks can keep running after it returns. Do not use it as
|
|
103
|
+
a pause, a drain, or a guarantee that no more tasks run: the public API has
|
|
104
|
+
no operation that stops the timer. It rejects if `enableListener` was never
|
|
105
|
+
called.
|
|
86
106
|
- Peer interfaces `@antelopejs/interface-core` and `@antelopejs/interface-redis`
|
|
87
107
|
must be installed alongside this package.
|
|
88
108
|
|
|
89
109
|
## Deeper reference
|
|
90
110
|
|
|
91
|
-
See this package's `docs/1.introduction.md` (
|
|
92
|
-
|
|
93
|
-
and `dist/index.d.ts`. Do not duplicate them here.
|
|
111
|
+
See this package's `docs/1.introduction.md` (overview, getting started, core
|
|
112
|
+
concepts, one section per function, retry logic, Redis storage, complete
|
|
113
|
+
example, known limitations) and `dist/index.d.ts`. Do not duplicate them here.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"cases": [
|
|
4
|
+
{
|
|
5
|
+
"id": "redis-scheduler-interface-delayed-job",
|
|
6
|
+
"area": "framework",
|
|
7
|
+
"style": "clean",
|
|
8
|
+
"prompt": "In my AntelopeJS module, schedule a reminder email to run 24 hours after a booking is created, and have it run on whichever instance is listening.",
|
|
9
|
+
"expect": {
|
|
10
|
+
"skills": ["redis-scheduler-interface"],
|
|
11
|
+
"acceptable": [
|
|
12
|
+
"redis-interface",
|
|
13
|
+
"ajs-consume-interface",
|
|
14
|
+
"antelopejs"
|
|
15
|
+
],
|
|
16
|
+
"mustMention": ["setHandler", "addTask"]
|
|
17
|
+
}
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"id": "redis-scheduler-interface-delayed-job-casual",
|
|
21
|
+
"area": "framework",
|
|
22
|
+
"style": "casual",
|
|
23
|
+
"prompt": "need to run a job later, like in an hour, across my instances. whats the antelope way",
|
|
24
|
+
"expect": {
|
|
25
|
+
"skills": ["redis-scheduler-interface"],
|
|
26
|
+
"acceptable": [
|
|
27
|
+
"redis-interface",
|
|
28
|
+
"ajs-consume-interface",
|
|
29
|
+
"antelopejs"
|
|
30
|
+
],
|
|
31
|
+
"mustMention": ["addTask"]
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"id": "redis-scheduler-interface-redis-neighbour",
|
|
36
|
+
"area": "framework",
|
|
37
|
+
"style": "clean",
|
|
38
|
+
"prompt": "Cache the result of an expensive lookup in Redis for 10 minutes from my AntelopeJS module.",
|
|
39
|
+
"expect": {
|
|
40
|
+
"skills": ["redis-interface"],
|
|
41
|
+
"acceptable": ["ajs-consume-interface", "antelopejs"],
|
|
42
|
+
"avoid": ["redis-scheduler-interface"]
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"id": "redis-scheduler-interface-two-listeners",
|
|
47
|
+
"area": "framework",
|
|
48
|
+
"style": "clean",
|
|
49
|
+
"prompt": "Three instances of my module call enableListener from @antelopejs/interface-redis-scheduler. Can a due task run on more than one of them?",
|
|
50
|
+
"expect": {
|
|
51
|
+
"skills": ["redis-scheduler-interface"],
|
|
52
|
+
"acceptable": ["redis-interface", "antelopejs"],
|
|
53
|
+
"mustMention": ["Lua"]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
]
|
|
57
|
+
}
|