notifkit 0.1.14 → 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-m107TukN.mjs → bootstrap-BMDRPjgp.mjs} +1 -1
- package/dist/{bulk-xAd_biYV.mjs → bulk-CJ5QXiPa.mjs} +1 -1
- package/dist/index.d.mts +71 -27
- package/dist/index.mjs +2 -2
- package/dist/{main-CWIBUEc7.mjs → main-6_bXQBDH.mjs} +21 -41
- package/dist/{main-WkxXwP5q.mjs → main-8nP3qmCT.mjs} +29 -49
- package/dist/{main-HT5c6jyf.mjs → main-B82bsFoy.mjs} +183 -334
- package/dist/{main-C87TSAqM.mjs → main-CpaHF1Zw.mjs} +13 -15
- package/dist/{main-DRHL2bst.mjs → main-DULD8-th.mjs} +8 -6
- package/dist/{main-D_62f9fH.mjs → main-ZW5RaiOK.mjs} +77 -64
- package/dist/{main-5kVwbbnW.mjs → main-g1KEcXXp.mjs} +676 -582
- package/dist/{main-C0MjK1Au.mjs → main-mGIT8jv4.mjs} +4 -4
- package/dist/schedule-or-dispatch-Cd7GLfc3.mjs +52 -0
- package/dist/{src-DYqdD694.mjs → src-BE_EUpZ6.mjs} +93 -93
- package/package.json +1 -1
- package/scripts/create-admin.mjs +0 -0
- package/scripts/create-project.mjs +6 -2
- package/scripts/migrate.mjs +0 -0
- package/scripts/notifkit.mjs +0 -0
- 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 -235
- 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/README.md +0 -29
- package/dashboard/dist/assets/index-ggpJKZqZ.js +0 -315
- package/dashboard/dist/assets/index-s-SXGIwv.css +0 -1
|
@@ -24,7 +24,7 @@ export type TypedEventEnvelope<K extends KnownEventType> = Omit<
|
|
|
24
24
|
payload: EventPayloadMap[K];
|
|
25
25
|
};
|
|
26
26
|
|
|
27
|
-
//
|
|
27
|
+
// The name the queue and workers use for an envelope.
|
|
28
28
|
export type StreamEvent = EventEnvelope;
|
|
29
29
|
export const StreamEventSchema = EventEnvelopeSchema;
|
|
30
30
|
export type StreamEventMetadata = EventMetadata;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
2
|
import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contracts/common.js";
|
|
3
3
|
|
|
4
|
+
/** @deprecated Nothing publishes `notification.created`; removed in the next minor version. */
|
|
4
5
|
export const NotificationCreatedPayloadSchema = z.object({
|
|
5
6
|
projectId: z.string().uuid(),
|
|
6
7
|
recipientId: z.string().min(1),
|
|
@@ -11,4 +12,5 @@ export const NotificationCreatedPayloadSchema = z.object({
|
|
|
11
12
|
scheduledAt: z.string().datetime().optional(),
|
|
12
13
|
idempotencyKey: z.string().optional(),
|
|
13
14
|
});
|
|
15
|
+
/** @deprecated Nothing publishes `notification.created`; removed in the next minor version. */
|
|
14
16
|
export type NotificationCreatedPayload = z.infer<typeof NotificationCreatedPayloadSchema>;
|
|
@@ -9,7 +9,7 @@ export const NotificationDeliveredPayloadSchema = z.object({
|
|
|
9
9
|
deliveredAt: z.string().datetime(),
|
|
10
10
|
providerMessageId: z.string().optional(),
|
|
11
11
|
providerResponse: z.record(z.string(), z.unknown()).optional(),
|
|
12
|
-
templateId: z.string().
|
|
12
|
+
templateId: z.string().min(1).optional(),
|
|
13
13
|
workflowInstanceId: z.string().uuid().optional(),
|
|
14
14
|
/** Campaign this message belongs to, carried from the originating request. */
|
|
15
15
|
campaignId: z.string().min(1).max(128).optional(),
|
|
@@ -11,7 +11,7 @@ export const NotificationFailedPayloadSchema = z.object({
|
|
|
11
11
|
retryable: z.boolean(),
|
|
12
12
|
attempt: z.number().int().positive(),
|
|
13
13
|
providerResponse: z.record(z.string(), z.unknown()).optional(),
|
|
14
|
-
templateId: z.string().
|
|
14
|
+
templateId: z.string().min(1).optional(),
|
|
15
15
|
workflowInstanceId: z.string().uuid().optional(),
|
|
16
16
|
/** Campaign this message belongs to, carried from the originating request. */
|
|
17
17
|
campaignId: z.string().min(1).max(128).optional(),
|
|
@@ -4,10 +4,11 @@ import { NotificationChannelSchema, NotificationPrioritySchema } from "@/contrac
|
|
|
4
4
|
/**
|
|
5
5
|
* A high-level notification request as issued by the SDK's `notify()` call.
|
|
6
6
|
*
|
|
7
|
-
* Unlike `notification.
|
|
7
|
+
* Unlike `notification.enriched` (which targets a single resolved address),
|
|
8
8
|
* this event carries the *unresolved* target — a user id, a segment, or a
|
|
9
9
|
* topic. A downstream resolver stage fans it out into one
|
|
10
|
-
* `notification.
|
|
10
|
+
* `notification.enriched` per matching address and channel, applying
|
|
11
|
+
* preference filters.
|
|
11
12
|
*/
|
|
12
13
|
export const NotificationTargetSchema = z.discriminatedUnion("type", [
|
|
13
14
|
z.object({ type: z.literal("user"), userId: z.string().min(1) }),
|
package/src/contracts/helpers.ts
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import { type EventEnvelope } from "./envelope.js";
|
|
3
3
|
|
|
4
|
-
//
|
|
5
|
-
// which accepts Omit<StreamEvent, "id" | "timestamp">.
|
|
4
|
+
// Builds the event shape `StreamProducer.publish()` takes.
|
|
6
5
|
export function buildStreamEvent(
|
|
7
6
|
type: string,
|
|
8
7
|
payload: Record<string, unknown>,
|
package/src/contracts/index.ts
CHANGED
|
@@ -35,6 +35,7 @@ import { NotificationCanceledPayloadSchema } from "./events/notification-cancele
|
|
|
35
35
|
import { NotificationAiPendingPayloadSchema } from "./events/notification-ai-pending.js";
|
|
36
36
|
|
|
37
37
|
registry.define("notification.requested", NotificationRequestedPayloadSchema);
|
|
38
|
+
// Deprecated: nothing publishes notification.created. Remove in the next minor.
|
|
38
39
|
registry.define("notification.created", NotificationCreatedPayloadSchema);
|
|
39
40
|
registry.define("notification.enriched", NotificationEnrichedPayloadSchema);
|
|
40
41
|
registry.define("notification.scheduled", NotificationScheduledPayloadSchema);
|
|
@@ -23,6 +23,7 @@ import type { NotificationAiPendingPayload } from "./events/notification-ai-pend
|
|
|
23
23
|
*/
|
|
24
24
|
export interface EventPayloadMap {
|
|
25
25
|
"notification.requested": NotificationRequestedPayload;
|
|
26
|
+
/** @deprecated Nothing publishes `notification.created`; removed in the next minor version. */
|
|
26
27
|
"notification.created": NotificationCreatedPayload;
|
|
27
28
|
"notification.enriched": NotificationEnrichedPayload;
|
|
28
29
|
"notification.scheduled": NotificationScheduledPayload;
|
package/src/contracts/sdk.ts
CHANGED
|
@@ -5,11 +5,12 @@ import { NotificationChannelSchema, NotificationPrioritySchema } from "./common.
|
|
|
5
5
|
//
|
|
6
6
|
// Preferences are stored as JSONB and are intentionally open-ended so new
|
|
7
7
|
// channels/topics can be added without a migration. `channels` and `topics`
|
|
8
|
-
// are boolean opt-in maps; `quietHours` is a list of
|
|
8
|
+
// are boolean opt-in maps; `quietHours` is a list of
|
|
9
|
+
// HH:MM windows in the user's own timezone.
|
|
9
10
|
|
|
10
11
|
export const QuietHoursSchema = z.object({
|
|
11
|
-
start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h,
|
|
12
|
-
end: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h,
|
|
12
|
+
start: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h, user's timezone)"),
|
|
13
|
+
end: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "expected HH:MM (24h, user's timezone)"),
|
|
13
14
|
});
|
|
14
15
|
export type QuietHours = z.infer<typeof QuietHoursSchema>;
|
|
15
16
|
|
|
@@ -23,17 +24,7 @@ export type Preferences = z.infer<typeof PreferencesSchema>;
|
|
|
23
24
|
// ─── Contacts ─────────────────────────────────────────────────────────────────
|
|
24
25
|
|
|
25
26
|
/** Channels that carry an addressable target (email address, phone, push token, url, chat id). */
|
|
26
|
-
export const ContactChannelSchema =
|
|
27
|
-
"email",
|
|
28
|
-
"sms",
|
|
29
|
-
"push",
|
|
30
|
-
"webhook",
|
|
31
|
-
"in-app",
|
|
32
|
-
"telegram",
|
|
33
|
-
"discord",
|
|
34
|
-
"whatsapp",
|
|
35
|
-
"slack",
|
|
36
|
-
]);
|
|
27
|
+
export const ContactChannelSchema = NotificationChannelSchema;
|
|
37
28
|
export type ContactChannel = z.infer<typeof ContactChannelSchema>;
|
|
38
29
|
|
|
39
30
|
/** Accept a single value or an array; always normalise to a non-empty array. */
|
|
@@ -85,14 +76,7 @@ export const UpdateUserSchema = z.object({
|
|
|
85
76
|
export type UpdateUserInput = z.input<typeof UpdateUserSchema>;
|
|
86
77
|
|
|
87
78
|
/** addUserContact(userId, channel, { target, preferences, label, isPrimary, enabled }) */
|
|
88
|
-
export const AddContactSchema =
|
|
89
|
-
channel: ContactChannelSchema,
|
|
90
|
-
target: z.string().min(1),
|
|
91
|
-
label: z.string().optional(),
|
|
92
|
-
isPrimary: z.boolean().optional(),
|
|
93
|
-
enabled: z.boolean().optional(),
|
|
94
|
-
preferences: PreferencesSchema.optional(),
|
|
95
|
-
});
|
|
79
|
+
export const AddContactSchema = UserContactInputSchema;
|
|
96
80
|
export type AddContactInput = z.infer<typeof AddContactSchema>;
|
|
97
81
|
|
|
98
82
|
export const BatchAddContactsSchema = z.union([AddContactSchema, z.array(AddContactSchema).min(1)]);
|
|
@@ -103,10 +87,7 @@ export type BatchAddContactsInput = z.infer<typeof BatchAddContactsSchema>;
|
|
|
103
87
|
export const TemplateSchema = z.object({
|
|
104
88
|
id: z.string().min(1),
|
|
105
89
|
channel: NotificationChannelSchema,
|
|
106
|
-
topic:
|
|
107
|
-
.union([z.string().min(1), z.array(z.string().min(1))])
|
|
108
|
-
.transform((v) => (Array.isArray(v) ? v : [v]))
|
|
109
|
-
.optional(),
|
|
90
|
+
topic: stringOrArray.optional(),
|
|
110
91
|
content: z.record(z.string(), z.unknown()),
|
|
111
92
|
aiPrompts: z.record(z.string(), z.string()).optional(),
|
|
112
93
|
});
|
|
@@ -120,17 +101,7 @@ export type SyncTemplatesInput = z.input<typeof SyncTemplatesSchema>;
|
|
|
120
101
|
// ─── notify() ─────────────────────────────────────────────────────────────────
|
|
121
102
|
|
|
122
103
|
/** Inline user object accepted by notify({ user: {...} }). */
|
|
123
|
-
export const InlineUserSchema =
|
|
124
|
-
id: z.string().min(1),
|
|
125
|
-
language: z.string().optional(),
|
|
126
|
-
timezone: z.string().optional(),
|
|
127
|
-
contacts: z.array(UserContactInputSchema).optional(),
|
|
128
|
-
email: stringOrArray.optional(),
|
|
129
|
-
phone: stringOrArray.optional(),
|
|
130
|
-
pushToken: stringOrArray.optional(),
|
|
131
|
-
segments: z.array(z.string().min(1)).optional(),
|
|
132
|
-
preferences: PreferencesSchema.optional(),
|
|
133
|
-
});
|
|
104
|
+
export const InlineUserSchema = AddUserSchema;
|
|
134
105
|
export type InlineUser = z.infer<typeof InlineUserSchema>;
|
|
135
106
|
|
|
136
107
|
/**
|
package/src/db/schema.ts
CHANGED
|
@@ -15,18 +15,13 @@ import {
|
|
|
15
15
|
integer,
|
|
16
16
|
} from "drizzle-orm/pg-core";
|
|
17
17
|
import { sql } from "drizzle-orm";
|
|
18
|
+
import { NotificationChannelSchema, type NotificationChannel } from "../contracts/common.js";
|
|
18
19
|
|
|
19
|
-
export const channelEnum = pgEnum(
|
|
20
|
-
"
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
"in-app",
|
|
25
|
-
"telegram",
|
|
26
|
-
"discord",
|
|
27
|
-
"whatsapp",
|
|
28
|
-
"slack",
|
|
29
|
-
]);
|
|
20
|
+
export const channelEnum = pgEnum(
|
|
21
|
+
"channel",
|
|
22
|
+
// zod types .options as a plain array; pgEnum needs a non-empty tuple.
|
|
23
|
+
NotificationChannelSchema.options as [NotificationChannel, ...NotificationChannel[]],
|
|
24
|
+
);
|
|
30
25
|
|
|
31
26
|
export const projects = pgTable("projects", {
|
|
32
27
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
@@ -311,8 +306,8 @@ export const workflowSteps = pgTable(
|
|
|
311
306
|
instanceId: uuid("instance_id")
|
|
312
307
|
.notNull()
|
|
313
308
|
.references(() => workflowInstances.id, { onDelete: "cascade" }),
|
|
314
|
-
stepIndex: varchar("step_index").notNull(), //
|
|
315
|
-
action: varchar("action").notNull(), //
|
|
309
|
+
stepIndex: varchar("step_index").notNull(), // "0", "1", ... in step order
|
|
310
|
+
action: varchar("action").notNull(), // "notify", "wait", "waitForEvent" or "run"
|
|
316
311
|
output: jsonb("output"),
|
|
317
312
|
error: text("error"),
|
|
318
313
|
createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
|
package/src/idempotency/index.ts
CHANGED
|
@@ -9,10 +9,8 @@ export interface IdempotencyOptions {
|
|
|
9
9
|
export type LeaseResult = "acquired" | "locked" | "completed";
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* - Phase 1 (:lock): Short lease acquired at the start of message processing.
|
|
15
|
-
* - Phase 2 (:sent): Long-lived completion marker recorded when processing succeeds.
|
|
12
|
+
* SET NX-based idempotency guard.
|
|
13
|
+
* One key per id: `L` while leased, `1` once processed.
|
|
16
14
|
*/
|
|
17
15
|
export class IdempotencyGuard {
|
|
18
16
|
private readonly redis: Redis;
|
|
@@ -29,19 +27,19 @@ export class IdempotencyGuard {
|
|
|
29
27
|
return `${this.keyPrefix}:${id}`;
|
|
30
28
|
}
|
|
31
29
|
|
|
30
|
+
/** @deprecated Nothing writes `:lock` keys any more; read only for markers from older versions. Remove in the next minor. */
|
|
32
31
|
private lockKey(id: string): string {
|
|
33
32
|
return `${this.keyPrefix}:${id}:lock`;
|
|
34
33
|
}
|
|
35
34
|
|
|
35
|
+
/** @deprecated Nothing writes `:sent` keys any more; read only for markers from older versions. Remove in the next minor. */
|
|
36
36
|
private completedKey(id: string): string {
|
|
37
37
|
return `${this.keyPrefix}:${id}:sent`;
|
|
38
38
|
}
|
|
39
39
|
|
|
40
40
|
/**
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
* - Happy path (new message): single native SET NX command storing "L" (lock lease).
|
|
44
|
-
* - If already present: checks if "S" (sent/completed) or "L" (locked by another worker).
|
|
41
|
+
* Leases the id with SET NX. One key per id: `L` while leased, `1` once processed.
|
|
42
|
+
* Returns "completed" if already processed, "locked" if another worker holds the lease.
|
|
45
43
|
*/
|
|
46
44
|
async acquireLease(id: string, lockTtlSeconds: number = 30): Promise<LeaseResult> {
|
|
47
45
|
const mainKey = this.key(id);
|
package/src/metrics/index.ts
CHANGED
|
@@ -28,6 +28,7 @@ export const metrics = {
|
|
|
28
28
|
labelNames: ["channel", "reason"],
|
|
29
29
|
registers: [register],
|
|
30
30
|
}),
|
|
31
|
+
/** @deprecated Never set, so it always reads 0. Removed in the next minor version. */
|
|
31
32
|
workerActiveTasks: new promClient.Gauge({
|
|
32
33
|
name: "notifkit_worker_active_tasks",
|
|
33
34
|
help: "Number of currently active tasks per worker",
|
|
@@ -40,6 +41,7 @@ export const metrics = {
|
|
|
40
41
|
labelNames: ["stream"],
|
|
41
42
|
registers: [register],
|
|
42
43
|
}),
|
|
44
|
+
/** @deprecated Never set, so it always reads 0. Removed in the next minor version. */
|
|
43
45
|
pendingAcks: new promClient.Gauge({
|
|
44
46
|
name: "notifkit_pending_acks",
|
|
45
47
|
help: "Number of pending un-acked messages per group",
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
import type { Redis } from "@/index.js";
|
|
2
|
+
import type { Logger } from "@/logger/index.js";
|
|
3
|
+
|
|
4
|
+
// Leases token chunks from Redis sliding-window counters into local memory.
|
|
5
|
+
// Eliminates per-request Redis network roundtrips on API ingress.
|
|
6
|
+
|
|
7
|
+
export interface ApiRateLimiterOptions {
|
|
8
|
+
redis: Redis;
|
|
9
|
+
windowMs?: number;
|
|
10
|
+
maxBatchSize?: number;
|
|
11
|
+
logger?: Logger;
|
|
12
|
+
/** Redis key namespace. Distinct limiters must not share one. */
|
|
13
|
+
keyPrefix?: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Computes dynamic token lease batch size based on RPM.
|
|
18
|
+
* Targets ~5s of limit capacity so Redis is contacted at most ~12 times/min
|
|
19
|
+
* regardless of instantaneous request rate. Bounded between 1 and maxBatchSize.
|
|
20
|
+
*/
|
|
21
|
+
export function calculateTokenBatchSize(limitRpm: number, maxBatchSize = 500): number {
|
|
22
|
+
if (limitRpm <= 0) return 0;
|
|
23
|
+
if (limitRpm <= 10) return 1;
|
|
24
|
+
if (limitRpm <= 60) return 5;
|
|
25
|
+
const perSecond = limitRpm / 60;
|
|
26
|
+
// 5 s window = perSecond * 5; at least 10 to absorb jitter.
|
|
27
|
+
return Math.min(Math.max(Math.ceil(perSecond * 5), 10), maxBatchSize);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
interface ProjectTokenLeaseState {
|
|
31
|
+
bucketIndex: number;
|
|
32
|
+
tokens: number;
|
|
33
|
+
batchSize: number;
|
|
34
|
+
inFlightLease: Promise<number> | null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export class ApiRateLimiter {
|
|
38
|
+
private readonly redis: Redis;
|
|
39
|
+
private readonly windowMs: number;
|
|
40
|
+
private readonly maxBatchSize: number;
|
|
41
|
+
private readonly logger?: Logger;
|
|
42
|
+
private readonly keyPrefix: string;
|
|
43
|
+
private readonly leases = new Map<string, ProjectTokenLeaseState>();
|
|
44
|
+
|
|
45
|
+
constructor({
|
|
46
|
+
redis,
|
|
47
|
+
windowMs = 60_000,
|
|
48
|
+
maxBatchSize = 500,
|
|
49
|
+
logger,
|
|
50
|
+
keyPrefix = "rate-limit:api:req",
|
|
51
|
+
}: ApiRateLimiterOptions) {
|
|
52
|
+
this.redis = redis;
|
|
53
|
+
this.windowMs = windowMs;
|
|
54
|
+
this.maxBatchSize = maxBatchSize;
|
|
55
|
+
this.logger = logger;
|
|
56
|
+
this.keyPrefix = keyPrefix;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Evaluates if a request for `projectId` is allowed within its `limitRpm`.
|
|
61
|
+
* Fast-path uses local in-memory token lease (0ms Redis network latency).
|
|
62
|
+
* Refills in the background before tokens are depleted.
|
|
63
|
+
*/
|
|
64
|
+
async check(projectId: string, limitRpm: number): Promise<boolean> {
|
|
65
|
+
if (limitRpm <= 0) return false;
|
|
66
|
+
|
|
67
|
+
const nowMs = Date.now();
|
|
68
|
+
const currentBucket = Math.floor(nowMs / this.windowMs);
|
|
69
|
+
|
|
70
|
+
let state = this.leases.get(projectId);
|
|
71
|
+
if (!state) {
|
|
72
|
+
state = {
|
|
73
|
+
bucketIndex: currentBucket,
|
|
74
|
+
tokens: 0,
|
|
75
|
+
batchSize: calculateTokenBatchSize(limitRpm, this.maxBatchSize),
|
|
76
|
+
inFlightLease: null,
|
|
77
|
+
};
|
|
78
|
+
this.leases.set(projectId, state);
|
|
79
|
+
this.maybePrune(currentBucket);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// Rollover to new bucket window when minute boundary elapses.
|
|
83
|
+
// Kick off a prefill immediately so the first request of the new window
|
|
84
|
+
// doesn't have to wait — it will land before tokens hit 0 again.
|
|
85
|
+
if (state.bucketIndex !== currentBucket) {
|
|
86
|
+
state.bucketIndex = currentBucket;
|
|
87
|
+
state.tokens = 0;
|
|
88
|
+
state.batchSize = calculateTokenBatchSize(limitRpm, this.maxBatchSize);
|
|
89
|
+
state.inFlightLease = null;
|
|
90
|
+
// Fire the first lease for the new window now, don't await it here.
|
|
91
|
+
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// 1. Fast Path: Local token available in memory (0ms network latency)
|
|
95
|
+
if (state.tokens > 0) {
|
|
96
|
+
state.tokens--;
|
|
97
|
+
|
|
98
|
+
// Background refill when tokens drop below 25% of batch size
|
|
99
|
+
const refillThreshold = Math.max(1, Math.floor(state.batchSize * 0.25));
|
|
100
|
+
if (state.tokens <= refillThreshold && !state.inFlightLease) {
|
|
101
|
+
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
return true;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// 2. Slow Path: tokens are depleted, block on the in-flight lease or start one.
|
|
108
|
+
// Concurrent requests racing here all join the *same* promise so one Redis
|
|
109
|
+
// round trip serves them. A lease only grants `batchSize` tokens, so a
|
|
110
|
+
// burst larger than that leases again rather than rejecting requests the
|
|
111
|
+
// window still has room for: a request is refused only once Redis itself
|
|
112
|
+
// reports the window spent.
|
|
113
|
+
for (;;) {
|
|
114
|
+
if (!state.inFlightLease) {
|
|
115
|
+
this.refill(projectId, state, limitRpm, nowMs, currentBucket).catch(() => {});
|
|
116
|
+
}
|
|
117
|
+
const granted = state.inFlightLease ? await state.inFlightLease : 0;
|
|
118
|
+
|
|
119
|
+
// Only claim a token if the lease came back for the same bucket we waited on.
|
|
120
|
+
if (state.bucketIndex !== currentBucket) return false;
|
|
121
|
+
if (state.tokens > 0) {
|
|
122
|
+
state.tokens--;
|
|
123
|
+
return true;
|
|
124
|
+
}
|
|
125
|
+
if (granted <= 0) return false;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
private async refill(
|
|
130
|
+
projectId: string,
|
|
131
|
+
state: ProjectTokenLeaseState,
|
|
132
|
+
limitRpm: number,
|
|
133
|
+
nowMs: number,
|
|
134
|
+
bucketIndex: number,
|
|
135
|
+
): Promise<number> {
|
|
136
|
+
if (state.inFlightLease) {
|
|
137
|
+
return state.inFlightLease;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const prevBucket = bucketIndex - 1;
|
|
141
|
+
const rlTag = `{${this.keyPrefix}:${projectId || "global"}}`;
|
|
142
|
+
const currentKey = `${rlTag}:${bucketIndex}`;
|
|
143
|
+
const prevKey = `${rlTag}:${prevBucket}`;
|
|
144
|
+
const requested = state.batchSize;
|
|
145
|
+
let inFlightRef: Promise<number> | null = null;
|
|
146
|
+
const executeLease = async (): Promise<number> => {
|
|
147
|
+
try {
|
|
148
|
+
let granted = await this.redis.leaseApiRateLimit(
|
|
149
|
+
currentKey,
|
|
150
|
+
prevKey,
|
|
151
|
+
nowMs,
|
|
152
|
+
this.windowMs,
|
|
153
|
+
limitRpm,
|
|
154
|
+
requested,
|
|
155
|
+
);
|
|
156
|
+
|
|
157
|
+
// On invalid return or negative, fail-open
|
|
158
|
+
if (typeof granted !== "number" || granted < 0) {
|
|
159
|
+
granted = requested;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
if (state.bucketIndex === bucketIndex) {
|
|
163
|
+
state.tokens += granted;
|
|
164
|
+
}
|
|
165
|
+
return granted;
|
|
166
|
+
} catch (err) {
|
|
167
|
+
this.logger?.warn(
|
|
168
|
+
{ err, projectId },
|
|
169
|
+
"project rate limit lease failed — allowing request (fail-open)",
|
|
170
|
+
);
|
|
171
|
+
// Fail-open: credit requested tokens locally to prevent tight retry loops during Redis hiccups
|
|
172
|
+
if (state.bucketIndex === bucketIndex) {
|
|
173
|
+
state.tokens += requested;
|
|
174
|
+
}
|
|
175
|
+
return requested;
|
|
176
|
+
} finally {
|
|
177
|
+
if (state.inFlightLease === inFlightRef) {
|
|
178
|
+
state.inFlightLease = null;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
};
|
|
182
|
+
|
|
183
|
+
const promise = executeLease();
|
|
184
|
+
inFlightRef = promise;
|
|
185
|
+
state.inFlightLease = promise;
|
|
186
|
+
return promise;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
private maybePrune(currentBucket: number): void {
|
|
190
|
+
if (this.leases.size > 2000) {
|
|
191
|
+
for (const [id, s] of this.leases) {
|
|
192
|
+
if (currentBucket - s.bucketIndex > 1) {
|
|
193
|
+
this.leases.delete(id);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** Reset all local cached leases */
|
|
200
|
+
clear(): void {
|
|
201
|
+
this.leases.clear();
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Invalidate local lease for a specific project */
|
|
205
|
+
invalidate(projectId: string): void {
|
|
206
|
+
this.leases.delete(projectId);
|
|
207
|
+
}
|
|
208
|
+
}
|