pgkiln 0.47.0 → 0.49.0

package/src/pgcron.ts

@@ -0,0 +1,225 @@
+import pg from 'pg';
+import { createHash } from 'node:crypto';
+import { owner, ownerUrl } from './db.ts';
+import { parseSchedule, ScheduleError } from './cron-schedule.ts';
+
+// (sprint 101, Database Actions DA-12) pg_cron for SQL Workshop › Scheduling (src/builder/scheduling.ts): whether it
+// can be used here, its jobs and runs, the SQL that changes them (shown to the administrator before it runs) and
+// Run now. Schedules are parsed and explained by src/cron-schedule.ts; pg_cron itself decides what it accepts.
+
+export type CronState =
+  | { ok: true; version: string; timeZone: string; user: string; database: string; seesAll: boolean }
+  | { ok: false; reason: 'not_available' | 'not_loaded' | 'other_database' | 'not_created' | 'no_access' | 'old'; database: string; cronDatabase: string | null; message?: string };
+
+const FUNCTIONS = ['cron.schedule_in_database(text,text,text,text,text,boolean)', 'cron.alter_job(bigint,text,text,text,text,boolean)', 'cron.unschedule(bigint)'];
+
+/** Can pg_cron be used from pgkiln's owner connection, and if not, why. */
+export async function cronState(): Promise<CronState> {
+  const info = (await owner.one<{ version: string | null; available: boolean; preload: string; cron_db: string | null; database: string; user: string; tz: string | null; job: boolean; funcs: boolean; sees_all: boolean }>(
+    `select (select extversion from pg_extension where extname = 'pg_cron') as version,
+            exists (select 1 from pg_available_extensions where name = 'pg_cron') as available,
+            current_setting('shared_preload_libraries') as preload,
+            current_setting('cron.database_name', true) as cron_db,
+            current_database() as database, current_user as "user",
+            current_setting('cron.timezone', true) as tz,
+            to_regclass('cron.job') is not null and to_regclass('cron.job_run_details') is not null as job,
+            (select bool_and(to_regprocedure(f) is not null) from unnest($1::text[]) f) as funcs,
+            (select rolsuper or rolbypassrls from pg_roles where rolname = current_user) as sees_all`, [FUNCTIONS]))!;
+  const base = { database: info.database, cronDatabase: info.cron_db };
+  // a cron schema with pg_cron's tables and functions counts as installed (tests stand in for pg_cron with one)
+  if (!info.version && !info.job) {
+    if (!info.available) return { ok: false, reason: 'not_available', ...base };
+    if (!/(^|[\s,])"?pg_cron"?($|[\s,])/.test(info.preload)) return { ok: false, reason: 'not_loaded', ...base };
+    if ((info.cron_db ?? 'postgres') !== info.database) return { ok: false, reason: 'other_database', ...base, cronDatabase: info.cron_db ?? 'postgres' };
+    return { ok: false, reason: 'not_created', ...base };
+  }
+  if (!info.funcs) return { ok: false, reason: 'old', ...base, message: info.version ?? undefined };
+  try {
+    await owner.query('select 1 from cron.job limit 1');
+    await owner.query('select 1 from cron.job_run_details limit 1');
+  } catch (e) {
+    return { ok: false, reason: 'no_access', ...base, message: (e as Error).message };
+  }
+  return { ok: true, version: info.version ?? '(no extension)', timeZone: info.tz || 'GMT', user: info.user, database: info.database, seesAll: info.sees_all };
+}
+
+export interface Job {
+  jobid: string;
+  jobname: string | null;
+  schedule: string;
+  command: string;
+  database: string;
+  username: string;
+  active: boolean;
+  last_status: string | null;
+  last_start: string | null;
+  last_secs: number | null;
+  last_message: string | null;
+  failures: number;
+}
+
+const JOBS_SQL = `
+  select j.jobid::text as jobid, j.jobname, j.schedule, j.command, j.database, j.username, j.active,
+         r.status as last_status, to_char(r.start_time at time zone $1, 'YYYY-MM-DD HH24:MI:SS') as last_start,
+         round(extract(epoch from r.end_time - r.start_time)::numeric, 3)::float8 as last_secs, r.return_message as last_message,
+         (select count(*)::int from (select status from cron.job_run_details f where f.jobid = j.jobid order by f.runid desc limit 10) x where x.status = 'failed') as failures
+    from cron.job j
+    left join lateral (select d.status, d.start_time, d.end_time, d.return_message from cron.job_run_details d
+                        where d.jobid = j.jobid order by d.runid desc limit 1) r on true`;
+
+export const listJobs = async (timeZone: string) => (await owner.query<Job>(`${JOBS_SQL} order by lower(coalesce(j.jobname, '')), j.jobid`, [timeZone])).rows;
+export const oneJob = async (timeZone: string, id: string) =>
+  /^\d{1,18}$/.test(id) ? ((await owner.one<Job>(`${JOBS_SQL} where j.jobid = $2::bigint`, [timeZone, id])) ?? null) : null;
+
+export interface Run {
+  runid: string;
+  jobid: string | null;
+  jobname: string | null;
+  database: string | null;
+  username: string | null;
+  command: string | null;
+  status: string | null;
+  return_message: string | null;
+  start: string | null;
+  secs: number | null;
+}
+
+export const RUN_STATUSES = ['starting', 'running', 'sending', 'connecting', 'succeeded', 'failed'];
+
+/** Runs, newest first: of one job, with a status, or whose message or command contains a text. */
+export async function listRuns(timeZone: string, f: { job?: string; status?: string; q?: string; limit?: number }) {
+  const where: string[] = [];
+  const params: unknown[] = [timeZone];
+  if (f.job && /^\d{1,18}$/.test(f.job)) where.push(`d.jobid = $${params.push(f.job)}::bigint`);
+  if (f.status && RUN_STATUSES.includes(f.status)) where.push(`d.status = $${params.push(f.status)}`);
+  if (f.q) where.push(`(strpos(lower(d.return_message), lower($${params.push(f.q)})) > 0 or strpos(lower(d.command), lower($${params.length})) > 0)`);
+  return (await owner.query<Run>(
+    `select d.runid::text as runid, d.jobid::text as jobid, j.jobname, d.database, d.username, d.command, d.status, d.return_message,
+            to_char(d.start_time at time zone $1, 'YYYY-MM-DD HH24:MI:SS') as start,
+            round(extract(epoch from d.end_time - d.start_time)::numeric, 3)::float8 as secs
+       from cron.job_run_details d left join cron.job j on j.jobid = d.jobid
+      ${where.length ? `where ${where.join(' and ')}` : ''} order by d.runid desc limit ${Math.min(Math.max(f.limit ?? 200, 1), 1000)}`, params)).rows;
+}
+
+/** Runs older than a number of days (or all of one job's), as the purge would delete them. */
+export async function countPurge(days: number | null, job: string | null) {
+  const p = purgeWhere(days, job);
+  return (await owner.one<{ n: number }>(`select count(*)::int as n from cron.job_run_details ${p}`))!.n;
+}
+
+// ------------------------------------------------------------------ SQL
+
+export interface JobSpec {
+  name: string;
+  schedule: string;
+  command: string;
+  database: string;
+  username: string;
+  active: boolean;
+}
+
+export const lit = (v: string) => pg.escapeLiteral(v);
+
+/** The command as a dollar-quoted string (readable when it has quotes and lines), with a tag it doesn't contain. */
+export function dollar(v: string) {
+  let tag = '$cmd$';
+  for (let i = 1; v.includes(tag) || v.endsWith(tag.slice(0, -1)); i++) tag = `$cmd${i}$`;
+  return `${tag}${v}${tag}`;
+}
+
+/** What is wrong with a job (empty: nothing). */
+export function checkJob(spec: JobSpec, o: { databases: string[]; users: string[] }) {
+  const errors: string[] = [];
+  if (!spec.name) errors.push('Give the job a name.');
+  else if (spec.name.length > 100) errors.push('A name is at most 100 characters.');
+  else if (/[\x00-\x1f\x7f]/.test(spec.name)) errors.push('A name has no control characters.');
+  try {
+    parseSchedule(spec.schedule);
+  } catch (e) {
+    if (!(e instanceof ScheduleError)) throw e;
+    errors.push(`Schedule: ${e.message}`);
+  }
+  if (!spec.command.trim()) errors.push('Enter the SQL the job runs.');
+  else if (spec.command.length > 100_000) errors.push('The command is at most 100,000 characters.');
+  else if (spec.command.includes('\0')) errors.push('The command has a NUL character.');
+  if (!o.databases.includes(spec.database)) errors.push('Choose a database that accepts connections.');
+  if (!o.users.includes(spec.username)) errors.push('Choose a role that can sign in to run the job as.');
+  return errors;
+}
+
+/** The statements that create (before null) or change a job. */
+export function jobSql(before: (JobSpec & { jobid: string }) | null, spec: JobSpec): string[] {
+  if (!before) {
+    return [`select cron.schedule_in_database(\n  job_name := ${lit(spec.name)},\n  schedule := ${lit(spec.schedule)},\n  command := ${dollar(spec.command)},\n  database := ${lit(spec.database)},\n  username := ${lit(spec.username)},\n  active := ${spec.active}\n);`];
+  }
+  const set: string[] = [];
+  if (spec.schedule !== before.schedule) set.push(`schedule := ${lit(spec.schedule)}`);
+  if (spec.command !== before.command) set.push(`command := ${dollar(spec.command)}`);
+  if (spec.database !== before.database) set.push(`database := ${lit(spec.database)}`);
+  if (spec.username !== before.username) set.push(`username := ${lit(spec.username)}`);
+  if (spec.active !== before.active) set.push(`active := ${spec.active}`);
+  const out = set.length ? [`select cron.alter_job(\n  job_id := ${BigInt(before.jobid)},\n  ${set.join(',\n  ')}\n);`] : [];
+  // pg_cron's alter_job has no name: the name is cron.job's own column (unique per user)
+  if (spec.name !== before.name) out.push(`update cron.job set jobname = ${lit(spec.name)} where jobid = ${BigInt(before.jobid)};`);
+  return out;
+}
+
+export const activeSql = (jobid: string, active: boolean) => [`select cron.alter_job(job_id := ${BigInt(jobid)}, active := ${active});`];
+export const unscheduleSql = (jobid: string) => [`select cron.unschedule(job_id := ${BigInt(jobid)});`];
+
+function purgeWhere(days: number | null, job: string | null) {
+  const w: string[] = [];
+  if (job !== null) w.push(`jobid = ${BigInt(job)}`);
+  if (days !== null) w.push(`end_time < now() - interval '${Math.trunc(days)} days'`);
+  return w.length ? `where ${w.join(' and ')}` : '';
+}
+export const purgeSql = (days: number | null, job: string | null) => [`delete from cron.job_run_details ${purgeWhere(days, job)}`.trim() + ';'];
+
+/** A digest of reviewed statements: Apply runs only what the review showed. */
+export const reviewDigest = (stmts: string[]) => createHash('sha256').update(stmts.join('\n')).digest('base64url');
+
+/** Run reviewed statements in one transaction; the error message when they fail (nothing changed). */
+export async function applySql(stmts: string[]): Promise<string> {
+  try {
+    await owner.tx(async (c) => {
+      await c.query(`set local lock_timeout = '10s'`);
+      for (const x of stmts) await c.query(x);
+    });
+    return '';
+  } catch (e) {
+    return (e as Error).message;
+  }
+}
+
+// ------------------------------------------------------------------ Run now
+
+export interface RunNow { ok: boolean; ms: number; message: string; notices: string[] }
+
+/**
+ * Run a job's command once, now, as pg_cron would: in the job's database (a new connection with the owner's login
+ * to it), as the job's user (SET ROLE when it isn't the owner), outside a transaction block so VACUUM works, each
+ * statement in its own transaction unless the command says otherwise. pg_cron doesn't record the run (it has no
+ * run-now): the caller logs it.
+ */
+export async function runNow(job: Pick<Job, 'command' | 'database' | 'username'>, timeoutMs = 600_000): Promise<RunNow> {
+  const url = new URL(ownerUrl);
+  url.pathname = `/${encodeURIComponent(job.database)}`;
+  const client = new pg.Client({ connectionString: url.toString(), application_name: 'pgkiln-cron-run-now', statement_timeout: timeoutMs, connectionTimeoutMillis: 10_000 });
+  const notices: string[] = [];
+  client.on('notice', (n) => notices.length < 100 && notices.push(`${n.severity ?? 'NOTICE'}: ${n.message}`));
+  const t0 = performance.now();
+  try {
+    await client.connect();
+    const me = (await client.query<{ u: string }>('select current_user as u')).rows[0].u;
+    if (job.username !== me) await client.query(`set role ${pg.escapeIdentifier(job.username)}`);
+    // the simple query protocol: several statements, and no transaction block around them (as pg_cron runs them)
+    const res = await client.query(job.command);
+    const last = Array.isArray(res) ? res[res.length - 1] : res;
+    const tag = last ? `${last.command ?? ''}${last.rowCount !== null && last.rowCount !== undefined ? ` ${last.rowCount}` : ''}`.trim() : '';
+    return { ok: true, ms: performance.now() - t0, message: tag || 'done', notices };
+  } catch (e) {
+    return { ok: false, ms: performance.now() - t0, message: (e as Error).message, notices };
+  } finally {
+    await client.end().catch(() => undefined);
+  }
+}

