pipework 0.68.0 → 0.70.0

package/dist/infra/access-links/person-check.js

@@ -0,0 +1,128 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+const ALGORITHM = 'SHA-256';
+const MIN_SECRET_BYTES = 32;
+const MAX_NUMBER_LIMIT = 10_000_000;
+const PRUNE_BATCH = 100;
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+function sameHex(a, b) {
+    return sameBytes(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}
+function positive(name, value) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`personCheck: ${name} must be a positive number`);
+    return value;
+}
+function createPersonCheck(config) {
+    const secret = typeof config.secret === 'string' ? Buffer.from(config.secret, 'utf8') : config.secret;
+    if (!Buffer.isBuffer(secret) || secret.length < MIN_SECRET_BYTES) {
+        throw new Error(`personCheck: secret must be ${String(MIN_SECRET_BYTES)} bytes or more, the same in every process (no random fallback: a per-process secret breaks passes across processes)`);
+    }
+    const maxNumber = config.maxNumber ?? 100_000;
+    if (!Number.isInteger(maxNumber) || maxNumber < 1 || maxNumber > MAX_NUMBER_LIMIT) {
+        throw new Error(`personCheck: maxNumber must be an integer from 1 to ${String(MAX_NUMBER_LIMIT)}`);
+    }
+    const challengeMs = positive('challengeMs', config.challengeMs ?? 600_000);
+    const passMs = positive('passMs', config.passMs ?? 1_800_000);
+    const database = config.database;
+    const key = (purpose) => createHmac('sha256', secret).update(`pipework access links person check: ${purpose}`).digest();
+    const challengeKey = key('challenge');
+    const passKey = key('pass');
+    function challenge(code) {
+        const expires = Math.floor((Date.now() + challengeMs) / 1000);
+        const salt = `${randomBytes(12).toString('hex')}?expires=${String(expires)}&link=${encodeURIComponent(code)}`;
+        const secretNumber = randomBytes(4).readUInt32BE() % (maxNumber + 1);
+        const digest = sha256Hex(salt + String(secretNumber));
+        const signature = createHmac('sha256', challengeKey).update(digest).digest('hex');
+        return { algorithm: ALGORITHM, challenge: digest, maxnumber: maxNumber, salt, signature };
+    }
+    function issuePass(code) {
+        const exp = Date.now() + passMs;
+        const body = Buffer.from(JSON.stringify({ code, exp })).toString('base64url');
+        const mac = createHmac('sha256', passKey).update(body).digest('base64url');
+        return { pass: `${body}.${mac}`, expiresAt: new Date(exp) };
+    }
+    // The challenge's expiry in ms when `solution` solves a live challenge made for `code`; otherwise null.
+    function solvedUntil(code, solution) {
+        if (typeof solution !== 'string')
+            return null;
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(solution, 'base64').toString('utf8'));
+        }
+        catch {
+            return null;
+        }
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+            return null;
+        const { algorithm, challenge: id, number, salt, signature } = payload;
+        if (algorithm !== ALGORITHM || typeof id !== 'string' || typeof salt !== 'string' || typeof signature !== 'string')
+            return null;
+        if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < 0)
+            return null;
+        const params = new URLSearchParams(salt.split('?')[1] ?? '');
+        const expires = Number(params.get('expires'));
+        if (!Number.isFinite(expires) || expires * 1000 <= Date.now() || params.get('link') !== code)
+            return null;
+        const expected = createHmac('sha256', challengeKey).update(id).digest('hex');
+        if (!sameHex(expected, signature))
+            return null;
+        if (!sameHex(sha256Hex(salt + String(number)), id))
+            return null;
+        return { id, untilMs: expires * 1000 };
+    }
+    async function verify(code, solution) {
+        const solved = solvedUntil(code, solution);
+        if (solved === null)
+            return null;
+        const db = pipeSystem(database);
+        const spent = await db.execute(sql `
+      INSERT INTO access_link_check_spent (challenge, expires_at)
+      VALUES (${solved.id}, ${new Date(solved.untilMs).toISOString()})
+      ON CONFLICT DO NOTHING RETURNING 1 AS spent`);
+        if (spent.length === 0)
+            return null;
+        // Kept an hour past expiry so clock skew between processes and the database never reopens a solution.
+        await db.execute(sql `
+      DELETE FROM access_link_check_spent WHERE ctid IN (
+        SELECT ctid FROM access_link_check_spent WHERE expires_at < now() - interval '1 hour' LIMIT ${PRUNE_BATCH})`);
+        return issuePass(code);
+    }
+    const check = ({ link, proof }) => {
+        if (typeof proof !== 'string')
+            return Promise.resolve(false);
+        const parts = proof.split('.');
+        const [body, mac] = parts;
+        if (parts.length !== 2 || body === undefined || mac === undefined)
+            return Promise.resolve(false);
+        const expected = createHmac('sha256', passKey).update(body).digest();
+        if (!sameBytes(Buffer.from(mac, 'base64url'), expected))
+            return Promise.resolve(false);
+        try {
+            const claims = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+            return Promise.resolve(typeof claims.exp === 'number' && claims.exp > Date.now() && claims.code === link.code);
+        }
+        catch {
+            return Promise.resolve(false);
+        }
+    };
+    return { challenge, verify, check };
+}
+/** Solves a challenge the way the widget does and returns its base64 payload. For tests: it does the work the browser would. */
+function solvePersonChallenge(c) {
+    for (let n = 0; n <= c.maxnumber; n++) {
+        if (sha256Hex(c.salt + String(n)) === c.challenge) {
+            const payload = { algorithm: c.algorithm, challenge: c.challenge, number: n, salt: c.salt, signature: c.signature, took: 0 };
+            return Buffer.from(JSON.stringify(payload)).toString('base64');
+        }
+    }
+    throw new Error('personCheck.solve: challenge has no solution');
+}
+export const personCheck = Object.assign(createPersonCheck, { solve: solvePersonChallenge });
+//# sourceMappingURL=person-check.js.map

