@everystack/server 0.4.36 → 0.4.38

package/src/purge.ts

@@ -0,0 +1,337 @@
+/** Real lifecycle removal. Provision ENSURE_PURGE_LOG_SQL on the owner connection first. */
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { sql, type SQL } from 'drizzle-orm';
+import type { ModelDescriptor, DestroyContext } from '@everystack/model';
+import type { SessionTx } from './db-session';
+import { unsupportedPurgeGraphs } from './purge-graph';
+export { ENSURE_PURGE_LOG_SQL } from './purge-log';
+
+/** A destroy hook failed after physical removal committed. */
+export interface PurgeHookFault {
+  kind: 'hook';
+  name: string;
+  method: 'DELETE';
+  status: 500;
+  table: string;
+  key: string;
+  message: string;
+  stack?: string;
+}
+export interface PurgeOptions {
+  /** Retention in milliseconds, strictly positive. */
+  after: number;
+  /** Maximum rows physically purged across all tables. */
+  batch: number;
+  /** One clock for both selection and receipts. Defaults to the run's start. */
+  now?: Date;
+  /** Elapsed-time budget, checked between rows; a current transaction finishes. Default 30000. */
+  budgetMs?: number;
+  /** Cooldown for skipped or failed keys, in milliseconds. Default one hour. Zero disables it. */
+  retryAfterMs?: number;
+  /** After-commit hook faults; a sink failure cannot undo removal or stop the run. */
+  onError?: (fault: PurgeHookFault) => void | Promise<void>;
+}
+export interface PurgeCounts { purged: number; skipped: number; failed: number; }
+export interface PurgeResult {
+  runId: string;
+  perTable: Record<string, PurgeCounts>;
+  noHook: string[];
+  skipped: { table: string; key: string; reason: string }[];
+  afterDestroyErrors: number;
+  afterDestroyFailures: { table: string; key: string; message: string }[];
+  incomplete?: true;
+  /** Why no rows were purged, when the run removed none. */
+  reason?: string;
+}
+
+type Row = Record<string, unknown>;
+type Receipt = { model: ModelDescriptor; row: Row; outcome: 'purged' | 'skipped' | 'failed'; hook: 'ran' | 'none' | 'failed'; detail?: string };
+const context: DestroyContext = Object.freeze({ source: 'purge', user: null, client: null });
+const param = (value: unknown): unknown => value instanceof Date ? value.toISOString() : typeof value === 'bigint' ? value.toString() : value;
+const snake = (name: string): string => name.replace(/[A-Z]/g, c => '_' + c.toLowerCase());
+const label = (m: ModelDescriptor): string => `${m.schema}.${m.table}`;
+const table = (m: ModelDescriptor): SQL => sql`${sql.identifier(m.schema)}.${sql.identifier(m.table)}`;
+const column = (key: string): SQL => sql`${sql.identifier(snake(key))}`;
+const rowsOf = (result: unknown): Row[] => Array.isArray(result) ? result : (result as { rows: Row[] }).rows;
+function fieldParam(model: ModelDescriptor, key: string, value: unknown): unknown {
+  const spec = model.fields[key].spec;
+  if (spec.isArray) return sql`(jsonb_populate_record(NULL::${table(model)}, jsonb_build_object(${snake(key)}::text, ${JSON.stringify(value)}::jsonb))).${column(key)}`;
+  const type = spec.type;
+  return type === 'json' || type === 'jsonb' ? JSON.stringify(value) : param(value);
+}
+
+/** Keep timestamp key identity independent of the session timezone without losing microseconds. */
+function keyValue(model: ModelDescriptor, key: string, row: Row): unknown {
+  const value = row[snake(key)];
+  if (value instanceof Uint8Array) return '\\x' + Buffer.from(value).toString('hex');
+  const spec = model.fields[key].spec;
+  if (spec.isArray || spec.type === 'json' || spec.type === 'jsonb') return JSON.stringify(value);
+  const type = spec.type === 'pgType' ? spec.pgTypeName : spec.type;
+  if (!/^(timestamptz|timestamp(?:\(\d+\))? with time zone)$/i.test(type ?? '')) return param(value);
+  if (value === 'infinity' || value === '-infinity') return value;
+  const date = value instanceof Date ? value : new Date(String(value));
+  if (!Number.isFinite(date.getTime())) throw new Error(`purge cannot normalize timestamp key on ${label(model)}`);
+  const iso = date.toISOString();
+  const fraction = typeof value === 'string' ? value.match(/\.(\d+)/)?.[1] : undefined;
+  const precise = (fraction ?? iso.match(/\.(\d+)Z$/)![1]).replace(/0+$/, '').padEnd(3, '0');
+  return iso.replace(/\.\d{3}Z$/, `.${precise}Z`);
+}
+const keyValues = (m: ModelDescriptor, row: Row): unknown[] => m.primaryKey.map(k => keyValue(m, k, row));
+function keyOf(model: ModelDescriptor, row: Row): string {
+  const values = keyValues(model, row);
+  if (values.length !== 1) return JSON.stringify(values);
+  return typeof values[0] === 'object' ? JSON.stringify(values[0]) : String(values[0]);
+}
+const keyWhere = (m: ModelDescriptor, row: Row): SQL => sql.join(m.primaryKey.map(k => sql`${column(k)} = ${fieldParam(m, k, row[snake(k)])}`), sql` AND `);
+const hookRow = (m: ModelDescriptor, row: Row): Row => Object.fromEntries(Object.keys(m.fields).map(k => [k, row[snake(k)]]));
+
+/** Compare keys as their native type while guarding casts from other tables' receipts. */
+function cooldownKeyMatches(model: ModelDescriptor): SQL {
+  const key = model.primaryKey[0];
+  const spec = model.fields[key].spec;
+  const type = spec.type === 'pgType' ? spec.pgTypeName ?? '' : spec.type;
+  const candidate = sql`${table(model)}.${column(key)}`;
+  const ownKey = sql`CASE WHEN receipt."table" = ${label(model)} THEN receipt."key" END`;
+  if (spec.isArray) {
+    return sql`(jsonb_populate_record(NULL::${table(model)}, jsonb_build_object(${snake(key)}::text, ${ownKey}::jsonb))).${column(key)} = ${candidate}`;
+  }
+  if (type === 'json' || type === 'jsonb') return sql`${ownKey}::jsonb = ${candidate}`;
+  if (/^(timestamptz|timestamp(?:\(\d+\))? with time zone)$/i.test(type)) return sql`${ownKey}::timestamptz = ${candidate}`;
+  if (/^timestamp(?:\(\d+\))?(?: without time zone)?$/i.test(type)) return sql`${ownKey}::timestamp = ${candidate}`;
+  if (type === 'real') return sql`${ownKey}::real = ${candidate}`;
+  if (type === 'doublePrecision' || type === 'double precision') return sql`${ownKey}::double precision = ${candidate}`;
+  if (type === 'bytea') return sql`${ownKey}::bytea = ${candidate}`;
+  if (type === 'date') return sql`${ownKey}::date = ${candidate}`;
+  return sql`receipt."key" = ${candidate}::text`;
+}
+
+/** Every declared lifecycle edge orders the child before the parent, nullify included. */
+function orderedModels(models: ModelDescriptor[]): ModelDescriptor[] {
+  const lifecycle = models.filter(m => m.lifecycle);
+  const set = new Set(lifecycle);
+  const visiting = new Set<ModelDescriptor>();
+  const visited = new Set<ModelDescriptor>();
+  const ordered: ModelDescriptor[] = [];
+  const visit = (m: ModelDescriptor): void => {
+    if (visiting.has(m)) throw new Error(`purge relation cycle at ${label(m)}`);
+    if (visited.has(m)) return;
+    visiting.add(m);
+    for (const rel of Object.values(m.relations)) {
+      if (rel.kind === 'hasMany' && rel.dependent) {
+        const child = rel.target();
+        if (child.lifecycle && !set.has(child)) throw new Error(`purge needs declared child ${label(child)}`);
+        if (set.has(child)) visit(child);
+      }
+    }
+    visiting.delete(m); visited.add(m); ordered.push(m);
+  };
+  for (const m of lifecycle) {
+    if (m.primaryKey.length !== 1) throw new Error(`purge needs a single-column primary key on ${label(m)}`);
+    visit(m);
+  }
+  return ordered;
+}
+
+async function appendReceipt(tx: SessionTx, runId: string, now: Date, receipt: Receipt): Promise<void> {
+  const { model, row, outcome, hook, detail } = receipt;
+  await tx.execute(sql`SET LOCAL ROLE everystack_lifecycle`);
+  await tx.execute(sql`INSERT INTO everystack.purge_log
+    (run_id, "table", "key", deleted_batch, deleted_at, purged_at, actor, outcome, hook, detail)
+    VALUES (${runId}, ${label(model)}, ${keyOf(model, row)}, ${row.deleted_batch}, ${param(row.deleted_at)}, ${now.toISOString()}, 'purge', ${outcome}, ${hook}, ${detail ?? null})`);
+}
+
+/**
+ * Purge expired lifecycle rows, children first, in one transaction per selected row.
+ * The executor is the existing ops Drizzle database (execute/transaction); its caller
+ * must read the selected tables and purge_log, and SET ROLE to everystack_lifecycle. Hooks run outside
+ * that role after DELETE and immediate constraint checks; a hook throw rolls back the
+ * removal. A successful hook can repeat if commit fails, so it must be idempotent. A skipped row appends another
+ * skipped receipt on each retry. Plain children with ON DELETE CASCADE are removed by
+ * referential integrity; they receive neither a destroy hook nor a purge receipt.
+ * The receipt's hook status describes beforeDestroy. afterDestroy is best-effort after
+ * commit and cannot change that append-only receipt or undo the physical removal.
+ */
+export async function purgeExpired(exec: SessionTx, models: ModelDescriptor[], options: PurgeOptions): Promise<PurgeResult> {
+  const started = performance.now();
+  const after = options.after;
+  const batch = options.batch;
+  const budgetMs = options.budgetMs ?? 30_000;
+  const retryAfterMs = options.retryAfterMs ?? 3_600_000;
+  if (!Number.isFinite(budgetMs) || budgetMs < 0) throw new Error('purge budgetMs must be nonnegative milliseconds');
+  if (!Number.isFinite(retryAfterMs) || retryAfterMs < 0) throw new Error('purge retryAfterMs must be nonnegative milliseconds');
+  const outOfBudget = (): boolean => performance.now() - started >= budgetMs;
+  if (!Number.isFinite(after) || after <= 0) throw new Error('purge after must be positive milliseconds');
+  if (!Number.isSafeInteger(batch) || batch <= 0) throw new Error('purge batch must be a positive integer');
+  const now = new Date(options.now?.getTime() ?? Date.now());
+  const cutoff = new Date(now.getTime() - after);
+  if (!Number.isFinite(now.getTime()) || !Number.isFinite(cutoff.getTime())) throw new Error('purge needs a valid clock');
+  const retryCutoff = new Date(now.getTime() - retryAfterMs);
+  if (!Number.isFinite(retryCutoff.getTime())) throw new Error('purge retryAfterMs exceeds clock range');
+  const ordered = orderedModels(models);
+  const result: PurgeResult = { runId: randomUUID(), perTable: {}, noHook: [], skipped: [], afterDestroyErrors: 0, afterDestroyFailures: [] };
+  let purged = 0;
+  const finish = (incomplete = false): PurgeResult => {
+    if (incomplete) result.incomplete = true;
+    if (purged === 0) result.reason = incomplete ? 'time budget exhausted'
+      : result.skipped[0]?.reason ?? 'no expired lifecycle rows';
+    return result;
+  };
+  if (outOfBudget()) return finish(true);
+  const unsupported = await unsupportedPurgeGraphs(exec, models);
+  for (const model of ordered) {
+    const name = label(model);
+    const counts = result.perTable[name] = { purged: 0, skipped: 0, failed: 0 };
+    const unsupportedReason = unsupported.get(name);
+    if (unsupportedReason) {
+      // '*' is a table-level refusal, not an attempted row or an audit receipt.
+      result.skipped.push({ table: name, key: '*', reason: unsupportedReason });
+      continue;
+    }
+    const attempted = new Set<string>();
+    let cursor: Row | undefined;
+    while (purged < batch) {
+      if (outOfBudget()) return finish(true);
+      const tuple = sql.join([sql`deleted_at`, ...model.primaryKey.map(column)], sql`, `);
+      const cursorValues = cursor ? sql.join([sql`${param(cursor.deleted_at)}`, ...model.primaryKey.map(k => sql`${fieldParam(model, k, cursor![snake(k)])}`)], sql`, `) : undefined;
+      const cooldown = retryAfterMs > 0 ? sql`AND NOT EXISTS (
+        SELECT 1 FROM everystack.purge_log AS receipt
+        WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
+          AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+      )` : sql``;
+      const page = rowsOf(await exec.execute(sql`SELECT * FROM ${table(model)}
+        WHERE deleted_at <= ${cutoff.toISOString()} ${cooldown} ${cursorValues ? sql`AND (${tuple}) > (${cursorValues})` : sql``}
+        ORDER BY ${tuple} LIMIT ${Math.min(100, batch - purged)}`));
+      if (!page.length) {
+        if (retryAfterMs > 0 && purged === 0 && result.skipped.length === 0) {
+          const expired = rowsOf(await exec.execute(sql`SELECT 1 FROM ${table(model)} WHERE deleted_at <= ${cutoff.toISOString()} LIMIT 1`));
+          if (expired.length) result.skipped.push({ table: name, key: '*', reason: 'retry cooldown' });
+        }
+        break;
+      }
+      for (const candidate of page) {
+        cursor = candidate;
+        if (outOfBudget()) return finish(true);
+        const candidateKey = keyOf(model, candidate);
+        if (attempted.has(candidateKey)) continue;
+        attempted.add(candidateKey);
+        let selected: Row | undefined;
+        let beforeFailed = false;
+        let beforeRan = false;
+        let skippedReason: string | undefined;
+        let failureReason: string | undefined;
+        const removed = await exec.transaction(async tx => {
+          const [isolation] = rowsOf(await tx.execute(sql`SHOW transaction_isolation`));
+          if (isolation?.transaction_isolation !== 'read committed') throw new Error('purge requires READ COMMITTED');
+          const locked = rowsOf(await tx.execute(sql`SELECT * FROM ${table(model)}
+            WHERE ${keyWhere(model, candidate)} AND deleted_at <= ${cutoff.toISOString()} FOR UPDATE SKIP LOCKED`));
+          selected = locked[0];
+          if (!selected) return false;
+          const row = selected;
+          // Selection precedes the row lock. Another run may have committed a failure since then.
+          if (retryAfterMs > 0) {
+            const cooling = rowsOf(await tx.execute(sql`SELECT 1 FROM ${table(model)}
+              WHERE ${keyWhere(model, row)} AND EXISTS (
+                SELECT 1 FROM everystack.purge_log AS receipt
+                WHERE receipt."table" = ${name} AND ${cooldownKeyMatches(model)}
+                  AND receipt.outcome IN ('skipped', 'failed') AND receipt.purged_at > ${retryCutoff.toISOString()}
+              )`));
+            if (cooling.length) { skippedReason = 'retry cooldown'; return false; }
+          }
+          try {
+            // Keep the row lock outside the savepoint, including while recording a failed attempt.
+            return await tx.transaction(async work => {
+              for (const rel of Object.values(model.relations)) {
+                const child = rel.kind === 'hasMany' && (rel.dependent === 'cascade' || rel.dependent === 'restrict') ? rel.target() : undefined;
+                if (!child?.lifecycle) continue;
+                const reference = rel.references ?? model.primaryKey[0];
+                const remains = rowsOf(await work.execute(sql`SELECT 1 FROM ${table(child)} WHERE ${column(rel.column)} = ${fieldParam(model, reference, row[snake(reference)])} LIMIT 1`));
+                if (remains.length) {
+                  skippedReason = `remaining lifecycle child ${label(child)}`;
+                  await appendReceipt(work, result.runId, now, { model, row, outcome: 'skipped', hook: 'none', detail: skippedReason });
+                  return false;
+                }
+              }
+              const caller = model.hooks?.beforeDestroy
+                ? rowsOf(await work.execute(sql`SELECT current_user AS role`))[0] : undefined;
+              await work.execute(sql`SET LOCAL ROLE everystack_lifecycle`);
+              const deleted = rowsOf(await work.execute(sql`DELETE FROM ${table(model)} WHERE ${keyWhere(model, row)} RETURNING ${sql.join(model.primaryKey.map(column), sql`, `)}`));
+              if (deleted.length !== 1 || keyOf(model, deleted[0]) !== keyOf(model, row)) throw new Error('purge DELETE did not return the locked key');
+              // Refuse deferred constraints before invoking a hook with external effects.
+              await work.execute(sql`SET CONSTRAINTS ALL IMMEDIATE`);
+              if (caller) await work.execute(sql`SET LOCAL ROLE ${sql.identifier(String(caller.role))}`);
+              if (model.hooks?.beforeDestroy) {
+                try { await model.hooks.beforeDestroy(hookRow(model, row), context); beforeRan = true; }
+                catch (error) { beforeFailed = true; throw error; }
+              }
+              await appendReceipt(work, result.runId, now, { model, row, outcome: 'purged', hook: beforeRan ? 'ran' : 'none' });
+              return true;
+            });
+          } catch (error) {
+            failureReason = error instanceof Error ? error.message : String(error);
+            await appendReceipt(tx, result.runId, now, { model, row, outcome: 'failed', hook: beforeFailed ? 'failed' : beforeRan ? 'ran' : 'none', detail: failureReason });
+            return false;
+          }
+        });
+        if (failureReason !== undefined) {
+          counts.failed++;
+          result.skipped.push({ table: name, key: keyOf(model, selected!), reason: failureReason });
+          continue;
+        }
+        if (skippedReason) {
+          counts.skipped++;
+          result.skipped.push({ table: name, key: keyOf(model, candidate), reason: skippedReason });
+        }
+        if (!removed) {
+          if (!selected) {
+            counts.skipped++;
+            result.skipped.push({ table: name, key: candidateKey, reason: 'row locked or no longer expired' });
+          }
+          continue;
+        }
+        purged++; counts.purged++;
+        if (!model.hooks?.beforeDestroy && !model.hooks?.afterDestroy && !result.noHook.includes(name)) result.noHook.push(name);
+        if (model.hooks?.afterDestroy) {
+          try { await model.hooks.afterDestroy(hookRow(model, selected!), context); }
+          catch (error) {
+            // Formatting an arbitrary rejection must not lose a committed outcome.
+            let message = 'unreadable error';
+            let stack: string | undefined;
+            try { message = String(error instanceof Error ? error.message : error); } catch { /* Keep the fallback. */ }
+            try { stack = error instanceof Error ? error.stack : undefined; } catch { /* Stack is optional. */ }
+            const key = keyOf(model, selected!);
+            result.afterDestroyErrors++;
+            result.afterDestroyFailures.push({ table: name, key, message });
+            try {
+              await options.onError?.({ kind: 'hook', name: `${name}.afterDestroy`, method: 'DELETE', status: 500,
+                table: name, key, message: `after-hook failed after the write: ${message}`,
+                stack });
+            } catch { /* The observability sink cannot replace a committed outcome. */ }
+          }
+        }
+        if (purged >= batch) break;
+      }
+    }
+    if (purged >= batch) break;
+  }
+  return finish();
+}
+
+/** Count expired lifecycle rows without invoking hooks or changing data. */
+export async function overdueLifecycleRows(
+  exec: Pick<SessionTx, 'execute'>,
+  models: ModelDescriptor[],
+  options: { after: number },
+): Promise<Record<string, number>> {
+  if (!Number.isFinite(options.after) || options.after <= 0) throw new Error('purge after must be positive milliseconds');
+  const cutoff = new Date(Date.now() - options.after);
+  if (!Number.isFinite(cutoff.getTime())) throw new Error('purge after exceeds clock range');
+  const counts: Record<string, number> = {};
+  for (const model of models.filter(m => m.lifecycle)) {
+    const [row] = rowsOf(await exec.execute(sql`SELECT count(*) AS count FROM ${table(model)} WHERE deleted_at <= ${cutoff.toISOString()}`));
+    const count = Number(row.count);
+    if (!Number.isSafeInteger(count) || count < 0) throw new Error(`invalid overdue count on ${label(model)}`);
+    counts[label(model)] = count;
+  }
+  return counts;
+}