package/src/runtime/autorest.ts

@@ -0,0 +1,336 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import pg from 'pg';
+import { owner, runtime, type Client } from '../db.ts';
+import { english } from '../i18n.ts';
+import { loadApp, type App } from '../metadata.ts';
+import { clientIp } from '../session.ts';
+import { availabilityRefusal } from './availability.ts';
+import { publicError } from './context.ts';
+import { caller, RestError, restServicesOn } from './rest.ts';
+
+// (sprint 100, Database Actions DA-11 part 1) AutoREST: a table or view that SQL Workshop › RESTful Services
+// enabled (meta.rest_object, migration 113), served through an application:
+//
+//   GET    /a/<alias>/autorest/<object>/           rows, paged: ?limit= (1–500) &offset= ; filters: ?<column>=<value>
+//                                                  (equality), ?q= (text columns contain it), ?order=col,col.desc
+//   POST   /a/<alias>/autorest/<object>/           a JSON object: the new row (201)
+//   GET    /a/<alias>/autorest/<object>/<key>      one row by primary key (composite keys: 1,2), 404 when there is none
+//   PUT    /a/<alias>/autorest/<object>/<key>      the JSON object's columns changed; the row (200) or 404
+//   DELETE /a/<alias>/autorest/<object>/<key>      204 or 404
+//   GET    /a/<alias>/autorest/openapi.json        OpenAPI 3 of the application's objects (public ones without a token)
+//
+// Authentication is the application's (as for its REST modules, rest.ts caller()): a bearer token of an account
+// or an OAuth client of the application; "public" objects need none (meta.app_user() = nobody). The statement
+// runs as the application's database role with meta.app_user() and meta.has_role() set, so grants (also column
+// grants) and row level security apply. The role may not be the object's owner (or a member of it), a superuser
+// or a role that bypasses row level security: checked at every request, after SET ROLE. Names come from the
+// catalog and are quoted; every value is a query parameter.
+
+export interface RestObject {
+  id: number;
+  app_id: number;
+  schema_name: string;
+  object_name: string;
+  alias: string;
+  methods: string[];
+  auth: 'token' | 'public';
+  roles: string[];
+  page_size: number;
+  enabled: boolean;
+}
+
+export interface Column {
+  name: string;
+  type: string;
+  /** pg_type.typcategory: S string, N numeric, B boolean, D date/time, … */
+  cat: string;
+  readable: boolean;
+  /** position in the primary key (1…), or null */
+  pk: number | null;
+}
+
+export const AUTOREST_METHODS = ['GET', 'POST', 'PUT', 'DELETE'] as const;
+export const MAX_PAGE = 500;
+/** Query parameters that are not column filters. */
+const RESERVED = new Set(['limit', 'offset', 'q', 'order']);
+export const RELKINDS: Record<string, string> = { r: 'table', p: 'table', v: 'view', m: 'materialized view', f: 'foreign table' };
+
+const ident = pg.escapeIdentifier;
+export const qualified = (o: Pick<RestObject, 'schema_name' | 'object_name'>) => `${ident(o.schema_name)}.${ident(o.object_name)}`;
+
+/** The columns of a relation as `role` may use them (the catalog only; no privilege needed to read it). */
+export async function describeColumns(db: { query: (sql: string, params: unknown[]) => Promise<pg.QueryResult> }, schema: string, name: string, role: string): Promise<Column[]> {
+  return (await db.query(
+    `select a.attname as name, format_type(a.atttypid, a.atttypmod) as type, t.typcategory as cat,
+            has_column_privilege($3, c.oid, a.attnum, 'SELECT') as readable,
+            (select array_position(i.indkey::int2[], a.attnum) from pg_index i where i.indrelid = c.oid and i.indisprimary) as pk
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace
+       join pg_attribute a on a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped
+       join pg_type t on t.oid = a.atttypid
+      where n.nspname = $1 and c.relname = $2
+      order by a.attnum`,
+    [schema, name, role],
+  )).rows as Column[];
+}
+
+/** The primary key's columns in key order. */
+export const keyColumns = (cols: Column[]) => cols.filter((c) => c.pk !== null).sort((a, b) => a.pk! - b.pk!);
+
+/** The object a request names, if the application published it and it is on. */
+async function objectOf(a: App, alias: string) {
+  const o = await runtime.one<RestObject>('select * from meta.rest_object where app_id = $1 and alias = $2', [a.id, alias]);
+  return o?.enabled ? o : undefined;
+}
+
+/** Split a key segment "1" or "10,20" into its values (each part URL-decoded on its own). */
+export function splitKey(raw: string, n: number): string[] | null {
+  if (!raw || raw.includes('/')) return null;
+  const parts = raw.split(',');
+  if (parts.length !== n) return null;
+  try {
+    return parts.map((p) => decodeURIComponent(p));
+  } catch {
+    return null;
+  }
+}
+
+/** The ORDER BY of ?order=a,b.desc: only readable columns; null when it names something else. */
+export function orderBy(spec: string | undefined, cols: Column[]): string | null {
+  const readable = new Map(cols.filter((c) => c.readable).map((c) => [c.name, c]));
+  if (spec === undefined || spec === '') {
+    const key = keyColumns(cols).filter((c) => c.readable);
+    return key.length ? key.map((c) => `t.${ident(c.name)}`).join(', ') : '1';
+  }
+  const out: string[] = [];
+  for (const part of spec.split(',')) {
+    const m = /^(.+?)(?:\.(asc|desc))?$/.exec(part);
+    if (!m || !readable.has(m[1])) return null;
+    out.push(`t.${ident(m[1])}${m[2] === 'desc' ? ' desc' : ''}`);
+  }
+  return out.join(', ');
+}
+
+const likeEscape = (s: string) => s.replace(/[\\%_]/g, (x) => `\\${x}`);
+const one = (v: unknown) => (Array.isArray(v) ? v[0] : v);
+
+/** Checks run after SET ROLE: the role isn't the owner and doesn't bypass row level security. */
+async function checkRole(c: Client, o: RestObject) {
+  const r = (await c.query(
+    `select c.relkind, pg_has_role(current_user, c.relowner, 'MEMBER') as owns, r.rolsuper or r.rolbypassrls as bypass
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace, pg_roles r
+      where n.nspname = $1 and c.relname = $2 and r.rolname = current_user`,
+    [o.schema_name, o.object_name],
+  )).rows[0];
+  if (!r || !RELKINDS[r.relkind]) throw new RestError(404, 'Not found');
+  if (r.owns || r.bypass) throw new RestError(403, 'The application\'s database role owns this object or bypasses row level security: AutoREST refuses it.');
+  return r.relkind as string;
+}
+
+/** A JSON body as an object of known columns; RestError otherwise. */
+function bodyColumns(body: unknown, cols: Column[]) {
+  if (!body || typeof body !== 'object' || Array.isArray(body) || Buffer.isBuffer(body)) throw new RestError(400, 'The body is a JSON object of column values.');
+  const names = new Set(cols.map((c) => c.name));
+  const keys = Object.keys(body as object);
+  const unknown = keys.filter((k) => !names.has(k));
+  if (unknown.length) throw new RestError(400, `Unknown column(s): ${unknown.slice(0, 5).join(', ')}.`);
+  return keys;
+}
+
+async function handle(req: FastifyRequest, reply: FastifyReply) {
+  const p = req.params as { alias: string; object: string; '*'?: string };
+  const keyRaw = (p['*'] ?? '').replace(/\/+$/, '');
+  const a = await loadApp(p.alias);
+  const o = a ? await objectOf(a, p.object) : undefined;
+  if (!a || !o || !(await restServicesOn(a.id))) return reply.code(404).send({ error: 'Not found' });
+  const method = req.method;
+  const allowed = o.methods.filter((m) => (keyRaw ? m !== 'POST' : m === 'GET' || m === 'POST'));
+  if (!o.methods.includes(method) || !allowed.includes(method)) return reply.code(405).header('allow', allowed.join(', ')).send({ error: `${method} is not allowed here.` });
+  try {
+    const who = await caller(req, a, o.auth === 'public');
+    const refusal = availabilityRefusal(a, { username: who.user === 'nobody' ? null : who.user, developer: false });
+    if (refusal) throw new RestError(refusal.status, refusal.message ?? english(refusal.key));
+    if (!a.db_role) throw new RestError(403, 'The application has no database role: AutoREST needs one.');
+    const result = await runtime.tx(async (c) => {
+      await c.query(
+        `select set_config('pgkiln.app_id', $1, true), set_config('pgkiln.app_user', $2, true), set_config('pgkiln.session_id', '', true),
+                set_config('request.jwt.claims', $3, true), set_config('statement_timeout', '30s', true)`,
+        [String(a.id), who.user, who.claims ? JSON.stringify(who.claims) : ''],
+      );
+      if (o.roles.length) {
+        const ok = (await c.query('select bool_or(meta.has_role(r)) as ok from unnest($1::text[]) r', [o.roles])).rows[0].ok;
+        if (!ok) throw new RestError(403, 'You do not have a role this endpoint needs.');
+      }
+      await c.query(`set local role ${ident(a.db_role!)}`);
+      await checkRole(c, o);
+      const cols = await describeColumns(c, o.schema_name, o.object_name, a.db_role!);
+      const readable = cols.filter((x) => x.readable);
+      const list = readable.map((x) => `t.${ident(x.name)}`).join(', ');
+      const returning = list ? ` returning ${list}` : '';
+      const rel = qualified(o);
+      const key = keyColumns(cols);
+      const params: unknown[] = [];
+      const param = (v: unknown) => `$${params.push(v)}`;
+      let where = '';
+      if (keyRaw) {
+        const values = key.length ? splitKey(keyRaw, key.length) : null;
+        if (!values) throw new RestError(404, 'Not found');
+        where = key.map((k, i) => `t.${ident(k.name)} = ${param(values[i])}`).join(' and ');
+      }
+
+      if (method === 'GET' && !keyRaw) {
+        if (!readable.length) throw new RestError(403, 'Not allowed.');
+        const q = req.query as Record<string, string | string[]>;
+        const conds: string[] = [];
+        for (const [k, raw] of Object.entries(q)) {
+          if (RESERVED.has(k)) continue;
+          const col = readable.find((x) => x.name === k);
+          if (!col) throw new RestError(400, `Unknown parameter ${k.slice(0, 63)}: filter on a column, or use limit, offset, q, order.`);
+          conds.push(`t.${ident(col.name)} = ${param(String(one(raw)))}`);
+        }
+        const search = one(q.q);
+        if (search) {
+          const text = readable.filter((x) => x.cat === 'S');
+          if (!text.length) throw new RestError(400, 'q= searches text columns, and this object has none you may read.');
+          const v = param(`%${likeEscape(String(search))}%`);
+          conds.push(`(${text.map((x) => `t.${ident(x.name)} ilike ${v}`).join(' or ')})`);
+        }
+        const order = orderBy(one(q.order) as string | undefined, cols);
+        if (order === null) throw new RestError(400, 'order= is a list of readable columns, each optionally followed by .asc or .desc.');
+        const limitRaw = one(q.limit);
+        const offsetRaw = one(q.offset);
+        if ((limitRaw !== undefined && !/^\d{1,9}$/.test(String(limitRaw))) || (offsetRaw !== undefined && !/^\d{1,12}$/.test(String(offsetRaw))))
+          throw new RestError(400, 'limit and offset are whole numbers.');
+        const limit = Math.max(1, Math.min(MAX_PAGE, limitRaw !== undefined ? Number(limitRaw) : o.page_size));
+        const offset = offsetRaw !== undefined ? Number(offsetRaw) : 0;
+        const rows = (await c.query(
+          `select ${list} from ${rel} t${conds.length ? ` where ${conds.join(' and ')}` : ''} order by ${order} limit ${limit + 1} offset ${offset}`,
+          params,
+        )).rows;
+        return { status: 200, body: { items: rows.slice(0, limit), offset, limit, has_more: rows.length > limit } };
+      }
+      if (method === 'GET') {
+        if (!readable.length) throw new RestError(403, 'Not allowed.');
+        const row = (await c.query(`select ${list} from ${rel} t where ${where} limit 1`, params)).rows[0];
+        if (!row) throw new RestError(404, 'Not found');
+        return { status: 200, body: row };
+      }
+      if (method === 'POST') {
+        const names = bodyColumns(req.body, cols);
+        const sql = names.length
+          ? `insert into ${rel} as t (${names.map(ident).join(', ')}) select ${names.map((n) => `b.${ident(n)}`).join(', ')} from json_populate_record(null::${rel}, ${param(JSON.stringify(req.body))}::json) b${returning}`
+          : `insert into ${rel} as t default values${returning}`;
+        const row = (await c.query(sql, params)).rows[0];
+        const keyOk = key.length && key.every((k) => k.readable) && row;
+        return { status: 201, body: row ?? {}, location: keyOk ? key.map((k) => encodeURIComponent(String(row[k.name] instanceof Date ? row[k.name].toISOString() : row[k.name]))).join(',') : undefined };
+      }
+      if (method === 'PUT') {
+        const names = bodyColumns(req.body, cols);
+        if (!names.length) throw new RestError(400, 'The body names no columns to change.');
+        const b = param(JSON.stringify(req.body));
+        const res = await c.query(
+          `update ${rel} as t set ${names.map((n) => `${ident(n)} = b.${ident(n)}`).join(', ')} from json_populate_record(null::${rel}, ${b}::json) b where ${where}${returning}`,
+          params,
+        );
+        if (!res.rowCount) throw new RestError(404, 'Not found');
+        return { status: 200, body: res.rows[0] ?? {} };
+      }
+      // DELETE
+      const res = await c.query(`delete from ${rel} t where ${where}`, params);
+      if (!res.rowCount) throw new RestError(404, 'Not found');
+      return { status: 204, body: undefined };
+    });
+    reply.header('cache-control', 'no-store');
+    if ('location' in result && result.location) reply.header('location', `/a/${encodeURIComponent(a.alias)}/autorest/${o.alias}/${result.location}`);
+    return result.body === undefined ? reply.code(204).send() : reply.code(result.status).send(result.body);
+  } catch (e) {
+    if (e instanceof RestError) return reply.code(e.status).send({ error: e.message });
+    const err = e as pg.DatabaseError;
+    const message = await publicError({ app: a, page: { page_no: 0 } as never, user: 'api', ip: clientIp(req) }, e, `AutoREST ${method} ${o.alias}`);
+    const status = err.code === '42501' ? 403 : err.code && /^(P0001|22|23|42804|428C9)/.test(err.code) ? 400 : 500;
+    return reply.code(status).send({ error: status === 403 ? 'Not allowed.' : message });
+  }
+}
+
+/** JSON Schema of a column type (for the OpenAPI description). */
+function jsonType(c: Column): Record<string, unknown> {
+  if (/^(smallint|integer|bigint)$/.test(c.type)) return { type: 'integer' };
+  if (c.cat === 'N') return { type: 'number' };
+  if (c.cat === 'B') return { type: 'boolean' };
+  if (c.type === 'date') return { type: 'string', format: 'date' };
+  if (c.cat === 'D') return { type: 'string', format: 'date-time' };
+  if (c.cat === 'S') return { type: 'string' };
+  if (c.cat === 'A') return { type: 'array', items: {} };
+  return {};
+}
+
+/** The OpenAPI 3 description of an application's AutoREST objects. */
+export function autoRestOpenApi(a: Pick<App, 'alias' | 'name'>, objects: { o: RestObject; cols: Column[] }[]) {
+  const paths: Record<string, Record<string, unknown>> = {};
+  const schemas: Record<string, unknown> = {};
+  const errors = (o: RestObject) => (o.auth === 'public' ? {} : { 401: { description: 'No valid token' }, 403: { description: 'Not allowed' } });
+  for (const { o, cols } of objects) {
+    const readable = cols.filter((c) => c.readable);
+    const name = o.alias.replace(/[^A-Za-z0-9_.-]/g, '_');
+    schemas[name] = { type: 'object', properties: Object.fromEntries(readable.map((c) => [c.name, { ...jsonType(c), description: c.type }])) };
+    const ref = { $ref: `#/components/schemas/${name}` };
+    const sec = o.auth === 'public' ? { security: [] } : {};
+    const body = { required: true, content: { 'application/json': { schema: ref } } };
+    const coll: Record<string, unknown> = {};
+    if (o.methods.includes('GET'))
+      coll.get = {
+        summary: `Rows of ${o.schema_name}.${o.object_name}`, ...sec,
+        parameters: [
+          { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: MAX_PAGE, default: o.page_size } },
+          { name: 'offset', in: 'query', schema: { type: 'integer', minimum: 0 } },
+          { name: 'q', in: 'query', description: 'Rows whose text columns contain this', schema: { type: 'string' } },
+          { name: 'order', in: 'query', description: 'Columns, each optionally .asc or .desc, comma separated', schema: { type: 'string' } },
+          ...readable.filter((c) => !RESERVED.has(c.name)).map((c) => ({ name: c.name, in: 'query', description: `${c.name} equals`, schema: { type: 'string' } })),
+        ],
+        responses: { 200: { description: '{items, offset, limit, has_more}', content: { 'application/json': { schema: { type: 'object', properties: { items: { type: 'array', items: ref }, offset: { type: 'integer' }, limit: { type: 'integer' }, has_more: { type: 'boolean' } } } } } }, 400: { description: 'A filter is not valid' }, ...errors(o) },
+      };
+    if (o.methods.includes('POST'))
+      coll.post = { summary: `New row in ${o.schema_name}.${o.object_name}`, ...sec, requestBody: body, responses: { 201: { description: 'The new row', content: { 'application/json': { schema: ref } } }, 400: { description: 'Invalid values' }, ...errors(o) } };
+    if (Object.keys(coll).length) paths[`/${o.alias}/`] = coll;
+    const key = keyColumns(cols);
+    if (!key.length) continue;
+    const item: Record<string, unknown> = { parameters: [{ name: 'key', in: 'path', required: true, description: `${key.map((k) => k.name).join(', ')}${key.length > 1 ? ' (comma separated)' : ''}`, schema: { type: 'string' } }] };
+    const notFound = { 404: { description: 'Not found' } };
+    if (o.methods.includes('GET')) item.get = { summary: 'One row by its key', ...sec, responses: { 200: { description: 'The row', content: { 'application/json': { schema: ref } } }, ...notFound, ...errors(o) } };
+    if (o.methods.includes('PUT')) item.put = { summary: 'Change the columns the body names', ...sec, requestBody: body, responses: { 200: { description: 'The changed row', content: { 'application/json': { schema: ref } } }, ...notFound, ...errors(o) } };
+    if (o.methods.includes('DELETE')) item.delete = { summary: 'Delete the row', ...sec, responses: { 204: { description: 'Deleted' }, ...notFound, ...errors(o) } };
+    if (Object.keys(item).length > 1) paths[`/${o.alias}/{key}`] = item;
+  }
+  return {
+    openapi: '3.0.3',
+    info: { title: `${a.name} AutoREST`, description: 'Tables and views published with SQL Workshop › RESTful Services', version: '1' },
+    servers: [{ url: `/a/${a.alias}/autorest` }],
+    components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } }, schemas },
+    security: [{ bearer: [] }],
+    paths,
+  };
+}
+
+export async function autoRestRoutes(app: FastifyInstance) {
+  // without a token: the public objects only; with a valid token of the application: all of them
+  app.get<{ Params: { alias: string } }>('/a/:alias/autorest/openapi.json', async (req, reply) => {
+    const a = await loadApp(req.params.alias);
+    if (!a || !(await restServicesOn(a.id))) return reply.code(404).send({ error: english('error.not_found') });
+    let all = false;
+    if (req.headers.authorization) {
+      try {
+        all = (await caller(req, a, false)).user !== 'nobody';
+      } catch (e) {
+        if (e instanceof RestError) return reply.code(e.status).send({ error: e.message });
+        throw e;
+      }
+    }
+    const rows = (await runtime.query<RestObject>('select * from meta.rest_object where app_id = $1 and enabled order by alias', [a.id])).rows.filter((o) => all || o.auth === 'public');
+    const objects = a.db_role
+      ? await Promise.all(rows.map(async (o) => ({ o, cols: await describeColumns(owner, o.schema_name, o.object_name, a.db_role!) })))
+      : [];
+    return reply.header('cache-control', 'no-store').send(autoRestOpenApi(a, objects.filter((x) => x.cols.length)));
+  });
+  const methods = [...AUTOREST_METHODS] as never;
+  app.route({ method: methods, url: '/a/:alias/autorest/:object', handler: handle });
+  app.route({ method: methods, url: '/a/:alias/autorest/:object/*', handler: handle });
+}

