notifkit 0.1.15 → 0.1.16
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/dashboard/dist/assets/index-C-DJYu0_.css +1 -0
- package/dashboard/dist/assets/index-CzFZcEon.js +318 -0
- package/dashboard/dist/index.html +2 -2
- package/dist/{bootstrap-BOmT69OH.mjs → bootstrap-BMDRPjgp.mjs} +1 -1
- package/dist/{bulk-ZPiOJRx-.mjs → bulk-CJ5QXiPa.mjs} +1 -1
- package/dist/index.d.mts +71 -27
- package/dist/index.mjs +2 -2
- package/dist/{main-CCqcFDDe.mjs → main-6_bXQBDH.mjs} +21 -41
- package/dist/{main-BdZvBgV7.mjs → main-8nP3qmCT.mjs} +22 -48
- package/dist/{main-C0m9-Eos.mjs → main-B82bsFoy.mjs} +183 -334
- package/dist/{main-CTjaZ7ZD.mjs → main-CpaHF1Zw.mjs} +13 -15
- package/dist/{main-JEXBLP2A.mjs → main-DULD8-th.mjs} +8 -6
- package/dist/{main-C6S3EsJ3.mjs → main-ZW5RaiOK.mjs} +77 -64
- package/dist/{main-g33jpia4.mjs → main-g1KEcXXp.mjs} +676 -582
- package/dist/{main-24J4U8yP.mjs → main-mGIT8jv4.mjs} +4 -4
- package/dist/schedule-or-dispatch-Cd7GLfc3.mjs +52 -0
- package/dist/{src-9LXITcNi.mjs → src-BE_EUpZ6.mjs} +93 -93
- package/package.json +1 -1
- package/scripts/create-project.mjs +6 -2
- package/src/client.ts +3 -3
- package/src/config/index.ts +1 -0
- package/src/contracts/common.ts +2 -0
- package/src/contracts/envelope.ts +1 -1
- package/src/contracts/events/notification-created.ts +2 -0
- package/src/contracts/events/notification-delivered.ts +1 -1
- package/src/contracts/events/notification-failed.ts +1 -1
- package/src/contracts/events/notification-requested.ts +3 -2
- package/src/contracts/helpers.ts +1 -2
- package/src/contracts/index.ts +1 -0
- package/src/contracts/registry.ts +1 -0
- package/src/contracts/sdk.ts +8 -37
- package/src/db/schema.ts +8 -13
- package/src/idempotency/index.ts +6 -8
- package/src/metrics/index.ts +2 -0
- package/src/rate-limiter/api-rate-limiter.ts +208 -0
- package/src/rate-limiter/index.ts +3 -411
- package/src/rate-limiter/project-settings-cache.ts +99 -0
- package/src/rate-limiter/user-throttle.ts +100 -0
- package/src/redis/index.ts +10 -3
- package/src/repositories/admin-user.ts +83 -0
- package/src/repositories/contact.ts +359 -0
- package/src/repositories/index.ts +9 -1416
- package/src/repositories/preference.ts +35 -0
- package/src/repositories/project.ts +110 -0
- package/src/repositories/segment.ts +16 -0
- package/src/repositories/template.ts +72 -0
- package/src/repositories/types.ts +49 -0
- package/src/repositories/user.ts +644 -0
- package/src/repositories/workflow.ts +64 -0
- package/src/services/ai/main.ts +29 -71
- package/src/services/api/admin-static.ts +4 -1
- package/src/services/api/handlers/auth.ts +109 -0
- package/src/services/api/handlers/campaigns.ts +191 -0
- package/src/services/api/handlers/events.ts +99 -0
- package/src/services/api/handlers/notifications.ts +356 -0
- package/src/services/api/handlers/projects.ts +116 -0
- package/src/services/api/handlers/shared.ts +262 -0
- package/src/services/api/handlers/suppressions.ts +95 -0
- package/src/services/api/handlers/system.ts +314 -0
- package/src/services/api/handlers/templates.ts +97 -0
- package/src/services/api/handlers/unsubscribe.ts +215 -0
- package/src/services/api/handlers/users.ts +262 -0
- package/src/services/api/handlers/workflows.ts +150 -0
- package/src/services/api/handlers.ts +25 -2190
- package/src/services/api/health.ts +133 -0
- package/src/services/api/http.ts +12 -0
- package/src/services/api/main.ts +32 -322
- package/src/services/api/router.ts +1 -1
- package/src/services/api/webhooks.ts +172 -0
- package/src/services/delivery/main.ts +256 -498
- package/src/services/engine/main.ts +31 -247
- package/src/services/engine/quiet-hours.ts +151 -0
- package/src/services/engine/schedule-or-dispatch.ts +104 -0
- package/src/services/enricher/main.ts +9 -21
- package/src/services/events/main.ts +2 -2
- package/src/services/scheduler/main.ts +16 -25
- package/src/services/workflow/duration.ts +24 -0
- package/src/services/workflow/main.ts +6 -164
- package/src/services/workflow/timers.ts +157 -0
- package/src/shared/events.ts +3 -2
- package/src/templates/render.ts +1 -0
- package/src/workers/index.ts +7 -4
- package/src/workflows/sdk.ts +1 -0
- package/dashboard/dist/assets/index-ggpJKZqZ.js +0 -315
- package/dashboard/dist/assets/index-s-SXGIwv.css +0 -1
|
@@ -1,411 +1,3 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
import { randomUUID } from "crypto";
|
|
6
|
-
|
|
7
|
-
export interface ThrottleResult {
|
|
8
|
-
allowed: boolean;
|
|
9
|
-
count: number;
|
|
10
|
-
limit: number;
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
// ─── Per-project overrides ──────────────────────────────────────────────────
|
|
14
|
-
|
|
15
|
-
/**
|
|
16
|
-
* Throttle overrides stored on the project row. `null` on either field means
|
|
17
|
-
* "no override" — fall back to the process-wide default.
|
|
18
|
-
*/
|
|
19
|
-
export interface ProjectThrottleSettings {
|
|
20
|
-
throttleLimit: number | null;
|
|
21
|
-
throttleWindowHours: number | null;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
const NO_OVERRIDES: ProjectThrottleSettings = {
|
|
25
|
-
throttleLimit: null,
|
|
26
|
-
throttleWindowHours: null,
|
|
27
|
-
};
|
|
28
|
-
|
|
29
|
-
export interface ProjectSettingsCacheOptions {
|
|
30
|
-
maxSize?: number;
|
|
31
|
-
ttlMs?: number;
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
* Caches per-project throttle overrides for the engine.
|
|
36
|
-
*
|
|
37
|
-
* The throttle check runs once per notification, so an uncached lookup here
|
|
38
|
-
* would put a Postgres round trip on the hot path. Projects with no overrides
|
|
39
|
-
* are cached as well — the common case must not cost a query per message.
|
|
40
|
-
*
|
|
41
|
-
* The TTL bounds staleness on its own; `invalidate()` exists so a settings
|
|
42
|
-
* change published over pub/sub applies immediately rather than at expiry.
|
|
43
|
-
*/
|
|
44
|
-
export class ProjectSettingsCache {
|
|
45
|
-
private readonly cache: LRUCache<string, ProjectThrottleSettings>;
|
|
46
|
-
/**
|
|
47
|
-
* Lookups already on the wire, keyed by project.
|
|
48
|
-
*
|
|
49
|
-
* The cache only fills once a query has come back, so without this a cold
|
|
50
|
-
* project at the start of a campaign puts one query per in-flight message on
|
|
51
|
-
* Postgres before the first answer lands — exactly when the database is
|
|
52
|
-
* busiest. Followers wait on the leader's promise instead.
|
|
53
|
-
*/
|
|
54
|
-
private readonly inFlight = new Map<string, Promise<ProjectThrottleSettings>>();
|
|
55
|
-
|
|
56
|
-
constructor(
|
|
57
|
-
private readonly load: (projectId: string) => Promise<ProjectThrottleSettings | null>,
|
|
58
|
-
{ maxSize = 1000, ttlMs = 60_000 }: ProjectSettingsCacheOptions = {},
|
|
59
|
-
) {
|
|
60
|
-
this.cache = new LRUCache<string, ProjectThrottleSettings>(maxSize, ttlMs);
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/**
|
|
64
|
-
* Throws whatever the loader throws. The caller decides whether a settings
|
|
65
|
-
* lookup failure should drop the message or fall back to defaults.
|
|
66
|
-
*/
|
|
67
|
-
async get(projectId: string): Promise<ProjectThrottleSettings> {
|
|
68
|
-
const cached = this.cache.get(projectId);
|
|
69
|
-
if (cached) return cached;
|
|
70
|
-
|
|
71
|
-
const existing = this.inFlight.get(projectId);
|
|
72
|
-
if (existing) return existing;
|
|
73
|
-
|
|
74
|
-
// Assigned before any callback below can run, since `load` cannot settle
|
|
75
|
-
// within this synchronous block.
|
|
76
|
-
let pending!: Promise<ProjectThrottleSettings>;
|
|
77
|
-
pending = this.load(projectId)
|
|
78
|
-
.then((settings) => {
|
|
79
|
-
const resolved = settings ?? NO_OVERRIDES;
|
|
80
|
-
// Only cache while this is still the current lookup: an invalidate()
|
|
81
|
-
// that landed while the query was on the wire means the answer in hand
|
|
82
|
-
// already describes the old settings.
|
|
83
|
-
if (this.inFlight.get(projectId) === pending) {
|
|
84
|
-
this.cache.set(projectId, resolved);
|
|
85
|
-
}
|
|
86
|
-
return resolved;
|
|
87
|
-
})
|
|
88
|
-
.finally(() => {
|
|
89
|
-
// Cleared on failure too, so one bad lookup does not pin every later
|
|
90
|
-
// caller to the same rejection.
|
|
91
|
-
if (this.inFlight.get(projectId) === pending) {
|
|
92
|
-
this.inFlight.delete(projectId);
|
|
93
|
-
}
|
|
94
|
-
});
|
|
95
|
-
|
|
96
|
-
this.inFlight.set(projectId, pending);
|
|
97
|
-
return pending;
|
|
98
|
-
}
|
|
99
|
-
|
|
100
|
-
invalidate(projectId: string): void {
|
|
101
|
-
this.cache.delete(projectId);
|
|
102
|
-
// A lookup that started before the change would write a stale value on
|
|
103
|
-
// arrival; dropping it here sends the next caller back to the database.
|
|
104
|
-
this.inFlight.delete(projectId);
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
clear(): void {
|
|
108
|
-
this.cache.clear();
|
|
109
|
-
this.inFlight.clear();
|
|
110
|
-
}
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
// ─── UserThrottle ──────────────────────────────────────────────────────────
|
|
114
|
-
// True sliding window counter using Redis ZSET: max N sends per window per user.
|
|
115
|
-
|
|
116
|
-
export interface UserThrottleOptions {
|
|
117
|
-
redis: Redis;
|
|
118
|
-
maxPerHour?: number;
|
|
119
|
-
windowHours?: number;
|
|
120
|
-
}
|
|
121
|
-
|
|
122
|
-
export interface ThrottleCheckOptions {
|
|
123
|
-
/** Per-project cap for this window. `0` blocks every non-critical send. */
|
|
124
|
-
limit?: number | null;
|
|
125
|
-
/** Per-project window length in hours. */
|
|
126
|
-
windowHours?: number | null;
|
|
127
|
-
/** Future send time. The window is evaluated at that instant, not at now. */
|
|
128
|
-
scheduledAt?: string;
|
|
129
|
-
/**
|
|
130
|
-
* Stable id of the message being counted. A retry of the same message is
|
|
131
|
-
* then counted once, not once per attempt. Random when omitted.
|
|
132
|
-
*/
|
|
133
|
-
messageId?: string;
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
/** Reject stored values that would make the window meaningless. */
|
|
137
|
-
function positiveOrNull(value: number | null | undefined): number | null {
|
|
138
|
-
return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
|
|
139
|
-
}
|
|
140
|
-
|
|
141
|
-
/** A limit of 0 is a legitimate kill switch, so zero is allowed here. */
|
|
142
|
-
function nonNegativeOrNull(value: number | null | undefined): number | null {
|
|
143
|
-
return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
|
|
144
|
-
}
|
|
145
|
-
|
|
146
|
-
export class UserThrottle {
|
|
147
|
-
private readonly redis: Redis;
|
|
148
|
-
private readonly maxPerHour: number;
|
|
149
|
-
private readonly windowHours: number;
|
|
150
|
-
|
|
151
|
-
constructor({ redis, maxPerHour = 3, windowHours = 1 }: UserThrottleOptions) {
|
|
152
|
-
this.redis = redis;
|
|
153
|
-
this.maxPerHour = maxPerHour;
|
|
154
|
-
this.windowHours = windowHours;
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
/**
|
|
158
|
-
* @param projectId Tenant that owns `userId`. User ids are caller-supplied
|
|
159
|
-
* external ids, so they collide across tenants and MUST be namespaced —
|
|
160
|
-
* otherwise one tenant's traffic throttles another's.
|
|
161
|
-
* @param options Per-project overrides. Values that are absent, null, or
|
|
162
|
-
* nonsensical fall back to this instance's defaults.
|
|
163
|
-
*/
|
|
164
|
-
async check(
|
|
165
|
-
projectId: string,
|
|
166
|
-
userId: string,
|
|
167
|
-
priority?: string,
|
|
168
|
-
options: ThrottleCheckOptions = {},
|
|
169
|
-
): Promise<ThrottleResult> {
|
|
170
|
-
const limit = nonNegativeOrNull(options.limit) ?? this.maxPerHour;
|
|
171
|
-
const windowHours = positiveOrNull(options.windowHours) ?? this.windowHours;
|
|
172
|
-
|
|
173
|
-
if (priority === "critical") {
|
|
174
|
-
return { allowed: true, count: 0, limit };
|
|
175
|
-
}
|
|
176
|
-
|
|
177
|
-
const windowMs = windowHours * 3600_000;
|
|
178
|
-
const key = `throttle:${projectId}:user:${userId}`;
|
|
179
|
-
const targetTime = options.scheduledAt ? new Date(options.scheduledAt).getTime() : Date.now();
|
|
180
|
-
const windowStart = targetTime - windowMs;
|
|
181
|
-
const memberId = options.messageId ?? randomUUID();
|
|
182
|
-
|
|
183
|
-
// The key must outlive the window it is counting. For a future-dated send
|
|
184
|
-
// that means surviving until targetTime plus one more window, so a task
|
|
185
|
-
// scheduled for next week still counts against the right bucket.
|
|
186
|
-
const windowSeconds = Math.ceil(windowMs / 1000);
|
|
187
|
-
const ttlSeconds = Math.max(
|
|
188
|
-
windowSeconds,
|
|
189
|
-
Math.ceil((targetTime - Date.now()) / 1000) + windowSeconds,
|
|
190
|
-
);
|
|
191
|
-
|
|
192
|
-
const count = await this.redis.throttleUser(
|
|
193
|
-
key,
|
|
194
|
-
windowStart,
|
|
195
|
-
limit,
|
|
196
|
-
targetTime,
|
|
197
|
-
memberId,
|
|
198
|
-
ttlSeconds,
|
|
199
|
-
Date.now() - windowMs,
|
|
200
|
-
);
|
|
201
|
-
|
|
202
|
-
return { allowed: count <= limit, count, limit };
|
|
203
|
-
}
|
|
204
|
-
}
|
|
205
|
-
|
|
206
|
-
// ─── ApiRateLimiter (In-Memory Token Leasing) ──────────────────────────────
|
|
207
|
-
// Leases token chunks from Redis sliding-window counters into local memory.
|
|
208
|
-
// Eliminates per-request Redis network roundtrips on API ingress.
|
|
209
|
-
|
|
210
|
-
export interface ApiRateLimiterOptions {
|
|
211
|
-
redis: Redis;
|
|
212
|
-
windowMs?: number;
|
|
213
|
-
maxBatchSize?: number;
|
|
214
|
-
logger?: Logger;
|
|
215
|
-
/** Redis key namespace. Distinct limiters must not share one. */
|
|
216
|
-
keyPrefix?: string;
|
|
217
|
-
}
|
|
218
|
-
|
|
219
|
-
/**
|
|
220
|
-
* Computes dynamic token lease batch size based on RPM.
|
|
221
|
-
* Targets ~5s of limit capacity so Redis is contacted at most ~12 times/min
|
|
222
|
-
* regardless of instantaneous request rate. Bounded between 1 and maxBatchSize.
|
|
223
|
-
*/
|
|
224
|
-
export function calculateTokenBatchSize(limitRpm: number, maxBatchSize = 500): number {
|
|
225
|
-
if (limitRpm <= 0) return 0;
|
|
226
|
-
if (limitRpm <= 10) return 1;
|
|
227
|
-
if (limitRpm <= 60) return 5;
|
|
228
|
-
const perSecond = limitRpm / 60;
|
|
229
|
-
// 5 s window = perSecond * 5; at least 10 to absorb jitter.
|
|
230
|
-
return Math.min(Math.max(Math.ceil(perSecond * 5), 10), maxBatchSize);
|
|
231
|
-
}
|
|
232
|
-
|
|
233
|
-
interface ProjectTokenLeaseState {
|
|
234
|
-
bucketIndex: number;
|
|
235
|
-
tokens: number;
|
|
236
|
-
batchSize: number;
|
|
237
|
-
inFlightLease: Promise<number> | null;
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
export class ApiRateLimiter {
|
|
241
|
-
private readonly redis: Redis;
|
|
242
|
-
private readonly windowMs: number;
|
|
243
|
-
private readonly maxBatchSize: number;
|
|
244
|
-
private readonly logger?: Logger;
|
|
245
|
-
private readonly keyPrefix: string;
|
|
246
|
-
private readonly leases = new Map<string, ProjectTokenLeaseState>();
|
|
247
|
-
|
|
248
|
-
constructor({
|
|
249
|
-
redis,
|
|
250
|
-
windowMs = 60_000,
|
|
251
|
-
maxBatchSize = 500,
|
|
252
|
-
logger,
|
|
253
|
-
keyPrefix = "rate-limit:api:req",
|
|
254
|
-
}: ApiRateLimiterOptions) {
|
|
255
|
-
this.redis = redis;
|
|
256
|
-
this.windowMs = windowMs;
|
|
257
|
-
this.maxBatchSize = maxBatchSize;
|
|
258
|
-
this.logger = logger;
|
|
259
|
-
this.keyPrefix = keyPrefix;
|
|
260
|
-
}
|
|
261
|
-
|
|
262
|
-
/**
|
|
263
|
-
* Evaluates if a request for `projectId` is allowed within its `limitRpm`.
|
|
264
|
-
* Fast-path uses local in-memory token lease (0ms Redis network latency).
|
|
265
|
-
* Refills in the background before tokens are depleted.
|
|
266
|
-
*/
|
|
267
|
-
async check(projectId: string, limitRpm: number): Promise<boolean> {
|
|
268
|
-
if (limitRpm <= 0) return false;
|
|
269
|
-
|
|
270
|
-
const nowMs = Date.now();
|
|
271
|
-
const currentBucket = Math.floor(nowMs / this.windowMs);
|
|
272
|
-
|
|
273
|
-
let state = this.leases.get(projectId);
|
|
274
|
-
if (!state) {
|
|
275
|
-
state = {
|
|
276
|
-
bucketIndex: currentBucket,
|
|
277
|
-
tokens: 0,
|
|
278
|
-
batchSize: calculateTokenBatchSize(limitRpm, this.maxBatchSize),
|
|
279
|
-
inFlightLease: null,
|
|
280
|
-
};
|
|
281
|
-
this.leases.set(projectId, state);
|
|
282
|
-
this.maybePrune(currentBucket);
|
|
283
|
-
}
|
|
284
|
-
|
|
285
|
-
// Rollover to new bucket window when minute boundary elapses.
|
|
286
|
-
// Kick off a prefill immediately so the first request of the new window
|
|
287
|
-
// doesn't have to wait — it will land before tokens hit 0 again.
|
|
288
|
-
if (state.bucketIndex !== currentBucket) {
|
|
289
|
-
state.bucketIndex = currentBucket;
|
|
290
|
-
state.tokens = 0;
|
|
291
|
-
state.batchSize = calculateTokenBatchSize(limitRpm, this.maxBatchSize);
|
|
292
|
-
state.inFlightLease = null;
|
|
293
|
-
// Fire the first lease for the new window now, don't await it here.
|
|
294
|
-
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
295
|
-
}
|
|
296
|
-
|
|
297
|
-
// 1. Fast Path: Local token available in memory (0ms network latency)
|
|
298
|
-
if (state.tokens > 0) {
|
|
299
|
-
state.tokens--;
|
|
300
|
-
|
|
301
|
-
// Background refill when tokens drop below 25% of batch size
|
|
302
|
-
const refillThreshold = Math.max(1, Math.floor(state.batchSize * 0.25));
|
|
303
|
-
if (state.tokens <= refillThreshold && !state.inFlightLease) {
|
|
304
|
-
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
305
|
-
}
|
|
306
|
-
|
|
307
|
-
return true;
|
|
308
|
-
}
|
|
309
|
-
|
|
310
|
-
// 2. Slow Path: tokens are depleted, block on the in-flight lease or start one.
|
|
311
|
-
// Concurrent requests racing here all join the *same* promise so one Redis
|
|
312
|
-
// round trip serves them. A lease only grants `batchSize` tokens, so a
|
|
313
|
-
// burst larger than that leases again rather than rejecting requests the
|
|
314
|
-
// window still has room for: a request is refused only once Redis itself
|
|
315
|
-
// reports the window spent.
|
|
316
|
-
for (;;) {
|
|
317
|
-
if (!state.inFlightLease) {
|
|
318
|
-
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
319
|
-
}
|
|
320
|
-
const granted = state.inFlightLease ? await state.inFlightLease : 0;
|
|
321
|
-
|
|
322
|
-
// Only claim a token if the lease came back for the same bucket we waited on.
|
|
323
|
-
if (state.bucketIndex !== currentBucket) return false;
|
|
324
|
-
if (state.tokens > 0) {
|
|
325
|
-
state.tokens--;
|
|
326
|
-
return true;
|
|
327
|
-
}
|
|
328
|
-
if (granted <= 0) return false;
|
|
329
|
-
}
|
|
330
|
-
}
|
|
331
|
-
|
|
332
|
-
private async refill(
|
|
333
|
-
projectId: string,
|
|
334
|
-
state: ProjectTokenLeaseState,
|
|
335
|
-
limitRpm: number,
|
|
336
|
-
nowMs: number,
|
|
337
|
-
bucketIndex: number,
|
|
338
|
-
): Promise<number> {
|
|
339
|
-
if (state.inFlightLease) {
|
|
340
|
-
return state.inFlightLease;
|
|
341
|
-
}
|
|
342
|
-
|
|
343
|
-
const prevBucket = bucketIndex - 1;
|
|
344
|
-
const rlTag = `{${this.keyPrefix}:${projectId || "global"}}`;
|
|
345
|
-
const currentKey = `${rlTag}:${bucketIndex}`;
|
|
346
|
-
const prevKey = `${rlTag}:${prevBucket}`;
|
|
347
|
-
const requested = state.batchSize;
|
|
348
|
-
let inFlightRef: Promise<number> | null = null;
|
|
349
|
-
const executeLease = async (): Promise<number> => {
|
|
350
|
-
try {
|
|
351
|
-
let granted = await this.redis.leaseApiRateLimit(
|
|
352
|
-
currentKey,
|
|
353
|
-
prevKey,
|
|
354
|
-
nowMs,
|
|
355
|
-
this.windowMs,
|
|
356
|
-
limitRpm,
|
|
357
|
-
requested,
|
|
358
|
-
);
|
|
359
|
-
|
|
360
|
-
// On invalid return or negative, fail-open
|
|
361
|
-
if (typeof granted !== "number" || granted < 0) {
|
|
362
|
-
granted = requested;
|
|
363
|
-
}
|
|
364
|
-
|
|
365
|
-
if (state.bucketIndex === bucketIndex) {
|
|
366
|
-
state.tokens += granted;
|
|
367
|
-
}
|
|
368
|
-
return granted;
|
|
369
|
-
} catch (err) {
|
|
370
|
-
this.logger?.warn(
|
|
371
|
-
{ err, projectId },
|
|
372
|
-
"project rate limit lease failed — allowing request (fail-open)",
|
|
373
|
-
);
|
|
374
|
-
// Fail-open: credit requested tokens locally to prevent tight retry loops during Redis hiccups
|
|
375
|
-
if (state.bucketIndex === bucketIndex) {
|
|
376
|
-
state.tokens += requested;
|
|
377
|
-
}
|
|
378
|
-
return requested;
|
|
379
|
-
} finally {
|
|
380
|
-
if (state.inFlightLease === inFlightRef) {
|
|
381
|
-
state.inFlightLease = null;
|
|
382
|
-
}
|
|
383
|
-
}
|
|
384
|
-
};
|
|
385
|
-
|
|
386
|
-
const promise = executeLease();
|
|
387
|
-
inFlightRef = promise;
|
|
388
|
-
state.inFlightLease = promise;
|
|
389
|
-
return promise;
|
|
390
|
-
}
|
|
391
|
-
|
|
392
|
-
private maybePrune(currentBucket: number): void {
|
|
393
|
-
if (this.leases.size > 2000) {
|
|
394
|
-
for (const [id, s] of this.leases) {
|
|
395
|
-
if (currentBucket - s.bucketIndex > 1) {
|
|
396
|
-
this.leases.delete(id);
|
|
397
|
-
}
|
|
398
|
-
}
|
|
399
|
-
}
|
|
400
|
-
}
|
|
401
|
-
|
|
402
|
-
/** Reset all local cached leases */
|
|
403
|
-
clear(): void {
|
|
404
|
-
this.leases.clear();
|
|
405
|
-
}
|
|
406
|
-
|
|
407
|
-
/** Invalidate local lease for a specific project */
|
|
408
|
-
invalidate(projectId: string): void {
|
|
409
|
-
this.leases.delete(projectId);
|
|
410
|
-
}
|
|
411
|
-
}
|
|
1
|
+
export * from "./project-settings-cache.js";
|
|
2
|
+
export * from "./user-throttle.js";
|
|
3
|
+
export * from "./api-rate-limiter.js";
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { LRUCache } from "@/shared/index.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Throttle overrides stored on the project row. `null` on either field means
|
|
5
|
+
* "no override" — fall back to the process-wide default.
|
|
6
|
+
*/
|
|
7
|
+
export interface ProjectThrottleSettings {
|
|
8
|
+
throttleLimit: number | null;
|
|
9
|
+
throttleWindowHours: number | null;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
const NO_OVERRIDES: ProjectThrottleSettings = {
|
|
13
|
+
throttleLimit: null,
|
|
14
|
+
throttleWindowHours: null,
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
export interface ProjectSettingsCacheOptions {
|
|
18
|
+
maxSize?: number;
|
|
19
|
+
ttlMs?: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Caches per-project throttle overrides for the engine.
|
|
24
|
+
*
|
|
25
|
+
* The throttle check runs once per notification, so an uncached lookup here
|
|
26
|
+
* would put a Postgres round trip on the hot path. Projects with no overrides
|
|
27
|
+
* are cached as well — the common case must not cost a query per message.
|
|
28
|
+
*
|
|
29
|
+
* The TTL bounds staleness on its own; `invalidate()` exists so a settings
|
|
30
|
+
* change published over pub/sub applies immediately rather than at expiry.
|
|
31
|
+
*/
|
|
32
|
+
export class ProjectSettingsCache {
|
|
33
|
+
private readonly cache: LRUCache<string, ProjectThrottleSettings>;
|
|
34
|
+
/**
|
|
35
|
+
* Lookups already on the wire, keyed by project.
|
|
36
|
+
*
|
|
37
|
+
* The cache only fills once a query has come back, so without this a cold
|
|
38
|
+
* project at the start of a campaign puts one query per in-flight message on
|
|
39
|
+
* Postgres before the first answer lands — exactly when the database is
|
|
40
|
+
* busiest. Followers wait on the leader's promise instead.
|
|
41
|
+
*/
|
|
42
|
+
private readonly inFlight = new Map<string, Promise<ProjectThrottleSettings>>();
|
|
43
|
+
|
|
44
|
+
constructor(
|
|
45
|
+
private readonly load: (projectId: string) => Promise<ProjectThrottleSettings | null>,
|
|
46
|
+
{ maxSize = 1000, ttlMs = 60_000 }: ProjectSettingsCacheOptions = {},
|
|
47
|
+
) {
|
|
48
|
+
this.cache = new LRUCache<string, ProjectThrottleSettings>(maxSize, ttlMs);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Throws whatever the loader throws. The caller decides whether a settings
|
|
53
|
+
* lookup failure should drop the message or fall back to defaults.
|
|
54
|
+
*/
|
|
55
|
+
async get(projectId: string): Promise<ProjectThrottleSettings> {
|
|
56
|
+
const cached = this.cache.get(projectId);
|
|
57
|
+
if (cached) return cached;
|
|
58
|
+
|
|
59
|
+
const existing = this.inFlight.get(projectId);
|
|
60
|
+
if (existing) return existing;
|
|
61
|
+
|
|
62
|
+
// Assigned before any callback below can run, since `load` cannot settle
|
|
63
|
+
// within this synchronous block.
|
|
64
|
+
let pending!: Promise<ProjectThrottleSettings>;
|
|
65
|
+
pending = this.load(projectId)
|
|
66
|
+
.then((settings) => {
|
|
67
|
+
const resolved = settings ?? NO_OVERRIDES;
|
|
68
|
+
// Only cache while this is still the current lookup: an invalidate()
|
|
69
|
+
// that landed while the query was on the wire means the answer in hand
|
|
70
|
+
// already describes the old settings.
|
|
71
|
+
if (this.inFlight.get(projectId) === pending) {
|
|
72
|
+
this.cache.set(projectId, resolved);
|
|
73
|
+
}
|
|
74
|
+
return resolved;
|
|
75
|
+
})
|
|
76
|
+
.finally(() => {
|
|
77
|
+
// Cleared on failure too, so one bad lookup does not pin every later
|
|
78
|
+
// caller to the same rejection.
|
|
79
|
+
if (this.inFlight.get(projectId) === pending) {
|
|
80
|
+
this.inFlight.delete(projectId);
|
|
81
|
+
}
|
|
82
|
+
});
|
|
83
|
+
|
|
84
|
+
this.inFlight.set(projectId, pending);
|
|
85
|
+
return pending;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
invalidate(projectId: string): void {
|
|
89
|
+
this.cache.delete(projectId);
|
|
90
|
+
// A lookup that started before the change would write a stale value on
|
|
91
|
+
// arrival; dropping it here sends the next caller back to the database.
|
|
92
|
+
this.inFlight.delete(projectId);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
clear(): void {
|
|
96
|
+
this.cache.clear();
|
|
97
|
+
this.inFlight.clear();
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import type { Redis } from "@/index.js";
|
|
2
|
+
import { randomUUID } from "crypto";
|
|
3
|
+
|
|
4
|
+
export interface ThrottleResult {
|
|
5
|
+
allowed: boolean;
|
|
6
|
+
count: number;
|
|
7
|
+
limit: number;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
// True sliding window counter using Redis ZSET: max N sends per window per user.
|
|
11
|
+
|
|
12
|
+
export interface UserThrottleOptions {
|
|
13
|
+
redis: Redis;
|
|
14
|
+
maxPerHour?: number;
|
|
15
|
+
windowHours?: number;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface ThrottleCheckOptions {
|
|
19
|
+
/** Per-project cap for this window. `0` blocks every non-critical send. */
|
|
20
|
+
limit?: number | null;
|
|
21
|
+
/** Per-project window length in hours. */
|
|
22
|
+
windowHours?: number | null;
|
|
23
|
+
/** Future send time. The window is evaluated at that instant, not at now. */
|
|
24
|
+
scheduledAt?: string;
|
|
25
|
+
/**
|
|
26
|
+
* Stable id of the message being counted. A retry of the same message is
|
|
27
|
+
* then counted once, not once per attempt. Random when omitted.
|
|
28
|
+
*/
|
|
29
|
+
messageId?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Reject stored values that would make the window meaningless. */
|
|
33
|
+
function positiveOrNull(value: number | null | undefined): number | null {
|
|
34
|
+
return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** A limit of 0 is a legitimate kill switch, so zero is allowed here. */
|
|
38
|
+
function nonNegativeOrNull(value: number | null | undefined): number | null {
|
|
39
|
+
return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export class UserThrottle {
|
|
43
|
+
private readonly redis: Redis;
|
|
44
|
+
private readonly maxPerHour: number;
|
|
45
|
+
private readonly windowHours: number;
|
|
46
|
+
|
|
47
|
+
constructor({ redis, maxPerHour = 3, windowHours = 1 }: UserThrottleOptions) {
|
|
48
|
+
this.redis = redis;
|
|
49
|
+
this.maxPerHour = maxPerHour;
|
|
50
|
+
this.windowHours = windowHours;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* @param projectId Tenant that owns `userId`. User ids are caller-supplied
|
|
55
|
+
* external ids, so they collide across tenants and MUST be namespaced —
|
|
56
|
+
* otherwise one tenant's traffic throttles another's.
|
|
57
|
+
* @param options Per-project overrides. Values that are absent, null, or
|
|
58
|
+
* nonsensical fall back to this instance's defaults.
|
|
59
|
+
*/
|
|
60
|
+
async check(
|
|
61
|
+
projectId: string,
|
|
62
|
+
userId: string,
|
|
63
|
+
priority?: string,
|
|
64
|
+
options: ThrottleCheckOptions = {},
|
|
65
|
+
): Promise<ThrottleResult> {
|
|
66
|
+
const limit = nonNegativeOrNull(options.limit) ?? this.maxPerHour;
|
|
67
|
+
const windowHours = positiveOrNull(options.windowHours) ?? this.windowHours;
|
|
68
|
+
|
|
69
|
+
if (priority === "critical") {
|
|
70
|
+
return { allowed: true, count: 0, limit };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const windowMs = windowHours * 3600_000;
|
|
74
|
+
const key = `throttle:${projectId}:user:${userId}`;
|
|
75
|
+
const targetTime = options.scheduledAt ? new Date(options.scheduledAt).getTime() : Date.now();
|
|
76
|
+
const windowStart = targetTime - windowMs;
|
|
77
|
+
const memberId = options.messageId ?? randomUUID();
|
|
78
|
+
|
|
79
|
+
// The key must outlive the window it is counting. For a future-dated send
|
|
80
|
+
// that means surviving until targetTime plus one more window, so a task
|
|
81
|
+
// scheduled for next week still counts against the right bucket.
|
|
82
|
+
const windowSeconds = Math.ceil(windowMs / 1000);
|
|
83
|
+
const ttlSeconds = Math.max(
|
|
84
|
+
windowSeconds,
|
|
85
|
+
Math.ceil((targetTime - Date.now()) / 1000) + windowSeconds,
|
|
86
|
+
);
|
|
87
|
+
|
|
88
|
+
const count = await this.redis.throttleUser(
|
|
89
|
+
key,
|
|
90
|
+
windowStart,
|
|
91
|
+
limit,
|
|
92
|
+
targetTime,
|
|
93
|
+
memberId,
|
|
94
|
+
ttlSeconds,
|
|
95
|
+
Date.now() - windowMs,
|
|
96
|
+
);
|
|
97
|
+
|
|
98
|
+
return { allowed: count <= limit, count, limit };
|
|
99
|
+
}
|
|
100
|
+
}
|
package/src/redis/index.ts
CHANGED
|
@@ -170,7 +170,10 @@ export const LUA_COUNT_REQUEST = `
|
|
|
170
170
|
return count
|
|
171
171
|
`;
|
|
172
172
|
|
|
173
|
-
/**
|
|
173
|
+
/**
|
|
174
|
+
* Two-phase idempotency lease acquisition. Checks sent/legacy, then attempts SET NX lock.
|
|
175
|
+
* @deprecated Nothing calls the `acquireLease` command; removed in the next minor version.
|
|
176
|
+
*/
|
|
174
177
|
export const LUA_ACQUIRE_LEASE = `
|
|
175
178
|
if redis.call('EXISTS', KEYS[1]) == 1 or redis.call('EXISTS', KEYS[3]) == 1 then
|
|
176
179
|
return 'completed'
|
|
@@ -185,7 +188,10 @@ export const LUA_ACQUIRE_LEASE = `
|
|
|
185
188
|
return 'locked'
|
|
186
189
|
`;
|
|
187
190
|
|
|
188
|
-
/**
|
|
191
|
+
/**
|
|
192
|
+
* Two-phase idempotency completion marker. Atomically sets completed + legacy and deletes lock.
|
|
193
|
+
* @deprecated Nothing calls the `markProcessed` command; removed in the next minor version.
|
|
194
|
+
*/
|
|
189
195
|
export const LUA_MARK_PROCESSED = `
|
|
190
196
|
redis.call('SET', KEYS[1], '1', 'EX', ARGV[1])
|
|
191
197
|
redis.call('SET', KEYS[2], '1', 'EX', ARGV[1])
|
|
@@ -224,6 +230,7 @@ export function registerCustomCommands(redis: Redis): void {
|
|
|
224
230
|
lua: LUA_SCHEDULER_POLL,
|
|
225
231
|
});
|
|
226
232
|
|
|
233
|
+
// Deprecated: nothing calls acquireLease or markProcessed. Remove both in the next minor.
|
|
227
234
|
redis.defineCommand("acquireLease", {
|
|
228
235
|
numberOfKeys: 3,
|
|
229
236
|
lua: LUA_ACQUIRE_LEASE,
|
|
@@ -361,7 +368,7 @@ export class RedisClient {
|
|
|
361
368
|
}
|
|
362
369
|
}
|
|
363
370
|
|
|
364
|
-
function redactUrl(url: string): string {
|
|
371
|
+
export function redactUrl(url: string): string {
|
|
365
372
|
try {
|
|
366
373
|
const parsed = new URL(url);
|
|
367
374
|
if (parsed.password) parsed.password = "***";
|