@antelopejs/interface-redis-scheduler 0.0.6 → 0.0.8
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 +87 -13
- package/dist/antelope.test.js +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.js +6 -5
- package/dist/index.js.map +1 -1
- package/dist/tests/index.test.js +1 -1
- package/dist/tests/index.test.js.map +1 -1
- package/docs/1.introduction.md +252 -0
- package/package.json +40 -21
- package/skills/redis-scheduler-interface/SKILL.md +93 -0
package/README.md
CHANGED
|
@@ -1,28 +1,102 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
# Interface Redis Scheduler
|
|
1
|
+
# @antelopejs/interface-redis-scheduler
|
|
4
2
|
|
|
5
3
|
<div align="center">
|
|
6
|
-
<a href="https://www.npmjs.com/package/@antelopejs/interface-redis-scheduler"><img src="https://img.shields.io/npm/v/@antelopejs/interface-redis-scheduler?style=for-the-badge&labelColor=000000&color=000000"
|
|
7
|
-
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/
|
|
8
|
-
<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"
|
|
9
|
-
<a href="
|
|
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/sjK28QHrA7"><img 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 alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
10
8
|
</div>
|
|
11
9
|
|
|
12
|
-
|
|
10
|
+
Task scheduling on Redis for AntelopeJS: schedule a task for a given time, and the application runs it when it is due, with up to three retries on failure.
|
|
11
|
+
|
|
12
|
+
## What it offers
|
|
13
|
+
|
|
14
|
+
- `setHandler` registers the function that runs one kind of task.
|
|
15
|
+
- `addTask` schedules a task for a Unix timestamp in milliseconds; `removeTask` cancels it.
|
|
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 restarts and every instance of the application sees the same queue.
|
|
18
|
+
|
|
19
|
+
## Implementations
|
|
20
|
+
|
|
21
|
+
| Module | Notes |
|
|
22
|
+
| ---------------------------------------------------------- | --------------------------------------------- |
|
|
23
|
+
| [`@antelopejs/redis`](https://github.com/AntelopeJS/redis) | Also implements `@antelopejs/interface-redis` |
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
Add the interface to the module that schedules tasks:
|
|
13
28
|
|
|
14
|
-
|
|
29
|
+
```bash
|
|
30
|
+
pnpm add @antelopejs/interface-redis-scheduler
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Then add the implementation to the project:
|
|
15
34
|
|
|
16
35
|
```bash
|
|
17
|
-
|
|
36
|
+
ajs project modules add @antelopejs/redis
|
|
18
37
|
```
|
|
19
38
|
|
|
39
|
+
## Quick start
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { Logging } from "@antelopejs/interface-core/logging";
|
|
43
|
+
import {
|
|
44
|
+
addTask,
|
|
45
|
+
disableListener,
|
|
46
|
+
enableListener,
|
|
47
|
+
setHandler,
|
|
48
|
+
} from "@antelopejs/interface-redis-scheduler";
|
|
49
|
+
|
|
50
|
+
const ONE_HOUR_MS = 60 * 60 * 1000;
|
|
51
|
+
|
|
52
|
+
setHandler("overdue-notice", async (taskInfo) => {
|
|
53
|
+
const { memberId } = JSON.parse(taskInfo);
|
|
54
|
+
Logging.Info(`Remind member ${memberId}`);
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
export async function start() {
|
|
58
|
+
await enableListener();
|
|
59
|
+
await addTask(
|
|
60
|
+
"overdue-notice",
|
|
61
|
+
Date.now() + ONE_HOUR_MS,
|
|
62
|
+
JSON.stringify({ memberId: "M-1042" }),
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export async function stop() {
|
|
67
|
+
await disableListener();
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Register a handler before you schedule tasks for it: `addTask` throws for an unknown handler name.
|
|
72
|
+
|
|
73
|
+
`disableListener()` is not a full shutdown or pause: a pending timer and running handlers can continue processing tasks. See the [current lifecycle and delivery limitations](./docs/1.introduction.md#disablelistener) before using it for shutdown.
|
|
74
|
+
|
|
20
75
|
## Documentation
|
|
21
76
|
|
|
22
|
-
|
|
77
|
+
- [Introduction and scheduler reference](./docs/1.introduction.md)
|
|
78
|
+
|
|
79
|
+
## Compatibility
|
|
80
|
+
|
|
81
|
+
Requires AntelopeJS core `1.x` and the following peer dependencies:
|
|
23
82
|
|
|
24
|
-
-
|
|
83
|
+
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
84
|
+
|
|
85
|
+
| Package | Range |
|
|
86
|
+
| ----------------------------- | ---------------- |
|
|
87
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
88
|
+
| `@antelopejs/interface-redis` | `>=0.0.9 <1.0.0` |
|
|
89
|
+
|
|
90
|
+
## Contributing
|
|
91
|
+
|
|
92
|
+
Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
pnpm install
|
|
96
|
+
pnpm lint
|
|
97
|
+
pnpm test
|
|
98
|
+
```
|
|
25
99
|
|
|
26
100
|
## License
|
|
27
101
|
|
|
28
|
-
|
|
102
|
+
[Apache-2.0](./LICENSE)
|
package/dist/antelope.test.js
CHANGED
package/dist/index.d.ts
CHANGED
|
@@ -46,8 +46,9 @@ export declare function setHandler(handlerName: string, handler: HandlerType): v
|
|
|
46
46
|
*/
|
|
47
47
|
export declare function enableListener(): Promise<void>;
|
|
48
48
|
/**
|
|
49
|
-
*
|
|
50
|
-
* This
|
|
49
|
+
* Closes the Redis notification subscriber after enableListener() has completed.
|
|
50
|
+
* This does not clear the pending timer, stop running handlers, or await task completion.
|
|
51
|
+
* Tasks may continue to execute and schedule further timer checks; this is not a full shutdown.
|
|
51
52
|
*
|
|
52
53
|
* @example
|
|
53
54
|
* ```typescript
|
|
@@ -56,7 +57,7 @@ export declare function enableListener(): Promise<void>;
|
|
|
56
57
|
* // During application shutdown
|
|
57
58
|
* async function stopApp() {
|
|
58
59
|
* await disableListener();
|
|
59
|
-
* console.log('
|
|
60
|
+
* console.log('Scheduler notification subscriber closed; task processing may continue');
|
|
60
61
|
* }
|
|
61
62
|
* ```
|
|
62
63
|
*/
|
package/dist/index.js
CHANGED
|
@@ -7,9 +7,9 @@ exports.addTask = addTask;
|
|
|
7
7
|
exports.removeTask = removeTask;
|
|
8
8
|
exports.updateTimer = updateTimer;
|
|
9
9
|
exports.runTasks = runTasks;
|
|
10
|
-
const interface_core_1 = require("@antelopejs/interface-core");
|
|
11
|
-
const logging_1 = require("@antelopejs/interface-core/logging");
|
|
12
10
|
const interface_redis_1 = require("@antelopejs/interface-redis");
|
|
11
|
+
const logging_1 = require("@antelopejs/interface-core/logging");
|
|
12
|
+
const interface_core_1 = require("@antelopejs/interface-core");
|
|
13
13
|
/** Redis key used to store scheduled tasks in a sorted set */
|
|
14
14
|
const RedisKey = "SchedulerUtil.Tasks";
|
|
15
15
|
const SchedulerChannel = "SchedulerUtil";
|
|
@@ -99,8 +99,9 @@ async function enableListener() {
|
|
|
99
99
|
void updateTimer();
|
|
100
100
|
}
|
|
101
101
|
/**
|
|
102
|
-
*
|
|
103
|
-
* This
|
|
102
|
+
* Closes the Redis notification subscriber after enableListener() has completed.
|
|
103
|
+
* This does not clear the pending timer, stop running handlers, or await task completion.
|
|
104
|
+
* Tasks may continue to execute and schedule further timer checks; this is not a full shutdown.
|
|
104
105
|
*
|
|
105
106
|
* @example
|
|
106
107
|
* ```typescript
|
|
@@ -109,7 +110,7 @@ async function enableListener() {
|
|
|
109
110
|
* // During application shutdown
|
|
110
111
|
* async function stopApp() {
|
|
111
112
|
* await disableListener();
|
|
112
|
-
* console.log('
|
|
113
|
+
* console.log('Scheduler notification subscriber closed; task processing may continue');
|
|
113
114
|
* }
|
|
114
115
|
* ```
|
|
115
116
|
*/
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAyDA,gCAEC;AAgCD,wCAgBC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/tests/index.test.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
const chai_1 = require("chai");
|
|
3
4
|
const interface_redis_1 = require("@antelopejs/interface-redis");
|
|
4
5
|
const interface_redis_scheduler_1 = require("@antelopejs/interface-redis-scheduler");
|
|
5
|
-
const chai_1 = require("chai");
|
|
6
6
|
const RedisKey = "SchedulerUtil.Tasks";
|
|
7
7
|
async function cleanupRedis() {
|
|
8
8
|
const client = await (0, interface_redis_1.GetClient)();
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":";;AAAA,iEAAwD;AACxD,qFAO+C;
|
|
1
|
+
{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# Interface Redis Scheduler Documentation
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Interface Redis Scheduler stores tasks in a Redis sorted set with their due timestamps as scores. A local timer checks for due tasks, and Redis pub/sub notifies listeners when the schedule changes. Handlers that throw are retried, but the current implementation does not provide exactly-once delivery or an atomic claim across listeners.
|
|
6
|
+
|
|
7
|
+
Use one active listener for a queue and make handlers idempotent. Concurrent listeners can read the same due tasks before either removes them, and a process failure after removal but before handler completion can lose a task. Redis persistence protects queued entries only according to the server's persistence configuration.
|
|
8
|
+
|
|
9
|
+
## Getting Started
|
|
10
|
+
|
|
11
|
+
Install the package in your project:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @antelopejs/interface-redis-scheduler
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
> **Note:** This package depends on `@antelopejs/interface-redis`. You must have it installed and configured for the scheduler to connect to Redis.
|
|
18
|
+
|
|
19
|
+
## Core Concepts
|
|
20
|
+
|
|
21
|
+
The scheduler operates around three main ideas:
|
|
22
|
+
|
|
23
|
+
- **Handlers** process tasks of a specific type. Register them with `setHandler()` before scheduling any tasks.
|
|
24
|
+
- **Tasks** are stored in a Redis sorted set with their due time as the score. When a task is due, the scheduler calls the matching handler.
|
|
25
|
+
- **Listener** monitors the sorted set and executes tasks when they become due. Enable it with `enableListener()`.
|
|
26
|
+
|
|
27
|
+
## `setHandler`
|
|
28
|
+
|
|
29
|
+
The `setHandler` function registers a handler for a specific task type. Each handler has a unique name and a callback function that receives the task data as a string.
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
33
|
+
|
|
34
|
+
setHandler("send-email", async (taskInfo) => {
|
|
35
|
+
const emailData = JSON.parse(taskInfo);
|
|
36
|
+
await sendEmail({
|
|
37
|
+
to: emailData.recipient,
|
|
38
|
+
subject: emailData.subject,
|
|
39
|
+
body: emailData.body,
|
|
40
|
+
});
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Handler names must not contain the `:` character, as the scheduler uses it internally as a delimiter.
|
|
45
|
+
|
|
46
|
+
### Parameters
|
|
47
|
+
|
|
48
|
+
| Parameter | Type | Description |
|
|
49
|
+
| ------------- | --------------------------------------------- | ----------------------------------- |
|
|
50
|
+
| `handlerName` | `string` | Unique identifier for the task type |
|
|
51
|
+
| `handler` | `(taskInfo: string) => void \| Promise<void>` | Function that processes the task |
|
|
52
|
+
|
|
53
|
+
## `enableListener`
|
|
54
|
+
|
|
55
|
+
The `enableListener` function starts the task execution loop. It creates a dedicated Redis subscriber connection to receive real-time notifications when new tasks are added, and sets up a timer to check for due tasks.
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { enableListener } from "@antelopejs/interface-redis-scheduler";
|
|
59
|
+
|
|
60
|
+
async function startApp() {
|
|
61
|
+
// Register all handlers first
|
|
62
|
+
// ...
|
|
63
|
+
|
|
64
|
+
// Then start the listener
|
|
65
|
+
await enableListener();
|
|
66
|
+
console.log("Scheduler is active");
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
> **Important:** Register all task handlers before calling `enableListener()`. The listener begins processing tasks immediately.
|
|
71
|
+
|
|
72
|
+
## `disableListener`
|
|
73
|
+
|
|
74
|
+
`disableListener()` returns `Promise<void>` and only calls `quit()` on the notification subscriber. Call it only after `enableListener()` has completed successfully.
|
|
75
|
+
|
|
76
|
+
> **Warning:** It does not clear the pending timer, cancel running handlers, or wait for task completion. An already scheduled timer can still execute tasks and schedule another timer through `updateTimer()`. Do not use this function as a pause, a drain, or a guarantee that no more tasks run. The current public API has no complete timer shutdown operation.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { disableListener } from "@antelopejs/interface-redis-scheduler";
|
|
80
|
+
|
|
81
|
+
async function stopApp() {
|
|
82
|
+
await disableListener();
|
|
83
|
+
console.log("Notification subscriber closed; task processing may continue");
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## `addTask`
|
|
88
|
+
|
|
89
|
+
The `addTask` function schedules a task for execution at a specific time. The task is stored in a Redis sorted set with the due time as its score.
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
import { addTask } from "@antelopejs/interface-redis-scheduler";
|
|
93
|
+
|
|
94
|
+
async function scheduleReminder(userId: string) {
|
|
95
|
+
// Schedule for 3 days from now
|
|
96
|
+
const dueTime = Date.now() + 3 * 24 * 60 * 60 * 1000;
|
|
97
|
+
|
|
98
|
+
const taskInfo = JSON.stringify({
|
|
99
|
+
userId,
|
|
100
|
+
type: "password_reminder",
|
|
101
|
+
createdAt: new Date().toISOString(),
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
await addTask("send-email", dueTime, taskInfo);
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The function throws an error if the specified handler name has not been registered.
|
|
109
|
+
|
|
110
|
+
### Parameters
|
|
111
|
+
|
|
112
|
+
| Parameter | Type | Description |
|
|
113
|
+
| ------------- | -------- | ------------------------------------------------------------ |
|
|
114
|
+
| `handlerName` | `string` | The registered handler name that processes this task |
|
|
115
|
+
| `dueTime` | `number` | Unix timestamp in milliseconds when the task should execute |
|
|
116
|
+
| `taskInfo` | `string` | Data passed to the handler (typically a JSON-encoded string) |
|
|
117
|
+
|
|
118
|
+
## `removeTask`
|
|
119
|
+
|
|
120
|
+
The `removeTask` function cancels a previously scheduled task. The `taskInfo` string must match the one used when the task was added.
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
import { removeTask } from "@antelopejs/interface-redis-scheduler";
|
|
124
|
+
|
|
125
|
+
async function cancelReminder(userId: string) {
|
|
126
|
+
const taskInfo = JSON.stringify({
|
|
127
|
+
userId,
|
|
128
|
+
type: "password_reminder",
|
|
129
|
+
createdAt: "2025-04-05T12:00:00.000Z", // Must match exactly
|
|
130
|
+
});
|
|
131
|
+
|
|
132
|
+
await removeTask("send-email", taskInfo);
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The function throws an error if the specified handler name has not been registered.
|
|
137
|
+
|
|
138
|
+
> **Warning:** The `taskInfo` must be an exact string match of the original task. If the serialized JSON differs in key order or whitespace, the removal fails silently.
|
|
139
|
+
|
|
140
|
+
### Parameters
|
|
141
|
+
|
|
142
|
+
| Parameter | Type | Description |
|
|
143
|
+
| ------------- | -------- | ---------------------------------------------------- |
|
|
144
|
+
| `handlerName` | `string` | The handler name associated with the task |
|
|
145
|
+
| `taskInfo` | `string` | The exact task info string used when adding the task |
|
|
146
|
+
|
|
147
|
+
## Retry Logic
|
|
148
|
+
|
|
149
|
+
The scheduler automatically retries failed tasks. When a handler throws an error, the scheduler reschedules the task with a retry counter.
|
|
150
|
+
|
|
151
|
+
- **Maximum retries:** 3 retries after the initial attempt (4 attempts total)
|
|
152
|
+
- **Retry delay:** 5 seconds between each attempt
|
|
153
|
+
- **Behavior on exhaustion:** After 3 failed retries, the task is discarded and the error is logged to the console
|
|
154
|
+
|
|
155
|
+
No additional code is required to enable retries. The mechanism is built into the task execution loop.
|
|
156
|
+
|
|
157
|
+
```typescript
|
|
158
|
+
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
159
|
+
|
|
160
|
+
// If this handler throws, the scheduler retries up to 3 times
|
|
161
|
+
setHandler("process-payment", async (taskInfo) => {
|
|
162
|
+
const data = JSON.parse(taskInfo);
|
|
163
|
+
await processPayment(data);
|
|
164
|
+
// On failure: retry after 5s, then 5s, then 5s, then discard
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## Redis Storage
|
|
169
|
+
|
|
170
|
+
The scheduler uses a single Redis sorted set with the key `SchedulerUtil.Tasks`. Each member in the sorted set follows the format `handlerName:taskInfo`, and its score is the due timestamp in milliseconds.
|
|
171
|
+
|
|
172
|
+
For retried tasks, the format becomes `RETRY-{count}:handlerName:taskInfo`, where `{count}` tracks the number of retry attempts.
|
|
173
|
+
|
|
174
|
+
The scheduler also uses a Redis pub/sub channel named `SchedulerUtil` to notify listener instances when new tasks are added. These notifications refresh timers; they do not lock or atomically claim tasks across processes.
|
|
175
|
+
|
|
176
|
+
## `updateTimer`
|
|
177
|
+
|
|
178
|
+
The `updateTimer` function refreshes the internal timer that tracks the next due task. The scheduler calls this function automatically when tasks are added or completed. You do not need to call it in normal usage.
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
import { updateTimer } from "@antelopejs/interface-redis-scheduler";
|
|
182
|
+
|
|
183
|
+
// Force a timer refresh (advanced usage)
|
|
184
|
+
await updateTimer();
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
## `runTasks`
|
|
188
|
+
|
|
189
|
+
The `runTasks` function executes all tasks that are currently due. The scheduler calls this function automatically when the timer fires. It includes the retry logic for failed tasks. You do not need to call it in normal usage.
|
|
190
|
+
|
|
191
|
+
```typescript
|
|
192
|
+
import { runTasks } from "@antelopejs/interface-redis-scheduler";
|
|
193
|
+
|
|
194
|
+
// Manually trigger task execution (advanced usage)
|
|
195
|
+
await runTasks();
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Complete Example
|
|
199
|
+
|
|
200
|
+
Here is a full integration example showing handler registration, listener startup, task scheduling, and shutdown.
|
|
201
|
+
|
|
202
|
+
```typescript
|
|
203
|
+
import {
|
|
204
|
+
setHandler,
|
|
205
|
+
enableListener,
|
|
206
|
+
disableListener,
|
|
207
|
+
addTask,
|
|
208
|
+
removeTask,
|
|
209
|
+
} from "@antelopejs/interface-redis-scheduler";
|
|
210
|
+
|
|
211
|
+
// 1. Register task handlers
|
|
212
|
+
setHandler("send-email", async (taskInfo) => {
|
|
213
|
+
const data = JSON.parse(taskInfo);
|
|
214
|
+
await sendEmail(data.to, data.subject, data.body);
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
setHandler("cleanup-session", async (taskInfo) => {
|
|
218
|
+
const { sessionId } = JSON.parse(taskInfo);
|
|
219
|
+
await deleteSession(sessionId);
|
|
220
|
+
});
|
|
221
|
+
|
|
222
|
+
// 2. Start the listener
|
|
223
|
+
async function start() {
|
|
224
|
+
await enableListener();
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// 3. Schedule tasks from your application logic
|
|
228
|
+
async function onUserSignup(userId: string, email: string) {
|
|
229
|
+
// Send a welcome email in 1 hour
|
|
230
|
+
const dueTime = Date.now() + 60 * 60 * 1000;
|
|
231
|
+
await addTask(
|
|
232
|
+
"send-email",
|
|
233
|
+
dueTime,
|
|
234
|
+
JSON.stringify({
|
|
235
|
+
to: email,
|
|
236
|
+
subject: "Welcome!",
|
|
237
|
+
body: "Thanks for signing up.",
|
|
238
|
+
}),
|
|
239
|
+
);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
async function onUserLogout(sessionId: string) {
|
|
243
|
+
// Clean up session data in 24 hours
|
|
244
|
+
const dueTime = Date.now() + 24 * 60 * 60 * 1000;
|
|
245
|
+
await addTask("cleanup-session", dueTime, JSON.stringify({ sessionId }));
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
// 4. Close notifications on shutdown (pending timers and handlers may continue)
|
|
249
|
+
async function shutdown() {
|
|
250
|
+
await disableListener();
|
|
251
|
+
}
|
|
252
|
+
```
|
package/package.json
CHANGED
|
@@ -1,24 +1,30 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-redis-scheduler",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "AntelopeJS interface for Redis
|
|
3
|
+
"version": "0.0.8",
|
|
4
|
+
"description": "AntelopeJS interface for scheduling tasks on Redis, with retries on failure",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
7
7
|
"interface",
|
|
8
8
|
"redis",
|
|
9
|
-
"scheduler"
|
|
9
|
+
"scheduler",
|
|
10
|
+
"tasks"
|
|
10
11
|
],
|
|
12
|
+
"homepage": "https://interfaces.antelopejs.com/docs/redis-scheduler",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/AntelopeJS/interface-redis-scheduler/issues"
|
|
15
|
+
},
|
|
16
|
+
"license": "Apache-2.0",
|
|
11
17
|
"repository": {
|
|
12
18
|
"type": "git",
|
|
13
19
|
"url": "git+https://github.com/AntelopeJS/interface-redis-scheduler.git"
|
|
14
20
|
},
|
|
15
|
-
"license": "Apache-2.0",
|
|
16
|
-
"packageManager": "pnpm@10.6.5",
|
|
17
|
-
"main": "dist/index.js",
|
|
18
|
-
"types": "dist/index.d.ts",
|
|
19
21
|
"files": [
|
|
20
|
-
"dist"
|
|
22
|
+
"dist",
|
|
23
|
+
"docs",
|
|
24
|
+
"skills"
|
|
21
25
|
],
|
|
26
|
+
"main": "dist/index.js",
|
|
27
|
+
"types": "dist/index.d.ts",
|
|
22
28
|
"exports": {
|
|
23
29
|
".": {
|
|
24
30
|
"types": "./dist/index.d.ts",
|
|
@@ -26,39 +32,52 @@
|
|
|
26
32
|
},
|
|
27
33
|
"./package.json": "./package.json"
|
|
28
34
|
},
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public",
|
|
37
|
+
"provenance": true
|
|
38
|
+
},
|
|
29
39
|
"scripts": {
|
|
30
40
|
"build": "rimraf dist && tsc",
|
|
31
|
-
"format": "
|
|
32
|
-
"lint:fix": "
|
|
33
|
-
"lint": "
|
|
41
|
+
"format": "oxfmt .",
|
|
42
|
+
"lint:fix": "oxlint --fix",
|
|
43
|
+
"lint": "oxlint",
|
|
34
44
|
"prepack": "pnpm run build",
|
|
35
45
|
"release": "pnpm run lint && pnpm run prepack && release-it",
|
|
36
|
-
"test": "pnpm run build && ajs module test ."
|
|
46
|
+
"test": "pnpm run build && ajs module test .",
|
|
47
|
+
"format:check": "oxfmt --check .",
|
|
48
|
+
"knip": "knip"
|
|
37
49
|
},
|
|
38
50
|
"dependencies": {
|
|
39
51
|
"ioredis": "^5.10.1"
|
|
40
52
|
},
|
|
41
53
|
"devDependencies": {
|
|
42
|
-
"@antelopejs/
|
|
43
|
-
"@antelopejs/interface-
|
|
44
|
-
"@
|
|
54
|
+
"@antelopejs/core": "^1.16.0",
|
|
55
|
+
"@antelopejs/interface-core": "^0.2.4",
|
|
56
|
+
"@antelopejs/interface-redis": "^0.0.9",
|
|
57
|
+
"@antelopejs/tooling-configs": "^0.0.9",
|
|
45
58
|
"@types/chai": "^4.3.20",
|
|
46
59
|
"@types/mocha": "^10.0.10",
|
|
47
60
|
"@types/node": "^22.19.15",
|
|
48
61
|
"chai": "^4.5.0",
|
|
62
|
+
"eslint-plugin-perfectionist": "^5.11.0",
|
|
63
|
+
"knip": "^6.34.0",
|
|
64
|
+
"oxfmt": "^0.66.0",
|
|
65
|
+
"oxlint": "1.81.0",
|
|
66
|
+
"oxlint-tsgolint": "^7.0.2001",
|
|
49
67
|
"release-it": "^19.2.4",
|
|
50
68
|
"release-it-changelogen": "^0.1.0",
|
|
51
69
|
"rimraf": "^6.1.3",
|
|
52
70
|
"typescript": "^5.9.3"
|
|
53
71
|
},
|
|
54
72
|
"peerDependencies": {
|
|
55
|
-
"@antelopejs/interface-core": ">=0.
|
|
56
|
-
"@antelopejs/interface-redis": ">=0.0.
|
|
57
|
-
},
|
|
58
|
-
"publishConfig": {
|
|
59
|
-
"access": "public"
|
|
73
|
+
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
74
|
+
"@antelopejs/interface-redis": ">=0.0.9 <1.0.0"
|
|
60
75
|
},
|
|
76
|
+
"packageManager": "pnpm@10.6.5",
|
|
61
77
|
"antelopeJs": {
|
|
62
|
-
"test": "src/antelope.test.ts"
|
|
78
|
+
"test": "src/antelope.test.ts",
|
|
79
|
+
"skills": [
|
|
80
|
+
"./skills"
|
|
81
|
+
]
|
|
63
82
|
}
|
|
64
83
|
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: redis-scheduler-interface
|
|
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 coordinated across instances via pub/sub. 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
|
+
category: antelopejs-interface
|
|
5
|
+
tags: [antelopejs, redis, scheduler, tasks, background-jobs]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Redis Scheduler Interface
|
|
9
|
+
|
|
10
|
+
Distributed task scheduler on top of Redis: tasks live in one sorted set
|
|
11
|
+
(`SchedulerUtil.Tasks`) scored by their due timestamp; listener instances
|
|
12
|
+
coordinate through the `SchedulerUtil` pub/sub channel. Mental model: this is a
|
|
13
|
+
consumer-side utility, not a proxied service. All exported functions run in
|
|
14
|
+
your own module; Redis access goes through `GetClient()` from
|
|
15
|
+
`@antelopejs/interface-redis` (`setHandler` itself is purely local, no Redis
|
|
16
|
+
call) - there is no provider to write with
|
|
17
|
+
`ImplementInterface`. A Redis interface implementation (e.g. the
|
|
18
|
+
`@antelopejs/redis` module) must be loaded in the app.
|
|
19
|
+
|
|
20
|
+
## Imports
|
|
21
|
+
|
|
22
|
+
Only the package root is exported:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
import {
|
|
26
|
+
setHandler,
|
|
27
|
+
enableListener,
|
|
28
|
+
disableListener,
|
|
29
|
+
addTask,
|
|
30
|
+
removeTask,
|
|
31
|
+
} from "@antelopejs/interface-redis-scheduler";
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
(`updateTimer` and `runTasks` are also exported but belong to the internal
|
|
35
|
+
execution loop - only call them in tests or advanced scenarios.)
|
|
36
|
+
|
|
37
|
+
## Consumption example
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import {
|
|
41
|
+
setHandler,
|
|
42
|
+
enableListener,
|
|
43
|
+
disableListener,
|
|
44
|
+
addTask,
|
|
45
|
+
} from "@antelopejs/interface-redis-scheduler";
|
|
46
|
+
|
|
47
|
+
// 1. Register handlers first (name must not contain ':')
|
|
48
|
+
setHandler("overdue-notice", async (taskInfo) => {
|
|
49
|
+
const data = JSON.parse(taskInfo);
|
|
50
|
+
await notifyMember(data.memberId, data.bookTitle);
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
// 2. Start the execution loop (module start)
|
|
54
|
+
await enableListener();
|
|
55
|
+
|
|
56
|
+
// 3. Schedule a task: dueTime is a Unix timestamp in milliseconds
|
|
57
|
+
await addTask(
|
|
58
|
+
"overdue-notice",
|
|
59
|
+
Date.now() + 60 * 60 * 1000,
|
|
60
|
+
JSON.stringify({ memberId: "M-1042", bookTitle: "The Heron's Atlas" }),
|
|
61
|
+
);
|
|
62
|
+
|
|
63
|
+
// 4. On shutdown
|
|
64
|
+
await disableListener();
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Gotchas
|
|
68
|
+
|
|
69
|
+
- Handler names must not contain `:` - it delimits the sorted-set member
|
|
70
|
+
format `handlerName:taskInfo`. `setHandler` throws otherwise.
|
|
71
|
+
- `addTask` and `removeTask` throw for handler names not registered in the
|
|
72
|
+
current process. Always call `setHandler` before scheduling.
|
|
73
|
+
- Register all handlers before `enableListener()`; the listener starts
|
|
74
|
+
executing due tasks immediately.
|
|
75
|
+
- `taskInfo` is a plain string. Serialize/parse (typically JSON) yourself.
|
|
76
|
+
- `removeTask` needs the exact original `taskInfo` string; a JSON payload with
|
|
77
|
+
different key order or whitespace fails to match, silently removing nothing.
|
|
78
|
+
- Failed handlers are retried up to 3 times with a 5-second delay (the member
|
|
79
|
+
becomes `RETRY-{n}:handlerName:taskInfo`), then discarded; errors are logged
|
|
80
|
+
through interface-core `Logging.Error`.
|
|
81
|
+
- `enableListener` duplicates the shared Redis client into a dedicated
|
|
82
|
+
subscriber connection; `disableListener` quits that subscriber on shutdown.
|
|
83
|
+
- `disableListener` only quits the subscriber connection; it does not clear a
|
|
84
|
+
pending execution timer, so a task that comes due right after shutdown may
|
|
85
|
+
still run once. It also throws if `enableListener` was never called.
|
|
86
|
+
- Peer interfaces `@antelopejs/interface-core` and `@antelopejs/interface-redis`
|
|
87
|
+
must be installed alongside this package.
|
|
88
|
+
|
|
89
|
+
## Deeper reference
|
|
90
|
+
|
|
91
|
+
See this package's `docs/1.introduction.md` (Overview, Getting Started, Core
|
|
92
|
+
Concepts, per-function sections, Retry Logic, Redis Storage, Complete Example)
|
|
93
|
+
and `dist/index.d.ts`. Do not duplicate them here.
|