package/dist/infra/access-links/person-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"person-check.js","sourceRoot":"","sources":["../../../src/infra/access-links/person-check.ts"],"names":[],"mappings":"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"}

package/dist/infra/access-links/schema.d.ts

@@ -124,4 +124,12 @@ export declare const accessLinkUse: import("../../data/domain/types.js").Defined
         nullable: true;
     }>;
 }, "access_link_use">;
+export declare const accessLinkCheckSpent: import("../../data/domain/types.js").DefinedTable<{
+    challenge: import("../../data/domain/types.js").FieldDescriptor<string, {
+        primaryKey: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string, {
+        primaryKey: true;
+    }>;
+    expiresAt: import("../../data/domain/types.js").FieldDescriptor<Date, {}> & import("../../data/domain/field.js").FieldModifiers<Date, {}>;
+}, "access_link_check_spent">;
 //# sourceMappingURL=schema.d.ts.map

package/dist/infra/access-links/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,wBAAwB,gDAAiD,CAAA;AAEtF,eAAO,MAAM,cAAc;;;;;;;;;;;;;sBAKzB,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBrB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiBxB,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,wBAAwB,gDAAiD,CAAA;AAEtF,eAAO,MAAM,cAAc;;;;;;;;;;;;;sBAKzB,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBrB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiBxB,CAAA;AAIF,eAAO,MAAM,oBAAoB;;;;;;;6BAG/B,CAAA"}

package/dist/infra/access-links/schema.js

@@ -1,4 +1,4 @@
-// The three tables behind access links. `access_link_code` is deliberately NOT
+// The four tables behind access links. `access_link_code` is deliberately NOT
 // tenant-scoped: it maps a code to its tenant so a request with no tenant can
 // find where to look, and holds nothing else. `access_link` and
 // `access_link_use` carry a `.tenant()` key, so generated migrations put them
@@ -49,4 +49,10 @@ export const accessLinkUse = define('access_link_use', {
         byLink: index('idx_access_link_use_link').on(t['linkId'], t['status']),
     }),
 });
