@softistx/janus-webhooks-redis 0.0.0-stage → 0.12.5
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/LICENSE +21 -0
- package/README.md +203 -2
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +431 -0
- package/dist/index.js.map +12 -0
- package/dist/queue.d.ts +30 -0
- package/dist/queue.d.ts.map +1 -0
- package/dist/replies.d.ts +28 -0
- package/dist/replies.d.ts.map +1 -0
- package/dist/scripts.d.ts +58 -0
- package/dist/scripts.d.ts.map +1 -0
- package/docs/README.md +12 -0
- package/docs/guide/wiring.md +162 -0
- package/docs/roadmap.md +63 -0
- package/docs/troubleshooting.md +339 -0
- package/package.json +65 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Steve Tsala
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,204 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @softistx/janus-webhooks-redis
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Redis queue for [`@softistx/janus-webhooks`](https://github.com/softistx/nxgt-janus/tree/develop/packages/janus-webhooks):
|
|
4
|
+
**deliveries wait in Redis**, on
|
|
5
|
+
[`@softistx/redis`](https://github.com/softistx/nxgt-data/blob/develop/packages/redis/README.md)'s connection,
|
|
6
|
+
shared by every process of your application. A retry waiting when a process
|
|
7
|
+
crashes, restarts or is redeployed is sent by the next one, and a request cut
|
|
8
|
+
short is sent again once its lease lapses.
|
|
9
|
+
|
|
10
|
+
It implements the `WebhookQueue` port, and passes the
|
|
11
|
+
`@softistx/janus-webhooks/conformance` suite against a real Redis, outages
|
|
12
|
+
included, on every CI run.
|
|
13
|
+
|
|
14
|
+
> **0.x.** A minor version may still change the surface; the changelog says how.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
Public on npmjs:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
bun add @softistx/janus-webhooks-redis @softistx/janus-webhooks @softistx/janus @softistx/redis
|
|
22
|
+
bun add zod # @softistx/redis's peer, zod 4, if your application has none
|
|
23
|
+
bun add -d typescript # 6 or 7
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Every peer is required:
|
|
27
|
+
- `@softistx/janus-webhooks`, whose port it implements;
|
|
28
|
+
- `@softistx/janus`, whose `UserEvent` it holds and whose `StoreFailure` it
|
|
29
|
+
throws — a **peer**, never a dependency, so `instanceof StoreFailure` holds
|
|
30
|
+
in your code;
|
|
31
|
+
- `@softistx/redis`, `>=0.14.0 <1`, whose connection wraps Bun's own `RedisClient`,
|
|
32
|
+
so this runs on **Bun**;
|
|
33
|
+
- `typescript` 6 or 7.
|
|
34
|
+
|
|
35
|
+
The `@softistx/redis` floor is tested, not claimed: the package's specs and its
|
|
36
|
+
typecheck run on `@softistx/redis` 0.14.0 as well, in the Floors job, on every CI
|
|
37
|
+
run.
|
|
38
|
+
|
|
39
|
+
It needs **Redis 7.0 or later**, or Valkey — see
|
|
40
|
+
[what Redis must be configured with](docs/guide/wiring.md#what-redis-must-be-configured-with).
|
|
41
|
+
Like `@softistx/janus`, it expects `"moduleResolution": "bundler"`.
|
|
42
|
+
|
|
43
|
+
## Usage
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { webhooks } from '@softistx/janus-webhooks';
|
|
47
|
+
import { createRedisWebhookQueue } from '@softistx/janus-webhooks-redis';
|
|
48
|
+
import { connectRedis } from '@softistx/redis';
|
|
49
|
+
|
|
50
|
+
const secret = process.env.CRM_WEBHOOK_SECRET; // whsec_…, from mintWebhookSecret()
|
|
51
|
+
if (!secret) throw new Error('CRM_WEBHOOK_SECRET is not set');
|
|
52
|
+
|
|
53
|
+
const redis = await connectRedis(process.env.REDIS_URL ?? 'redis://localhost:6379', {
|
|
54
|
+
enableOfflineQueue: false, // an outage fails the insert at once, not after 31 s
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
export const listener = webhooks({
|
|
58
|
+
endpoints: [{ id: 'crm', url: 'https://crm.example.com/hooks/janus', secrets: [secret] }],
|
|
59
|
+
queue: createRedisWebhookQueue(redis), // every process passes the same Redis and prefix
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
// janus({ …, events: listener })
|
|
63
|
+
|
|
64
|
+
process.on('SIGTERM', async () => {
|
|
65
|
+
await listener.close(); // gives nothing up: what waits is sent by the next process
|
|
66
|
+
process.exit(0);
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Give each endpoint an `id` when you first pass a queue: it is what the queue
|
|
71
|
+
knows the endpoint by. [Wiring](docs/guide/wiring.md) covers the connection,
|
|
72
|
+
the prefix, and what Redis must be configured with.
|
|
73
|
+
|
|
74
|
+
## API
|
|
75
|
+
|
|
76
|
+
| Export | What it is |
|
|
77
|
+
| --- | --- |
|
|
78
|
+
| `createRedisWebhookQueue(redis, options?)` | Returns a `WebhookQueue`, for `webhooks({ queue })`. `redis` is what `connectRedis` returns. It connects to nothing and creates nothing: the keys are made by the first insert. |
|
|
79
|
+
| `RedisWebhookQueueOptions` | `{ prefix? }`: what every key starts with, `janus:webhooks:` by default. Every process sharing deliveries passes the same one. |
|
|
80
|
+
|
|
81
|
+
## Several applications, one Redis
|
|
82
|
+
|
|
83
|
+
`prefix` starts every key (`janus:webhooks:` by default). Applications, or
|
|
84
|
+
partitions of one, sharing a Redis each take a prefix of their own — and every
|
|
85
|
+
process of one of them the same:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
import { createRedisWebhookQueue } from '@softistx/janus-webhooks-redis';
|
|
89
|
+
|
|
90
|
+
const billing = createRedisWebhookQueue(redis, { prefix: 'billing:webhooks:' });
|
|
91
|
+
const orders = createRedisWebhookQueue(redis, { prefix: 'orders:webhooks:' });
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## What Redis holds
|
|
95
|
+
|
|
96
|
+
Each delivery's event — a user event's fields, or a generic event's `data` as
|
|
97
|
+
JSON — and endpoint id, **never a URL or a secret** — with
|
|
98
|
+
[one Lua script per method](docs/guide/wiring.md#one-lua-script-per-method),
|
|
99
|
+
so no two claims answer one delivery.
|
|
100
|
+
[Wiring](docs/guide/wiring.md#what-redis-holds-and-for-how-long) has each key
|
|
101
|
+
and how long it stays.
|
|
102
|
+
|
|
103
|
+
## Traps
|
|
104
|
+
|
|
105
|
+
- **Hold the new event types back until every process sharing a queue is
|
|
106
|
+
upgraded.** A delivery of `user.secondFactorEnabled` or
|
|
107
|
+
`user.secondFactorDisabled`, written by 0.2.0, is `STORE_FAILED` (`a reply
|
|
108
|
+
that is not … a user event type`) in a 0.1.x process that claims it — and
|
|
109
|
+
so is one of `user.recoveryCodesRegenerated` or `user.recoveryCodeUsed`,
|
|
110
|
+
written by 0.3.0, in a 0.2.x process, and one of `user.passwordChanged` or
|
|
111
|
+
`user.emailChanged`, written by 0.4.0, in a 0.3.x process, and one of
|
|
112
|
+
`user.newDeviceSignedIn`, written by 0.5.0, in a 0.4.x process, and one of
|
|
113
|
+
`user.avatarChanged` or `user.avatarRemoved`, written by 0.6.0, in a 0.5.x
|
|
114
|
+
process, and one of `user.socialLinked` or `user.socialUnlinked`, written by
|
|
115
|
+
0.8.0, in a 0.7.x process, and one of `user.passkeyAdded`,
|
|
116
|
+
`user.passkeyRemoved` or `user.passkeyCloneSuspected`, written by 0.10.0, in
|
|
117
|
+
a 0.9.x process, and one of `user.apiKeyCreated` or `user.apiKeyRevoked`,
|
|
118
|
+
written by 0.11.0, in a 0.10.x or earlier process — and that
|
|
119
|
+
endpoint's claims fail
|
|
120
|
+
there until every process is upgraded. Upgrade
|
|
121
|
+
`@softistx/janus`, `@softistx/janus-webhooks` and `@softistx/janus-webhooks-redis`
|
|
122
|
+
together — their peer ranges move as one — with each endpoint limited to
|
|
123
|
+
the `types` the older processes know, and drop the limit once every
|
|
124
|
+
process runs the new versions:
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
webhooks({
|
|
128
|
+
queue,
|
|
129
|
+
endpoints: [{ id: 'crm', url, secrets: [secret], types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.deleted'] }],
|
|
130
|
+
});
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
That list is for 0.1.x processes. When the oldest run 0.2.x, which read the
|
|
134
|
+
second factor's events but not the recovery codes', add those two:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.deleted'],
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
When the oldest run 0.3.x, which read the recovery codes' events but not
|
|
141
|
+
the change events', add those two:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.recoveryCodesRegenerated', 'user.recoveryCodeUsed', 'user.deleted'],
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
When the oldest run 0.4.x, which read the change events but not the new
|
|
148
|
+
device's, add those two:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
types: ['user.created', 'user.emailVerified', 'user.passwordReset', 'user.passwordChanged', 'user.emailChanged', 'user.secondFactorEnabled', 'user.secondFactorDisabled', 'user.recoveryCodesRegenerated', 'user.recoveryCodeUsed', 'user.deleted'],
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The same holds for the passkey events: when the oldest run 0.9.x, leave
|
|
155
|
+
`user.passkeyAdded`, `user.passkeyRemoved` and `user.passkeyCloneSuspected`
|
|
156
|
+
out of the list until every process runs 0.10.0 or later, and
|
|
157
|
+
`user.apiKeyCreated` and `user.apiKeyRevoked` until every process runs
|
|
158
|
+
0.11.0 or later.
|
|
159
|
+
|
|
160
|
+
- **Send events of your own only once every process sharing a queue is
|
|
161
|
+
upgraded** to 0.12.0 or later: an earlier process that claims a generic
|
|
162
|
+
event's delivery cannot read it back (`STORE_FAILED`), and that endpoint's
|
|
163
|
+
claims fail there until it is upgraded.
|
|
164
|
+
- **Eviction is data loss.** A Redis whose `maxmemory-policy` evicts keys
|
|
165
|
+
drops deliveries without a word — no retry, no `onGivingUp`. Run this on a
|
|
166
|
+
Redis with `noeviction`; a full one then refuses the insert with `OOM`,
|
|
167
|
+
which `janus` reports as `JANUS_EVENT_FAILED`.
|
|
168
|
+
- **Persistence is what makes it durable.** Without RDB or AOF, restarting
|
|
169
|
+
Redis loses every delivery waiting in it. Enable AOF (`appendfsync
|
|
170
|
+
everysec` loses at most a second of inserts on a crash) or RDB snapshots.
|
|
171
|
+
- **Redis Cluster is not supported.** A script touches the keys of a
|
|
172
|
+
delivery and of its endpoint, which may live in different slots. Use a
|
|
173
|
+
single Redis, or a primary with replicas.
|
|
174
|
+
- **By default, an outage makes every flow wait 31 seconds.** The listener
|
|
175
|
+
awaits the insert, and Bun's client queues commands while it reconnects.
|
|
176
|
+
With `enableOfflineQueue: false` the insert fails at once, the flow goes
|
|
177
|
+
on, and the event is reported as `JANUS_EVENT_FAILED`.
|
|
178
|
+
- **One prefix per application.** Two applications sharing a prefix share
|
|
179
|
+
deliveries, and each gives up the other's endpoints as `endpointRemoved`
|
|
180
|
+
after `orphanGrace` — or, with `endpoints` a function, at the delivery's
|
|
181
|
+
next attempt.
|
|
182
|
+
- **A generic event's `data` is stored as JSON.** `insertDeliveries` refuses,
|
|
183
|
+
with a `TypeError` and before anything is written, an `event.data` that is
|
|
184
|
+
not a JSON object (`webhookQueue.insertDeliveries: event.data is a JSON object`).
|
|
185
|
+
|
|
186
|
+
## Documentation
|
|
187
|
+
|
|
188
|
+
- [Guides](docs/README.md): wiring the queue, the prefix, what Redis must be configured with, what Redis holds and how each method stays atomic
|
|
189
|
+
- [Troubleshooting](docs/troubleshooting.md): look up the error message you see
|
|
190
|
+
- [Roadmap](docs/roadmap.md): what is next, and what is not planned
|
|
191
|
+
- [`@softistx/janus-webhooks`'s queues guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-webhooks/docs/guide/queues.md): claims, leases, orphans, and what a queue must do
|
|
192
|
+
|
|
193
|
+
## Type safety, counted
|
|
194
|
+
|
|
195
|
+
Four plausible mistakes are refused by the compiler, each with a
|
|
196
|
+
`@ts-expect-error` case in `test/types/queue.ts`:
|
|
197
|
+
- a URL instead of a connection;
|
|
198
|
+
- Bun's client instead of the connection that holds it;
|
|
199
|
+
- the promise `connectRedis` answers, not awaited;
|
|
200
|
+
- a `prefix` that is not a string.
|
|
201
|
+
|
|
202
|
+
## Licence
|
|
203
|
+
|
|
204
|
+
MIT
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@softistx/janus-webhooks-redis` — the Redis queue for `@softistx/janus-webhooks`,
|
|
3
|
+
* on `@softistx/redis`.
|
|
4
|
+
*
|
|
5
|
+
* Implements the `WebhookQueue` port: deliveries wait in Redis, shared by
|
|
6
|
+
* every process of an application, so a retry waiting when one stops is sent
|
|
7
|
+
* by the next. It defines **no error class**: a failure is `@softistx/janus`'s
|
|
8
|
+
* own `StoreFailure`, and a date, a `limit` or a `failed.status` the queue
|
|
9
|
+
* could not read back is a `TypeError` before any I/O.
|
|
10
|
+
*/
|
|
11
|
+
export { createRedisWebhookQueue, type RedisWebhookQueueOptions, } from './queue';
|
|
12
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACN,uBAAuB,EACvB,KAAK,wBAAwB,GAC7B,MAAM,SAAS,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
// src/queue.ts
|
|
2
|
+
import { randomUUID } from "node:crypto";
|
|
3
|
+
import { StoreFailure as StoreFailure2 } from "@softistx/janus";
|
|
4
|
+
|
|
5
|
+
// src/replies.ts
|
|
6
|
+
import {
|
|
7
|
+
StoreFailure
|
|
8
|
+
} from "@softistx/janus";
|
|
9
|
+
function stamp(at) {
|
|
10
|
+
return String(at.getTime());
|
|
11
|
+
}
|
|
12
|
+
function stampOf(at, operation, name) {
|
|
13
|
+
if (!(at instanceof Date) || Number.isNaN(at.getTime())) {
|
|
14
|
+
throw new TypeError(`webhookQueue.${operation}: ${name} is a valid Date`);
|
|
15
|
+
}
|
|
16
|
+
return stamp(at);
|
|
17
|
+
}
|
|
18
|
+
function limitOf(limit, operation) {
|
|
19
|
+
if (!Number.isSafeInteger(limit) || limit < 0) {
|
|
20
|
+
throw new TypeError(`webhookQueue.${operation}: limit is a whole number of deliveries, 0 or more`);
|
|
21
|
+
}
|
|
22
|
+
return String(limit);
|
|
23
|
+
}
|
|
24
|
+
function statusOf(status, operation) {
|
|
25
|
+
if (status === null)
|
|
26
|
+
return "";
|
|
27
|
+
if (!Number.isSafeInteger(status) || status < 0) {
|
|
28
|
+
throw new TypeError(`webhookQueue.${operation}: failed.status is null or a whole number`);
|
|
29
|
+
}
|
|
30
|
+
return String(status);
|
|
31
|
+
}
|
|
32
|
+
function toDeliveries(reply, operation) {
|
|
33
|
+
if (!Array.isArray(reply))
|
|
34
|
+
throw unreadable(operation, "a list");
|
|
35
|
+
return reply.map((one) => toDelivery(one, operation));
|
|
36
|
+
}
|
|
37
|
+
function toHeld(reply, operation) {
|
|
38
|
+
if (reply !== 0 && reply !== 1)
|
|
39
|
+
throw unreadable(operation, "0 or 1");
|
|
40
|
+
return reply === 1;
|
|
41
|
+
}
|
|
42
|
+
function toCount(reply, operation) {
|
|
43
|
+
if (!Number.isSafeInteger(reply) || reply < 0) {
|
|
44
|
+
throw unreadable(operation, "a count");
|
|
45
|
+
}
|
|
46
|
+
return reply;
|
|
47
|
+
}
|
|
48
|
+
function toDelivery(reply, operation) {
|
|
49
|
+
if (!Array.isArray(reply) || typeof reply[0] !== "string") {
|
|
50
|
+
throw unreadable(operation, "a delivery");
|
|
51
|
+
}
|
|
52
|
+
const [id, ...rest] = reply;
|
|
53
|
+
const read = readerOf(rest, operation);
|
|
54
|
+
const lease = read.text("lease");
|
|
55
|
+
if (lease === "")
|
|
56
|
+
throw unreadable(operation, "a delivery claimed");
|
|
57
|
+
const event = read.has("data") ? {
|
|
58
|
+
id: read.text("eventId"),
|
|
59
|
+
type: read.name("type"),
|
|
60
|
+
occurredAt: read.date("occurredAt"),
|
|
61
|
+
data: read.json("data")
|
|
62
|
+
} : {
|
|
63
|
+
id: read.text("eventId"),
|
|
64
|
+
type: read.type("type"),
|
|
65
|
+
occurredAt: read.date("occurredAt"),
|
|
66
|
+
userId: read.text("userId"),
|
|
67
|
+
userType: read.text("userType"),
|
|
68
|
+
...read.optionalProvider()
|
|
69
|
+
};
|
|
70
|
+
return {
|
|
71
|
+
id,
|
|
72
|
+
event,
|
|
73
|
+
endpoint: read.text("endpoint"),
|
|
74
|
+
attempts: read.count("attempts"),
|
|
75
|
+
failed: read.failure(),
|
|
76
|
+
lease
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
var TYPES = {
|
|
80
|
+
"user.created": true,
|
|
81
|
+
"user.emailVerified": true,
|
|
82
|
+
"user.passwordReset": true,
|
|
83
|
+
"user.passwordChanged": true,
|
|
84
|
+
"user.emailChanged": true,
|
|
85
|
+
"user.secondFactorEnabled": true,
|
|
86
|
+
"user.secondFactorDisabled": true,
|
|
87
|
+
"user.recoveryCodesRegenerated": true,
|
|
88
|
+
"user.recoveryCodeUsed": true,
|
|
89
|
+
"user.newDeviceSignedIn": true,
|
|
90
|
+
"user.avatarChanged": true,
|
|
91
|
+
"user.avatarRemoved": true,
|
|
92
|
+
"user.socialLinked": true,
|
|
93
|
+
"user.socialUnlinked": true,
|
|
94
|
+
"user.passkeyAdded": true,
|
|
95
|
+
"user.passkeyRemoved": true,
|
|
96
|
+
"user.passkeyCloneSuspected": true,
|
|
97
|
+
"user.apiKeyCreated": true,
|
|
98
|
+
"user.apiKeyRevoked": true,
|
|
99
|
+
"user.deleted": true
|
|
100
|
+
};
|
|
101
|
+
function readerOf(reply, operation) {
|
|
102
|
+
const fields = new Map;
|
|
103
|
+
for (let i = 0;i + 1 < reply.length; i += 2) {
|
|
104
|
+
fields.set(String(reply[i]), String(reply[i + 1]));
|
|
105
|
+
}
|
|
106
|
+
const text = (name) => {
|
|
107
|
+
const value = fields.get(name);
|
|
108
|
+
if (value === undefined) {
|
|
109
|
+
throw unreadable(operation, `a hash with \`${name}\``);
|
|
110
|
+
}
|
|
111
|
+
return value;
|
|
112
|
+
};
|
|
113
|
+
const digits = (name, what) => {
|
|
114
|
+
const value = text(name);
|
|
115
|
+
const read = /^(0|[1-9]\d*)$/.test(value) ? Number(value) : Number.NaN;
|
|
116
|
+
if (!Number.isSafeInteger(read))
|
|
117
|
+
throw unreadable(operation, what);
|
|
118
|
+
return read;
|
|
119
|
+
};
|
|
120
|
+
return {
|
|
121
|
+
text,
|
|
122
|
+
has: (name) => fields.has(name),
|
|
123
|
+
name: (name) => {
|
|
124
|
+
const value = text(name);
|
|
125
|
+
if (value === "")
|
|
126
|
+
throw unreadable(operation, "an event type");
|
|
127
|
+
return value;
|
|
128
|
+
},
|
|
129
|
+
json: (name) => {
|
|
130
|
+
let value;
|
|
131
|
+
try {
|
|
132
|
+
value = JSON.parse(text(name));
|
|
133
|
+
} catch {
|
|
134
|
+
value = null;
|
|
135
|
+
}
|
|
136
|
+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
|
|
137
|
+
throw unreadable(operation, `a JSON object in \`${name}\``);
|
|
138
|
+
}
|
|
139
|
+
return value;
|
|
140
|
+
},
|
|
141
|
+
count: (name) => digits(name, `a count in \`${name}\``),
|
|
142
|
+
date: (name) => {
|
|
143
|
+
const value = text(name);
|
|
144
|
+
const at = new Date(Number(value));
|
|
145
|
+
if (value === "" || Number.isNaN(at.getTime())) {
|
|
146
|
+
throw unreadable(operation, `a date in \`${name}\``);
|
|
147
|
+
}
|
|
148
|
+
return at;
|
|
149
|
+
},
|
|
150
|
+
type: (name) => {
|
|
151
|
+
const value = text(name);
|
|
152
|
+
if (!Object.hasOwn(TYPES, value))
|
|
153
|
+
throw unreadable(operation, "a user event type");
|
|
154
|
+
return value;
|
|
155
|
+
},
|
|
156
|
+
optionalProvider: () => {
|
|
157
|
+
const provider = fields.get("provider");
|
|
158
|
+
return provider === undefined || provider === "" ? {} : { provider };
|
|
159
|
+
},
|
|
160
|
+
failure: () => {
|
|
161
|
+
if (!fields.has("status") && !fields.has("error"))
|
|
162
|
+
return null;
|
|
163
|
+
const status = text("status");
|
|
164
|
+
const error = text("error");
|
|
165
|
+
return {
|
|
166
|
+
status: status === "" ? null : digits("status", "a status in `status`"),
|
|
167
|
+
error: error === "" ? null : error
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
function unreadable(operation, what) {
|
|
173
|
+
return new StoreFailure(`webhookQueue.${operation}: a reply that is not ${what} — a key under the prefix this adapter did not write`, { operation });
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// src/scripts.ts
|
|
177
|
+
var CLAIM_FROM = `
|
|
178
|
+
local function claimFrom(p, endpoint, now, leaseUntil, lease, remaining, out, seen)
|
|
179
|
+
local due = p .. 'due:' .. endpoint
|
|
180
|
+
local here = 0
|
|
181
|
+
local stale
|
|
182
|
+
repeat
|
|
183
|
+
stale = false
|
|
184
|
+
local ids = redis.call('ZRANGEBYSCORE', due, '-inf', now, 'LIMIT', 0, remaining + here)
|
|
185
|
+
for _, id in ipairs(ids) do
|
|
186
|
+
local key = p .. 'delivery:' .. id
|
|
187
|
+
if seen[id] or remaining <= 0 then
|
|
188
|
+
-- claimed by this call already, or the limit is reached
|
|
189
|
+
elseif redis.call('EXISTS', key) == 0 then
|
|
190
|
+
redis.call('ZREM', due, id)
|
|
191
|
+
stale = true
|
|
192
|
+
else
|
|
193
|
+
seen[id] = true
|
|
194
|
+
here = here + 1
|
|
195
|
+
redis.call('HINCRBY', key, 'attempts', 1)
|
|
196
|
+
redis.call('HSET', key, 'lease', lease)
|
|
197
|
+
redis.call('ZADD', due, leaseUntil, id)
|
|
198
|
+
local fields = redis.call('HGETALL', key)
|
|
199
|
+
table.insert(fields, 1, id)
|
|
200
|
+
out[#out + 1] = fields
|
|
201
|
+
remaining = remaining - 1
|
|
202
|
+
end
|
|
203
|
+
end
|
|
204
|
+
until remaining <= 0 or not stale
|
|
205
|
+
if redis.call('ZCARD', due) == 0 then
|
|
206
|
+
redis.call('SREM', p .. 'endpoints', endpoint)
|
|
207
|
+
end
|
|
208
|
+
return remaining
|
|
209
|
+
end
|
|
210
|
+
`;
|
|
211
|
+
var LEASED = `
|
|
212
|
+
local function leased(p, id, lease)
|
|
213
|
+
local key = p .. 'delivery:' .. id
|
|
214
|
+
if lease == '' or redis.call('HGET', key, 'lease') ~= lease then return nil end
|
|
215
|
+
return key
|
|
216
|
+
end
|
|
217
|
+
`;
|
|
218
|
+
var INSERT_DELIVERIES = `
|
|
219
|
+
local p, eventId, eventType, dueAt = ARGV[1], ARGV[2], ARGV[3], ARGV[9]
|
|
220
|
+
local undo = {}
|
|
221
|
+
local function write(rollback, ...)
|
|
222
|
+
local reply = redis.call(...)
|
|
223
|
+
undo[#undo + 1] = rollback
|
|
224
|
+
return reply
|
|
225
|
+
end
|
|
226
|
+
local inserted = 0
|
|
227
|
+
local ok, failure = pcall(function()
|
|
228
|
+
local endpoints = p .. 'endpoints'
|
|
229
|
+
for i = 10, #ARGV do
|
|
230
|
+
local endpoint = ARGV[i]
|
|
231
|
+
local id = eventId .. ':' .. eventType .. ':' .. endpoint
|
|
232
|
+
local key = p .. 'delivery:' .. id
|
|
233
|
+
if redis.call('EXISTS', key) == 0 then
|
|
234
|
+
local due = p .. 'due:' .. endpoint
|
|
235
|
+
write({ 'ZREM', due, id }, 'ZADD', due, dueAt, id)
|
|
236
|
+
if redis.call('SISMEMBER', endpoints, endpoint) == 0 then
|
|
237
|
+
write({ 'SREM', endpoints, endpoint }, 'SADD', endpoints, endpoint)
|
|
238
|
+
end
|
|
239
|
+
local fields = {
|
|
240
|
+
'eventId', eventId, 'type', eventType, 'occurredAt', ARGV[4],
|
|
241
|
+
'endpoint', endpoint, 'attempts', '0', 'lease', '' }
|
|
242
|
+
if ARGV[8] ~= '' then
|
|
243
|
+
fields[#fields + 1] = 'data'
|
|
244
|
+
fields[#fields + 1] = ARGV[8]
|
|
245
|
+
else
|
|
246
|
+
fields[#fields + 1] = 'userId'
|
|
247
|
+
fields[#fields + 1] = ARGV[5]
|
|
248
|
+
fields[#fields + 1] = 'userType'
|
|
249
|
+
fields[#fields + 1] = ARGV[6]
|
|
250
|
+
end
|
|
251
|
+
write({ 'DEL', key }, 'HSET', key, unpack(fields))
|
|
252
|
+
if ARGV[7] ~= '' then redis.call('HSET', key, 'provider', ARGV[7]) end
|
|
253
|
+
inserted = inserted + 1
|
|
254
|
+
end
|
|
255
|
+
end
|
|
256
|
+
end)
|
|
257
|
+
if ok then return inserted end
|
|
258
|
+
for i = #undo, 1, -1 do redis.pcall(unpack(undo[i])) end
|
|
259
|
+
if type(failure) == 'table' and failure.err then
|
|
260
|
+
return redis.error_reply(failure.err)
|
|
261
|
+
end
|
|
262
|
+
return redis.error_reply(tostring(failure))
|
|
263
|
+
`;
|
|
264
|
+
var CLAIM_DELIVERIES = `${CLAIM_FROM}
|
|
265
|
+
local p, now, leaseUntil, lease = ARGV[1], ARGV[2], ARGV[3], ARGV[5]
|
|
266
|
+
local remaining = tonumber(ARGV[4])
|
|
267
|
+
local out, seen, walked = {}, {}, {}
|
|
268
|
+
for i = 6, #ARGV do
|
|
269
|
+
if remaining <= 0 then break end
|
|
270
|
+
local endpoint = ARGV[i]
|
|
271
|
+
-- An endpoint named twice is walked once, as the memory queue does.
|
|
272
|
+
if not walked[endpoint] then
|
|
273
|
+
walked[endpoint] = true
|
|
274
|
+
remaining = claimFrom(p, endpoint, now, leaseUntil, lease, remaining, out, seen)
|
|
275
|
+
end
|
|
276
|
+
end
|
|
277
|
+
return out
|
|
278
|
+
`;
|
|
279
|
+
var CLAIM_ORPHANED_DELIVERIES = `${CLAIM_FROM}
|
|
280
|
+
local p, dueBefore, leaseUntil, lease = ARGV[1], ARGV[2], ARGV[3], ARGV[5]
|
|
281
|
+
local remaining = tonumber(ARGV[4])
|
|
282
|
+
local known = {}
|
|
283
|
+
for i = 6, #ARGV do known[ARGV[i]] = true end
|
|
284
|
+
local orphaned = {}
|
|
285
|
+
for _, endpoint in ipairs(redis.call('SMEMBERS', p .. 'endpoints')) do
|
|
286
|
+
if not known[endpoint] then orphaned[#orphaned + 1] = endpoint end
|
|
287
|
+
end
|
|
288
|
+
table.sort(orphaned)
|
|
289
|
+
local out, seen = {}, {}
|
|
290
|
+
for _, endpoint in ipairs(orphaned) do
|
|
291
|
+
if remaining <= 0 then break end
|
|
292
|
+
remaining = claimFrom(p, endpoint, dueBefore, leaseUntil, lease, remaining, out, seen)
|
|
293
|
+
end
|
|
294
|
+
return out
|
|
295
|
+
`;
|
|
296
|
+
var EXTEND_LEASE = `${LEASED}
|
|
297
|
+
local p, id = ARGV[1], ARGV[2]
|
|
298
|
+
local key = leased(p, id, ARGV[3])
|
|
299
|
+
if not key then return 0 end
|
|
300
|
+
local endpoint = redis.call('HGET', key, 'endpoint')
|
|
301
|
+
redis.call('ZADD', p .. 'due:' .. endpoint, ARGV[4], id)
|
|
302
|
+
return 1
|
|
303
|
+
`;
|
|
304
|
+
var SCHEDULE_RETRY = `${LEASED}
|
|
305
|
+
local p, id = ARGV[1], ARGV[2]
|
|
306
|
+
local key = leased(p, id, ARGV[3])
|
|
307
|
+
if not key then return 0 end
|
|
308
|
+
-- The endpoint is read before the first write. A refusal of the ZADD after
|
|
309
|
+
-- the HSET leaves the lease released and the failure stored, with the
|
|
310
|
+
-- delivery due when the old lease ends: retried then, earlier than scheduled.
|
|
311
|
+
local endpoint = redis.call('HGET', key, 'endpoint')
|
|
312
|
+
redis.call('HSET', key, 'status', ARGV[5], 'error', ARGV[6], 'lease', '')
|
|
313
|
+
redis.call('ZADD', p .. 'due:' .. endpoint, ARGV[4], id)
|
|
314
|
+
return 1
|
|
315
|
+
`;
|
|
316
|
+
var DELETE_DELIVERY = `${LEASED}
|
|
317
|
+
local p, id = ARGV[1], ARGV[2]
|
|
318
|
+
local key = leased(p, id, ARGV[3])
|
|
319
|
+
if not key then return 0 end
|
|
320
|
+
local endpoint = redis.call('HGET', key, 'endpoint')
|
|
321
|
+
local due = p .. 'due:' .. endpoint
|
|
322
|
+
-- The hash first: a member left without it is dropped by the next claim,
|
|
323
|
+
-- where a hash left without its member would wait for ever.
|
|
324
|
+
redis.call('DEL', key)
|
|
325
|
+
redis.call('ZREM', due, id)
|
|
326
|
+
if redis.call('ZCARD', due) == 0 then
|
|
327
|
+
redis.call('SREM', p .. 'endpoints', endpoint)
|
|
328
|
+
end
|
|
329
|
+
return 1
|
|
330
|
+
`;
|
|
331
|
+
|
|
332
|
+
// src/queue.ts
|
|
333
|
+
function createRedisWebhookQueue(redis, options = {}) {
|
|
334
|
+
const run = runner(scriptsOver(redis.client), options.prefix ?? "janus:webhooks:");
|
|
335
|
+
return {
|
|
336
|
+
insertDeliveries: (event, endpoints, dueAt) => run("insertDeliveries", INSERT_DELIVERIES, insertArgsOf(event, endpoints, dueAt), toCount),
|
|
337
|
+
claimDeliveries: (endpoints, now, leaseUntil, limit) => run("claimDeliveries", CLAIM_DELIVERIES, (operation) => [
|
|
338
|
+
stampOf(now, operation, "now"),
|
|
339
|
+
...claimArgsOf(leaseUntil, limit, operation),
|
|
340
|
+
...endpoints
|
|
341
|
+
], toDeliveries),
|
|
342
|
+
claimOrphanedDeliveries: (known, dueBefore, leaseUntil, limit) => run("claimOrphanedDeliveries", CLAIM_ORPHANED_DELIVERIES, (operation) => [
|
|
343
|
+
stampOf(dueBefore, operation, "dueBefore"),
|
|
344
|
+
...claimArgsOf(leaseUntil, limit, operation),
|
|
345
|
+
...known
|
|
346
|
+
], toDeliveries),
|
|
347
|
+
extendLease: (id, lease, until) => run("extendLease", EXTEND_LEASE, (operation) => [id, lease, stampOf(until, operation, "until")], toHeld),
|
|
348
|
+
scheduleRetry: (id, lease, dueAt, failed) => run("scheduleRetry", SCHEDULE_RETRY, retryArgsOf(id, lease, dueAt, failed), toHeld),
|
|
349
|
+
deleteDelivery: (id, lease) => run("deleteDelivery", DELETE_DELIVERY, () => [id, lease], toHeld)
|
|
350
|
+
};
|
|
351
|
+
}
|
|
352
|
+
function runner(evaluate, prefix) {
|
|
353
|
+
return async (operation, script, argsOf, decode) => {
|
|
354
|
+
const args = argsOf(operation);
|
|
355
|
+
return decode(await evaluate(operation, script, [prefix, ...args]), operation);
|
|
356
|
+
};
|
|
357
|
+
}
|
|
358
|
+
function insertArgsOf(event, endpoints, dueAt) {
|
|
359
|
+
return (operation) => [
|
|
360
|
+
event.id,
|
|
361
|
+
event.type,
|
|
362
|
+
stampOf(event.occurredAt, operation, "event.occurredAt"),
|
|
363
|
+
"data" in event ? "" : event.userId,
|
|
364
|
+
"data" in event ? "" : event.userType,
|
|
365
|
+
"data" in event ? "" : event.provider ?? "",
|
|
366
|
+
"data" in event ? dataOf(event.data, operation) : "",
|
|
367
|
+
stampOf(dueAt, operation, "dueAt"),
|
|
368
|
+
...endpoints
|
|
369
|
+
];
|
|
370
|
+
}
|
|
371
|
+
function dataOf(data, operation) {
|
|
372
|
+
let json;
|
|
373
|
+
try {
|
|
374
|
+
json = JSON.stringify(data);
|
|
375
|
+
} catch {
|
|
376
|
+
json = undefined;
|
|
377
|
+
}
|
|
378
|
+
if (json === undefined || !json.startsWith("{")) {
|
|
379
|
+
throw new TypeError(`webhookQueue.${operation}: event.data is a JSON object`);
|
|
380
|
+
}
|
|
381
|
+
return json;
|
|
382
|
+
}
|
|
383
|
+
function claimArgsOf(leaseUntil, limit, operation) {
|
|
384
|
+
return [
|
|
385
|
+
stampOf(leaseUntil, operation, "leaseUntil"),
|
|
386
|
+
limitOf(limit, operation),
|
|
387
|
+
randomUUID()
|
|
388
|
+
];
|
|
389
|
+
}
|
|
390
|
+
function retryArgsOf(id, lease, dueAt, failed) {
|
|
391
|
+
return (operation) => [
|
|
392
|
+
id,
|
|
393
|
+
lease,
|
|
394
|
+
stampOf(dueAt, operation, "dueAt"),
|
|
395
|
+
statusOf(failed.status, operation),
|
|
396
|
+
failed.error ?? ""
|
|
397
|
+
];
|
|
398
|
+
}
|
|
399
|
+
function scriptsOver(client) {
|
|
400
|
+
const shas = new Map;
|
|
401
|
+
const shaOf = (script) => {
|
|
402
|
+
let sha = shas.get(script);
|
|
403
|
+
if (sha === undefined) {
|
|
404
|
+
sha = new Bun.CryptoHasher("sha1").update(script).digest("hex");
|
|
405
|
+
shas.set(script, sha);
|
|
406
|
+
}
|
|
407
|
+
return sha;
|
|
408
|
+
};
|
|
409
|
+
return async (operation, script, args) => {
|
|
410
|
+
try {
|
|
411
|
+
try {
|
|
412
|
+
return await client.send("EVALSHA", [shaOf(script), "0", ...args]);
|
|
413
|
+
} catch (error) {
|
|
414
|
+
if (!isNoScript(error))
|
|
415
|
+
throw error;
|
|
416
|
+
return await client.send("EVAL", [script, "0", ...args]);
|
|
417
|
+
}
|
|
418
|
+
} catch (error) {
|
|
419
|
+
throw new StoreFailure2(`webhookQueue.${operation}: the queue could not answer`, { operation, cause: error });
|
|
420
|
+
}
|
|
421
|
+
};
|
|
422
|
+
}
|
|
423
|
+
function isNoScript(error) {
|
|
424
|
+
return error instanceof Error && error.message.startsWith("NOSCRIPT");
|
|
425
|
+
}
|
|
426
|
+
export {
|
|
427
|
+
createRedisWebhookQueue
|
|
428
|
+
};
|
|
429
|
+
|
|
430
|
+
//# debugId=A2BC8E2E4D2633C864756E2164756E21
|
|
431
|
+
//# sourceMappingURL=index.js.map
|