@sanoma-ai/workflows 0.5.0 → 0.7.0

package/dist/wakeup-service.d.ts

@@ -0,0 +1,83 @@
+/** Where the accounts live: one per party that registers instances, its token's hash alone. */
+export declare const WAKEUP_ACCOUNTS_TABLE = "sanoma_wakeup_accounts";
+/** Where the instances live: each one's URL, its token's hash and its registered wake. */
+export declare const WAKEUP_INSTANCES_TABLE = "sanoma_wakeup_instances";
+/** The shape of `@sanoma-ai/app`'s `IngressRoute`, which `startApp`'s `ingress` takes. */
+export interface WakeupRoute {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    /** `/wakeup`, with every path under it (`prefix`). */
+    path: string;
+    prefix: true;
+    handle(request: Request): Promise<Response>;
+}
+export interface WakeupServiceOptions {
+    /** The service's own Postgres: its tables are made there when missing (the database too). */
+    databaseUrl: string;
+    /** The clock: what is due, and what `called_at` and `next_attempt_at` are set from. */
+    now?: () => Date;
+    /** How the instances are called. */
+    fetch?: typeof globalThis.fetch;
+    /** One `info` line per call, a `warn` per failure; the runtime's logger by default. */
+    log?: {
+        info(line: string): void;
+        warn(line: string): void;
+    };
+}
+export interface WakeupService {
+    /** One route answering everything under `/wakeup`, for `startApp`'s `ingress` or a server of its own. */
+    routes: WakeupRoute[];
+    /** An account that may register instances: its id, and its token, shown this once. */
+    mintAccount(label: string): Promise<{
+        id: string;
+        token: string;
+    }>;
+    /** Refuses the account's token and its instances' from now on, and wakes its instances no more. */
+    revokeAccount(id: string): Promise<void>;
+    /** Ends the loop, abandoning the calls in flight (called again once their claim lapses), and closes the pool. */
+    stop(): Promise<void>;
+}
+/**
+ * A new instance token (`swi_…`), which the company mints and stores as `SANOMA_WAKEUP_TOKEN`
+ * before anything is applied, so its host is given it from the first apply; the wakeup's create
+ * then registers it with the service. The service never mints one.
+ */
+export declare const mintInstanceToken: () => string;
+/** The secret a company keeps its instance token in: what its host's `secrets` name and its wakeup's driver reads. */
+export declare const WAKEUP_TOKEN = "SANOMA_WAKEUP_TOKEN";
+/** An instance token the service takes: `swi_`, then at least as many base64url characters as a minted one has. */
+export declare const INSTANCE_TOKEN: RegExp;
+/**
+ * An instance's URL as it is stored, without a trailing slash, or why it is refused: `http(s)`, no
+ * user or password, no query, no fragment (`/wake?generation=N` is added to it).
+ */
+export declare function instanceUrl(value: unknown): {
+    url: string;
+} | {
+    error: string;
+};
+/**
+ * An account of the wakeup service on `databaseUrl`, minted without starting the service (its
+ * tables made when missing): what `sanoma wakeup account <label>` prints.
+ */
+export declare function mintWakeupAccount(databaseUrl: string, label: string): Promise<{
+    id: string;
+    token: string;
+}>;
+/**
+ * Starts the wakeup service on its own database: its two tables made when missing, its one loop
+ * running, and `routes` for whoever serves it (`sanoma wakeup`, or `sanoma serve` with
+ * `wakeup: true`). Routes, each JSON and `no-store`:
+ *
+ * - `POST /wakeup/instances { url, token }`, an account's token → 201 `{ id }` for a new instance
+ *   token, 200 `{ id }` for one the account registered already, its URL now the given one (a lost
+ *   reply, or a host that moved; its registered wake kept only when the URL is the same), 409 for
+ *   another account's
+ * - `GET /wakeup/instances/{id}`, its account's token → `{ id, url, at, generation, calledAt, attempts, lastError }`
+ * - `DELETE /wakeup/instances/{id}`, its account's token → 204
+ * - `PUT /wakeup/wake { at, generation }`, an instance's own token, which names the instance → 204,
+ *   applied only when `generation` is newer than the one it has, and waking the loop
+ *
+ * 401 without a token or with an unknown one, 403 for another account's instance, 400 for a bad
+ * body, 404 for an unknown id or path.
+ */
+export declare function startWakeupService({ databaseUrl, now, fetch, log, }: WakeupServiceOptions): Promise<WakeupService>;