package/src/role-chain.ts

@@ -168,6 +168,32 @@ export function generateReaderRoleSQL(options: ReaderRoleOptions = {}): string {
   ].join('\n') + '\n';
 }
 
+/**
+ * The reserved role `lifecycle: true` models compile grants and policies to, and that owns their
+ * SECURITY DEFINER functions. Equal to LIFECYCLE_OWNER_ROLE in @everystack/model (this package
+ * keeps no dependency on it).
+ */
+export const LIFECYCLE_ROLE = 'everystack_lifecycle';
+
+/**
+ * Generate idempotent DDL for the reserved lifecycle role: create it if absent, then re-assert
+ * its attributes so a hand-made role is brought into line.
+ *
+ *   - NOLOGIN     — no one connects as it. It is a function owner and a grantee, not an identity.
+ *   - NOINHERIT   — it never ambiently gains another role's privileges.
+ *   - NOBYPASSRLS — its reads and writes go through the policies the compiler writes for it.
+ *
+ * It grants the role NOTHING and grants it TO no one. Membership is SET ROLE, and SET ROLE to it
+ * passes the lifecycle guard, so no tool hands membership out here (db:provision reports members).
+ */
+export function generateLifecycleRoleSQL(role: string = LIFECYCLE_ROLE): string {
+  assertIdent(role, 'lifecycle role');
+  return [
+    `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE ${role} NOLOGIN NOINHERIT NOBYPASSRLS; END IF; END $$;`,
+    `ALTER ROLE ${role} WITH NOLOGIN NOINHERIT NOBYPASSRLS;`,
+  ].join('\n') + '\n';
+}
+
 export interface ReaderGrantOptions {
   /** The SELECT-only login the grants are made TO. Default 'reader'. */
   readerRole?: string;