@engenty/wizards-runtime 0.0.0-stage → 0.7.6

package/apps/runtime/dist/store/index.js

@@ -0,0 +1,299 @@
+import { note } from "@engenty-wizards/shared/run";
+import { firstRowAt, newCells, patchCells, rowKey, STORE_LIMITS, } from "@engenty-wizards/shared/store";
+import { cleanPath, mimeForPath } from "@engenty-wizards/shared/workspace";
+import { and, asc, eq, inArray, like, lt, sql } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { env } from "../env.js";
+import { getBlob, putBlob } from "../files/blobs.js";
+import { seal, unseal } from "../secrets/crypto.js";
+import { StoreError } from "./errors.js";
+import { deleteSharedRows, saveSharedRows, sharedRows } from "./shared-lists.js";
+export { StoreError };
+/** The person a run belongs to: the signed-in admin, else the visitor of the shared link. */
+export function holderOf(run) {
+    if (run.userId) {
+        return `u:${run.userId}`;
+    }
+    return run.visitorId ? `v:${run.visitorId}` : `r:${run.id}`;
+}
+export function scopeOf(run) {
+    return { wizardId: run.wizardId, holder: holderOf(run) };
+}
+/** Marks the store as in use; stores nobody came back to are cleaned up. */
+export async function touchStore(scope) {
+    await db
+        .insert(schema.storeHolder)
+        .values({ ...scope, usedAt: new Date() })
+        .onConflictDoUpdate({
+        target: [schema.storeHolder.wizardId, schema.storeHolder.holder],
+        set: { usedAt: new Date() },
+    });
+}
+// --- lists -------------------------------------------------------------------
+const inList = (scope, list) => and(eq(schema.storeRow.wizardId, scope.wizardId), eq(schema.storeRow.holder, scope.holder), eq(schema.storeRow.list, list));
+function toRow(r) {
+    return { id: r.id, cells: r.cells, updatedAt: r.updatedAt.toISOString() };
+}
+/** The rows of a list: the person's, or every run's where the list is shared. */
+export async function listRows(scope, def) {
+    if (def.shared) {
+        return sharedRows(scope.wizardId, def);
+    }
+    const rows = await db.query.storeRow.findMany({
+        where: inList(scope, def.id),
+        orderBy: [asc(schema.storeRow.createdAt), asc(schema.storeRow.id)],
+    });
+    return rows.map(toRow);
+}
+/**
+ * Saves rows into a list. With a key column, a row whose key is already there is updated — only
+ * the columns given change, so a step can add "how to get the invoice" without wiping the rest.
+ * A row with a bad value is refused as a whole (`TableColumnValueError` names the column).
+ */
+export async function saveRows(scope, def, input) {
+    if (def.shared) {
+        return saveSharedRows(scope.wizardId, def, input);
+    }
+    let added = 0;
+    let updated = 0;
+    const existing = await db.query.storeRow.findMany({ where: inList(scope, def.id) });
+    const byKey = new Map(existing.filter((r) => r.key).map((r) => [r.key, r]));
+    let count = existing.length;
+    const at = firstRowAt(existing);
+    for (const raw of input) {
+        const key = rowKey(def, raw);
+        const hit = key ? byKey.get(key) : undefined;
+        if (hit) {
+            const cells = patchCells(def, hit.cells, raw);
+            await db
+                .update(schema.storeRow)
+                .set({ cells, updatedAt: new Date() })
+                .where(eq(schema.storeRow.id, hit.id));
+            hit.cells = cells;
+            updated++;
+            continue;
+        }
+        const cells = newCells(def, raw);
+        if (Object.values(cells).every((v) => v === null)) {
+            continue;
+        }
+        if (count >= STORE_LIMITS.rowsPerList) {
+            throw new StoreError(`List "${def.id}" is full (${STORE_LIMITS.rowsPerList} rows).`);
+        }
+        const row = {
+            id: nanoid(14),
+            ...scope,
+            list: def.id,
+            key,
+            cells,
+            createdAt: new Date(at + added),
+        };
+        await db.insert(schema.storeRow).values(row);
+        if (key) {
+            byKey.set(key, { ...row, updatedAt: new Date() });
+        }
+        count++;
+        added++;
+    }
+    await touchStore(scope);
+    return { added, updated };
+}
+/** Changes cells of one row (the person edited it). A shared list is never the person's. */
+export async function updateRow(scope, def, rowId, patch) {
+    if (def.shared) {
+        return false;
+    }
+    const row = await db.query.storeRow.findFirst({
+        where: and(inList(scope, def.id), eq(schema.storeRow.id, rowId)),
+    });
+    if (!row) {
+        return false;
+    }
+    const cells = patchCells(def, row.cells, patch);
+    const key = rowKey(def, cells);
+    const clash = key && key !== row.key
+        ? await db.query.storeRow.findFirst({
+            where: and(inList(scope, def.id), eq(schema.storeRow.key, key)),
+        })
+        : null;
+    if (clash) {
+        throw new StoreError(note("entryAlreadyExists"));
+    }
+    await db
+        .update(schema.storeRow)
+        .set({ cells, key, updatedAt: new Date() })
+        .where(eq(schema.storeRow.id, rowId));
+    return true;
+}
+/** Deletes rows by id, or by the value of the key column. */
+export async function deleteRows(scope, def, idsOrKeys) {
+    if (def.shared) {
+        return deleteSharedRows(scope.wizardId, def, idsOrKeys);
+    }
+    if (!idsOrKeys.length) {
+        return 0;
+    }
+    const keys = idsOrKeys.map((k) => k.trim().toLowerCase());
+    const byId = await db
+        .delete(schema.storeRow)
+        .where(and(inList(scope, def.id), inArray(schema.storeRow.id, idsOrKeys)))
+        .returning({ id: schema.storeRow.id });
+    const byKey = await db
+        .delete(schema.storeRow)
+        .where(and(inList(scope, def.id), inArray(schema.storeRow.key, keys)))
+        .returning({ id: schema.storeRow.id });
+    return byId.length + byKey.length;
+}
+// --- files -------------------------------------------------------------------
+const ownFiles = (scope) => and(eq(schema.storeFile.wizardId, scope.wizardId), eq(schema.storeFile.holder, scope.holder));
+function toFile(r) {
+    return {
+        path: r.path,
+        mime: r.mime,
+        size: r.size,
+        source: r.source,
+        updatedAt: r.updatedAt.toISOString(),
+    };
+}
+/** Any name a model or a mail server comes up with, as a path the store accepts. */
+export function storePath(raw) {
+    const path = raw
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/ß/g, "ss")
+        .split("/")
+        .map((part) => part
+        .trim()
+        .replace(/[^A-Za-z0-9_.-]+/g, "_")
+        .replace(/^[._]+/, "")
+        .slice(0, 80))
+        .filter(Boolean)
+        .join("/");
+    const clean = cleanPath(path);
+    if (!clean) {
+        throw new StoreError(`"${raw}" is not a usable file name.`);
+    }
+    return clean;
+}
+export async function storeFiles(scope, folder) {
+    const rows = await db.query.storeFile.findMany({
+        where: folder
+            ? and(ownFiles(scope), like(schema.storeFile.path, `${folder.replace(/\/+$/, "")}/%`))
+            : ownFiles(scope),
+        orderBy: [asc(schema.storeFile.path)],
+    });
+    return rows.map(toFile);
+}
+/** Whether the wizard keeps any file for the holder: one row, not the whole list. */
+export async function hasStoreFiles(scope) {
+    const row = await db.query.storeFile.findFirst({
+        where: ownFiles(scope),
+        columns: { path: true },
+    });
+    return row !== undefined;
+}
+export async function readStoreFile(scope, rawPath) {
+    const path = cleanPath(rawPath);
+    const row = path
+        ? await db.query.storeFile.findFirst({
+            where: and(ownFiles(scope), eq(schema.storeFile.path, path)),
+        })
+        : undefined;
+    return row ? { file: toFile(row), data: await getBlob(row.hash) } : null;
+}
+export async function writeStoreFile(scope, rawPath, content, meta = {}) {
+    const path = storePath(rawPath);
+    const data = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+    if (data.byteLength > STORE_LIMITS.fileBytes) {
+        throw new StoreError(`${path} is larger than 15 MB.`);
+    }
+    const [usage] = await db
+        .select({
+        files: sql `count(*)`,
+        bytes: sql `coalesce(sum(${schema.storeFile.size}), 0)`,
+    })
+        .from(schema.storeFile)
+        .where(ownFiles(scope));
+    if (usage.files >= STORE_LIMITS.files ||
+        usage.bytes + data.byteLength > STORE_LIMITS.totalBytes) {
+        throw new StoreError("The wizard's storage is full.");
+    }
+    const hash = await putBlob(data);
+    const mime = meta.mime && meta.mime !== "application/octet-stream" ? meta.mime : mimeForPath(path);
+    const updatedAt = new Date();
+    await db
+        .insert(schema.storeFile)
+        .values({ ...scope, path, hash, mime, size: data.byteLength, source: meta.source ?? null })
+        .onConflictDoUpdate({
+        target: [schema.storeFile.wizardId, schema.storeFile.holder, schema.storeFile.path],
+        set: { hash, mime, size: data.byteLength, source: meta.source ?? null, updatedAt },
+    });
+    await touchStore(scope);
+    return {
+        path,
+        mime,
+        size: data.byteLength,
+        source: meta.source ?? null,
+        updatedAt: updatedAt.toISOString(),
+    };
+}
+// --- secrets -----------------------------------------------------------------
+const ownSecrets = (scope) => and(eq(schema.storeSecret.wizardId, scope.wizardId), eq(schema.storeSecret.holder, scope.holder));
+export async function getSecret(scope, slot) {
+    const row = await db.query.storeSecret.findFirst({
+        where: and(ownSecrets(scope), eq(schema.storeSecret.slot, slot)),
+    });
+    const data = row ? unseal(row.data) : null;
+    return row && data
+        ? { provider: row.provider, label: row.label, data, createdAt: row.createdAt }
+        : null;
+}
+export async function putSecret(scope, slot, provider, label, data) {
+    const sealed = seal(data);
+    await db
+        .insert(schema.storeSecret)
+        .values({ id: nanoid(14), ...scope, slot, provider, label, data: sealed })
+        .onConflictDoUpdate({
+        target: [schema.storeSecret.wizardId, schema.storeSecret.holder, schema.storeSecret.slot],
+        set: { provider, label, data: sealed, updatedAt: new Date() },
+    });
+    await touchStore(scope);
+}
+export async function deleteSecret(scope, slot) {
+    await db
+        .delete(schema.storeSecret)
+        .where(and(ownSecrets(scope), eq(schema.storeSecret.slot, slot)));
+}
+export async function listSecrets(scope) {
+    const rows = await db.query.storeSecret.findMany({ where: ownSecrets(scope) });
+    return rows.map((r) => ({
+        slot: r.slot,
+        provider: r.provider,
+        label: r.label,
+        createdAt: r.createdAt.toISOString(),
+    }));
+}
+// --- everything --------------------------------------------------------------
+/** Deletes everything the wizard keeps for this person. Blobs stay: other files may share them. */
+export async function clearStore(scope) {
+    await db
+        .delete(schema.storeRow)
+        .where(and(eq(schema.storeRow.wizardId, scope.wizardId), eq(schema.storeRow.holder, scope.holder)));
+    await db.delete(schema.storeFile).where(ownFiles(scope));
+    await db.delete(schema.storeSecret).where(ownSecrets(scope));
+    await db
+        .delete(schema.storeHolder)
+        .where(and(eq(schema.storeHolder.wizardId, scope.wizardId), eq(schema.storeHolder.holder, scope.holder)));
+}
+/** Stores nobody used for STORE_TTL_DAYS are deleted — a visitor's cookie is long gone by then. */
+export async function purgeUnusedStores() {
+    const cutoff = new Date(Date.now() - env.limits.storeTtlDays * 24 * 60 * 60 * 1000);
+    const stale = await db.query.storeHolder.findMany({
+        where: lt(schema.storeHolder.usedAt, cutoff),
+    });
+    for (const scope of stale) {
+        await clearStore(scope);
+    }
+    return stale.length;
+}

