@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/queue.js

@@ -7,8 +7,10 @@
  * so it stays edge-safe.
  *
  *   class SendWelcome extends Job {
+ *     static maxRetries = 3;
  *     constructor(private userId: number) { super(); }
  *     async handle() { await mail().to(...).send(); }
+ *     async failed(error: unknown) { logger().error("welcome failed", { error }); }
  *   }
  *
  *   await dispatch(new SendWelcome(user.id));   // runs now with the sync driver
@@ -17,38 +19,248 @@
  *   setQueue(new MemoryDriver());
  *   await dispatch(new SendWelcome(user.id));   // queued
  *   await work();                               // runs everything pending
+ *
+ * A job that throws is **retried** with backoff up to `maxRetries`, and only then
+ * declared failed — at which point `failed()` runs and it lands in the driver's
+ * dead-letter list rather than vanishing.
+ */
+import { logger, hasApplication } from "./helpers.js";
+import { instrument, currentRequestId } from "./instrumentation.js";
+/**
+ * A unit of background work. Subclass and implement `handle`.
+ *
+ * Retry policy is per-class, via statics:
+ *
+ *   class ChargeCard extends Job {
+ *     static maxRetries = 5;
+ *     static backoff = exponentialBackoff(1_000);
+ *     async handle() { … }
+ *   }
  */
-/** A unit of background work. Subclass and implement `handle`. */
 export class Job {
+    /** How many times to retry after the first failure. Default: 0 (no retries). */
+    static maxRetries = 0;
+    /** How long to wait before each retry. Default: exponential from 1s. */
+    static backoff = exponentialBackoff(1_000);
+    /** Default lane for this job class. */
+    static queue;
+    /** Default priority for this job class (lower runs first). */
+    static priority;
+    /** Set by the driver before `handle()` runs. */
+    context;
+    /**
+     * Called once the job has exhausted its retries — the last chance to record
+     * the failure, alert, or compensate. A throw in here is logged and swallowed:
+     * failing to handle a failure must not itself crash the worker.
+     */
+    failed(_error) { }
+}
+/** Doubles each time: 1s, 2s, 4s, 8s… Capped at `maxMs`. */
+export function exponentialBackoff(baseMs = 1_000, maxMs = 60_000) {
+    return (attempt) => Math.min(baseMs * 2 ** (attempt - 1), maxMs);
+}
+/** Adds a fixed step each time: 5s, 10s, 15s… Capped at `maxMs`. */
+export function linearBackoff(stepMs = 1_000, maxMs = 60_000) {
+    return (attempt) => Math.min(stepMs * attempt, maxMs);
+}
+/** The same delay every time. */
+export function fixedBackoff(delayMs = 1_000) {
+    return () => delayMs;
+}
+/** No delay at all — retry straight away. */
+export const noBackoff = () => 0;
+/* ------------------------------- execution -------------------------------- */
+/** The retry policy for a dispatchable, from its class statics and any overrides. */
+function policy(job, options) {
+    const cls = job instanceof Job ? job.constructor : undefined;
+    return {
+        maxRetries: options.maxRetries ?? cls?.maxRetries ?? 0,
+        backoff: options.backoff ?? cls?.backoff ?? exponentialBackoff(1_000),
+    };
+}
+/** The display name of a dispatchable — its class name, or "fn" for a closure. */
+function jobName(job) {
+    return job instanceof Job ? job.constructor.name : "fn";
+}
+async function invoke(job, context) {
+    const name = jobName(job);
+    const requestId = currentRequestId();
+    const start = Date.now();
+    instrument("job.processing", {
+        job: name,
+        ...(job instanceof Job ? { payload: { ...job } } : {}),
+        ...(requestId ? { requestId } : {}),
+    });
+    if (typeof job === "function")
+        await job();
+    else {
+        job.context = context;
+        await job.handle();
+    }
+    instrument("job.processed", {
+        job: name,
+        durationMs: Date.now() - start,
+        ...(requestId ? { requestId } : {}),
+    });
+}
+/**
+ * Log through the application logger, falling back to the console. The queue is
+ * a primitive — it has to work in a worker that never bootstrapped an
+ * Application — and reporting a failure must never itself be the thing that
+ * throws.
+ */
+function log(message, context) {
+    if (hasApplication())
+        logger().error(message, context);
+    else
+        console.error(message, context);
 }
