@marktiderman/genesis-notifications 0.0.0-stage → 0.1.0

package/dist/runner.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `@marktiderman/genesis-notifications/runner`: the one outbox runner. Claim a
+ * batch of due jobs, send them (grouped, so a destination that takes many at
+ * once gets one request), and record what happened. No dependencies.
+ *
+ * The store is the caller's (a SQL outbox claimed with SKIP LOCKED, a
+ * queue): `claim` hands over leased jobs and `record` takes back outcomes.
+ * The runner owns the rest: turning each send result into an outcome with a
+ * retry time, jittered backoff, the deferral cap, and never throwing for one
+ * job's failure. The notifier's push and email channels run on it, and so do
+ * genesis-forms' destinations (Sheets, webhooks), each with its own claim.
+ *
+ * Outcomes:
+ * - `sent`: delivered (or already there, on a redelivery: `alreadyThere`).
+ * - `filtered`: the sender decided it doesn't apply; nothing sent, nothing to retry.
+ * - `skipped`: deliberately not sent (`notSent`: a reason safe to store); never retried.
+ * - `retry`: a retryable failure. With the service's own Retry-After it is
+ *   deferred without counting an attempt (`counted: false`), until
+ *   `maxDeferrals`; otherwise it backs off by attempt (`counted: true`), until
+ *   `maxAttempts`.
+ * - `failed`: permanent, or out of attempts. With `disable: true` the receiver
+ *   asked to be switched off (a 410 Gone): stop sending to it.
+ *
+ * It never logs content, addresses or secrets: only what `label` gives and
+ * the senders' safe error messages.
+ *
+ * @packageDocumentation
+ */
+/** One claimed job. Extend it with what your sender needs. */
+interface RunnerJob {
+    /** Stable across retries (an idempotency key is made from it). */
+    id: string;
+    /** This attempt's number, from 1. */
+    attempt: number;
+    /** Deferrals so far (outcomes with `counted: false`); pass it back so `maxDeferrals` holds. Default 0. */
+    deferrals?: number | undefined;
+    /** An earlier attempt may have gone through (its lease ran out): senders that can look first do. */
+    redelivery?: boolean | undefined;
+}
+/** What a sender says about one job. */
+type JobResult = {
+    ok: true;
+    /** Deliberately sent nothing; the reason, safe to store. Recorded as `skipped`. */
+    notSent?: string | undefined;
+    /** It was already there (a redelivery), so nothing was sent this time. */
+    alreadyThere?: boolean | undefined;
+} | JobFailure;
+interface JobFailure {
+    ok: false;
+    /** The same request may succeed later (rate limited, the service down, a timeout). */
+    retryable: boolean;
+    /** The service said when to come back: retry after this many seconds, without counting an attempt. */
+    retryAfterSeconds?: number | undefined;
+    status?: number | undefined;
+    /** The receiver asked to be switched off. Always with `retryable: false`. */
+    disable?: true | undefined;
+    /** Safe to store and log: never secrets, content or addresses. */
+    error: string;
+}
+type JobOutcome = {
+    status: "sent";
+    alreadyThere?: boolean;
+} | {
+    status: "filtered";
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "retry";
+    error: string;
+    retryAt: Date;
+    retryAfterSeconds: number;
+    /** Whether this attempt counts toward `maxAttempts`. False when the service said when to come back. */
+    counted: boolean;
+    httpStatus?: number;
+} | {
+    status: "failed";
+    error: string;
+    httpStatus?: number;
+    disable?: true;
+};
+interface RunReport {
+    claimed: number;
+    sent: number;
+    filtered: number;
+    skipped: number;
+    /** Retryable failures, backed off by attempt. */
+    retrying: number;
+    /** Retryable failures the service said when to retry; no attempt used. */
+    deferred: number;
+    failed: number;
+    /** Recorded after the claim was lost (`record` resolved false). */
+    stale: number;
+    /** `record` threw. */
+    unrecorded: number;
+}
+interface ClaimRequest<Filter> {
+    limit: number;
+    filter?: Filter | undefined;
+}
+interface SendContext {
+    signal?: AbortSignal | undefined;
+}
+interface RunnerOptions<J extends RunnerJob, Filter = undefined> {
+    /** Claims up to `limit` due jobs, each leased so no other runner sends it meanwhile. */
+    claim(request: ClaimRequest<Filter>): Promise<readonly J[]>;
+    /**
+     * Sends one group of jobs (those with the same `group` key) and resolves one
+     * result per job, in order, or `"filtered"`. A throw fails the whole group
+     * with a retryable error.
+     */
+    send(group: readonly J[], context: SendContext): Promise<readonly (JobResult | "filtered")[]>;
+    /** Jobs with the same key are sent together. Default: each job alone. */
+    group?: ((job: J) => string) | undefined;
+    /**
+     * Records an outcome. Resolve `false` when the claim was no longer held: it
+     * is counted as stale. A rejection is counted as unrecorded; the lease runs
+     * out and the job comes back on its own.
+     */
+    record(job: J, outcome: JobOutcome): Promise<void | boolean>;
+    now?: (() => number) | undefined;
+    /** Safe lines (ids, kinds, short reasons). Default: nothing is logged. */
+    log?: ((message: string) => void) | undefined;
+    /** How a job is named in a log line, capitalised ("Delivery d1 (email)"). Default `Job <id>`. */
+    label?: ((job: J) => string) | undefined;
+    /** How a job is named when recording it failed ("delivery d1"). Default `job <id>`. */
+    recordLabel?: ((job: J) => string) | undefined;
+    /** Jobs claimed per run. Default 25. */
+    batchSize?: number | undefined;
+    /** Counted attempts before a retryable failure is given up. Default 8. */
+    maxAttempts?: number | undefined;
+    /** Deferrals allowed before a further one counts as an attempt. Default 24. */
+    maxDeferrals?: number | undefined;
+    /** Seconds to wait after a counted failed attempt. Default `defaultBackoff`. */
+    backoff?: ((attempt: number) => number) | undefined;
+}
+interface RunOptions<Filter> {
+    filter?: Filter | undefined;
+    /** Overrides `batchSize` for this run. */
+    limit?: number | undefined;
+    /** Aborts the sends in flight. */
+    signal?: AbortSignal | undefined;
+}
+interface Runner<Filter = undefined> {
+    /** One claim, its sends and their records. Never rejects for a job's failure; a failing `claim` rejects. */
+    run(options?: RunOptions<Filter>): Promise<RunReport>;
+}
+declare const DEFAULT_MAX_ATTEMPTS = 8;
+declare const DEFAULT_MAX_DEFERRALS = 24;
+declare const DEFAULT_BATCH_SIZE = 25;
+/**
+ * 5 minutes, quadrupling each attempt, at most 24 hours: 5m, 20m, 80m, 5h20m,
+ * 21h20m, then 24h; about 3 days across 8 attempts. Each wait is jittered by
+ * up to ±20%, so jobs that failed together don't all come back at once.
+ */
+declare function defaultBackoff(attempt: number, random?: () => number): number;
+/** Turns a send result into an outcome for a job on its `attempt`. */
+declare function jobOutcome(result: JobResult, attempt: number, options?: {
+    now?: number | undefined;
+    maxAttempts?: number | undefined;
+    backoff?: ((attempt: number) => number) | undefined;
+    deferrals?: number | undefined;
+    maxDeferrals?: number | undefined;
+}): JobOutcome;
+/** A thrown error as a retryable failure with a safe message. */
+declare function failureOf(error: unknown): JobFailure;
+/**
+ * The runner.
+ *
+ * @stability Beta
+ */
+declare function createRunner<J extends RunnerJob, Filter = undefined>(options: RunnerOptions<J, Filter>): Runner<Filter>;
+
+export { type ClaimRequest, DEFAULT_BATCH_SIZE, DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_DEFERRALS, type JobFailure, type JobOutcome, type JobResult, type RunOptions, type RunReport, type Runner, type RunnerJob, type RunnerOptions, type SendContext, createRunner, defaultBackoff, failureOf, jobOutcome };

package/dist/runner.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BATCH_SIZE, DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_DEFERRALS, createRunner, defaultBackoff, failureOf, jobOutcome } from './chunk-UXNWI7OS.js';
+//# sourceMappingURL=runner.js.map
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"runner.js"}