@shaferllc/keel 0.66.0 → 0.68.0

package/dist/core/health.js

@@ -0,0 +1,226 @@
+/**
+ * Health checks — the two endpoints an orchestrator (Kubernetes, Fly, Railway,
+ * a load balancer) asks about before it sends you traffic:
+ *
+ *   /health/live   is the process up?          — answers instantly, checks nothing
+ *   /health/ready  can it serve requests?      — runs every registered check
+ *
+ * A liveness probe that touched the database would restart a healthy app during a
+ * database blip, so it deliberately checks nothing. Readiness is where the checks
+ * live: it reports 200 while everything it depends on is reachable, and 503 when
+ * something isn't — which pulls the instance out of the pool without killing it.
+ *
+ *   health().register([new DatabaseCheck(), new RedisCheck()]);
+ *   this.use(healthCheck());                    // serves both endpoints
+ *
+ * Keel ships the checks that mean something wherever it runs — a database, Redis,
+ * the cache. Deliberately absent are AdonisJS's disk-space and heap/RSS checks:
+ * they measure a Node process, and on Workers there isn't one.
+ */
+import { connection } from "./database.js";
+import { redis } from "./redis.js";
+import { cache } from "./helpers.js";
+/** The outcome of a single check. Build one with `Result.ok/warning/failed`. */
+export class Result {
+    status;
+    message;
+    error;
+    meta;
+    constructor(status, message, error, meta) {
+        this.status = status;
+        this.message = message;
+        this.error = error;
+        this.meta = meta;
+    }
+    /** Healthy. */
+    static ok(message) {
+        return new Result("ok", message);
+    }
+    /**
+     * Working, but degraded — worth paging someone, not worth pulling the instance
+     * out of the pool. A warning keeps readiness at 200.
+     */
+    static warning(message) {
+        return new Result("warning", message);
+    }
+    /** Broken. Any failed check takes readiness to 503. */
+    static failed(message, error) {
+        return new Result("error", message, error);
+    }
+    /** Attach arbitrary detail — connection counts, latencies, versions. */
+    withMeta(meta) {
+        this.meta = { ...this.meta, ...meta };
+        return this;
+    }
+}
+/* --------------------------------- checks --------------------------------- */
+/** One thing worth knowing about before serving traffic. */
+export class BaseCheck {
+    ttl = 0;
+    cached;
+    /**
+     * Reuse this check's last result for `seconds`, so a probe every few seconds
+     * doesn't hammer the thing it's checking. The report marks a reused result
+     * with `isCached: true`.
+     */
+    cacheFor(seconds) {
+        this.ttl = seconds;
+        return this;
+    }
+    /**
+     * Run the check, honouring `cacheFor`, and never throw: a check that blows up
+     * is itself a failure, and one broken check must not take down the report.
+     *
+     * @internal — called by `HealthChecks.run()`.
+     */
+    async execute() {
+        const now = Date.now();
+        if (this.cached && this.cached.expiresAt > now) {
+            return { result: this.cached.result, isCached: true };
+        }
+        let result;
+        try {
+            result = await this.run();
+        }
+        catch (error) {
+            result = Result.failed(error instanceof Error ? error.message : `The "${this.name}" check threw.`, error);
+        }
+        if (this.ttl > 0) {
+            this.cached = { result, expiresAt: now + this.ttl * 1000 };
+        }
+        return { result, isCached: false };
+    }
+}
+/**
+ * A check from a plain function — the escape hatch, for anything Keel doesn't
+ * ship a check for.
+ *
+ *   health().register([
+ *     check("stripe", async () => {
+ *       const res = await fetch("https://api.stripe.com/healthcheck");
+ *       return res.ok ? Result.ok("Stripe is reachable") : Result.failed("Stripe is down");
+ *     }),
+ *   ]);
+ */
+export function check(name, run) {
+    return new (class extends BaseCheck {
+        name = name;
+        async run() {
+            return run();
+        }
+    })();
+}
+/** Is the database reachable? Runs `SELECT 1` on a connection. */
+export class DatabaseCheck extends BaseCheck {
+    connectionName;
+    name;
+    constructor(connectionName) {
+        super();
+        this.connectionName = connectionName;
+        this.name = connectionName ? `database (${connectionName})` : "database";
+    }
+    async run() {
+        const started = Date.now();
+        await connection(this.connectionName).select("SELECT 1");
+        return Result.ok("Database is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/** Is Redis reachable? Reads a key — a failed read means a broken connection. */
+export class RedisCheck extends BaseCheck {
+    name = "redis";
+    async run() {
+        const started = Date.now();
+        await redis().get("keel:health");
+        return Result.ok("Redis is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/** Does the cache round-trip? Writes a key, reads it back, deletes it. */
+export class CacheCheck extends BaseCheck {
+    name = "cache";
+    async run() {
+        const started = Date.now();
+        const key = "keel:health";
+        const store = cache();
+        await store.put(key, "ok", 10);
+        const value = await store.get(key);
+        await store.forget(key);
+        if (value !== "ok") {
+            return Result.failed("The cache did not return the value just written to it.");
+        }
+        return Result.ok("Cache is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/* ------------------------------- the registry ------------------------------ */
+export class HealthChecks {
+    checks = [];
+    /** Add checks. Call it once, in a provider's `boot()`. */
+    register(checks) {
+        this.checks.push(...checks);
+        return this;
+    }
+    /** Every registered check. */
+    all() {
+        return [...this.checks];
+    }
+    clear() {
+        this.checks = [];
+        return this;
+    }
+    /** Run every check — concurrently, since they're independent I/O. */
+    async run() {
+        const results = await Promise.all(this.checks.map(async (c) => {
+            const { result, isCached } = await c.execute();
+            return {
+                name: c.name,
+                status: result.status,
+                message: result.message,
+                isCached,
+                finishedAt: new Date().toISOString(),
+                ...(result.meta ? { meta: result.meta } : {}),
+            };
+        }));
+        const status = results.some((r) => r.status === "error")
+            ? "error"
+            : results.some((r) => r.status === "warning")
+                ? "warning"
+                : "ok";
+        return {
+            isHealthy: status !== "error",
+            status,
+            finishedAt: new Date().toISOString(),
+            checks: results,
+        };
+    }
+}
+const registry = new HealthChecks();
+/** The application's health-check registry. */
+export function health() {
+    return registry;
+}
+/**
+ * Serve `/health/live` and `/health/ready`. Anything else falls through to your
+ * routes.
+ *
+ *   this.use(healthCheck());
+ *   this.use(healthCheck({ secret: env.HEALTH_SECRET }));
+ */
+export function healthCheck(options = {}) {
+    const basePath = (options.basePath ?? "/health").replace(/\/+$/, "");
+    return async (c, next) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+            return next();
+        const { pathname } = new URL(c.req.url);
+        // Liveness: the process answered, which is the whole question. Checking a
+        // dependency here would get a healthy app restarted during a database blip.
+        if (pathname === `${basePath}/live`) {
+            return c.json({ isHealthy: true, status: "ok" });
+        }
+        if (pathname !== `${basePath}/ready`)
+            return next();
+        if (options.secret && c.req.header("Authorization") !== `Bearer ${options.secret}`) {
+            return c.json({ message: "Unauthorized" }, 401);
+        }
+        const report = await (options.checks ?? registry).run();
+        return c.json(report, report.isHealthy ? 200 : 503);
+    };
+}

package/dist/core/helpers.d.ts

@@ -10,11 +10,17 @@
 import type { Application } from "./application.js";
 import type { Token, Factory } from "./container.js";
 import { type Renderable } from "./view.js";
-import { Events, type Listener } from "./events.js";
+import { Events, type Listener, type EventName, type EmitArgs, type Resolve } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
 /** Register the active application. Called by the Application constructor. */
 export declare function setApplication(app: Application): void;
+/**
+ * Whether an application has been bootstrapped. Primitives that must work
+ * without one — a queue worker, a mailer in a unit test — check this before
+ * reaching for `logger()` or `emit()`, both of which throw when there's no app.
+ */
+export declare function hasApplication(): boolean;
 /** The active application container. Throws if none has been created. */
 export declare function app(): Application;
 /** Run a callback once the active application has booted (see `Application.onReady`). */
@@ -47,9 +53,9 @@ export declare function restore(token?: Token): void;
 /** The application's event emitter. */
 export declare function events(): Events;
 /** Emit an event, awaiting every listener. */
-export declare function emit<T = unknown>(event: string, payload?: T): Promise<void>;
+export declare function emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
 /** Subscribe to an event; returns an unsubscribe function. */
-export declare function listen<T = unknown>(event: string, listener: Listener<T>): () => void;
+export declare function listen<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
 /** The application's cache. */
 export declare function cache(): Cache;
 /** The application's logger. */

package/dist/core/helpers.js

@@ -9,7 +9,7 @@
  */
 import { Config } from "./config.js";
 import { View } from "./view.js";
-import { Events } from "./events.js";
+import { Events, } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
 let current;
@@ -17,6 +17,14 @@ let current;
 export function setApplication(app) {
     current = app;
 }
+/**
+ * Whether an application has been bootstrapped. Primitives that must work
+ * without one — a queue worker, a mailer in a unit test — check this before
+ * reaching for `logger()` or `emit()`, both of which throw when there's no app.
+ */
+export function hasApplication() {
+    return current !== undefined;
+}
 /** The active application container. Throws if none has been created. */
 export function app() {
     if (!current) {
@@ -83,8 +91,8 @@ export function events() {
     return app().make(Events);
 }
 /** Emit an event, awaiting every listener. */
-export function emit(event, payload) {
-    return events().emit(event, payload);
+export function emit(event, ...args) {
+    return events().emit(event, ...args);
 }
 /** Subscribe to an event; returns an unsubscribe function. */
 export function listen(event, listener) {

package/dist/core/index.d.ts

@@ -6,17 +6,22 @@ export type { BootOptions, LifecycleHook, Configurator } from "./application.js"
 export { Config, env } from "./config.js";
 export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
-export type { LogLevel, LoggerOptions } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
+export type { LogLevel, LoggerOptions, LogRecord, Sink, RedactOptions } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
 export type { RequestLoggerOptions } from "./request-logger.js";
-export { Events } from "./events.js";
-export type { Listener } from "./events.js";
+export { Events, EventBuffer } from "./events.js";
+export type { Listener, AnyListener, ErrorHandler, EventsList, EventName, PayloadOf, RecordedEvent, } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
-export type { CacheStore } from "./cache.js";
+export type { CacheStore, RememberOptions, PutOptions } from "./cache.js";
 export { serveStatic } from "./static.js";
 export type { StaticOptions } from "./static.js";
-export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
-export type { Disk, Contents } from "./storage.js";
+export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
+export type { LockStore, AcquireOptions } from "./lock.js";
+export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
+export type { HealthStatus, HealthReport, CheckReport, HealthCheckOptions, } from "./health.js";
+export { Storage, FakeStorage, MemoryDisk, storage, setDisk, fakeDisk, restoreDisk, serveStorage, signStorageUrl, verifyStorageUrl, contentTypeFor, } from "./storage.js";
+export type { Disk, Contents, FileVisibility, WriteOptions, FileMetadata, SignedFileOptions, SignedUploadOptions, ServeStorageOptions, } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption, jwt } from "./crypto.js";
 export type { JwtPayload, JwtSignOptions, JwtVerifyOptions, EncryptOptions } from "./crypto.js";
@@ -35,10 +40,10 @@ export type { CastType, Casts } from "./casts.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
 export type { Definition } from "./factory.js";
-export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
-export type { Message, Transport, MailerOptions, FetchTransportOptions } from "./mail.js";
-export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
-export type { Dispatchable, JobOptions, QueueDriver, Drainable, QueuedJob } from "./queue.js";
+export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
+export type { Message, Transport, MailerOptions, FetchTransportOptions, Attachment, RecordedMail, } from "./mail.js";
+export { Job, Queue, FakeQueue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, fakeQueue, restoreQueue, exponentialBackoff, linearBackoff, fixedBackoff, noBackoff, } from "./queue.js";
+export type { Dispatchable, JobOptions, JobContext, JobClass, QueueDriver, Drainable, QueuedJob, FailedJob, Backoff, } from "./queue.js";
 export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
 export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
 export type { Broadcaster, Subscriber, ChannelAuthorizer } from "./broadcasting.js";

package/dist/core/index.js

@@ -4,11 +4,14 @@ export { Application } from "./application.js";
 export { Config, env } from "./config.js";
 export { app, config, view, bind, singleton, instance, make, bound, alias, swap, restore, events, emit, listen, cache, logger, onReady, onShutdown, terminate, } from "./helpers.js";
 export { Logger } from "./logger.js";
+export { consoleSink, MemorySink, setLogger, namedLogger } from "./logger.js";
 export { requestLogger, requestLog } from "./request-logger.js";
-export { Events } from "./events.js";
+export { Events, EventBuffer } from "./events.js";
 export { Cache, MemoryStore } from "./cache.js";
 export { serveStatic } from "./static.js";
-export { Storage, MemoryDisk, storage, setDisk } from "./storage.js";
+export { lock, restoreLock, setLockStore, getLockStore, Lock, MemoryLockStore, LockNotHeldError, } from "./lock.js";
+export { health, healthCheck, check, Result, BaseCheck, HealthChecks, DatabaseCheck, RedisCheck, CacheCheck, } from "./health.js";
+export { Storage, FakeStorage, MemoryDisk, storage, setDisk, fakeDisk, restoreDisk, serveStorage, signStorageUrl, verifyStorageUrl, contentTypeFor, } from "./storage.js";
 export { dump, dd } from "./debug.js";
 export { hash, encryption, jwt } from "./crypto.js";
 export { rateLimiter } from "./rate-limit.js";
@@ -19,8 +22,8 @@ export { db, connection, setConnection, addConnection, setDefaultConnection, con
 export { Model } from "./model.js";
 export { Relation, HasOne, HasMany, BelongsTo, BelongsToMany } from "./relations.js";
 export { Faker, Factory as ModelFactory, factory, Seeder, seed } from "./factory.js";
-export { Mailer, PendingMail, ArrayTransport, LogTransport, fetchTransport, mail, setMailer, getMailer, } from "./mail.js";
-export { Job, Queue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, } from "./queue.js";
+export { Mailer, FakeMailer, PendingMail, BaseMail, SendMailJob, ArrayTransport, LogTransport, fetchTransport, mail, mailer, send, sendLater, setMailer, getMailer, fakeMail, restoreMail, } from "./mail.js";
+export { Job, Queue, FakeQueue, SyncDriver, MemoryDriver, dispatch, work, setQueue, getQueue, fakeQueue, restoreQueue, exponentialBackoff, linearBackoff, fixedBackoff, noBackoff, } from "./queue.js";
 export { Scheduler, ScheduledTask, scheduler, setScheduler, schedule, cronMatches } from "./scheduler.js";
 export { MemoryBroadcaster, broadcast, setBroadcaster, getBroadcaster, channelAuth, authorizeChannel, clearChannels, } from "./broadcasting.js";
 export { Redis, MemoryRedis, redis, setRedis, redisStore } from "./redis.js";

package/dist/core/lock.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Distributed locks — "only one of you may do this at a time", across processes
+ * and across nodes. The counterpart to the cache's stampede protection: that
+ * collapses concurrent work *inside one isolate*, this one coordinates work
+ * *between* them.
+ *
+ *   const [ran] = await lock("invoice:42").run(async () => charge(invoice));
+ *   if (!ran) return;   // someone else is already charging it
+ *
+ * Like every other backend in keel, the store is a small pluggable seam and the
+ * core imports no driver — `MemoryLockStore` is the built-in default (per
+ * isolate, so it's for tests and single-process apps); the locks guide has Redis
+ * and database recipes for the real thing.
+ *
+ * ## Two safety properties, both easy to get wrong
+ *
+ * **Ownership.** Every acquisition mints a random owner token, and release and
+ * extend only succeed for the owner. Without that, a lock whose TTL expired
+ * mid-work gets picked up by process B, and process A's `release()` — arriving
+ * late — would delete *B's* lock, letting a third process in. A store must
+ * compare-and-delete, not just delete.
+ *
+ * **TTL.** A lock always expires. If a holder crashes, the lock must not be held
+ * forever, so there's no "hold until released" mode. Pick a TTL longer than the
+ * work; if the work might outrun it, `extend()` from inside.
+ */
+/**
+ * The bridge to a lock backend.
+ *
+ * Every method is keyed by `owner` for the reason above: implementations MUST
+ * make `acquire` atomic (set-if-absent) and `release`/`extend` conditional on
+ * the owner matching. A store that can't do that isn't a lock.
+ */
+export interface LockStore {
+    /** Set the key if absent. Returns whether this owner got it. Must be atomic. */
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Delete the key only if `owner` still holds it. Returns whether it did. */
+    release(key: string, owner: string): Promise<boolean>;
+    /** Push the expiry out, only if `owner` still holds it. */
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Whether anyone currently holds the key. */
+    isLocked(key: string): Promise<boolean>;
+    /** Milliseconds until the key expires, or null if nobody holds it. */
+    remainingTime(key: string): Promise<number | null>;
+}
+/**
+ * An in-memory `LockStore` — the default. Per-isolate, so it coordinates
+ * *within* one process and nothing more: perfect for tests and single-process
+ * apps, useless across a cluster. Point `setLockStore()` at Redis for that.
+ */
+export declare class MemoryLockStore implements LockStore {
+    private entries;
+    /** The live entry for a key, dropping it if it has expired. */
+    private live;
+    acquire(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    extend(key: string, owner: string, ttlMs: number): Promise<boolean>;
+    isLocked(key: string): Promise<boolean>;
+    remainingTime(key: string): Promise<number | null>;
+}
+export interface AcquireOptions {
+    /**
+     * Give up after this many milliseconds of waiting. Default: 0 — don't wait at
+     * all, fail immediately if the lock is held.
+     */
+    timeout?: number;
+    /** Milliseconds between attempts while waiting. Default: 50. */
+    retryDelay?: number;
+}
+/** A lock that has expired or was never held. */
+export declare class LockNotHeldError extends Error {
+    constructor(key: string);
+}
+export declare class Lock {
+    readonly key: string;
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    readonly ttlMs: number;
+    private store;
+    /** Non-null only while this instance holds the lock. */
+    private owner?;
+    constructor(key: string, 
+    /** How long the lock is held before it expires on its own. Milliseconds. */
+    ttlMs: number, store: LockStore, owner?: string);
+    /**
+     * Take the lock, run `fn`, and always give it back — the form you want almost
+     * every time, because the `finally` is what stops a throwing callback from
+     * leaving the lock held until its TTL runs out.
+     *
+     * Returns `[ran, result]`: `ran` is false if someone else holds it, in which
+     * case `fn` never ran.
+     *
+     *   const [ran, invoice] = await lock("invoice:42").run(() => charge(id));
+     *   if (!ran) return;   // another worker is on it
+     */
+    run<T>(fn: () => Promise<T> | T, options?: AcquireOptions): Promise<[boolean, T | undefined]>;
+    /** `run()`, but never waits: if the lock is held, give up at once. */
+    runImmediately<T>(fn: () => Promise<T> | T): Promise<[boolean, T | undefined]>;
+    /**
+     * Take the lock, waiting up to `timeout` for it. Returns whether we got it.
+     *
+     * Prefer `run()` — with a bare `acquire()` you own the `try/finally`, and a
+     * throw between here and `release()` leaks the lock for the rest of its TTL.
+     */
+    acquire(options?: AcquireOptions): Promise<boolean>;
+    /** Take the lock only if it's free right now. */
+    acquireImmediately(): Promise<boolean>;
+    /** Give the lock back. A no-op if we no longer hold it (it may have expired). */
+    release(): Promise<boolean>;
+    /**
+     * Push the expiry out — for work that might outrun the TTL. Throws
+     * `LockNotHeldError` if we've already lost it, because the alternative (a
+     * silent no-op) would let you carry on believing you hold a lock you don't.
+     */
+    extend(ttlMs?: number): Promise<void>;
+    /** Whether *anyone* holds this key — not necessarily us. */
+    isLocked(): Promise<boolean>;
+    /** Whether we held this lock but no longer do. */
+    isExpired(): Promise<boolean>;
+    /** Milliseconds until the lock expires, or null if nobody holds it. */
+    getRemainingTime(): Promise<number | null>;
+    /**
+     * Freeze the lock (key, TTL, owner token) to a string, so another process can
+     * `restoreLock()` it and release or extend the *same* lock — the handoff you
+     * need when one process takes the lock and another finishes the work.
+     */
+    serialize(): string;
+}
+/** Register the lock store used by `lock()`. */
+export declare function setLockStore(next: LockStore): LockStore;
+/** The active lock store. */
+export declare function getLockStore(): LockStore;
+/**
+ * A lock on `key`, held for `ttlMs` once acquired (default 30s).
+ *
+ *   const [ran] = await lock("invoice:42").run(() => charge(invoice));
+ */
+export declare function lock(key: string, ttlMs?: number): Lock;
+/** Rebuild a lock from `serialize()` — same key, same TTL, same owner token. */
+export declare function restoreLock(serialized: string): Lock;