@antelopejs/interface-redis-scheduler 0.0.5 → 0.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Interface Redis Scheduler Documentation
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Interface Redis Scheduler provides a distributed task scheduling system built on top of Redis. It stores tasks in a Redis sorted set with their due timestamps as scores, enabling precise scheduling and efficient retrieval of tasks that are ready to execute. The scheduler supports automatic retries for failed tasks and coordinates across multiple application instances using Redis pub/sub.
|
|
6
|
+
|
|
7
|
+
## Getting Started
|
|
8
|
+
|
|
9
|
+
Install the package in your project:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @antelopejs/interface-redis-scheduler
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
> **Note:** This package depends on `@antelopejs/interface-redis`. You must have it installed and configured for the scheduler to connect to Redis.
|
|
16
|
+
|
|
17
|
+
## Core Concepts
|
|
18
|
+
|
|
19
|
+
The scheduler operates around three main ideas:
|
|
20
|
+
|
|
21
|
+
- **Handlers** process tasks of a specific type. Register them with `setHandler()` before scheduling any tasks.
|
|
22
|
+
- **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.
|
|
23
|
+
- **Listener** monitors the sorted set and executes tasks when they become due. Enable it with `enableListener()`.
|
|
24
|
+
|
|
25
|
+
## `setHandler`
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
31
|
+
|
|
32
|
+
setHandler("send-email", async (taskInfo) => {
|
|
33
|
+
const emailData = JSON.parse(taskInfo);
|
|
34
|
+
await sendEmail({
|
|
35
|
+
to: emailData.recipient,
|
|
36
|
+
subject: emailData.subject,
|
|
37
|
+
body: emailData.body,
|
|
38
|
+
});
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Handler names must not contain the `:` character, as the scheduler uses it internally as a delimiter.
|
|
43
|
+
|
|
44
|
+
### Parameters
|
|
45
|
+
|
|
46
|
+
| Parameter | Type | Description |
|
|
47
|
+
| ------------- | ------------------------------------------- | ----------------------------------- |
|
|
48
|
+
| `handlerName` | `string` | Unique identifier for the task type |
|
|
49
|
+
| `handler` | `(taskInfo: string) => void \| Promise<void>` | Function that processes the task |
|
|
50
|
+
|
|
51
|
+
## `enableListener`
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
import { enableListener } from "@antelopejs/interface-redis-scheduler";
|
|
57
|
+
|
|
58
|
+
async function startApp() {
|
|
59
|
+
// Register all handlers first
|
|
60
|
+
// ...
|
|
61
|
+
|
|
62
|
+
// Then start the listener
|
|
63
|
+
await enableListener();
|
|
64
|
+
console.log("Scheduler is active");
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
> **Important:** Register all task handlers before calling `enableListener()`. The listener begins processing tasks immediately.
|
|
69
|
+
|
|
70
|
+
## `disableListener`
|
|
71
|
+
|
|
72
|
+
The `disableListener` function stops the scheduler from processing any further tasks. Call it during application shutdown.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
import { disableListener } from "@antelopejs/interface-redis-scheduler";
|
|
76
|
+
|
|
77
|
+
async function stopApp() {
|
|
78
|
+
await disableListener();
|
|
79
|
+
console.log("Scheduler stopped");
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## `addTask`
|
|
84
|
+
|
|
85
|
+
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.
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
import { addTask } from "@antelopejs/interface-redis-scheduler";
|
|
89
|
+
|
|
90
|
+
async function scheduleReminder(userId: string) {
|
|
91
|
+
// Schedule for 3 days from now
|
|
92
|
+
const dueTime = Date.now() + 3 * 24 * 60 * 60 * 1000;
|
|
93
|
+
|
|
94
|
+
const taskInfo = JSON.stringify({
|
|
95
|
+
userId,
|
|
96
|
+
type: "password_reminder",
|
|
97
|
+
createdAt: new Date().toISOString(),
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
await addTask("send-email", dueTime, taskInfo);
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The function throws an error if the specified handler name has not been registered.
|
|
105
|
+
|
|
106
|
+
### Parameters
|
|
107
|
+
|
|
108
|
+
| Parameter | Type | Description |
|
|
109
|
+
| ------------- | -------- | ------------------------------------------------------------ |
|
|
110
|
+
| `handlerName` | `string` | The registered handler name that processes this task |
|
|
111
|
+
| `dueTime` | `number` | Unix timestamp in milliseconds when the task should execute |
|
|
112
|
+
| `taskInfo` | `string` | Data passed to the handler (typically a JSON-encoded string) |
|
|
113
|
+
|
|
114
|
+
## `removeTask`
|
|
115
|
+
|
|
116
|
+
The `removeTask` function cancels a previously scheduled task. The `taskInfo` string must match the one used when the task was added.
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
import { removeTask } from "@antelopejs/interface-redis-scheduler";
|
|
120
|
+
|
|
121
|
+
async function cancelReminder(userId: string) {
|
|
122
|
+
const taskInfo = JSON.stringify({
|
|
123
|
+
userId,
|
|
124
|
+
type: "password_reminder",
|
|
125
|
+
createdAt: "2025-04-05T12:00:00.000Z", // Must match exactly
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
await removeTask("send-email", taskInfo);
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The function throws an error if the specified handler name has not been registered.
|
|
133
|
+
|
|
134
|
+
> **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.
|
|
135
|
+
|
|
136
|
+
### Parameters
|
|
137
|
+
|
|
138
|
+
| Parameter | Type | Description |
|
|
139
|
+
| ------------- | -------- | ------------------------------------------------- |
|
|
140
|
+
| `handlerName` | `string` | The handler name associated with the task |
|
|
141
|
+
| `taskInfo` | `string` | The exact task info string used when adding the task |
|
|
142
|
+
|
|
143
|
+
## Retry Logic
|
|
144
|
+
|
|
145
|
+
The scheduler automatically retries failed tasks. When a handler throws an error, the scheduler reschedules the task with a retry counter.
|
|
146
|
+
|
|
147
|
+
- **Maximum retries:** 3 attempts
|
|
148
|
+
- **Retry delay:** 5 seconds between each attempt
|
|
149
|
+
- **Behavior on exhaustion:** After 3 failed retries, the task is discarded and the error is logged to the console
|
|
150
|
+
|
|
151
|
+
No additional code is required to enable retries. The mechanism is built into the task execution loop.
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { setHandler } from "@antelopejs/interface-redis-scheduler";
|
|
155
|
+
|
|
156
|
+
// If this handler throws, the scheduler retries up to 3 times
|
|
157
|
+
setHandler("process-payment", async (taskInfo) => {
|
|
158
|
+
const data = JSON.parse(taskInfo);
|
|
159
|
+
await processPayment(data);
|
|
160
|
+
// On failure: retry after 5s, then 5s, then 5s, then discard
|
|
161
|
+
});
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Redis Storage
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
For retried tasks, the format becomes `RETRY-{count}:handlerName:taskInfo`, where `{count}` tracks the number of retry attempts.
|
|
169
|
+
|
|
170
|
+
The scheduler also uses a Redis pub/sub channel named `SchedulerUtil` to notify listener instances when new tasks are added, ensuring timers are updated across all nodes in a cluster.
|
|
171
|
+
|
|
172
|
+
## `updateTimer`
|
|
173
|
+
|
|
174
|
+
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.
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
import { updateTimer } from "@antelopejs/interface-redis-scheduler";
|
|
178
|
+
|
|
179
|
+
// Force a timer refresh (advanced usage)
|
|
180
|
+
await updateTimer();
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## `runTasks`
|
|
184
|
+
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
import { runTasks } from "@antelopejs/interface-redis-scheduler";
|
|
189
|
+
|
|
190
|
+
// Manually trigger task execution (advanced usage)
|
|
191
|
+
await runTasks();
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Complete Example
|
|
195
|
+
|
|
196
|
+
Here is a full integration example showing handler registration, listener startup, task scheduling, and shutdown.
|
|
197
|
+
|
|
198
|
+
```typescript
|
|
199
|
+
import {
|
|
200
|
+
setHandler,
|
|
201
|
+
enableListener,
|
|
202
|
+
disableListener,
|
|
203
|
+
addTask,
|
|
204
|
+
removeTask,
|
|
205
|
+
} from "@antelopejs/interface-redis-scheduler";
|
|
206
|
+
|
|
207
|
+
// 1. Register task handlers
|
|
208
|
+
setHandler("send-email", async (taskInfo) => {
|
|
209
|
+
const data = JSON.parse(taskInfo);
|
|
210
|
+
await sendEmail(data.to, data.subject, data.body);
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
setHandler("cleanup-session", async (taskInfo) => {
|
|
214
|
+
const { sessionId } = JSON.parse(taskInfo);
|
|
215
|
+
await deleteSession(sessionId);
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
// 2. Start the listener
|
|
219
|
+
async function start() {
|
|
220
|
+
await enableListener();
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
// 3. Schedule tasks from your application logic
|
|
224
|
+
async function onUserSignup(userId: string, email: string) {
|
|
225
|
+
// Send a welcome email in 1 hour
|
|
226
|
+
const dueTime = Date.now() + 60 * 60 * 1000;
|
|
227
|
+
await addTask(
|
|
228
|
+
"send-email",
|
|
229
|
+
dueTime,
|
|
230
|
+
JSON.stringify({ to: email, subject: "Welcome!", body: "Thanks for signing up." }),
|
|
231
|
+
);
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
async function onUserLogout(sessionId: string) {
|
|
235
|
+
// Clean up session data in 24 hours
|
|
236
|
+
const dueTime = Date.now() + 24 * 60 * 60 * 1000;
|
|
237
|
+
await addTask(
|
|
238
|
+
"cleanup-session",
|
|
239
|
+
dueTime,
|
|
240
|
+
JSON.stringify({ sessionId }),
|
|
241
|
+
);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
// 4. Stop the listener on shutdown
|
|
245
|
+
async function shutdown() {
|
|
246
|
+
await disableListener();
|
|
247
|
+
}
|
|
248
|
+
```
|
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.7",
|
|
4
4
|
"description": "AntelopeJS interface for Redis-based task scheduling",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -17,7 +17,9 @@
|
|
|
17
17
|
"main": "dist/index.js",
|
|
18
18
|
"types": "dist/index.d.ts",
|
|
19
19
|
"files": [
|
|
20
|
-
"dist"
|
|
20
|
+
"dist",
|
|
21
|
+
"docs",
|
|
22
|
+
"skills"
|
|
21
23
|
],
|
|
22
24
|
"exports": {
|
|
23
25
|
".": {
|
|
@@ -36,11 +38,11 @@
|
|
|
36
38
|
"test": "pnpm run build && ajs module test ."
|
|
37
39
|
},
|
|
38
40
|
"dependencies": {
|
|
39
|
-
"@antelopejs/interface-core": "^0.0.3",
|
|
40
|
-
"@antelopejs/interface-redis": "^0.0.5",
|
|
41
41
|
"ioredis": "^5.10.1"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
+
"@antelopejs/interface-core": "^0.0.5",
|
|
45
|
+
"@antelopejs/interface-redis": "^0.0.6",
|
|
44
46
|
"@biomejs/biome": "2.3.2",
|
|
45
47
|
"@types/chai": "^4.3.20",
|
|
46
48
|
"@types/mocha": "^10.0.10",
|
|
@@ -51,10 +53,17 @@
|
|
|
51
53
|
"rimraf": "^6.1.3",
|
|
52
54
|
"typescript": "^5.9.3"
|
|
53
55
|
},
|
|
56
|
+
"peerDependencies": {
|
|
57
|
+
"@antelopejs/interface-core": ">=0.0.3 <1.0.0",
|
|
58
|
+
"@antelopejs/interface-redis": ">=0.0.5 <1.0.0"
|
|
59
|
+
},
|
|
54
60
|
"publishConfig": {
|
|
55
61
|
"access": "public"
|
|
56
62
|
},
|
|
57
63
|
"antelopeJs": {
|
|
58
|
-
"test": "src/antelope.test.ts"
|
|
64
|
+
"test": "src/antelope.test.ts",
|
|
65
|
+
"skills": [
|
|
66
|
+
"./skills"
|
|
67
|
+
]
|
|
59
68
|
}
|
|
60
69
|
}
|
|
@@ -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.
|