package/apps/runtime/dist/store/shared-lists.js

@@ -0,0 +1,123 @@
+import { firstRowAt, newCells, patchCells, rowKey, STORE_LIMITS, } from "@engenty-wizards/shared/store";
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { StoreError } from "./errors.js";
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** The table a shared list is kept in: made the first time, following the list as it changes. */
+export async function sharedTable(wizardId, def) {
+    const where = and(eq(schema.spaceTable.wizardId, wizardId), eq(schema.spaceTable.list, def.id));
+    const found = await db.query.spaceTable.findFirst({ where });
+    const shape = { title: def.title, columns: def.columns, keyColumn: def.key ?? null };
+    if (found) {
+        if (found.title !== shape.title ||
+            found.keyColumn !== shape.keyColumn ||
+            !same(found.columns, shape.columns)) {
+            await db
+                .update(schema.spaceTable)
+                .set({ ...shape, updatedAt: new Date() })
+                .where(eq(schema.spaceTable.id, found.id));
+            return { ...found, ...shape };
+        }
+        return found;
+    }
+    const wizard = await db.query.wizard.findFirst({
+        where: eq(schema.wizard.id, wizardId),
+        columns: { projectId: true, tenantId: true },
+    });
+    if (!wizard) {
+        throw new StoreError("The wizard is gone.");
+    }
+    // Two runs that start at once make it once.
+    await db
+        .insert(schema.spaceTable)
+        .values({ id: nanoid(12), ...wizard, wizardId, list: def.id, ...shape })
+        .onConflictDoNothing();
+    const made = await db.query.spaceTable.findFirst({ where });
+    if (!made) {
+        throw new StoreError(`List "${def.id}" could not be made.`);
+    }
+    return made;
+}
+async function touch(tableId) {
+    await db
+        .update(schema.spaceTable)
+        .set({ updatedAt: new Date() })
+        .where(eq(schema.spaceTable.id, tableId));
+}
+function toRow(r) {
+    return { id: r.id, cells: r.cells, updatedAt: r.updatedAt.toISOString() };
+}
+export async function sharedRows(wizardId, def) {
+    const table = await sharedTable(wizardId, def);
+    const rows = await db.query.spaceTableRow.findMany({
+        where: eq(schema.spaceTableRow.tableId, table.id),
+        orderBy: [asc(schema.spaceTableRow.createdAt), asc(schema.spaceTableRow.id)],
+    });
+    return rows.map(toRow);
+}
+/** As `saveRows` does for one person's list: a row with a known key updates that row. */
+export async function saveSharedRows(wizardId, def, input) {
+    const table = await sharedTable(wizardId, def);
+    const existing = await db.query.spaceTableRow.findMany({
+        where: eq(schema.spaceTableRow.tableId, table.id),
+    });
+    const byKey = new Map(existing.filter((r) => r.key).map((r) => [r.key, r]));
+    let count = existing.length;
+    const at = firstRowAt(existing);
+    let added = 0;
+    let updated = 0;
+    for (const raw of input) {
+        const key = rowKey(def, raw);
+        const hit = key ? byKey.get(key) : undefined;
+        if (hit) {
+            const cells = patchCells(def, hit.cells, raw);
+            await db
+                .update(schema.spaceTableRow)
+                .set({ cells, updatedAt: new Date() })
+                .where(eq(schema.spaceTableRow.id, hit.id));
+            hit.cells = cells;
+            updated++;
+            continue;
+        }
+        const cells = newCells(def, raw);
+        if (Object.values(cells).every((v) => v === null)) {
+            continue;
+        }
+        if (count >= STORE_LIMITS.rowsPerList) {
+            throw new StoreError(`List "${def.id}" is full (${STORE_LIMITS.rowsPerList} rows).`);
+        }
+        const row = { id: nanoid(14), tableId: table.id, key, cells, createdAt: new Date(at + added) };
+        await db.insert(schema.spaceTableRow).values(row);
+        if (key) {
+            byKey.set(key, { ...row, updatedAt: new Date() });
+        }
+        count++;
+        added++;
+    }
+    if (added || updated) {
+        await touch(table.id);
+    }
+    return { added, updated };
+}
+/** Deletes rows by id, or by the value of the key column. */
+export async function deleteSharedRows(wizardId, def, idsOrKeys) {
+    if (!idsOrKeys.length) {
+        return 0;
+    }
+    const table = await sharedTable(wizardId, def);
+    const keys = idsOrKeys.map((k) => k.trim().toLowerCase());
+    const inTable = eq(schema.spaceTableRow.tableId, table.id);
+    const byId = await db
+        .delete(schema.spaceTableRow)
+        .where(and(inTable, inArray(schema.spaceTableRow.id, idsOrKeys)))
+        .returning({ id: schema.spaceTableRow.id });
+    const byKey = await db
+        .delete(schema.spaceTableRow)
+        .where(and(inTable, inArray(schema.spaceTableRow.key, keys)))
+        .returning({ id: schema.spaceTableRow.id });
+    if (byId.length + byKey.length) {
+        await touch(table.id);
+    }
+    return byId.length + byKey.length;
+}