-function run(job) {
-    return Promise.resolve(job instanceof Job ? job.handle() : job());
+/**
+ * A job has exhausted its retries. Log it — loudly, because a worker that keeps
+ * running past a failure must not do so silently — then run the `failed()` hook.
+ * A throw in the hook is logged too, never rethrown: failing to handle a failure
+ * must not itself crash the worker.
+ */
+async function reportFailure(job, error, context) {
+    log("queue: job failed", {
+        job: jobName(job),
+        jobId: context.jobId,
+        attempts: context.attempt,
+        queue: context.queue,
+        error,
+    });
+    instrument("job.failed", { job: jobName(job), error });
+    if (!(job instanceof Job))
+        return;
+    try {
+        await job.failed(error);
+    }
+    catch (hookError) {
+        log("queue: a job's failed() hook threw", { error: hookError });
+    }
 }
 /* -------------------------------- drivers --------------------------------- */
-/** Runs jobs the moment they're dispatched — the default; ideal for dev/tests. */
+let counter = 0;
+function nextId() {
+    return `job_${++counter}`;
+}
+/**
+ * Runs jobs the moment they're dispatched — the default; ideal for dev/tests.
+ *
+ * Retries still apply, but the backoff delay is **not** slept through: an
+ * inline driver blocking the request for a 30-second backoff would be worse than
+ * useless. Use `MemoryDriver` or a real broker to exercise real delays.
+ */
 export class SyncDriver {
-    async push(job, _options) {
-        await run(job);
+    /** Jobs that exhausted their retries. */
+    failed = [];
+    async push(job, options) {
+        const { maxRetries } = policy(job, options);
+        const id = nextId();
+        const queue = options.queue ?? "default";
+        for (let attempt = 1;; attempt++) {
+            const context = { jobId: id, attempt, queue };
+            try {
+                await invoke(job, context);
+                return;
+            }
+            catch (error) {
+                if (attempt > maxRetries) {
+                    await reportFailure(job, error, context);
+                    this.failed.push({ id, job, options, attempts: attempt, error });
+                    // The sync driver *is* the work — it ran inline, so the caller gets the
+                    // error. A background driver can't do that; it records instead.
+                    throw error;
+                }
+            }
+        }
     }
 }
 /** Holds jobs in memory; `work()` drains them. Assert on `.jobs` in tests. */
 export class MemoryDriver {
     jobs = [];
+    /** Jobs that exhausted their retries. */
+    failed = [];
     async push(job, options) {
-        this.jobs.push({ job, options });
+        this.jobs.push({
+            id: nextId(),
+            job,
+            options,
+            attempts: 0,
+            availableAt: Date.now() + (options.delay ?? 0) * 1000,
+        });
     }
     get size() {
         return this.jobs.length;
     }
-    /** Run every pending job in FIFO order; returns how many ran. */
+    /** The next job that's due, by priority then insertion order. */
+    takeNext(now) {
+        let best = -1;
+        for (let i = 0; i < this.jobs.length; i++) {
+            const candidate = this.jobs[i];
+            if (candidate.availableAt > now)
+                continue; // not due yet
+            if (best === -1) {
+                best = i;
+                continue;
+            }
+            const incumbent = this.jobs[best];
+            if ((candidate.options.priority ?? 0) < (incumbent.options.priority ?? 0))
+                best = i;
+        }
+        return best === -1 ? undefined : this.jobs.splice(best, 1)[0];
+    }
+    /**
+     * Run every job that's currently due, highest priority first; returns how many
+     * ran. A job that throws is re-queued with its backoff delay until it runs out
+     * of retries, then moves to `failed`.
+     *
+     * Jobs whose delay or backoff hasn't elapsed are left in place — `work()`
+     * drains what's *due*, it doesn't sleep. Call it again later, or advance your
+     * test's clock.
+     */
     async work() {
         let count = 0;
-        while (this.jobs.length) {
-            const next = this.jobs.shift();
-            await run(next.job);
-            count++;
+        for (;;) {
+            const now = Date.now();
+            const next = this.takeNext(now);
+            if (!next)
+                return count;
+            const { maxRetries, backoff } = policy(next.job, next.options);
+            const attempt = next.attempts + 1;
+            const context = {
+                jobId: next.id,
+                attempt,
+                queue: next.options.queue ?? "default",
+            };
+            try {
+                await invoke(next.job, context);
+                count++;
+            }
+            catch (error) {
+                if (attempt > maxRetries) {
+                    // A failed job must not take down the worker — record it, log it, and
+                    // carry on with the rest of the queue.
+                    await reportFailure(next.job, error, context);
+                    this.failed.push({
+                        id: next.id,
+                        job: next.job,
+                        options: next.options,
+                        attempts: attempt,
+                        error,
+                    });
+                }
+                else {
+                    // Back on the queue, not runnable until the backoff has elapsed.
+                    this.jobs.push({
+                        ...next,
+                        attempts: attempt,
+                        availableAt: Date.now() + backoff(attempt),
+                    });
+                }
+                count++;
+            }
         }
-        return count;
     }
 }
 /* --------------------------------- queue ---------------------------------- */
@@ -59,16 +271,93 @@ export class Queue {
     }
     /** Place a job on the queue (the driver decides when it runs). */
     async dispatch(job, options = {}) {
-        await this.driver.push(job, options);
+        const cls = job instanceof Job ? job.constructor : undefined;
+        await this.driver.push(job, {
+            ...options,
+            queue: options.queue ?? cls?.queue ?? "default",
+            priority: options.priority ?? cls?.priority ?? 0,
+        });
     }
     /** Drain the driver if it holds jobs locally; returns how many ran. */
     async work() {
         const drainable = this.driver;
         return typeof drainable.work === "function" ? drainable.work() : 0;
     }
+    /** Jobs that exhausted their retries, if the driver tracks them. */
+    get failed() {
+        return this.driver.failed ?? [];
+    }
+}
+/* --------------------------------- faking --------------------------------- */
+/**
+ * A driver that records dispatches without running anything, plus assertions —
+ * what `fakeQueue()` installs so a test can check a job was *queued* without
+ * paying for it to run.
+ */
+export class FakeQueue extends Queue {
+    pushed = [];
+    constructor() {
+        const pushed = [];
+        super({
+            async push(job, options) {
+                pushed.push({
+                    id: nextId(),
+                    job,
+                    options,
+                    attempts: 0,
+                    availableAt: Date.now() + (options.delay ?? 0) * 1000,
+                });
+            },
+        });
+        this.pushed = pushed;
+    }
+    /** Dispatches of a job class (or all of them, with no argument). */
+    matching(type, where) {
+        return this.pushed.filter((entry) => {
+            if (type && !(entry.job instanceof type))
+                return false;
+            return where ? where(entry.job) : true;
+        });
+    }
+    assertPushed(type, where) {
+        if (this.matching(type, where).length)
+            return;
+        const total = this.pushed.filter((e) => e.job instanceof type).length;
+        throw new Error(where && total
+            ? `Expected a ${type.name} matching the predicate. ${total} were pushed, but none matched.`
+            : `Expected ${type.name} to be pushed, but it was not. ${this.summary()}`);
+    }
+    assertNotPushed(type, where) {
+        const found = this.matching(type, where).length;
+        if (found)
+            throw new Error(`Expected no ${type.name}, but ${found} were pushed.`);
+    }
+    assertPushedCount(expected, type) {
+        const found = this.matching(type).length;
+        if (found !== expected) {
+            const what = type ? `${type.name} job(s)` : "job(s)";
+            throw new Error(`Expected ${expected} ${what} to be pushed, but ${found} were.`);
+        }
+    }
+    assertNothingPushed() {
+        if (this.pushed.length) {
+            throw new Error(`Expected nothing to be pushed, but ${this.pushed.length} were. ${this.summary()}`);
+        }
+    }
+    /** The queued entry for a job class — to assert on its delay, lane, or priority. */
+    pushedJobs(type) {
+        return this.matching(type);
+    }
+    summary() {
+        if (!this.pushed.length)
+            return "Nothing was pushed.";
+        const names = [...new Set(this.pushed.map((e) => (e.job instanceof Job ? e.job.constructor.name : "fn")))];
+        return `Pushed: ${names.join(", ")}.`;
+    }
 }
 /* --------------------------------- global --------------------------------- */
 let queue = new Queue(new SyncDriver());
+let real;
 /** Register the default queue driver used by `dispatch()`. */
 export function setQueue(driver) {
     queue = new Queue(driver);
@@ -86,3 +375,25 @@ export function dispatch(job, options) {
 export function work() {
     return queue.work();
 }
+/**
+ * Swap the queue for one that records dispatches without running them, so a test
+ * can assert a job was queued without paying for it to run. Undo with
+ * `restoreQueue()`.
+ *
+ *   const q = fakeQueue();
+ *   await register(user);
+ *   q.assertPushed(SendWelcome, (job) => job.userId === user.id);
+ */
+export function fakeQueue() {
+    if (!real)
+        real = queue; // only remember the *real* queue — faking twice must not stash a fake
+    const fake = new FakeQueue();
+    queue = fake;
+    return fake;
+}
+/** Restore the real queue after `fakeQueue()`. */
+export function restoreQueue() {
+    if (real)
+        queue = real;
+    real = undefined;
+}

package/dist/core/repl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An interactive shell with the application booted — `keel repl`.
+ *
+ *   keel repl
+ *   > await db("users").get()
+ *   > make(Router).all()
+ *   > .ls
+ *
+ * The point is that everything is *already wired*: the container is booted, the
+ * providers have run, and the global helpers are in scope. Poking at a model in a
+ * REPL is the fastest debugging loop there is, and it shouldn't cost you a
+ * throwaway script to get one.
+ *
+ * `node:repl` is imported dynamically, so the core still loads on the edge (where
+ * there is, of course, no REPL to start).
+ */
+import type { Application } from "./application.js";
+/** A helper exposed in the REPL, listed by `.ls`. */
+export interface ReplHelper {
+    name: string;
+    description: string;
+    value: unknown;
+}
+/** Extra helpers to put in scope, beyond the defaults. */
+export interface ReplOptions {
+    helpers?: ReplHelper[];
+    /** The prompt string. Default: `"keel > "`. */
+    prompt?: string;
+}
+/**
+ * Start the REPL. Resolves when the user exits it.
+ */
+export declare function startRepl(app: Application, options?: ReplOptions): Promise<void>;

package/dist/core/repl.js

@@ -0,0 +1,88 @@
+/**
+ * An interactive shell with the application booted — `keel repl`.
+ *
+ *   keel repl
+ *   > await db("users").get()
+ *   > make(Router).all()
+ *   > .ls
+ *
+ * The point is that everything is *already wired*: the container is booted, the
+ * providers have run, and the global helpers are in scope. Poking at a model in a
+ * REPL is the fastest debugging loop there is, and it shouldn't cost you a
+ * throwaway script to get one.
+ *
+ * `node:repl` is imported dynamically, so the core still loads on the edge (where
+ * there is, of course, no REPL to start).
+ */
+/** The helpers every Keel REPL gets. */
+async function defaultHelpers(app) {
+    const core = await import("./index.js");
+    const helpers = [
+        { name: "app", description: "The booted Application", value: app },
+        { name: "config", description: "config(key, fallback?)", value: core.config },
+        { name: "make", description: "Resolve a binding from the container", value: core.make },
+        { name: "db", description: "Start a query: db('users').where(…)", value: core.db },
+        { name: "cache", description: "The cache", value: core.cache },
+        { name: "logger", description: "The logger", value: core.logger },
+        { name: "events", description: "The event emitter", value: core.events },
+        { name: "mail", description: "Start a message", value: core.mail },
+        { name: "dispatch", description: "Dispatch a job", value: core.dispatch },
+        { name: "storage", description: "The default disk", value: core.storage },
+        { name: "router", description: "The router", value: app.make(core.Router) },
+        { name: "hash", description: "Password hashing", value: core.hash },
+        { name: "jwt", description: "JWT sign/verify", value: core.jwt },
+        {
+            name: "p",
+            description: "Await a promise and print the result — p(db('users').get())",
+            value: async (value) => await value,
+        },
+    ];
+    return helpers;
+}
+/**
+ * Start the REPL. Resolves when the user exits it.
+ */
+export async function startRepl(app, options = {}) {
+    const [{ start }, { join }] = await Promise.all([import("node:repl"), import("node:path")]);
+    const helpers = [...(await defaultHelpers(app)), ...(options.helpers ?? [])];
+    const name = app.config().get("app.name", "Keel");
+    console.log(`⚓ ${name} — type .ls to see what's in scope, .exit to leave.\n`);
+    const server = start({
+        prompt: options.prompt ?? "keel > ",
+        useColors: true,
+        // Await at the top level, so `> await db("users").get()` just works.
+        useGlobal: false,
+        breakEvalOnSigint: true,
+    });
+    for (const helper of helpers) {
+        Object.defineProperty(server.context, helper.name, {
+            configurable: false,
+            enumerable: true,
+            value: helper.value,
+        });
+    }
+    // History, so the last thing you typed survives a restart.
+    try {
+        await new Promise((resolve) => {
+            server.setupHistory(join(app.basePath, ".keel_repl_history"), () => resolve());
+        });
+    }
+    catch {
+        // No history file — not worth failing the REPL over.
+    }
+    server.defineCommand("ls", {
+        help: "List everything in scope",
+        action() {
+            const width = Math.max(...helpers.map((h) => h.name.length));
+            for (const helper of helpers) {
+                console.log(`  ${helper.name.padEnd(width + 2)}${helper.description}`);
+            }
+            this.displayPrompt();
+        },
+    });
+    return new Promise((resolve) => {
+        server.on("exit", () => {
+            void app.terminate().finally(() => resolve());
+        });
+    });
+}

package/dist/core/scheduler.js

@@ -15,6 +15,7 @@
  * cron expression matches `now` (to the minute).
  */
 import { Job } from "./queue.js";
+import { instrument } from "./instrumentation.js";
 function runTask(job) {
     return Promise.resolve(job instanceof Job ? job.handle() : job());
 }
@@ -142,7 +143,12 @@ export class Scheduler {
         let count = 0;
         for (const task of this.tasks) {
             if (task.isDue(now)) {
+                const start = Date.now();
                 await runTask(task.job);
+                instrument("schedule.task.run", {
+                    task: task.job instanceof Job ? task.job.constructor.name : "fn",
+                    durationMs: Date.now() - start,
+                });
                 count++;
             }
         }

package/dist/core/social.d.ts

@@ -1,8 +1,8 @@
 /**
- * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". Like Adonis
- * Ally, this owns the OAuth dance only: it hands you a normalized `SocialUser`,
- * and *you* find-or-create your own user and log them in (with a session,
- * `jwt`, or an access `token`). It stores nothing.
+ * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". This owns the
+ * OAuth dance only: it hands you a normalized `SocialUser`, and *you*
+ * find-or-create your own user and log them in (with a session, `jwt`, or an
+ * access `token`). It stores nothing.
  *
  *   const github = social.github({ clientId, clientSecret, redirectUri });
  *

package/dist/core/social.js

@@ -1,8 +1,8 @@
 /**
- * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". Like Adonis
- * Ally, this owns the OAuth dance only: it hands you a normalized `SocialUser`,
- * and *you* find-or-create your own user and log them in (with a session,
- * `jwt`, or an access `token`). It stores nothing.
+ * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". This owns the
+ * OAuth dance only: it hands you a normalized `SocialUser`, and *you*
+ * find-or-create your own user and log them in (with a session, `jwt`, or an
+ * access `token`). It stores nothing.
  *
  *   const github = social.github({ clientId, clientSecret, redirectUri });
  *