package/dist/wakeup-service.js

@@ -0,0 +1,421 @@
+import { createHash, randomUUID } from "node:crypto";
+import { connectMaking, createTable, openPool } from "./db.js";
+import { info, warn } from "./log.js";
+import { generateSecret } from "./secret.js";
+import { errorMessage } from "./shared.js";
+/*
+ * `@sanoma-ai/workflows/wakeup-service`: the service that wakes stopped instances, server-side
+ * only. An account (minted by whoever runs the service) registers an instance by its URL and the
+ * instance's own token, which the company mints (`mintInstanceToken`) and keeps; the instance,
+ * before it stops, `PUT`s with that token when it wants waking and a
+ * generation; the service then calls `GET {url}/wake?generation=N`, retrying until an answer is a
+ * 2xx. It makes its two tables itself, in the database it is given (sanoma-ops's own, when it
+ * hosts it): never among `db.ts`'s, which every company's database gets.
+ */
+/** Where the accounts live: one per party that registers instances, its token's hash alone. */
+export const WAKEUP_ACCOUNTS_TABLE = "sanoma_wakeup_accounts";
+/** Where the instances live: each one's URL, its token's hash and its registered wake. */
+export const WAKEUP_INSTANCES_TABLE = "sanoma_wakeup_instances";
+const TABLES = [
+    [
+        "wakeup accounts",
+        `CREATE TABLE IF NOT EXISTS ${WAKEUP_ACCOUNTS_TABLE} (id uuid PRIMARY KEY, token_hash text UNIQUE NOT NULL, ` +
+            "label text NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), revoked_at timestamptz)",
+    ],
+    [
+        "wakeup instances",
+        `CREATE TABLE IF NOT EXISTS ${WAKEUP_INSTANCES_TABLE} (id uuid PRIMARY KEY, ` +
+            `account_id uuid NOT NULL REFERENCES ${WAKEUP_ACCOUNTS_TABLE} (id), url text NOT NULL, ` +
+            "token_hash text UNIQUE NOT NULL, at timestamptz, generation bigint NOT NULL DEFAULT 0, " +
+            "called_at timestamptz, attempts integer NOT NULL DEFAULT 0, next_attempt_at timestamptz, " +
+            "last_error text, created_at timestamptz NOT NULL DEFAULT now())",
+    ],
+    // Each on its own, so one another process made first does not skip the next.
+    [
+        "wakeup instances",
+        `CREATE INDEX IF NOT EXISTS ${WAKEUP_INSTANCES_TABLE}_at ON ${WAKEUP_INSTANCES_TABLE} (at) WHERE at IS NOT NULL`,
+    ],
+    [
+        "wakeup instances",
+        `CREATE INDEX IF NOT EXISTS ${WAKEUP_INSTANCES_TABLE}_account ON ${WAKEUP_INSTANCES_TABLE} (account_id)`,
+    ],
+];
+/** How long a call to an instance's `/wake` may take. */
+const CALL_TIMEOUT_MS = 10_000;
+/** The longest the loop sleeps without looking again, whatever is due. */
+const MAX_SLEEP_MS = 60_000;
+/** How many instances are called at once. */
+const CONCURRENCY = 8;
+/** The longest wait between two tries of a failing instance, in seconds. */
+const MAX_BACKOFF_S = 300;
+/**
+ * How long a row taken for a call is the taker's: longer than a call may take. Two services on one
+ * database never call one row at once, and a call no outcome was recorded for (the process
+ * stopped, or the write failed) is tried again once it lapses.
+ */
+const CLAIM_S = 30;
+/** How many due rows a round takes: few enough to be called well within their claim. */
+const ROUND_ROWS = CONCURRENCY * 2;
+/** The most a request's body may hold: a registration is a few hundred bytes. */
+const MAX_BODY = 64 * 1024;
+/** A new token: the prefix, then 32 random bytes in base64url. */
+const newToken = (prefix) => `${prefix}${generateSecret()}`;
+/**
+ * A new instance token (`swi_…`), which the company mints and stores as `SANOMA_WAKEUP_TOKEN`
+ * before anything is applied, so its host is given it from the first apply; the wakeup's create
+ * then registers it with the service. The service never mints one.
+ */
+export const mintInstanceToken = () => newToken("swi_");
+/** The secret a company keeps its instance token in: what its host's `secrets` name and its wakeup's driver reads. */
+export const WAKEUP_TOKEN = "SANOMA_WAKEUP_TOKEN";
+/** An instance token the service takes: `swi_`, then at least as many base64url characters as a minted one has. */
+export const INSTANCE_TOKEN = /^swi_[\w-]{43,256}$/;
+/**
+ * The token's sha256, which is all the tables keep: a token is found by its hash (a unique index),
+ * so the secret itself is never compared, and a guess's timing says nothing an attacker can steer.
+ */
+const hashOf = (token) => createHash("sha256").update(token).digest("hex");
+/** A date-time as `Date.toISOString` writes one, or with an offset: four-digit years only. */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEADERS = { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" };
+const json = (status, body) => Response.json(body, { status, headers: HEADERS });
+const problem = (status, error, headers = {}) => Response.json({ error }, { status, headers: { ...HEADERS, ...headers } });
+/** 405, naming the methods the path answers. */
+const notAllowed = (allow) => problem(405, `this path answers ${allow} only`, { allow });
+const noContent = () => new Response(null, { status: 204, headers: { "cache-control": "no-store" } });
+/** The request's bearer token, or undefined without one. */
+function bearer(request) {
+    const match = /^Bearer (\S+)$/i.exec(request.headers.get("authorization") ?? "");
+    return match?.[1];
+}
+/** The request's body as text, or undefined once it holds more than `MAX_BODY` bytes. */
+async function bodyText(request) {
+    if (!request.body)
+        return "";
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (let read = await reader.read(); !read.done; read = await reader.read()) {
+        size += read.value.length;
+        if (size > MAX_BODY) {
+            await reader.cancel();
+            return undefined;
+        }
+        chunks.push(read.value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** The request's JSON object, undefined when its body is not one, or a 413 for one too large. */
+async function jsonBody(request) {
+    const text = await bodyText(request);
+    if (text === undefined)
+        return problem(413, "the body is too large");
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * An instance's URL as it is stored, without a trailing slash, or why it is refused: `http(s)`, no
+ * user or password, no query, no fragment (`/wake?generation=N` is added to it).
+ */
+export function instanceUrl(value) {
+    const refused = { error: "url must be an http(s) URL with no user, password, query or fragment" };
+    if (typeof value !== "string" || /[?#]/.test(value) || !URL.canParse(value))
+        return refused;
+    const url = new URL(value);
+    if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password)
+        return refused;
+    return { url: url.href.replace(/\/+$/, "") };
+}
+/** An instance as `GET` shows it to its account. */
+const shownInstance = (row) => ({
+    id: row.id,
+    url: row.url,
+    at: row.at?.toISOString() ?? null,
+    generation: Number(row.generation),
+    calledAt: row.called_at?.toISOString() ?? null,
+    attempts: row.attempts,
+    lastError: row.last_error,
+});
+/** A row waiting for its call: registered, not called since its `at`. */
+const WAITING = "i.at IS NOT NULL AND (i.called_at IS NULL OR i.called_at < i.at)";
+/** Of an account not revoked. */
+const LIVE = `JOIN ${WAKEUP_ACCOUNTS_TABLE} a ON a.id = i.account_id AND a.revoked_at IS NULL`;
+/**
+ * Runs `use` on a connection to `databaseUrl` once the service's two tables are there: the
+ * database and the tables made when missing.
+ */
+async function withTables(databaseUrl, use) {
+    const conn = await connectMaking(databaseUrl);
+    try {
+        for (const [what, ddl] of TABLES)
+            await createTable(conn, ddl, what);
+        return await use(conn);
+    }
+    finally {
+        await conn.end().catch(() => undefined);
+    }
+}
+async function insertAccount(db, label) {
+    if (!label.trim())
+        throw new Error("An account's label must not be empty");
+    const id = randomUUID();
+    const token = newToken("swa_");
+    await db.query(`INSERT INTO ${WAKEUP_ACCOUNTS_TABLE} (id, token_hash, label) VALUES ($1, $2, $3)`, [
+        id,
+        hashOf(token),
+        label,
+    ]);
+    return { id, token };
+}
+/**
+ * An account of the wakeup service on `databaseUrl`, minted without starting the service (its
+ * tables made when missing): what `sanoma wakeup account <label>` prints.
+ */
+export async function mintWakeupAccount(databaseUrl, label) {
+    return withTables(databaseUrl, (db) => insertAccount(db, label));
+}
+/**
+ * Starts the wakeup service on its own database: its two tables made when missing, its one loop
+ * running, and `routes` for whoever serves it (`sanoma wakeup`, or `sanoma serve` with
+ * `wakeup: true`). Routes, each JSON and `no-store`:
+ *
+ * - `POST /wakeup/instances { url, token }`, an account's token → 201 `{ id }` for a new instance
+ *   token, 200 `{ id }` for one the account registered already, its URL now the given one (a lost
+ *   reply, or a host that moved; its registered wake kept only when the URL is the same), 409 for
+ *   another account's
+ * - `GET /wakeup/instances/{id}`, its account's token → `{ id, url, at, generation, calledAt, attempts, lastError }`
+ * - `DELETE /wakeup/instances/{id}`, its account's token → 204
+ * - `PUT /wakeup/wake { at, generation }`, an instance's own token, which names the instance → 204,
+ *   applied only when `generation` is newer than the one it has, and waking the loop
+ *
+ * 401 without a token or with an unknown one, 403 for another account's instance, 400 for a bad
+ * body, 404 for an unknown id or path.
+ */
+export async function startWakeupService({ databaseUrl, now = () => new Date(), fetch = globalThis.fetch, log = { info, warn }, }) {
+    await withTables(databaseUrl, async () => { });
+    const pool = openPool(databaseUrl, "wakeup service");
+    const loop = startLoop({ pool, now, fetch, log });
+    /** The live account the request's token is, or a 401. */
+    async function account(request) {
+        const token = bearer(request);
+        if (!token?.startsWith("swa_"))
+            return problem(401, "an account's token is needed");
+        const { rows } = await pool.query(`SELECT id FROM ${WAKEUP_ACCOUNTS_TABLE} WHERE token_hash = $1 AND revoked_at IS NULL`, [hashOf(token)]);
+        return rows[0]?.id ?? problem(401, "the token is no account's");
+    }
+    /** The account's instance `id`, or a 404, or a 403 when it is another account's. */
+    async function owned(accountId, id) {
+        if (!UUID.test(id))
+            return problem(404, "no such instance");
+        const { rows } = await pool.query(`SELECT * FROM ${WAKEUP_INSTANCES_TABLE} WHERE id = $1`, [id]);
+        const row = rows[0];
+        if (!row)
+            return problem(404, "no such instance");
+        return row.account_id === accountId ? row : problem(403, "the instance is another account's");
+    }
+    async function register(request) {
+        const accountId = await account(request);
+        if (accountId instanceof Response)
+            return accountId;
+        const given = await jsonBody(request);
+        if (given instanceof Response)
+            return given;
+        const checked = instanceUrl(given?.url);
+        if ("error" in checked)
+            return problem(400, checked.error);
+        const token = given?.token;
+        if (typeof token !== "string" || !INSTANCE_TOKEN.test(token))
+            return problem(400, "token must be an instance's token: swi_, then 43 or more base64url characters");
+        // The token names the instance: a new one is a new row, one of this account's is moved to the
+        // URL given, and another account's is refused (no row returned).
+        const { rows } = await pool.query(`INSERT INTO ${WAKEUP_INSTANCES_TABLE} AS i (id, account_id, url, token_hash) VALUES ($1, $2, $3, $4) ` +
+            "ON CONFLICT (token_hash) DO UPDATE SET url = EXCLUDED.url, " +
+            "at = CASE WHEN i.url = EXCLUDED.url THEN i.at END, " +
+            "generation = CASE WHEN i.url = EXCLUDED.url THEN i.generation ELSE 0 END, " +
+            "called_at = CASE WHEN i.url = EXCLUDED.url THEN i.called_at END, " +
+            "attempts = CASE WHEN i.url = EXCLUDED.url THEN i.attempts ELSE 0 END, " +
+            "next_attempt_at = CASE WHEN i.url = EXCLUDED.url THEN i.next_attempt_at END, " +
+            "last_error = CASE WHEN i.url = EXCLUDED.url THEN i.last_error END " +
+            "WHERE i.account_id = EXCLUDED.account_id RETURNING i.id, i.id = $1 AS made", [randomUUID(), accountId, checked.url, hashOf(token)]);
+        const row = rows[0];
+        if (!row) {
+            return problem(409, "the token is another account's instance's");
+        }
+        return json(row.made ? 201 : 200, { id: row.id });
+    }
+    async function wake(request) {
+        const token = bearer(request);
+        if (!token?.startsWith("swi_"))
+            return problem(401, "an instance's token is needed");
+        const { rows } = await pool.query(`SELECT i.id FROM ${WAKEUP_INSTANCES_TABLE} i ${LIVE} WHERE i.token_hash = $1`, [hashOf(token)]);
+        const id = rows[0]?.id;
+        if (!id)
+            return problem(401, "the token is no instance's");
+        const given = await jsonBody(request);
+        if (given instanceof Response)
+            return given;
+        const at = given?.at;
+        const generation = given?.generation;
+        if (typeof at !== "string" || !ISO_DATE_TIME.test(at) || Number.isNaN(Date.parse(at)))
+            return problem(400, "at must be an ISO 8601 date-time");
+        // A new instance has generation 0, so a registration counts from 1.
+        if (typeof generation !== "number" || !Number.isSafeInteger(generation) || generation < 1)
+            return problem(400, "generation must be an integer, 1 or more");
+        // An older or equal generation changes nothing: callers retry, at least once each.
+        await pool.query(`UPDATE ${WAKEUP_INSTANCES_TABLE} SET at = $2, generation = $3, called_at = NULL, attempts = 0, ` +
+            "next_attempt_at = NULL, last_error = NULL WHERE id = $1 AND generation < $3", [id, new Date(at), generation]);
+        loop.poke();
+        return noContent();
+    }
+    async function handle(request) {
+        const path = new URL(request.url).pathname;
+        const method = request.method;
+        if (path === "/wakeup/instances") {
+            return method === "POST" ? register(request) : notAllowed("POST");
+        }
+        // Its token says which instance it is.
+        if (path === "/wakeup/wake")
+            return method === "PUT" ? wake(request) : notAllowed("PUT");
+        const match = /^\/wakeup\/instances\/([^/]+)$/.exec(path);
+        if (!match)
+            return problem(404, "no such route");
+        const id = match[1];
+        if (method !== "GET" && method !== "DELETE")
+            return notAllowed("GET, DELETE");
+        const accountId = await account(request);
+        if (accountId instanceof Response)
+            return accountId;
+        const row = await owned(accountId, id);
+        if (row instanceof Response)
+            return row;
+        if (method === "GET")
+            return json(200, shownInstance(row));
+        await pool.query(`DELETE FROM ${WAKEUP_INSTANCES_TABLE} WHERE id = $1`, [id]);
+        return noContent();
+    }
+    return {
+        routes: [{ path: "/wakeup", prefix: true, handle }],
+        mintAccount: (label) => insertAccount(pool, label),
+        async revokeAccount(id) {
+            if (!UUID.test(id))
+                return;
+            await pool.query(`UPDATE ${WAKEUP_ACCOUNTS_TABLE} SET revoked_at = $2 WHERE id = $1 AND revoked_at IS NULL`, [
+                id,
+                now(),
+            ]);
+        },
+        async stop() {
+            await loop.stop();
+            await pool.end();
+        },
+    };
+}
+/**
+ * The one loop: calls every row that is due, at most `CONCURRENCY` at once, then sleeps until the
+ * next is (at most `MAX_SLEEP_MS`) or until `poke`. A failed call is tried again after
+ * `min(2^attempts s, MAX_BACKOFF_S)`, for as long as it takes: no row is ever dropped.
+ */
+function startLoop({ pool, now, fetch, log, }) {
+    const stopping = new AbortController();
+    let poked = false;
+    let wakeUp;
+    /** Calls `row`'s instance once, and records how it went, unless the registration changed meanwhile. */
+    async function call(row) {
+        const target = `${row.url}/wake?generation=${row.generation}`;
+        let error;
+        try {
+            const signal = AbortSignal.any([stopping.signal, AbortSignal.timeout(CALL_TIMEOUT_MS)]);
+            // A redirect is no answer: it could send the service anywhere, so it is tried again as a failure.
+            const res = await fetch(target, { signal, redirect: "manual" });
+            await res.body?.cancel().catch(() => undefined);
+            if (!res.ok)
+                error = `answered ${res.status}`;
+        }
+        catch (err) {
+            error = errorMessage(err);
+        }
+        // Stopped mid-call: nothing is known of it, so it is called again once its claim lapses.
+        if (stopping.signal.aborted)
+            return;
+        // Recorded only on the registration called: one replaced (a newer generation), or moved to
+        // another URL (its generation counted again from 0), is called again.
+        const same = "WHERE id = $1 AND generation = $2 AND url = $3";
+        if (error === undefined) {
+            await pool.query(`UPDATE ${WAKEUP_INSTANCES_TABLE} SET called_at = $4, attempts = 0, next_attempt_at = NULL, ` +
+                `last_error = NULL ${same}`, [row.id, row.generation, row.url, now()]);
+            log.info(`wakeup: called ${target}`);
+        }
+        else {
+            await pool.query(`UPDATE ${WAKEUP_INSTANCES_TABLE} SET attempts = attempts + 1, last_error = $4, ` +
+                `next_attempt_at = $5::timestamptz + least(power(2, attempts), ${MAX_BACKOFF_S}) * interval '1 second' ` +
+                same, [row.id, row.generation, row.url, error, now()]);
+            log.warn(`wakeup: calling ${target} failed (${error}); it is tried again`);
+        }
+    }
+    /** Calls every due row; returns when the next one is due, or undefined with none waiting. */
+    async function round() {
+        // Taken for `CLAIM_S`, rows another service holds skipped: each due row is called by one service.
+        const { rows } = await pool.query(`UPDATE ${WAKEUP_INSTANCES_TABLE} SET next_attempt_at = $1::timestamptz + interval '${CLAIM_S} seconds' ` +
+            `WHERE id IN (SELECT i.id FROM ${WAKEUP_INSTANCES_TABLE} i ${LIVE} WHERE ${WAITING} ` +
+            "AND i.at <= $1 AND (i.next_attempt_at IS NULL OR i.next_attempt_at <= $1) " +
+            `ORDER BY i.at LIMIT ${ROUND_ROWS} FOR UPDATE OF i SKIP LOCKED) RETURNING id, url, generation`, [now()]);
+        const queue = [...rows];
+        const worker = async () => {
+            for (let row = queue.shift(); row && !stopping.signal.aborted; row = queue.shift()) {
+                await call(row).catch((err) => log.warn(`wakeup: could not record a call: ${errorMessage(err)}`));
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, worker));
+        const next = await pool.query(`SELECT min(greatest(i.at, coalesce(i.next_attempt_at, i.at))) AS next FROM ${WAKEUP_INSTANCES_TABLE} i ` +
+            `${LIVE} WHERE ${WAITING}`);
+        return next.rows[0]?.next ?? undefined;
+    }
+    const sleep = (ms) => new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        wakeUp = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+    });
+    const running = (async () => {
+        while (!stopping.signal.aborted) {
+            poked = false;
+            let ms = MAX_SLEEP_MS;
+            try {
+                const next = await round();
+                if (next)
+                    ms = Math.min(Math.max(next.getTime() - now().getTime(), 0), MAX_SLEEP_MS);
+            }
+            catch (err) {
+                if (stopping.signal.aborted)
+                    break;
+                log.warn(`wakeup: the loop could not read its instances: ${errorMessage(err)}`);
+                ms = 5_000;
+            }
+            // A poke during the round may have come after its last read: look again at once.
+            if (!poked && !stopping.signal.aborted)
+                await sleep(ms);
+        }
+    })();
+    return {
+        /** Wakes the loop now, or right after the round in progress. */
+        poke() {
+            poked = true;
+            wakeUp?.();
+        },
+        async stop() {
+            stopping.abort();
+            wakeUp?.();
+            await running;
+        },
+    };
+}
+//# sourceMappingURL=wakeup-service.js.map

package/dist/wakeup-service.js.map

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

package/dist/wakeup.d.ts

@@ -0,0 +1,84 @@
+import type { z } from "zod";
+import type { Op } from "./op.ts";
+import type { References, Resource } from "./resource.ts";
+import type { DeclaredResource } from "./resources.ts";
+/** What a wakeup's state says of it. */
+export interface WakeupOutputs {
+    healthy: boolean;
+}
+/** What the runtime calls a wakeup's `register` operation with. */
+export interface WakeupRegistration {
+    /** When to wake the instance, as an ISO 8601 date-time. */
+    at: string;
+    /** Counts up with each registration: one with a newer generation replaces the older. */
+    generation: number;
+}
+/**
+ * The `generation` of a `GET /wake?generation=N` request: a non-negative integer, in digits
+ * alone; undefined for none or any other.
+ */
+export declare function wakeGeneration(url: string | URL): number | undefined;
+/**
+ * A resource type's `wakeup`: the field it names the host in, the operation the runtime
+ * registers each deadline through, and how its state reads.
+ */
+export interface WakeupSpec {
+    inputs: {
+        /**
+         * The dotted path of the declared field that names the host's declaration: a
+         * `fields.references` entry, resolved `by` a field of the host's state holding its URL.
+         */
+        host: string;
+    };
+    /**
+     * The id of the type's own register operation, `<vendor>.<type>.<op>`: an operation in the
+     * type's own group of its connector, beside `read` and `import` (the way Supabase adds
+     * `project.health` beside `project`). The runtime calls it with `WakeupRegistration`,
+     * at least once per registration; a newer `generation` replaces the older.
+     */
+    register: string;
+    outputs: (state: Record<string, unknown>) => WakeupOutputs;
+}
+/** The operations `defineResource` gives a type itself: never its register, or a database's `storeUrl`. */
+export declare const RESOURCE_OPS: Set<string>;
+/**
+ * Throws what is wrong with a resource type's `wakeup`: a type apply cannot change (not
+ * `writable`), a host (stopped when its wake is due), a `host` that names no field or no
+ * reference resolved `by` a field, a `register` that is not an operation of the type's own group
+ * or is one of its resource operations, `outputs` that is not a function. Whether the connector
+ * has that operation, and the reference names a host, is `checkWakeupOps`'s, which
+ * `resolveConfig` runs.
+ */
+export declare function checkWakeup(what: string, wakeup: WakeupSpec, type: {
+    vendor: string;
+    type: string;
+    schema: z.ZodObject;
+    fields: {
+        references?: References;
+    };
+    writable?: boolean;
+    host?: unknown;
+}): void;
+/** The host types a wakeup type may name: its `inputs.host` reference's. */
+export declare const wakeupHostTypes: (type: Pick<Resource, "fields" | "wakeup">) => string[];
+/**
+ * Throws when a wakeup type's host reference names a type of the config that is no host, or its
+ * `register` is not among the config's operations, or does not take
+ * `WakeupRegistration`. Here rather than in `defineConnector`, which sees one connector before
+ * its package merges in the operations it adds to a resource's group (Supabase's pattern).
+ */
+export declare function checkWakeupOps(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>): void;
+/** The one wakeup the data files declare: its declaration, its type, and its binding when it is bound. */
+export interface DeclaredWakeup {
+    /** `<file>#<export>`, as `DeclaredResource.id`. */
+    id: string;
+    type: Resource;
+    declared: DeclaredResource;
+    /** The vendor's id of the object the lockfile binds it to; absent when unbound. */
+    binding?: string;
+    /** The declared host its `inputs.host` names: its declaration's id and its type, a host's (`checkWakeupOps`). */
+    host?: {
+        id: string;
+        type: Resource;
+    };
+}