package/src/runtime/rest-handlers.ts

@@ -0,0 +1,75 @@
+import type pg from 'pg';
+import { substitute, type BindValues } from '../binds.ts';
+
+// (sprint 104, Database Actions DA-11 part 2; migration 117) The handler source types REST modules gained with
+// SQL Workshop › RESTful Services, next to collection, item and sql (rest.ts):
+//
+//   plpgsql  a PL/pgSQL block run as an anonymous DO block as the application's role. A DO block takes no
+//            parameters, so the binds go in as transaction-local settings, set with query parameters (never part
+//            of the SQL text), and :NAME in the block becomes meta.rest_param('NAME'). The block answers with
+//            meta.rest_reply(body jsonb, status int); without a reply: 204.
+//   media    a query whose first row has content_type and content (bytea or text), optional filename: the
+//            response is that content. It is served sandboxed (CSP sandbox, nosniff), so an HTML or SVG
+//            "image" from the table can't run script in the application's origin.
+
+/** Bind names a PL/pgSQL handler can read (a setting name each): letters, digits and _. */
+const BIND_NAME = /^[A-Z_][A-Z0-9_]{0,62}$/;
+/** The dollar-quote tag around a PL/pgSQL handler's block. */
+export const DO_TAG = '$pgkiln_rest$';
+/** At most this many binds go into settings (a body with thousands of fields is not a handler's input). */
+const MAX_BINDS = 200;
+
+export class HandlerInputError extends Error {}
+
+/** The DO statement of a PL/pgSQL handler: its binds as meta.rest_param('NAME'), wrapped in begin … end if needed. */
+export function plpgsqlBlock(source: string): string {
+  if (source.includes(DO_TAG)) throw new Error(`A PL/pgSQL handler may not contain ${DO_TAG}.`);
+  let body = substitute(source.trim().replace(/;+\s*$/, ''), (name) => `meta.rest_param('${name}')`);
+  if (!/^(declare|begin|<<)/i.test(body.replace(/^(\s*(--[^\n]*(\n|$)|\/\*[\s\S]*?\*\/))*\s*/, ''))) body = `begin\n${body};\nend`;
+  return `do ${DO_TAG}\n${body}\n${DO_TAG}`;
+}
+
+/** Set the binds as transaction-local settings pgkiln_bind.<name>, as query parameters. */
+export async function setBinds(c: pg.PoolClient, binds: BindValues) {
+  const entries = Object.entries(binds).filter(([k]) => BIND_NAME.test(k)).slice(0, MAX_BINDS);
+  for (const [, v] of entries) if (typeof v === 'string' && v.includes('\0')) throw new HandlerInputError('A parameter contains a NUL byte.');
+  if (!entries.length) return;
+  await c.query(`select set_config('pgkiln_bind.' || lower(k), coalesce(v, ''), true) from unnest($1::text[], $2::text[]) as b(k, v)`,
+    [entries.map(([k]) => k), entries.map(([, v]) => v ?? null)]);
+}
+
+/** Run a PL/pgSQL handler; its reply (meta.rest_reply) or none. */
+export async function runPlpgsql(c: pg.PoolClient, source: string): Promise<{ body: unknown; status: number | null }> {
+  // a reply from an earlier statement of this transaction must not leak into this one
+  await c.query(`select set_config('pgkiln_rest.body', '', true), set_config('pgkiln_rest.status', '', true)`);
+  await c.query(plpgsqlBlock(source));
+  const r = (await c.query(`select current_setting('pgkiln_rest.body', true) as body, current_setting('pgkiln_rest.status', true) as status`)).rows[0];
+  return { body: r.body ? JSON.parse(r.body) : undefined, status: r.status ? Number(r.status) : null };
+}
+
+/** A content type safe to send as a header: type/subtype with optional parameters, no line breaks. */
+export function safeContentType(v: unknown): string {
+  const s = typeof v === 'string' ? v.trim() : '';
+  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(\s*;\s*[a-z0-9_-]+=("[^"\r\n]*"|[^;\s\r\n]+))*$/i.test(s) && s.length <= 200 ? s : 'application/octet-stream';
+}
+
+/** A file name for Content-Disposition: printable ASCII without quotes, slashes or backslashes. */
+export const safeFilename = (v: unknown) => (typeof v === 'string' ? v.replace(/[^\x20-\x7e]|["\\/;]/g, '_').slice(0, 200) : '');
+
+/** The response of a media handler's row. */
+export function mediaResponse(row: Record<string, unknown>) {
+  if (!('content' in row) || !('content_type' in row)) throw new Error('A media handler\'s query returns the columns content_type and content (and optionally filename).');
+  const c = row.content;
+  const body = c === null || c === undefined ? Buffer.alloc(0) : Buffer.isBuffer(c) ? c : Buffer.from(typeof c === 'string' ? c : JSON.stringify(c));
+  const name = safeFilename(row.filename);
+  return {
+    body,
+    headers: {
+      'content-type': safeContentType(row.content_type),
+      'x-content-type-options': 'nosniff',
+      'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox",
+      'cache-control': 'no-store',
+      ...(name ? { 'content-disposition': `inline; filename="${name}"` } : {}),
+    } as Record<string, string>,
+  };
+}