notifkit 0.1.13 → 0.1.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -0
- package/dist/{bootstrap-omGPIBny.mjs → bootstrap-BOmT69OH.mjs} +1 -1
- package/dist/{bulk-C4hTcnLu.mjs → bulk-ZPiOJRx-.mjs} +1 -1
- package/dist/index.d.mts +16 -4
- package/dist/index.mjs +2 -2
- package/dist/{main-DAXO-MiH.mjs → main-24J4U8yP.mjs} +3 -3
- package/dist/{main-BtnGmyaT.mjs → main-BdZvBgV7.mjs} +9 -3
- package/dist/{main-B5BwjIMu.mjs → main-C0m9-Eos.mjs} +58 -5
- package/dist/{main-DYGCl7Ja.mjs → main-C6S3EsJ3.mjs} +2 -2
- package/dist/{main-B-AZ-xoN.mjs → main-CCqcFDDe.mjs} +2 -2
- package/dist/{main-Bes11Ad3.mjs → main-CTjaZ7ZD.mjs} +2 -2
- package/dist/{main-BU27VjDC.mjs → main-JEXBLP2A.mjs} +2 -2
- package/dist/{main-BxAeC_k6.mjs → main-g33jpia4.mjs} +157 -76
- package/dist/{src-CIPTzq9i.mjs → src-9LXITcNi.mjs} +64 -39
- package/drizzle/0008_delivery_outbox_destination_idx.sql +3 -0
- package/drizzle/meta/_journal.json +7 -0
- package/package.json +3 -2
- package/scripts/create-admin.mjs +8 -0
- package/scripts/create-project.mjs +0 -0
- package/scripts/migrate.mjs +0 -0
- package/scripts/notifkit.mjs +0 -0
- package/src/config/index.ts +6 -3
- package/src/contracts/streams.ts +4 -0
- package/src/db/schema.ts +3 -0
- package/src/queue/index.ts +19 -23
- package/src/redis/index.ts +20 -0
- package/src/services/api/admin-static.ts +21 -11
- package/src/services/api/handlers.ts +51 -43
- package/src/services/api/http.ts +12 -9
- package/src/services/api/live-events.ts +74 -0
- package/src/services/api/main.ts +57 -23
- package/src/services/delivery/live-events.ts +68 -0
- package/src/services/delivery/main.ts +14 -2
- package/src/services/engine/main.ts +13 -1
- package/dashboard/README.md +0 -29
package/src/services/api/main.ts
CHANGED
|
@@ -18,6 +18,7 @@ import { readJsonBody, readRawBody, sendJson, HttpError } from "./http.js";
|
|
|
18
18
|
import { Router } from "./router.js";
|
|
19
19
|
import { createHandlers } from "./handlers.js";
|
|
20
20
|
import { handleAdminRequest } from "./admin-static.js";
|
|
21
|
+
import { RedisLiveDeliveryEvents } from "./live-events.js";
|
|
21
22
|
import { getAdminSession, hashPassword } from "@/services/auth/index.js";
|
|
22
23
|
import { projects, messageLogs, projectApiKeys, suppressions } from "@/db/schema.js";
|
|
23
24
|
import { eq, inArray } from "drizzle-orm";
|
|
@@ -61,6 +62,7 @@ let authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
|
|
|
61
62
|
let tokenHashToToken = new Map<string, string>();
|
|
62
63
|
let authSubscriber: Redis | null = null;
|
|
63
64
|
let router: Router;
|
|
65
|
+
let liveEvents: RedisLiveDeliveryEvents | null = null;
|
|
64
66
|
let apiRateLimiter: ApiRateLimiter;
|
|
65
67
|
|
|
66
68
|
export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string | undefined {
|
|
@@ -76,17 +78,34 @@ export function extractAuthToken(req: Pick<IncomingMessage, "headers">): string
|
|
|
76
78
|
}
|
|
77
79
|
|
|
78
80
|
/**
|
|
79
|
-
*
|
|
81
|
+
* What a dashboard user's role may do. `admin_users.role` is free text (the
|
|
82
|
+
* create-admin script takes any value), so only the roles known to grant
|
|
83
|
+
* writes do; anything else, `read_only` included, is read-only.
|
|
80
84
|
*/
|
|
81
|
-
export function
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
85
|
+
export function sessionKeyRole(role: string): "admin" | "read_only" {
|
|
86
|
+
return role === "superadmin" || role === "admin" ? "admin" : "read_only";
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Resolves the client address, given how many proxies (TRUST_PROXY) are in
|
|
91
|
+
* front of the API. Each one appends the address it saw to X-Forwarded-For,
|
|
92
|
+
* so the client is `trustedHops` back from the connecting peer. The leftmost
|
|
93
|
+
* entry is the one a client can write itself, so it is used only when the
|
|
94
|
+
* chain is shorter than the configured hops.
|
|
95
|
+
*/
|
|
96
|
+
export function getClientIp(req: IncomingMessage, trustedHops: number): string {
|
|
97
|
+
const peer = req.socket.remoteAddress || "unknown";
|
|
98
|
+
const forwarded = req.headers["x-forwarded-for"];
|
|
99
|
+
if (trustedHops <= 0 || typeof forwarded !== "string") return peer;
|
|
100
|
+
|
|
101
|
+
const chain = [
|
|
102
|
+
...forwarded
|
|
103
|
+
.split(",")
|
|
104
|
+
.map((s) => s.trim())
|
|
105
|
+
.filter(Boolean),
|
|
106
|
+
peer,
|
|
107
|
+
];
|
|
108
|
+
return chain[Math.max(chain.length - 1 - trustedHops, 0)]!;
|
|
90
109
|
}
|
|
91
110
|
|
|
92
111
|
async function handleCreateProject(req: IncomingMessage, res: ServerResponse): Promise<void> {
|
|
@@ -277,9 +296,11 @@ export async function startApiServer() {
|
|
|
277
296
|
}
|
|
278
297
|
}
|
|
279
298
|
|
|
299
|
+
liveEvents = new RedisLiveDeliveryEvents(redis.native, logger);
|
|
280
300
|
deps = {
|
|
281
301
|
logger,
|
|
282
302
|
redis,
|
|
303
|
+
liveEvents,
|
|
283
304
|
producers,
|
|
284
305
|
userRepo: new UserRepository(db),
|
|
285
306
|
contactRepo: new ContactRepository(db),
|
|
@@ -443,7 +464,7 @@ export async function startApiServer() {
|
|
|
443
464
|
const session = await getAdminSession(redis.native, token);
|
|
444
465
|
if (session) {
|
|
445
466
|
isAdminToken = true;
|
|
446
|
-
keyRole =
|
|
467
|
+
keyRole = sessionKeyRole(session.role);
|
|
447
468
|
}
|
|
448
469
|
} else if (config.ADMIN_API_KEY) {
|
|
449
470
|
const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
|
|
@@ -559,7 +580,15 @@ export async function startApiServer() {
|
|
|
559
580
|
let authorized = false;
|
|
560
581
|
if (token.startsWith("nk_sess_")) {
|
|
561
582
|
const session = await getAdminSession(redis.native, token);
|
|
562
|
-
if (session)
|
|
583
|
+
if (session) {
|
|
584
|
+
// Creating projects and minting keys hands out admin credentials, so
|
|
585
|
+
// a read-only dashboard user gets to look and nothing more.
|
|
586
|
+
if (sessionKeyRole(session.role) === "read_only" && req.method !== "GET") {
|
|
587
|
+
sendJson(res, 403, { error: "forbidden", message: "Session is read-only" });
|
|
588
|
+
return;
|
|
589
|
+
}
|
|
590
|
+
authorized = true;
|
|
591
|
+
}
|
|
563
592
|
} else if (config.ADMIN_API_KEY) {
|
|
564
593
|
const expectedBuffer = Buffer.from(config.ADMIN_API_KEY);
|
|
565
594
|
const providedBuffer = Buffer.from(token);
|
|
@@ -583,11 +612,10 @@ export async function startApiServer() {
|
|
|
583
612
|
// an open endpoint cannot be used to hammer the process. Generous, because
|
|
584
613
|
// a shared corporate egress IP can legitimately produce a burst.
|
|
585
614
|
if (isPublicUnsubscribe) {
|
|
586
|
-
const clientIp = getClientIp(req,
|
|
615
|
+
const clientIp = getClientIp(req, config.TRUST_PROXY);
|
|
587
616
|
try {
|
|
588
617
|
const key = `rate-limit:api:unsub:${clientIp}`;
|
|
589
|
-
const count = await redis.native.
|
|
590
|
-
if (count === 1) await redis.native.expire(key, 60);
|
|
618
|
+
const count = await redis.native.countRequest(key, 60);
|
|
591
619
|
if (count > 60) {
|
|
592
620
|
res.setHeader("Retry-After", "60");
|
|
593
621
|
sendJson(res, 429, { error: "too_many_requests" });
|
|
@@ -603,11 +631,10 @@ export async function startApiServer() {
|
|
|
603
631
|
// The login route is unauthenticated and CPU-intensive due to password hashing (scrypt).
|
|
604
632
|
// Throttle login attempts per IP to prevent credential brute-forcing and CPU exhaustion.
|
|
605
633
|
if (isPublicAuth) {
|
|
606
|
-
const clientIp = getClientIp(req,
|
|
634
|
+
const clientIp = getClientIp(req, config.TRUST_PROXY);
|
|
607
635
|
try {
|
|
608
636
|
const key = `rate-limit:api:auth:${clientIp}`;
|
|
609
|
-
const count = await redis.native.
|
|
610
|
-
if (count === 1) await redis.native.expire(key, 60);
|
|
637
|
+
const count = await redis.native.countRequest(key, 60);
|
|
611
638
|
if (count > 10) {
|
|
612
639
|
res.setHeader("Retry-After", "60");
|
|
613
640
|
sendJson(res, 429, {
|
|
@@ -694,6 +721,7 @@ export async function startApiServer() {
|
|
|
694
721
|
|
|
695
722
|
if (transport.parseWebhook) {
|
|
696
723
|
router.post(transport.webhookPath, async (req, res) => {
|
|
724
|
+
let deadline: NodeJS.Timeout | undefined;
|
|
697
725
|
try {
|
|
698
726
|
await Promise.race([
|
|
699
727
|
(async () => {
|
|
@@ -835,15 +863,19 @@ export async function startApiServer() {
|
|
|
835
863
|
}
|
|
836
864
|
if (!res.headersSent) sendJson(res, 200, { success: true });
|
|
837
865
|
})(),
|
|
838
|
-
new Promise((_, reject) =>
|
|
839
|
-
setTimeout(() => reject(new Error("Webhook processing timeout")), 15000)
|
|
840
|
-
),
|
|
866
|
+
new Promise((_, reject) => {
|
|
867
|
+
deadline = setTimeout(() => reject(new Error("Webhook processing timeout")), 15000);
|
|
868
|
+
}),
|
|
841
869
|
]);
|
|
842
|
-
} catch (err
|
|
870
|
+
} catch (err) {
|
|
871
|
+
// The detail is ours to log, not the provider's: providers keep
|
|
872
|
+
// response bodies in their delivery logs.
|
|
843
873
|
logger.error({ err, channel }, "webhook processing error or timeout");
|
|
844
874
|
if (!res.headersSent) {
|
|
845
|
-
sendJson(res, 500, { error: "internal_error"
|
|
875
|
+
sendJson(res, 500, { error: "internal_error" });
|
|
846
876
|
}
|
|
877
|
+
} finally {
|
|
878
|
+
clearTimeout(deadline);
|
|
847
879
|
}
|
|
848
880
|
});
|
|
849
881
|
logger.info(`Mounted webhook for ${channel} at ${transport.webhookPath}`);
|
|
@@ -873,6 +905,8 @@ export async function stopApiServer(): Promise<void> {
|
|
|
873
905
|
authSubscriber.disconnect();
|
|
874
906
|
authSubscriber = null;
|
|
875
907
|
}
|
|
908
|
+
await liveEvents?.close();
|
|
909
|
+
liveEvents = null;
|
|
876
910
|
// These are module-scoped, so a restart in the same process must not inherit
|
|
877
911
|
// the previous instance's cached auth or health.
|
|
878
912
|
authCache = new LRUCache<string, CachedAuthKey>(1000, AUTH_CACHE_TTL_MS);
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { EventEmitter } from "node:events";
|
|
2
|
+
import type { Redis } from "@/redis/index.js";
|
|
3
|
+
import { PUBSUB_CHANNELS } from "@/contracts/index.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Delivery outcomes as GET /v1/events/stream relays them. They cross from the
|
|
7
|
+
* delivery worker to the API over Redis pub/sub because the two are separate
|
|
8
|
+
* processes in any deployment that scales them apart; an in-process emitter
|
|
9
|
+
* only ever reached an API that happened to share the delivery's process.
|
|
10
|
+
*/
|
|
11
|
+
export type LiveDeliveryEvent =
|
|
12
|
+
| {
|
|
13
|
+
event: "delivery:delivered";
|
|
14
|
+
taskId: string;
|
|
15
|
+
providerMessageId: string;
|
|
16
|
+
channel: string;
|
|
17
|
+
projectId: string;
|
|
18
|
+
}
|
|
19
|
+
| { event: "delivery:failed"; taskId: string; error: string; channel: string; projectId: string };
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* How long to stop publishing after a publish nobody was subscribed to. Only
|
|
23
|
+
* a fallback: an API that starts listening says so on DELIVERY_EVENTS_WANTED,
|
|
24
|
+
* which ends the quiet straight away.
|
|
25
|
+
*/
|
|
26
|
+
const QUIET_MS = 5_000;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Forwards the delivery worker's `delivery:*` events to Redis.
|
|
30
|
+
*
|
|
31
|
+
* The API subscribes only while a client has the stream open, so most of the
|
|
32
|
+
* time a publish reaches nobody. PUBLISH says how many received it; after a 0
|
|
33
|
+
* this goes quiet rather than paying a round trip per delivery for no one,
|
|
34
|
+
* until an API announces it is listening.
|
|
35
|
+
*/
|
|
36
|
+
export function publishDeliveryEvents(redis: Redis, emitter: EventEmitter): () => void {
|
|
37
|
+
let quietUntil = 0;
|
|
38
|
+
const wanted = redis.duplicate({ enableAutoPipelining: false });
|
|
39
|
+
wanted.on("message", () => (quietUntil = 0));
|
|
40
|
+
wanted.subscribe(PUBSUB_CHANNELS.DELIVERY_EVENTS_WANTED).catch(() => {});
|
|
41
|
+
|
|
42
|
+
const publish = (message: LiveDeliveryEvent) => {
|
|
43
|
+
if (Date.now() < quietUntil) return;
|
|
44
|
+
redis
|
|
45
|
+
.publish(PUBSUB_CHANNELS.DELIVERY_EVENTS, JSON.stringify(message))
|
|
46
|
+
.then((receivers) => {
|
|
47
|
+
if (receivers === 0) quietUntil = Date.now() + QUIET_MS;
|
|
48
|
+
})
|
|
49
|
+
.catch(() => {});
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
const onDelivered = (
|
|
53
|
+
taskId: string,
|
|
54
|
+
providerMessageId: string,
|
|
55
|
+
channel: string,
|
|
56
|
+
projectId: string,
|
|
57
|
+
) => publish({ event: "delivery:delivered", taskId, providerMessageId, channel, projectId });
|
|
58
|
+
const onFailed = (taskId: string, error: string, channel: string, projectId: string) =>
|
|
59
|
+
publish({ event: "delivery:failed", taskId, error, channel, projectId });
|
|
60
|
+
|
|
61
|
+
emitter.on("delivery:delivered", onDelivered);
|
|
62
|
+
emitter.on("delivery:failed", onFailed);
|
|
63
|
+
return () => {
|
|
64
|
+
emitter.off("delivery:delivered", onDelivered);
|
|
65
|
+
emitter.off("delivery:failed", onFailed);
|
|
66
|
+
wanted.disconnect();
|
|
67
|
+
};
|
|
68
|
+
}
|
|
@@ -35,6 +35,7 @@ import {
|
|
|
35
35
|
uniqueConsumerId,
|
|
36
36
|
} from "@/workers/bootstrap.js";
|
|
37
37
|
import { BatchProcessor, CircuitBreaker } from "@/shared/index.js";
|
|
38
|
+
import { publishDeliveryEvents } from "./live-events.js";
|
|
38
39
|
import { ProviderThrottle } from "./throttle.js";
|
|
39
40
|
import { metrics } from "@/metrics/index.js";
|
|
40
41
|
|
|
@@ -59,6 +60,7 @@ let scheduledProducer: StreamProducer;
|
|
|
59
60
|
let enrichedProducers: Record<string, StreamProducer>;
|
|
60
61
|
let healthInterval: NodeJS.Timeout | null = null;
|
|
61
62
|
let subscriber: Redis | null = null;
|
|
63
|
+
let stopLiveEvents: (() => void) | null = null;
|
|
62
64
|
|
|
63
65
|
(global as any)._telemetry = (global as any)._telemetry || {
|
|
64
66
|
count: 0,
|
|
@@ -620,7 +622,9 @@ export class DeliveryWorker extends BaseWorker {
|
|
|
620
622
|
);
|
|
621
623
|
}),
|
|
622
624
|
]);
|
|
623
|
-
|
|
625
|
+
// A permanent rejection is the provider working: returned, not
|
|
626
|
+
// thrown, so the breaker does not count it.
|
|
627
|
+
if (!res.success && !res.invalidToken && res.retryable !== false) {
|
|
624
628
|
throw providerFailure(res);
|
|
625
629
|
}
|
|
626
630
|
return res;
|
|
@@ -833,7 +837,10 @@ export class DeliveryWorker extends BaseWorker {
|
|
|
833
837
|
);
|
|
834
838
|
}),
|
|
835
839
|
]);
|
|
836
|
-
|
|
840
|
+
// A permanent rejection (a bad address) is the provider working:
|
|
841
|
+
// returned, not thrown, so the breaker does not count it. A run
|
|
842
|
+
// of them in one list used to open it for every project.
|
|
843
|
+
if (!res.success && res.retryable !== false) {
|
|
837
844
|
throw providerFailure(res);
|
|
838
845
|
}
|
|
839
846
|
return res;
|
|
@@ -1078,6 +1085,9 @@ export async function startDeliveryWorker() {
|
|
|
1078
1085
|
|
|
1079
1086
|
// ─── Health check interval ──────────────────────────────────────────────────
|
|
1080
1087
|
|
|
1088
|
+
// Outcomes for the API's live event stream, which may be in another process.
|
|
1089
|
+
stopLiveEvents = publishDeliveryEvents(redis.native, globalEmitter);
|
|
1090
|
+
|
|
1081
1091
|
healthInterval = startHealthReporter("delivery", worker, redis, logger);
|
|
1082
1092
|
|
|
1083
1093
|
logger.info(
|
|
@@ -1104,4 +1114,6 @@ export async function stopDeliveryWorker(): Promise<void> {
|
|
|
1104
1114
|
});
|
|
1105
1115
|
healthInterval = null;
|
|
1106
1116
|
subscriber = null;
|
|
1117
|
+
stopLiveEvents?.();
|
|
1118
|
+
stopLiveEvents = null;
|
|
1107
1119
|
}
|
|
@@ -147,7 +147,7 @@ export function isInQuietHours(
|
|
|
147
147
|
targetDay = nextDay.getUTCDate();
|
|
148
148
|
}
|
|
149
149
|
|
|
150
|
-
|
|
150
|
+
let nextActive = localTimeToUtc(
|
|
151
151
|
targetYear,
|
|
152
152
|
targetMonth,
|
|
153
153
|
targetDay,
|
|
@@ -156,6 +156,18 @@ export function isInQuietHours(
|
|
|
156
156
|
0,
|
|
157
157
|
timezone,
|
|
158
158
|
);
|
|
159
|
+
// In a DST fall-back hour the end time occurs twice and localTimeToUtc
|
|
160
|
+
// picks the first, which can already be behind us; use the current
|
|
161
|
+
// UTC offset to land on the second occurrence instead.
|
|
162
|
+
if (nextActive.getTime() <= date.getTime()) {
|
|
163
|
+
const currentSec = parseInt(parts.find((p) => p.type === "second")?.value ?? "0", 10);
|
|
164
|
+
const offsetMs =
|
|
165
|
+
Date.UTC(year, month - 1, day, currentHour, currentMin, currentSec) -
|
|
166
|
+
Math.floor(date.getTime() / 1000) * 1000;
|
|
167
|
+
nextActive = new Date(
|
|
168
|
+
Date.UTC(targetYear, targetMonth - 1, targetDay, endH, endM, 0) - offsetMs,
|
|
169
|
+
);
|
|
170
|
+
}
|
|
159
171
|
return { inQuietHours: true, nextActiveTime: nextActive };
|
|
160
172
|
}
|
|
161
173
|
}
|
package/dashboard/README.md
DELETED
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
# Notifkit Admin & Observability Dashboard
|
|
2
|
-
|
|
3
|
-
This is the single-page application (SPA) admin console and real-time delivery observability dashboard for **Notifkit**, built with **Vite**, **React 19**, **React Router**, **Tailwind CSS v4**, and **shadcn/ui**.
|
|
4
|
-
|
|
5
|
-
## Development
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
# Start Vite development server
|
|
9
|
-
npm run dev
|
|
10
|
-
|
|
11
|
-
# Build production bundle to dist/
|
|
12
|
-
npm run build
|
|
13
|
-
|
|
14
|
-
# Preview built production bundle
|
|
15
|
-
npm run preview
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
## Features
|
|
19
|
-
|
|
20
|
-
- **Live Activity Feed**: Real-time SSE streaming of delivery statuses and handoffs.
|
|
21
|
-
- **Historical Audit Logs**: Queryable, paginated notification lifecycle trails and payload inspector.
|
|
22
|
-
- **System Health**: PostgreSQL and Redis latencies and worker heartbeat monitoring.
|
|
23
|
-
- **Analytics & Queues**: Real-time Redis Streams queue depth gauges and delivery SLA metrics.
|
|
24
|
-
- **Dead Letter Queue (DLQ)**: Poison message diagnostics with stream replay and purge capabilities.
|
|
25
|
-
- **Scheduled Pipeline**: Future dispatch scheduling and quiet hours deferrals.
|
|
26
|
-
- **Workflows**: Multi-step notification sequence diagrams and instance step execution tracing.
|
|
27
|
-
- **Templates**: Channel bindings, dynamic variables, and prompt previewing.
|
|
28
|
-
- **User Directory**: Contact channels and opt-out preferences.
|
|
29
|
-
- **Projects & API Keys**: Tenant workspace configuration and scoped token provisioning.
|