package/apps/runtime/dist/tenants/control.js

@@ -0,0 +1,238 @@
+import { and, count, eq, gte, inArray, isNull, lt, or, sql } from "drizzle-orm";
+import { control, controlDb } from "../db/client.js";
+import { env } from "../env.js";
+import { currentTenant } from "./tenant.js";
+/** Remembers which tenant a public token belongs to. */
+export async function putLink(token, kind, ref) {
+    await controlDb
+        .insert(control.link)
+        .values({ token, tenantId: currentTenant(), kind, ref })
+        .onConflictDoUpdate({
+        target: control.link.token,
+        set: { tenantId: currentTenant(), kind, ref },
+    });
+}
+/** A token's link goes, and with a wizard's share token its ID. */
+export async function dropLinks(tokens) {
+    if (tokens.length) {
+        await controlDb.delete(control.link).where(inArray(control.link.token, tokens));
+        await controlDb
+            .delete(control.link)
+            .where(and(eq(control.link.kind, "code"), inArray(control.link.ref, tokens)));
+    }
+}
+// --- wizard IDs ----------------------------------------------------------------------
+// The share token is 14 characters of both cases, `_` and `-`: nobody types that on a phone.
+// The ID is 8 capitals and digits without look-alikes (no 0 O 1 I), made the first time someone
+// asks for it and gone when the share token rotates.
+const CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ";
+const CODE_LENGTH = 8;
+function newCode() {
+    const bytes = crypto.getRandomValues(new Uint8Array(CODE_LENGTH));
+    return Array.from(bytes, (b) => CODE_ALPHABET[b % CODE_ALPHABET.length]).join("");
+}
+/** What a person typed, as stored: capitals, no spaces or dashes. */
+export const normalizeCode = (input) => input.toUpperCase().replace(/[\s-]/g, "");
+/** The ID of a wizard's share token; made on the first ask. */
+export async function codeOf(shareToken) {
+    const row = await controlDb.query.link.findFirst({
+        where: and(eq(control.link.kind, "code"), eq(control.link.ref, shareToken)),
+    });
+    if (row) {
+        return row.token;
+    }
+    for (;;) {
+        const code = newCode();
+        const made = await controlDb
+            .insert(control.link)
+            .values({ token: code, tenantId: currentTenant(), kind: "code", ref: shareToken })
+            .onConflictDoNothing()
+            .returning({ token: control.link.token });
+        if (made.length) {
+            return code;
+        }
+    }
+}
+/** The share token behind an ID, and its tenant. */
+export async function tokenOfCode(input) {
+    const code = normalizeCode(input);
+    if (code.length !== CODE_LENGTH) {
+        return null;
+    }
+    const row = await controlDb.query.link.findFirst({
+        where: and(eq(control.link.kind, "code"), eq(control.link.token, code)),
+    });
+    return row ? { token: row.ref, tenantId: row.tenantId } : null;
+}
+export async function tenantOfLink(token, kind) {
+    const row = await controlDb.query.link.findFirst({
+        where: and(eq(control.link.token, token), eq(control.link.kind, kind)),
+    });
+    return row?.tenantId ?? null;
+}
+// --- runs ----------------------------------------------------------------------
+const runTenants = new Map();
+export async function indexRun(input) {
+    const tenantId = currentTenant();
+    runTenants.set(input.runId, tenantId);
+    await controlDb.insert(control.runIndex).values({
+        runId: input.runId,
+        tenantId,
+        visitorId: input.visitorId ?? null,
+        ipHash: input.ipHash ?? null,
+    });
+}
+export async function tenantOfRun(runId) {
+    const known = runTenants.get(runId);
+    if (known) {
+        return known;
+    }
+    const row = await controlDb.query.runIndex.findFirst({
+        where: eq(control.runIndex.runId, runId),
+    });
+    if (row) {
+        runTenants.set(runId, row.tenantId);
+        if (runTenants.size > 5000) {
+            runTenants.delete(runTenants.keys().next().value);
+        }
+    }
+    return row?.tenantId ?? null;
+}
+export async function dropRuns(runIds) {
+    for (const id of runIds) {
+        runTenants.delete(id);
+    }
+    for (let i = 0; i < runIds.length; i += 200) {
+        await controlDb
+            .delete(control.runIndex)
+            .where(inArray(control.runIndex.runId, runIds.slice(i, i + 200)));
+    }
+}
+// --- the queue: which runner works on which run ---------------------------------
+// `active` = the run wants a runner. `owner` = the one driving it, `seen` = its last heartbeat.
+/** An owner silent this long has lost the run: another runner takes it. */
+export const RUNNER_STALE_MS = 30_000;
+/** Puts a run in line for a runner (again): active, owned by nobody. */
+export async function wakeRun(runId) {
+    await controlDb
+        .update(control.runIndex)
+        .set({ active: true, owner: null, seen: null })
+        .where(eq(control.runIndex.runId, runId));
+}
+/** The run is done with runners for now: a page, a review or the end. */
+export async function restRun(runId) {
+    await controlDb
+        .update(control.runIndex)
+        .set({ active: false, owner: null, seen: null })
+        .where(eq(control.runIndex.runId, runId));
+}
+/**
+ * Takes a run for this runner, in one statement: only while nobody (alive) holds it and the
+ * tenant's owned runs stay under its limit. False: someone else has it, or the tenant is at its
+ * limit — the run stays in line.
+ */
+export async function claimRun(runId, tenantId, limit) {
+    const now = Date.now();
+    const stale = now - RUNNER_STALE_MS;
+    const result = await controlDb.run(sql `
+    UPDATE run_index SET owner = ${env.runner.id}, seen = ${now}
+    WHERE run_id = ${runId} AND active = 1
+      AND (owner IS NULL OR seen IS NULL OR seen < ${stale})
+      AND (SELECT count(*) FROM run_index
+           WHERE tenant_id = ${tenantId} AND owner IS NOT NULL AND seen >= ${stale}
+             AND run_id != ${runId}) < ${limit}`);
+    return result.rowsAffected > 0;
+}
+/** This runner still works on these runs. */
+export async function heartbeatRuns(runIds) {
+    if (runIds.length) {
+        await controlDb
+            .update(control.runIndex)
+            .set({ seen: new Date() })
+            .where(and(eq(control.runIndex.owner, env.runner.id), inArray(control.runIndex.runId, runIds)));
+    }
+}
+/** A runner that stops hands its runs back to the line; another takes them at once. */
+export async function disownRuns() {
+    await controlDb
+        .update(control.runIndex)
+        .set({ owner: null, seen: null })
+        .where(eq(control.runIndex.owner, env.runner.id));
+}
+/** The runs in line: unowned, or whose owner fell silent. */
+export async function waitingRuns() {
+    const stale = new Date(Date.now() - RUNNER_STALE_MS);
+    return controlDb
+        .select({ runId: control.runIndex.runId, tenantId: control.runIndex.tenantId })
+        .from(control.runIndex)
+        .where(and(eq(control.runIndex.active, true), or(isNull(control.runIndex.owner), isNull(control.runIndex.seen), lt(control.runIndex.seen, stale))))
+        .orderBy(control.runIndex.createdAt);
+}
+/** Where the runner holding a run is reached; null when none holds it or it named no address. */
+export async function ownerUrl(runId) {
+    const row = await controlDb.query.runIndex.findFirst({
+        where: eq(control.runIndex.runId, runId),
+    });
+    if (!row?.owner || !row.seen || row.seen.getTime() < Date.now() - RUNNER_STALE_MS) {
+        return null;
+    }
+    const who = await controlDb.query.runner.findFirst({ where: eq(control.runner.id, row.owner) });
+    return who?.url || null;
+}
+/** This process reports as a runner: its address, and that it is alive. */
+export async function registerRunner() {
+    const now = new Date();
+    await controlDb
+        .insert(control.runner)
+        .values({ id: env.runner.id, url: env.runner.url || null, seen: now })
+        .onConflictDoUpdate({
+        target: control.runner.id,
+        set: { url: env.runner.url || null, seen: now },
+    });
+    // Runners gone for a day are forgotten.
+    await controlDb
+        .delete(control.runner)
+        .where(lt(control.runner.seen, new Date(now.getTime() - 86_400_000)));
+}
+export async function forgetRunner() {
+    await controlDb.delete(control.runner).where(eq(control.runner.id, env.runner.id));
+}
+/** A visitor's runs are counted across every wizard of every tenant. */
+export async function visitorOverLimit(visitorId, ipHash) {
+    const since = new Date(Date.now() - 3600_000);
+    const who = ipHash
+        ? or(eq(control.runIndex.visitorId, visitorId), eq(control.runIndex.ipHash, ipHash))
+        : eq(control.runIndex.visitorId, visitorId);
+    const [{ n }] = await controlDb
+        .select({ n: count() })
+        .from(control.runIndex)
+        .where(and(who, gte(control.runIndex.createdAt, since)));
+    return n >= env.limits.visitorRunsPerHour;
+}
+// --- tenants ---------------------------------------------------------------------
+export async function tenantStatus(id) {
+    const row = await controlDb.query.tenant.findFirst({ where: eq(control.tenant.id, id) });
+    return row?.status ?? null;
+}
+export async function setTenantStatus(id, status) {
+    await controlDb.update(control.tenant).set({ status }).where(eq(control.tenant.id, id));
+}
+/** Everything the control database knows about a tenant goes with it. */
+export async function forgetTenantRows(id) {
+    await controlDb.delete(control.link).where(eq(control.link.tenantId, id));
+    await controlDb.delete(control.runIndex).where(eq(control.runIndex.tenantId, id));
+    await controlDb.delete(control.session).where(eq(control.session.tenantId, id));
+    await controlDb.delete(control.tenant).where(eq(control.tenant.id, id));
+    for (const [runId, tenantId] of runTenants) {
+        if (tenantId === id) {
+            runTenants.delete(runId);
+        }
+    }
+}
+/** The line's view of one run: which tenant it belongs to, whether it is awake. */
+export async function runIndexOf(runId) {
+    const row = await controlDb.query.runIndex.findFirst({
+        where: eq(control.runIndex.runId, runId),
+    });
+    return row ? { tenantId: row.tenantId, active: row.active } : null;
+}

package/apps/runtime/dist/tenants/tenant.js

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** The tenant a request, a run or a background job works for. Set once per entry, never from a request body. */
+const current = new AsyncLocalStorage();
+export class NoTenantError extends Error {
+    constructor() {
+        super("No tenant in context: tenant tables are reached only inside inTenant().");
+    }
+}
+export function inTenant(tenantId, fn) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(tenantId)) {
+        throw new Error("bad tenant id");
+    }
+    return current.run({ tenantId }, fn);
+}
+export function currentTenant() {
+    const store = current.getStore();
+    if (!store) {
+        throw new NoTenantError();
+    }
+    return store.tenantId;
+}
+export function currentTenantOrNull() {
+    return current.getStore()?.tenantId ?? null;
+}
+/** The one tenant of a runtime that runs alone (desktop app, own machine). */
+export const LOCAL_TENANT = "local";