+// Person-check solutions already accepted, kept until the challenge has expired:
+// one solved challenge makes one pass, across processes. Not tenant-scoped.
+export const accessLinkCheckSpent = define('access_link_check_spent', {
+    challenge: field.text().primaryKey(),
+    expiresAt: field.timestamp(),
+});
 //# sourceMappingURL=schema.js.map

package/dist/infra/access-links/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"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"}

package/dist/infra/alerts/audit.d.ts

@@ -0,0 +1,3 @@
+/** Writes an `Alert` audit record under the Flow's open trace step; does nothing when no step is open. */
+export declare function auditAlert(verb: string, key: string, details: Record<string, unknown>, database?: string): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/infra/alerts/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/infra/alerts/audit.ts"],"names":[],"mappings":"AAMA,0GAA0G;AAC1G,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9H"}

package/dist/infra/alerts/audit.js

@@ -0,0 +1,25 @@
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+import { getContext } from '../../request/context/store.js';
+import { resolveActorId } from '../../data/write/audit/actor.js';
+import { getBaseLogger } from '../../core/logging/index.js';
+/** Writes an `Alert` audit record under the Flow's open trace step; does nothing when no step is open. */
+export async function auditAlert(verb, key, details, database) {
+    const flow = getContext();
+    const trace = flow?.trace;
+    const stepId = trace?.buffer.openStepId ?? null;
+    if (flow === undefined || trace === undefined || trace === null || stepId === null)
+        return;
+    try {
+        await pipeSystem(database).execute(sql `
+      INSERT INTO audit_record
+        (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
+      VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${flow.tenant}, ${resolveActorId(flow)},
+        'Alert', ${verb}, ${key}, ${JSON.stringify(details)}::jsonb, now())
+    `);
+    }
+    catch (err) {
+        getBaseLogger().error({ err, traceId: trace.id }, `Failed to write the alert ${verb} audit record`);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/infra/alerts/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/infra/alerts/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,GAAW,EAAE,OAAgC,EAAE,QAAiB;IAC7G,MAAM,IAAI,GAAG,UAAU,EAAE,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,CAAA;IACzB,MAAM,MAAM,GAAG,KAAK,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAA;IAC/C,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAM;IAC1F,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA;;;gBAG1B,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,EAAE,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC;mBAC7E,IAAI,KAAK,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KACtD,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,aAAa,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,6BAA6B,IAAI,eAAe,CAAC,CAAA;IACrG,CAAC;AACH,CAAC"}

package/dist/infra/alerts/handle.d.ts

@@ -0,0 +1,95 @@
+import type { Queue } from '../../async/jobs/queue.js';
+import type { Handler } from '../../request/di/types.js';
+import type { AlertPayload, AlertSink } from './sinks.js';
+import type { AlertSource } from './sources.js';
+export type AlertSeverity = 'info' | 'warning' | 'error' | 'critical';
+export interface AlertSubject {
+    readonly tenantId?: string;
+    readonly entity?: string;
+    readonly entityId?: string;
+}
+export interface AlertsConfig {
+    /** Where alerts are sent. At least one; names must be unique. */
+    readonly sinks: readonly AlertSink[];
+    /** The queue the alerts job runs on; its worker surface must run `handle.job`. */
+    readonly queue: Pick<Queue, 'enqueue'>;
+    /** Job type of `handle.job`; default `'pipework.alerts'`. */
+    readonly jobType?: string;
+    /** Send again while an alert stays open and is raised again after this long since the last send. Default `null`: never. */
+    readonly resendAfterMs?: number | null;
+    /** Resolve an open alert nobody raised for this long, on the job's tick. Default `null`: only `resolve`. */
+    readonly resolveAfterQuietMs?: number | null;
+    /** Delivery attempts before a row is given up on; default 10. */
+    readonly maxAttempts?: number;
+    /** First retry delay, doubling per attempt up to one hour; default 5000. */
+    readonly backoffMs?: number;
+    readonly sources?: readonly AlertSource[];
+    /** Database holding the alert tables; default the default database. */
+    readonly database?: string;
+}
+export interface RaiseOptions {
+    readonly severity: AlertSeverity;
+    readonly message: string;
+    readonly subject?: AlertSubject;
+    /** Overrides the handle's `resendAfterMs` for this alert. */
+    readonly resendAfterMs?: number;
+    /** Overrides the handle's `resolveAfterQuietMs` for this alert. */
+    readonly resolveAfterQuietMs?: number;
+}
+export interface Alert {
+    readonly key: string;
+    readonly status: 'open' | 'resolved';
+    readonly severity: AlertSeverity;
+    readonly message: string;
+    readonly subject: AlertSubject | null;
+    readonly count: number;
+    readonly firstSeenAt: Date;
+    readonly lastSeenAt: Date;
+    readonly lastSentAt: Date | null;
+    readonly resolvedAt: Date | null;
+    /** Latest ten traces that raised it, newest first. */
+    readonly traceIds: readonly string[];
+}
+export interface DeliveryRow {
+    readonly id: string;
+    readonly key: string;
+    readonly kind: 'raise' | 'repeat' | 'resolve';
+    readonly sink: string;
+    readonly payload: AlertPayload;
+    readonly attempts: number;
+    readonly nextAttemptAt: Date;
+    readonly deliveredAt: Date | null;
+    readonly failedAt: Date | null;
+    readonly lastError: string | null;
+}
+export interface TickResult {
+    /** Alerts resolved because nobody raised them for their quiet period, or because a source cleared them. */
+    readonly resolved: number;
+    readonly delivered: number;
+    /** Attempts that failed and will be retried. */
+    readonly retried: number;
+    /** Deliveries given up on. */
+    readonly failed: number;
+}
+export interface Alerts {
+    /**
+     * Raises the condition `key`. Not open: opens it and sends once. Open: groups it (count, last seen, trace id)
+     * and sends nothing, unless `resendAfterMs` has passed since the last send. Needs a Flow.
+     */
+    raise(key: string, options: RaiseOptions): Promise<{
+        status: 'opened' | 'grouped' | 'resent';
+    }>;
+    /** Resolves an open alert and sends `resolve` once. Not open: false, nothing sent. */
+    resolve(key: string): Promise<boolean>;
+    /** The job to add to a worker surface's `jobs` (and schedule, e.g. every minute): auto-resolve, sources, deliveries. */
+    readonly job: Handler<Record<string, unknown>, unknown>;
+    /** What one run of `job` does; callable from a test. Needs a Flow. */
+    tick(): Promise<TickResult>;
+    open(): Promise<Alert[]>;
+    get(key: string): Promise<Alert | null>;
+    deliveries(options?: {
+        key?: string;
+    }): Promise<DeliveryRow[]>;
+}
+export declare function createAlerts(config: AlertsConfig): Alerts;
+//# sourceMappingURL=handle.d.ts.map

package/dist/infra/alerts/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../../src/infra/alerts/handle.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAGxD,OAAO,KAAK,EAAiB,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;AAErE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,2HAA2H;IAC3H,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,4GAA4G;IAC5G,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IACzC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAA;IAChC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;KAAE,CAAC,CAAA;IAC/F,sFAAsF;IACtF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,wHAAwH;IACxH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAA;IACvD,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3B,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IACvC,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;CAC/D;AAsDD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+OzD"}

package/dist/infra/alerts/handle.js

@@ -0,0 +1,301 @@
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+import { fitting } from '../../request/di/index.js';
+import { getContext } from '../../request/context/store.js';
+import { getBaseLogger } from '../../core/logging/index.js';
+import { __flowStep } from '../../trace/runtime/flow-step.js';
+import { auditAlert } from './audit.js';
+const SEND_TIMEOUT_MS = 10_000;
+const LEASE_MS = 30_000;
+const BATCH = 50;
+const MAX_BATCHES = 20;
+const MAX_BACKOFF_MS = 3_600_000;
+const SEVERITIES = new Set(['info', 'warning', 'error', 'critical']);
+function toAlert(row) {
+    const date = (v) => new Date(v);
+    const dateOrNull = (v) => (v === null || v === undefined ? null : date(v));
+    return {
+        key: row['key'],
+        status: row['status'],
+        severity: row['severity'],
+        message: row['message'],
+        subject: (row['subject'] ?? null),
+        count: Number(row['count']),
+        firstSeenAt: date(row['first_seen_at']),
+        lastSeenAt: date(row['last_seen_at']),
+        lastSentAt: dateOrNull(row['last_sent_at']),
+        resolvedAt: dateOrNull(row['resolved_at']),
+        traceIds: (row['trace_ids'] ?? []),
+    };
+}
+function toDeliveryRow(row) {
+    return {
+        id: row['id'],
+        key: row['alert_key'],
+        kind: row['kind'],
+        sink: row['sink'],
+        payload: row['payload'],
+        attempts: Number(row['attempts']),
+        nextAttemptAt: new Date(row['next_attempt_at']),
+        deliveredAt: row['delivered_at'] === null ? null : new Date(row['delivered_at']),
+        failedAt: row['failed_at'] === null ? null : new Date(row['failed_at']),
+        lastError: (row['last_error'] ?? null),
+    };
+}
+function pgTextArray(values) {
+    return `{${values.map(v => `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(',')}}`;
+}
+function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`sink did not answer within ${String(ms)} ms`)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => { clearTimeout(timer); });
+}
+export function createAlerts(config) {
+    if (config.sinks.length === 0)
+        throw new Error('[pipework] alerts.create needs at least one sink.');
+    const sinks = new Map();
+    for (const s of config.sinks) {
+        if (sinks.has(s.name))
+            throw new Error(`[pipework] alerts.create: two sinks are named "${s.name}"; give each its own name.`);
+        sinks.set(s.name, s);
+    }
+    const sinkNames = pgTextArray([...sinks.keys()]);
+    const jobType = config.jobType ?? 'pipework.alerts';
+    const maxAttempts = config.maxAttempts ?? 10;
+    const backoffMs = config.backoffMs ?? 5000;
+    const defaultResend = config.resendAfterMs ?? null;
+    const defaultQuiet = config.resolveAfterQuietMs ?? null;
+    const sources = config.sources ?? [];
+    const database = config.database;
+    const log = getBaseLogger();
+    const db = () => pipeSystem(database);
+    // The alert and its deliveries move in one statement, so a crash cannot leave one without the other.
+    const payloadSql = (kind) => sql `jsonb_build_object(
+    'kind', ${kind}, 'key', up.key, 'severity', up.severity, 'message', up.message, 'subject', up.subject,
+    'count', up.count, 'firstSeenAt', up.first_seen_at, 'lastSeenAt', up.last_seen_at,
+    'resolvedAt', up.resolved_at, 'traceIds', to_jsonb(up.trace_ids))`;
+    async function enqueueJob() {
+        await config.queue.enqueue(db(), { type: jobType, payload: {}, continueFlow: true });
+    }
+    // Inside a tick the deliveries are sent by that same tick, so it does not enqueue another.
+    async function raise(key, options, enqueue = true) {
+        if (key.trim() === '')
+            throw new Error('[pipework] alerts.raise needs a non-empty key.');
+        if (!SEVERITIES.has(options.severity))
+            throw new Error(`[pipework] alerts.raise: severity must be info, warning, error or critical, got "${String(options.severity)}".`);
+        const traceId = getContext()?.trace?.id ?? null;
+        const traceArray = traceId === null ? '{}' : pgTextArray([traceId]);
+        const subject = options.subject === undefined ? null : JSON.stringify(options.subject);
+        const rows = await db().execute(sql `
+      WITH up AS (
+        INSERT INTO pipework_alerts AS a
+          (key, status, severity, message, subject, count, first_seen_at, last_seen_at, last_sent_at,
+           trace_ids, resend_after_ms, resolve_after_quiet_ms, updated_at)
+        SELECT ${key}, 'open', ${options.severity}, ${options.message}, ${subject}::jsonb, 1, c.ts, c.ts, c.ts,
+               ${traceArray}::text[], ${options.resendAfterMs ?? null}::int, ${options.resolveAfterQuietMs ?? null}::int, c.ts
+        FROM (SELECT clock_timestamp() AS ts) c
+        ON CONFLICT (key) DO UPDATE SET
+          status = 'open',
+          severity = EXCLUDED.severity,
+          message = EXCLUDED.message,
+          subject = EXCLUDED.subject,
+          count = CASE WHEN a.status = 'resolved' THEN 1 ELSE a.count + 1 END,
+          first_seen_at = CASE WHEN a.status = 'resolved' THEN EXCLUDED.first_seen_at ELSE a.first_seen_at END,
+          last_seen_at = EXCLUDED.last_seen_at,
+          resolved_at = NULL,
+          trace_ids = CASE
+            WHEN a.status = 'resolved' THEN EXCLUDED.trace_ids
+            WHEN ${traceId}::text IS NULL THEN a.trace_ids
+            ELSE (EXCLUDED.trace_ids || array_remove(a.trace_ids, ${traceId}::text))[1:10] END,
+          resend_after_ms = COALESCE(EXCLUDED.resend_after_ms, CASE WHEN a.status = 'resolved' THEN NULL ELSE a.resend_after_ms END),
+          resolve_after_quiet_ms = COALESCE(EXCLUDED.resolve_after_quiet_ms, CASE WHEN a.status = 'resolved' THEN NULL ELSE a.resolve_after_quiet_ms END),
+          last_sent_at = CASE
+            WHEN a.status = 'resolved' OR a.last_sent_at IS NULL THEN EXCLUDED.last_sent_at
+            WHEN COALESCE(EXCLUDED.resend_after_ms, a.resend_after_ms, ${defaultResend}::int) IS NOT NULL
+             AND EXCLUDED.last_sent_at - a.last_sent_at
+                 >= COALESCE(EXCLUDED.resend_after_ms, a.resend_after_ms, ${defaultResend}::int) * interval '1 millisecond'
+              THEN EXCLUDED.last_sent_at
+            ELSE a.last_sent_at END,
+          updated_at = EXCLUDED.updated_at
+        RETURNING a.*, (a.last_sent_at = a.last_seen_at) AS sent
+      ),
+      dels AS (
+        INSERT INTO pipework_alert_deliveries (alert_key, kind, sink, payload, created_at, next_attempt_at)
+        SELECT up.key, CASE WHEN up.count = 1 THEN 'raise' ELSE 'repeat' END, s.sink,
+               ${payloadSql(sql `CASE WHEN up.count = 1 THEN 'raise' ELSE 'repeat' END`)}, clock_timestamp(), clock_timestamp()
+        FROM up CROSS JOIN unnest(${sinkNames}::text[]) AS s(sink)
+        WHERE up.sent
+        RETURNING id
+      )
+      SELECT up.*, (SELECT count(*) FROM dels)::int AS queued FROM up`);
+        const row = rows[0];
+        const alert = toAlert(row);
+        const sent = row['sent'] === true;
+        const status = !sent ? 'grouped' : alert.count === 1 ? 'opened' : 'resent';
+        await auditAlert(status === 'opened' ? 'raise' : 'group', key, {
+            status, severity: alert.severity, count: alert.count, message: alert.message,
+        }, database);
+        if (sent && enqueue)
+            await enqueueJob();
+        return { status };
+    }
+    async function resolveKey(key, onlyIfQuiet, enqueue = true) {
+        const rows = await db().execute(sql `
+      WITH up AS (
+        UPDATE pipework_alerts SET status = 'resolved', resolved_at = clock_timestamp(), updated_at = clock_timestamp()
+        WHERE key = ${key} AND status = 'open'
+          AND (NOT ${onlyIfQuiet} OR last_seen_at < clock_timestamp()
+               - COALESCE(resolve_after_quiet_ms, ${defaultQuiet}::int) * interval '1 millisecond')
+        RETURNING *
+      ),
+      dels AS (
+        INSERT INTO pipework_alert_deliveries (alert_key, kind, sink, payload, created_at, next_attempt_at)
+        SELECT up.key, 'resolve', s.sink, ${payloadSql(sql `'resolve'`)}, clock_timestamp(), clock_timestamp()
+        FROM up CROSS JOIN unnest(${sinkNames}::text[]) AS s(sink)
+        RETURNING id
+      )
+      SELECT up.*, (SELECT count(*) FROM dels)::int AS queued FROM up`);
+        if (rows.length === 0)
+            return false;
+        const alert = toAlert(rows[0]);
+        await auditAlert('resolve', key, { count: alert.count, auto: onlyIfQuiet }, database);
+        if (enqueue)
+            await enqueueJob();
+        return true;
+    }
+    async function autoResolve() {
+        if (defaultQuiet === null) {
+            const any = await db().execute(sql `SELECT 1 FROM pipework_alerts WHERE status = 'open' AND resolve_after_quiet_ms IS NOT NULL LIMIT 1`);
+            if (any.length === 0)
+                return 0;
+        }
+        const due = await db().execute(sql `
+      SELECT key FROM pipework_alerts
+      WHERE status = 'open'
+        AND last_seen_at < clock_timestamp() - COALESCE(resolve_after_quiet_ms, ${defaultQuiet}::int) * interval '1 millisecond'`);
+        let resolved = 0;
+        for (const row of due)
+            if (await resolveKey(row['key'], true, false))
+                resolved++;
+        return resolved;
+    }
+    async function runSources() {
+        let resolved = 0;
+        for (const source of sources) {
+            let conditions;
+            try {
+                conditions = await source.evaluate();
+            }
+            catch (err) {
+                log.error({ err, source: source.name }, 'alert source failed');
+                continue;
+            }
+            for (const c of conditions) {
+                await raise(c.key, { severity: c.severity, message: c.message, ...(c.subject !== undefined ? { subject: c.subject } : {}) }, false);
+            }
+            if (source.owns === undefined)
+                continue;
+            const live = new Set(conditions.map(c => c.key));
+            const opened = await db().execute(sql `SELECT key FROM pipework_alerts WHERE status = 'open'`);
+            for (const row of opened) {
+                const key = row['key'];
+                if (source.owns(key) && !live.has(key) && await resolveKey(key, false, false))
+                    resolved++;
+            }
+        }
+        return resolved;
+    }
+    // Leases the due rows by pushing next_attempt_at out, so no row lock is held across a send. A row is
+    // due only if no older undelivered row of the same alert and sink exists: a resolve never overtakes its raise.
+    async function claimDue(dueBefore) {
+        return [...await db().execute(sql `
+      UPDATE pipework_alert_deliveries SET next_attempt_at = clock_timestamp() + ${LEASE_MS} * interval '1 millisecond'
+      WHERE id IN (
+        SELECT d.id FROM pipework_alert_deliveries d
+        WHERE d.delivered_at IS NULL AND d.failed_at IS NULL AND d.next_attempt_at <= ${dueBefore}::timestamptz
+          AND NOT EXISTS (
+            SELECT 1 FROM pipework_alert_deliveries o
+            WHERE o.alert_key = d.alert_key AND o.sink = d.sink AND o.delivered_at IS NULL AND o.failed_at IS NULL
+              AND (o.created_at, o.id) < (d.created_at, d.id))
+        ORDER BY d.next_attempt_at LIMIT ${BATCH} FOR UPDATE OF d SKIP LOCKED)
+      RETURNING *`)];
+    }
+    async function deliverBatch(batch, totals) {
+        await Promise.all(batch.map(async (row) => {
+            const id = row['id'];
+            const key = row['alert_key'];
+            const sinkName = row['sink'];
+            const kind = row['kind'];
+            const attempt = Number(row['attempts']) + 1;
+            const sink = sinks.get(sinkName);
+            let error = null;
+            if (sink === undefined) {
+                error = `sink "${sinkName}" is not configured`;
+            }
+            else {
+                try {
+                    await withTimeout(sink.send({ id, kind, key, sink: sinkName, payload: row['payload'], attempt }), SEND_TIMEOUT_MS);
+                }
+                catch (err) {
+                    error = err instanceof Error ? err.message : String(err);
+                }
+            }
+            if (error === null) {
+                await db().execute(sql `UPDATE pipework_alert_deliveries SET delivered_at = clock_timestamp(), attempts = ${attempt}, last_error = NULL WHERE id = ${id}::uuid`);
+                await auditAlert('deliver', key, { sink: sinkName, kind, attempt }, database);
+                totals.delivered++;
+            }
+            else if (sink === undefined || attempt >= maxAttempts) {
+                await db().execute(sql `UPDATE pipework_alert_deliveries SET failed_at = clock_timestamp(), attempts = ${attempt}, last_error = ${error} WHERE id = ${id}::uuid`);
+                log.error({ key, sink: sinkName, kind, attempt, error }, 'alert delivery given up');
+                await auditAlert('deliver-failed', key, { sink: sinkName, kind, attempt, error }, database);
+                totals.failed++;
+            }
+            else {
+                const delay = Math.min(backoffMs * 2 ** (attempt - 1), MAX_BACKOFF_MS);
+                await db().execute(sql `UPDATE pipework_alert_deliveries SET attempts = ${attempt}, last_error = ${error},
+          next_attempt_at = clock_timestamp() + ${delay} * interval '1 millisecond' WHERE id = ${id}::uuid`);
+                totals.retried++;
+            }
+        }));
+    }
+    async function runTick() {
+        const totals = { delivered: 0, retried: 0, failed: 0 };
+        let resolved = await autoResolve();
+        resolved += await runSources();
+        // Rows that fail during this tick wait for the next one, however short their backoff.
+        const dueBefore = String((await db().execute(sql `SELECT clock_timestamp()::text AS t`))[0]['t']);
+        for (let i = 0; i < MAX_BATCHES; i++) {
+            const batch = await claimDue(dueBefore);
+            if (batch.length === 0)
+                break;
+            await deliverBatch(batch, totals);
+        }
+        return { resolved, ...totals };
+    }
+    const tickStep = __flowStep({ ref: 'pipework/alerts:tick' }, runTick);
+    const job = fitting.use().job(jobType).fit(async () => tickStep());
+    return {
+        raise: (key, options) => raise(key, options),
+        resolve: key => resolveKey(key, false),
+        job: job,
+        tick: () => tickStep(),
+        async open() {
+            const rows = await db().execute(sql `SELECT * FROM pipework_alerts WHERE status = 'open' ORDER BY first_seen_at, key`);
+            return rows.map(toAlert);
+        },
+        async get(key) {
+            const rows = await db().execute(sql `SELECT * FROM pipework_alerts WHERE key = ${key}`);
+            return rows[0] === undefined ? null : toAlert(rows[0]);
+        },
+        async deliveries(options = {}) {
+            const rows = options.key === undefined
+                ? await db().execute(sql `SELECT * FROM pipework_alert_deliveries ORDER BY created_at, id`)
+                : await db().execute(sql `SELECT * FROM pipework_alert_deliveries WHERE alert_key = ${options.key} ORDER BY created_at, id`);
+            return rows.map(toDeliveryRow);
+        },
+    };
+}
+//# sourceMappingURL=handle.js.map