@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/api/postgres/catalog.js

@@ -31,10 +31,14 @@
  * The instance's TimeZone is UTC (the API treats every time as UTC, §4.8); its search_path is Postgres's default, so
  * `public."orders"` and `orders` both resolve, as a tool expects.
  */
+import { randomBytes } from "node:crypto";
 import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import { runnable } from "../../lib/runnable.js";
-import { PG_API_TYPE_SPELLING, typeNameParts } from "./schema.js";
+import { NO_ROLE_CATALOG } from "../../duck/grants.js";
+import { renderWhere, tableSql } from "../../duck/row-filter.js";
+import { cstr, frame, splitFrames } from "./protocol.js";
+import { HELD_ROW_INPUT, HELD_TYPE_INPUT, madeTypeName, PG_API_TYPE_SPELLING, typeNameParts } from "./schema.js";
 /** Ten minutes: long enough to outlive a tool's startup burst and a person's pause between two queries. */
 const DEFAULT_IDLE_MS = 10 * 60_000;
 /** A catalog statement's deadline (`MASON_PG_CATALOG_TIMEOUT_MS`): a tool's introspection answers in milliseconds; a
@@ -46,6 +50,7 @@ export const DEFAULT_STATEMENT_MS = 10_000;
 export const MIN_START_MS = 30_000;
 /** A SQL identifier, double-quoted with an inner quote doubled. */
 const ident = (name) => `"${name.replaceAll('"', '""')}"`;
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
 /** A SQL string literal, single-quoted with an inner quote doubled. */
 const literal = (text) => `'${text.replaceAll("'", "''")}'`;
 /** a table's name in the catalog: its schema (Mason's source schema, else public) and name */
@@ -70,11 +75,11 @@ function isForeignKey(schema, table, join) {
 }
 const joinNote = (join) => `joins ${join.table} on ${join.on[1]} (${join.relationship})`;
 /**
- * THE CATALOG'S DATABASE IS THE ONE A TOOL CONNECTED TO (the deployment): current_database(), pg_database — pgjdbc's
+ * THE CATALOG'S DATABASE IS THE ONE A TOOL CONNECTED TO (src/lib/database-name.ts): current_database(), pg_database — pgjdbc's
  * getCatalogs and every TABLE_CAT, DBeaver's navigator — once said the sidecar's own `postgres`. The current
  * database's row is renamed (ALTER DATABASE refuses the current one; the catalog row does not), after moving aside any
  * OTHER database already holding the name — PGlite's `template0` / `template1` — since pg_database's names are unique
- * (#484's review: a deployment named `template1` failed on pg_database_datname_index and the catalog never started).
+ * (#484's review: a name of `template1` failed on pg_database_datname_index and the catalog never started).
  */
 export function databaseNameSql(name) {
     const q = `'${name.replaceAll("'", "''")}'`;
@@ -112,12 +117,19 @@ export function catalogDdl(schema) {
     for (const name of [...new Set(schema.tables.map((t) => t.schema).filter((x) => x !== undefined && x !== "public"))]) {
         statements.push(`CREATE SCHEMA IF NOT EXISTS ${ident(name)};`);
     }
+    // THE SOURCE'S COLLATIONS (src/duck/collation.ts), before the tables: each the catalog lacks, declared under its name with
+    // the source's provider, locale and determinism (a locale PGlite cannot open declared on its root locale: what it
+    // MEANS is the source's row of its name, read by the resolver, never this one's), so a column's COLLATE and a
+    // statement's resolve as on the source. In pg_catalog, public, a table's schema, or a column's collation's schema
+    statements.push(...collationDdl(schema));
     // a source enum a column has: the type, its labels in their declared order, before the tables —
     // spelled as the source's format_type spells it (`mood`, `other.level`, `"Odd"`), its schema made first
     const enums = new Map();
+    // one declaration a type, the FIRST column's: the synced tables come first, and src/duck/sync.ts hands a generated
+    // table's column its synced type's labels (one source of an enum's labels), so no later column's can replace them
     for (const t of schema.tables)
         for (const c of t.columns)
-            if (c.enumLabels !== undefined && c.spelled !== undefined)
+            if (c.enumLabels !== undefined && c.spelled !== undefined && !enums.has(c.spelled.replace(/\[\]$/, "")))
                 enums.set(c.spelled.replace(/\[\]$/, ""), c.enumLabels);
     for (const [type, labels] of enums) {
         const qualifier = typeNameParts(type).schema;
@@ -125,10 +137,22 @@ export function catalogDdl(schema) {
             statements.push(`CREATE SCHEMA IF NOT EXISTS ${qualifier};`);
         statements.push(`CREATE TYPE ${type} AS ENUM (${labels.map(literal).join(", ")});`);
     }
+    // a type a database made, held as its text: its name, the text's input and output, and nothing over it
+    const made = new Map(schema.tables.flatMap((t) => t.columns.filter((c) => c.made !== undefined).map((c) => [madeTypeName(c.spelled), c.made])));
+    [...made].forEach(([type, kind], i) => {
+        const input = kind === "row" ? HELD_ROW_INPUT : HELD_TYPE_INPUT;
+        const qualifier = typeNameParts(type).schema;
+        if (qualifier !== null && qualifier !== '"public"' && qualifier !== "public")
+            statements.push(`CREATE SCHEMA IF NOT EXISTS ${qualifier};`);
+        statements.push(`CREATE TYPE ${type};`, `CREATE FUNCTION pg_catalog.${input}${i}(cstring) RETURNS ${type} LANGUAGE internal IMMUTABLE STRICT AS 'textin';`, `CREATE FUNCTION pg_catalog.mason_held_out${i}(${type}) RETURNS cstring LANGUAGE internal IMMUTABLE STRICT AS 'textout';`, `CREATE TYPE ${type} (INPUT = pg_catalog.${input}${i}, OUTPUT = pg_catalog.mason_held_out${i}, LIKE = text);`);
+    });
     for (const table of schema.tables) {
         const lines = [];
-        for (const c of table.columns)
-            lines.push(`${ident(c.name)} ${c.spelled ?? PG_API_TYPE_SPELLING[c.type]}${c.notNull === true ? " NOT NULL" : ""}`);
+        for (const c of table.columns) {
+            // a column's own collation: the source's, so Postgres's analysis orders it as the source does
+            const collate = c.collation !== undefined ? ` COLLATE ${ident(c.collation.schema)}.${ident(c.collation.name)}` : "";
+            lines.push(`${ident(c.name)} ${c.made !== undefined ? `${madeTypeName(c.spelled)}${c.spelled.endsWith("[]") ? "[]" : ""}` : c.spelled ?? PG_API_TYPE_SPELLING[c.type]}${collate}${c.notNull === true ? " NOT NULL" : ""}`);
+        }
         if (table.primaryKey.length > 0)
             lines.push(`PRIMARY KEY (${table.primaryKey.map(ident).join(", ")})`);
         statements.push(`CREATE TABLE ${qualified(table)} (\n  ${lines.join(",\n  ")}\n);`);
@@ -165,6 +189,38 @@ export function catalogDdl(schema) {
     }
     return [...statements, ...constraints, ...sourceTypeNames(schema)];
 }
+/**
+ * THE SOURCE'S COLLATIONS THE CATALOG LACKS, declared (one DO block: ~800 ICU collations in tens of milliseconds): each
+ * under its schema and name, by the source's provider, locale and determinism, else — a locale PGlite's ICU or libc
+ * cannot open — the same name on the root locale (ICU), C (libc) or C (builtin), which its analysis treats alike: the
+ * resolver reads what a collation means from the SOURCE's row of its name (src/duck/collation.ts), never this one. Only
+ * where a name can be met: pg_catalog, public, a table's schema, and a synced column's collation's own schema.
+ */
+export function collationDdl(schema) {
+    const used = schema.tables.flatMap((t) => t.columns.flatMap((c) => c.collation !== undefined ? [c.collation] : []));
+    const schemas = new Set(["pg_catalog", "public", ...schema.tables.map((t) => t.schema ?? "public"), ...used.map((c) => c.schema)]);
+    const declared = (schema.collations ?? []).filter((c) => c.provider !== "d" && schemas.has(c.schema));
+    if (declared.length === 0)
+        return [];
+    const out = [];
+    for (const s of new Set(declared.map((c) => c.schema)))
+        if (s !== "pg_catalog" && s !== "public")
+            out.push(`CREATE SCHEMA IF NOT EXISTS ${ident(s)};`);
+    // ONE INSERT of the rows, never a CREATE COLLATION each: a source lists about 1,600 (every ICU locale and every libc
+    // one the OS has), and a CREATE each took the catalog's start past its deadline (about 18 ms each, measured; the
+    // INSERT, 260 ms for 1,600). The catalog only ANALYSES under them: what a statement orders by is the synced data's, so
+    // a locale PGlite has no data for is never opened. A name the catalog has already (`C`, `und-x-icu`) is the source's
+    // too; the OIDs are past any the catalog makes, so none collides
+    const rows = declared.map((c) => ({ schema: c.schema, name: c.name, provider: c.provider, collate: c.collate, locale: c.locale, deterministic: c.deterministic }));
+    out.push(`INSERT INTO pg_catalog.pg_collation (oid, collname, collnamespace, collowner, collprovider, collisdeterministic, collencoding, collcollate, collctype, colllocale)
+SELECT (greatest((SELECT max(oid)::bigint FROM pg_catalog.pg_collation), 3000000000) + row_number() OVER ())::oid, c.name, n.oid, 10, c.provider, c.deterministic,
+  CASE WHEN c.provider = 'c' THEN 6 ELSE -1 END, CASE WHEN c.provider = 'c' THEN c."collate" END, CASE WHEN c.provider = 'c' THEN c."collate" END,
+  CASE WHEN c.provider <> 'c' THEN coalesce(c.locale, c."collate") END
+FROM json_to_recordset(${literal(JSON.stringify(rows))}) AS c(schema text, name text, provider "char", "collate" text, locale text, deterministic boolean)
+JOIN pg_catalog.pg_namespace n ON n.nspname = c.schema
+WHERE NOT EXISTS (SELECT FROM pg_catalog.pg_collation x WHERE x.collnamespace = n.oid AND x.collname = c.name AND x.collencoding IN (-1, 6));`);
+    return out;
+}
 /**
  * THE NAME OF A TYPE BY THE OID THE WIRE SENDS FOR IT. A column of a type the source made (an enum, a citext) is
  * sent with the SOURCE's OID (src/duck/plan.ts `userTypes`: what the source's own clients cached), which in this
@@ -185,14 +241,19 @@ export function sourceTypeNames(schema) {
             if (c.typeOid === undefined || c.spelled === undefined)
                 continue;
             // an array column's own OID is its array type's; an element's array type is the element's spelling with []
-            names.set(c.typeOid, c.spelled);
-            if (c.typeArrayOid !== undefined && !c.spelled.endsWith("[]"))
-                names.set(c.typeArrayOid, `${c.spelled}[]`);
+            const spelled = c.made !== undefined ? `${madeTypeName(c.spelled)}${c.spelled.endsWith("[]") ? "[]" : ""}` : c.spelled;
+            names.set(c.typeOid, spelled);
+            if (c.typeArrayOid !== undefined && !spelled.endsWith("[]"))
+                names.set(c.typeArrayOid, `${spelled}[]`);
         }
     }
     // with no type the source made, every OID the wire sends is Postgres's: the wire's name is format_type's
-    if (names.size === 0)
-        return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`];
+    // (format_type is declared all the same: a catalog statement's every unqualified call of it is spliced to this one,
+    // server.ts userSpliced, since the session's search_path puts pg_catalog first)
+    if (names.size === 0) {
+        return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`,
+            `CREATE OR REPLACE FUNCTION public.format_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`];
+    }
     const values = [...names].map(([oid, spelled]) => `(${oid}::oid, ${literal(spelled)})`).join(", ");
     return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$
   SELECT coalesce((SELECT pg_catalog.format_type(pg_catalog.to_regtype(v.spelled), $2) FROM (VALUES ${values}) AS v(source, spelled) WHERE v.source = $1),
@@ -234,15 +295,265 @@ export function catalogDefaults(schema) {
  * The source's views, one statement each beside `catalogDefaults`'s: a view reading a table
  * Mason has not copied (or a function the catalog lacks) is said in the log and left out. Each definition qualifies
  * every name outside pg_catalog (src/cli/preflight.ts VIEWS_SQL), so it reads the same tables here; a view over a view
- * is created once the other is (the worker runs these in passes).
+ * is created once the other is (the worker runs these in passes). Every role may SEE every view (`catalogRoles`: the
+ * grant is in the view's own statement, since the view must exist first): reading one is held to the tables it reads.
  */
-export function catalogViews(schema) {
+export function catalogViews(schema, roles = new Map()) {
     return (schema.views ?? []).map((v) => {
         const name = `${ident(v.schema)}.${ident(v.name)}`;
         const comment = v.description ? ` COMMENT ON VIEW ${name} IS ${literal(v.description)};` : "";
-        return `CREATE SCHEMA IF NOT EXISTS ${ident(v.schema)}; CREATE VIEW ${name} AS ${v.definition.replace(/;\s*$/, "")};${comment}`;
+        // every role of the file may see a view; the catalog's role of a user held to nothing sees none (as a login with no
+        // grant on Postgres)
+        const granted = [...roles.keys()].filter((r) => r !== NO_ROLE_CATALOG).map((r) => ` GRANT USAGE ON SCHEMA ${ident(v.schema)} TO ${ident(r)}; GRANT SELECT ON ${name} TO ${ident(r)};`).join("");
+        return `CREATE SCHEMA IF NOT EXISTS ${ident(v.schema)}; CREATE VIEW ${name} AS ${v.definition.replace(/;\s*$/, "")};${comment}${granted}`;
     });
 }
+/**
+ * THE CATALOG'S ROLES MIRROR THE ROLES FILE (GitHub issue 30; src/cli/roles.ts, src/duck/grants.ts): one Postgres role
+ * per Mason role, NOLOGIN, with `GRANT SELECT` on each table the role reads whole and `GRANT SELECT (columns)` on
+ * each it reads in part, and USAGE on every schema the copied tables are in. A session with a role runs its catalog
+ * statements under `SET ROLE` (`asRole`), so `information_schema.tables` / `.columns`, `has_table_privilege` and
+ * `has_column_privilege` answer for the role as Postgres's own do — and `mason mcp`'s `tables` and `describe`, which
+ * ask them, list a role what it may read. `pg_catalog` itself (pg_class, pg_attribute) does not filter by privilege
+ * on Postgres either; it still lists every synced column, said in docs/POSTGRES-API.md. A table the role names that the
+ * schema does not hold yet (added, not copied) is granted at the rebuild its copy brings; a column the copy lacks is
+ * left out (the roles file was held to the copy already, src/cli/roles.ts). Rebuilt with the schema: the server
+ * replaces the catalog when the roles move, as it does when the tables do. **`set_config` is revoked from PUBLIC
+ * while roles exist** (the review of #35): the catalog's one connection is the superuser's with `SET ROLE` on top, so
+ * inside one statement `set_config('role', 'none', false)` was a permitted RESET ROLE and the statement's later
+ * targets ran as the superuser (`information_schema` listed every hidden column's name); revoked, a role's session is
+ * refused it (42501 `permission denied for function set_config`) and the superuser keeps it. A role of `tables: all`
+ * (stage 1b) is resolved to a whole-table grant on every copied table (src/cli/roles.ts resolveRoles), so it is written
+ * here as per-table `GRANT SELECT`s, never `GRANT SELECT ON ALL TABLES IN SCHEMA`: the catalog is rebuilt from the
+ * resolved grants whenever the copied tables move, so a table added later is granted at that rebuild. The file's
+ * `default:` role is one of these roles: a user with no role of its own runs its catalog requests under it; under a
+ * file with no default it runs them as `NO_ROLE_CATALOG` (src/duck/grants.ts catalogRolesOf), a role with no grant.
+ */
+export function catalogRoles(schema, roles) {
+    const out = [];
+    if (roles.size === 0)
+        return out;
+    out.push("REVOKE EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) FROM PUBLIC;");
+    const schemas = [...new Set(schema.tables.map((t) => t.schema ?? "public"))];
+    const byName = new Map(schema.tables.map((t) => [`${t.schema ?? "public"}.${t.name}`, t]));
+    for (const r of roles.values()) {
+        const role = ident(r.name);
+        out.push(`CREATE ROLE ${role} NOLOGIN;`);
+        for (const s of schemas)
+            out.push(`GRANT USAGE ON SCHEMA ${ident(s)} TO ${role};`);
+        for (const g of r.tables.values()) {
+            const t = byName.get(g.table);
+            if (t === undefined)
+                continue;
+            if (g.all) {
+                out.push(`GRANT SELECT ON ${qualified(t)} TO ${role};`);
+                continue;
+            }
+            const columns = g.columns.filter((c) => t.columns.some((x) => x.name === c));
+            if (columns.length > 0)
+                out.push(`GRANT SELECT (${columns.map(ident).join(", ")}) ON ${qualified(t)} TO ${role};`);
+        }
+    }
+    return out;
+}
+/**
+ * THE ROLES' ROW FILTERS AS THE CATALOG'S OWN ROW SECURITY (src/duck/row-filter.ts): every copied table some role filters
+ * gets `ENABLE ROW LEVEL SECURITY` and one permissive SELECT policy per role that reads it — its `where:` with each
+ * attribute read as `current_setting('mason.attr.<name>')::<type>` (a list `string_to_array(…, ',')::<type>`), the type
+ * Postgres inferred for it (`filterTypes`, carried on the roles as `filterTypes`), each request carrying the session's
+ * attributes as settings (`asSession`); a `through:` as `EXISTS (SELECT 1 FROM <parent> …)`, the parent's own policy
+ * applying inside; `true` for a role that reads it unfiltered (row security with no policy hides every row). So
+ * `pg_policies`, `relrowsecurity` and the catalog's own analysis see what Postgres would. The catalog holds no row: the
+ * rows Mason answers are filtered on the copy (src/duck/plan.ts), never here. A filter whose types are not known (its
+ * check failed: the roles' problem refuses every user held to them) gets no policy. Idempotent: each policy dropped first.
+ */
+export function catalogPolicies(schema, roles) {
+    const filtered = new Set([...roles.values()].flatMap((g) => [...(g.filters?.keys() ?? [])]));
+    const out = [];
+    for (const t of schema.tables) {
+        const name = `${t.schema ?? "public"}.${t.name}`;
+        if (!filtered.has(name))
+            continue;
+        out.push(`ALTER TABLE ${qualified(t)} ENABLE ROW LEVEL SECURITY`);
+        for (const g of roles.values()) {
+            if (!g.tables.has(name))
+                continue;
+            const f = g.filters?.get(name);
+            let using;
+            if (f === undefined)
+                using = "true";
+            else if (f.through !== undefined)
+                using = `EXISTS (SELECT 1 FROM ${tableSql(f.through.parent)} AS __mason_parent WHERE __mason_parent.${ident(f.through.parentColumn)} = ${qualified(t)}.${ident(f.through.column)})`;
+            else {
+                const types = g.filterTypes?.get(name);
+                if (types === undefined || f.where === undefined)
+                    continue;
+                const shapes = g.attributes ?? new Map();
+                using = renderWhere(f.where.parts, (a) => {
+                    const read = `current_setting('mason.attr.${a}')`;
+                    return shapes.get(a) === "list" ? `string_to_array(${read}, ',')::${types.get(a) ?? "text[]"}` : `${read}::${types.get(a) ?? "text"}`;
+                });
+            }
+            out.push(`DROP POLICY IF EXISTS ${ident(`mason_${g.name}`)} ON ${qualified(t)}`);
+            out.push(`CREATE POLICY ${ident(`mason_${g.name}`)} ON ${qualified(t)} AS PERMISSIVE FOR SELECT TO ${ident(g.name)} USING (${using})`);
+        }
+    }
+    return out;
+}
+/**
+ * A SESSION'S CATALOG REQUEST AS ITS ROLE: `SET ROLE` before the request's frames and `RESET ROLE` after, in ONE
+ * message — the catalog runs one request at a time (`PgCatalog`'s chain) and a message whole, so no other session's
+ * request runs under this role, and none of this session's runs without it. A Sync is added before the RESET where
+ * the request has none: after an error Postgres ignores every message until a Sync (ignore_till_sync), the RESET
+ * included, and a role left set would be every session's.
+ */
+export function asRole(message, role) {
+    const own = Buffer.from(message.buffer, message.byteOffset, message.byteLength);
+    const synced = splitFrames(own).some((f) => f.type === "S");
+    const set = `SET ROLE ${ident(role)}`;
+    return Buffer.concat([frame("Q", cstr(set)), own, ...(synced ? [] : [frame("S")]), frame("Q", cstr("RESET ROLE"))]);
+}
+/**
+ * The reply to an `asRole` message, less the SET's and the RESET's own replies (each a CommandComplete and a
+ * ReadyForQuery; the Sync added by `asRole` leaves its ReadyForQuery, which every caller drops). `setRoleRefused`: the
+ * SET ROLE's ErrorResponse, when the catalog has no such role (its roles are a rebuild behind the file).
+ */
+export function unwrapRole(frames) {
+    const first = frames[0];
+    if (first === undefined)
+        return { frames: [], setRoleRefused: null };
+    if (first.type === "E")
+        return { frames: [], setRoleRefused: first.frame };
+    // the SET's CommandComplete and ReadyForQuery first; the RESET's CommandComplete and ReadyForQuery last
+    const inner = frames.slice(first.type === "C" && frames[1]?.type === "Z" ? 2 : 0);
+    const n = inner.length;
+    const end = n >= 2 && inner[n - 1].type === "Z" && inner[n - 2].type === "C" ? n - 2 : n;
+    return { frames: inner.slice(0, end), setRoleRefused: null };
+}
+/** the prefix of the placeholders a session's request rides in (`asSession`): named anew by each process, so no name a
+ *  tool writes is one of them — `current_setting('mason.session')` answered the carrier's JSON where Postgres (and
+ *  `SHOW`, and the same beside a copied table) answers 42704 (a review finding of #46). A placeholder stays defined once
+ *  SET, so the name, not a RESET, is what keeps it out of reach. */
+const CARRIER = `mason_${randomBytes(8).toString("hex")}`;
+/** the placeholder a session's settings ride in, for one request of its (`asSession`) */
+export const SESSION_SETTINGS = `${CARRIER}.session`;
+/** the catalog's own state, which its start sets and every request of a session leaves it in: UTC, `public` first (Mason's
+ *  own reads that name no schema find its overrides), ISO with month-day-year */
+export const CATALOG_BASE = { timeZone: "UTC", searchPath: "public, pg_catalog", dateStyle: "ISO, MDY" };
+/**
+ * A search_path as SET writes it, read as Postgres's `SplitIdentifierString` reads the parameter's text: a list split at
+ * the commas outside double quotes, an unquoted name folded to lower case, a quoted one as written (`"$user"` kept); an
+ * empty list is `''`. Every name is written quoted, so no text of a session's reaches the SQL but as an identifier.
+ */
+export function searchPathSql(path) {
+    const names = [];
+    let i = 0;
+    while (i < path.length) {
+        while (i < path.length && /[\s,]/.test(path[i]))
+            i++;
+        if (i >= path.length)
+            break;
+        let name = "";
+        if (path[i] === '"') {
+            i++;
+            while (i < path.length) {
+                if (path[i] === '"') {
+                    if (path[i + 1] === '"') {
+                        name += '"';
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                name += path[i++];
+            }
+        }
+        else {
+            while (i < path.length && path[i] !== ",")
+                name += path[i++];
+            name = name.trim().toLowerCase();
+        }
+        while (i < path.length && path[i] !== ",")
+            i++;
+        names.push(name);
+    }
+    return names.length === 0 ? "''" : names.map((n) => `"${n.replaceAll('"', '""')}"`).join(", ");
+}
+/** THE CATALOG'S ONE APPLIER of a session's state: its SETs, three statements (`local`: for the transaction they run
+ *  in, as a lookup of Mason's sets them inside one batch) */
+export function sessionSetSql(state, local = false) {
+    const set = local ? "SET LOCAL" : "SET";
+    return `${set} search_path = ${searchPathSql(state.searchPath)}; ${set} TimeZone = ${quoteLiteral(state.timeZone)}; ${set} DateStyle = ${quoteLiteral(state.dateStyle)}`;
+}
+/** the catalog's base set back (`CATALOG_BASE`), after a request that applied a session's state */
+export const CATALOG_BASE_SQL = sessionSetSql(CATALOG_BASE);
+/** how many CommandCompletes `sessionSetSql` answers: one a SET */
+const SESSION_SETS = 3;
+/**
+ * LATEST(x ORDER BY k…), THE AGGREGATE MASON ADDS: the x of the row its ORDER BY sorts last, by Postgres's sort rules.
+ * Declared in the catalog so that Postgres's analysis types and names it (an AGGREF of its argument's type), and by the
+ * oracle's real Postgres from this ONE definition, so the two compare like with like. Its transition keeps the latest
+ * row's value, a NULL included (not STRICT); over no rows it is NULL. In pg_catalog, so no search_path hides it. The
+ * engine never runs this: src/duck/rewrite.ts `latest` rewrites it, and refuses it without an ORDER BY (`latest-order`).
+ */
+export const LATEST_SQL = [
+    "CREATE OR REPLACE FUNCTION pg_catalog.mason_latest_step(anyelement, anyelement) RETURNS anyelement LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$ SELECT $2 $$",
+    "CREATE OR REPLACE AGGREGATE pg_catalog.latest(anyelement) (SFUNC = pg_catalog.mason_latest_step, STYPE = anyelement)",
+];
+/**
+ * THE CATALOG'S `current_setting(name[, missing_ok])` IS THE SESSION'S (GitHub issue 40: after `SET TimeZone` it answered
+ * the catalog's UTC, where `SHOW TimeZone` answered the session's): the value the session holds under that name, from
+ * the request's `SESSION_SETTINGS` (`asSession`: every parameter the listener's `sessionSetting` answers), else
+ * Postgres's own (`block_size`; its 42704, or NULL under missing_ok, for a name nobody knows). The `version()`
+ * override's way: search_path lists pg_catalog after public, so a statement reading no table and calling it is
+ * forwarded as ever; one that writes `pg_catalog.current_setting` is spliced to this one (server.ts
+ * userSpliced: Postgres's built-in runs its C function by OID, so its catalog row cannot be replaced). Plain
+ * SQL (plpgsql would load its library, and SHOW ALL list its `plpgsql.*`); STRICT, as Postgres's.
+ */
+export function currentSettingSql() {
+    const held = `nullif(pg_catalog.current_setting('${SESSION_SETTINGS}', true), '')::jsonb ->> lower($1)`;
+    return [
+        `CREATE OR REPLACE FUNCTION public.current_setting(text) RETURNS text LANGUAGE sql STABLE STRICT AS $$ SELECT coalesce(${held}, pg_catalog.current_setting($1)) $$`,
+        `CREATE OR REPLACE FUNCTION public.current_setting(text, boolean) RETURNS text LANGUAGE sql STABLE STRICT AS $$ SELECT coalesce(${held}, pg_catalog.current_setting($1, $2)) $$`,
+    ];
+}
+/**
+ * A SESSION'S CATALOG REQUEST UNDER ITS STATE AND WITH ITS SETTINGS, IN A TRANSACTION OF ITS OWN: `BEGIN`, the session's
+ * TimeZone, search_path and DateStyle (`sessionSetSql`) and `SET <SESSION_SETTINGS> = '<its settings as JSON>'` before
+ * the request's frames; `ROLLBACK` and the catalog's base (`CATALOG_BASE`) set back after, in ONE message, as `asRole`
+ * wraps a role (around it, when the session has one) — the catalog runs one request at a time and a message whole, so
+ * no other session's request reads these, and none of this session's runs without them. A Sync is added before the
+ * restore where the request has none (ignore_till_sync: a setting left set would be every session's). The `BEGIN`'s
+ * message is run at the session's transaction instant (`PgCatalog.run`'s `at`, catalog-worker.ts `pinnedClock`), so
+ * the transaction it begins starts at that instant and every reader of the transaction's start in the request —
+ * now(), the clock keywords, a relative word however it reaches a date or time — reads the session's (GitHub issue
+ * 253, review r3 of PR 333). The ROLLBACK undoes anything the request set, whether it succeeded or failed.
+ * `state` and `settings` are the listener's (`sessionState`, `sessionSetting`), never read here. The search_path is the
+ * session's as written, pg_catalog first unless it lists it, as on Postgres: the overrides of `version()`,
+ * `current_setting` and `format_type` are reached by the splice of every call of them (server.ts userSpliced), never by
+ * the order of the path.
+ */
+export function asSession(message, state, settings) {
+    const own = Buffer.from(message.buffer, message.byteOffset, message.byteLength);
+    const frames = splitFrames(own);
+    const synced = frames.some((f) => f.type === "S") || frames.at(-1)?.type === "Q";
+    const json = JSON.stringify(Object.fromEntries(settings));
+    const before = `BEGIN; ${sessionSetSql(state)}; SET ${SESSION_SETTINGS} = ${quoteLiteral(json)}`;
+    const after = `ROLLBACK; RESET ${SESSION_SETTINGS}; ${CATALOG_BASE_SQL}`;
+    return Buffer.concat([frame("Q", cstr(before)), own, ...(synced ? [] : [frame("S")]), frame("Q", cstr(after))]);
+}
+/** The reply to an `asSession` message, less the applier's and the restore's own replies (a CommandComplete a SET and a
+ *  ReadyForQuery, first and last). A SET the catalog refused is a Mason bug, said. */
+export function unwrapSession(frames) {
+    const sets = SESSION_SETS + 2;
+    const run = (from) => frames.slice(from, from + sets).every((f) => f.type === "C") && frames[from + sets]?.type === "Z";
+    const n = frames.length;
+    if (n < 2 * (sets + 1) || !run(0) || !run(n - sets - 1)) {
+        throw new Error(`the catalog Postgres did not take the session's settings around a request (${frames.map((f) => f.type).join(", ")}): report it`);
+    }
+    return frames.slice(sets + 1, n - sets - 1);
+}
 /**
  * WHAT A LEFT-OUT DEFAULT OR VIEW IS SAID AS, in one line (the test server's log printed every left-out source
  * view's whole definition at each start of the instance — 7 multi-line entries per start, most of a 190 KB log, their
@@ -257,7 +568,7 @@ export function leftOutLine(r) {
         return `catalog: a source default left out (${r.message}): ${r.statement}`;
     const missing = /^relation "([^"]+)" does not exist$/.exec(r.message)?.[1];
     const name = `${unquote(view[1])}.${unquote(view[2])}`;
-    return missing !== undefined ? `catalog: view ${name} left out: it reads ${missing}, which is not copied` : `catalog: view ${name} left out (${r.message})`;
+    return missing !== undefined ? `catalog: view ${name} left out: it reads ${missing}, which is not synced` : `catalog: view ${name} left out (${r.message})`;
 }
 const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
 /** One worker thread holding one PGlite: requests one at a time (PgCatalog's chain), each with a deadline. */
@@ -303,7 +614,8 @@ class CatalogWorker {
         return new Promise((resolve, reject) => {
             const id = this.#next++;
             const timer = setTimeout(() => {
-                this.#die(new Error(`the catalog did not answer ${what} within ${ms / 1000} s: PGlite was discarded (the next statement starts a fresh one; MASON_PG_CATALOG_TIMEOUT_MS raises the deadline)`));
+                // the message reaches the client on the wire and the request log: Mason's words, never the catalog's engine's name
+                this.#die(new Error(`the catalog did not answer ${what} within ${ms / 1000} s, so Mason started it again (the next statement is answered as usual; MASON_PG_CATALOG_TIMEOUT_MS raises the deadline)`));
                 void this.#worker.terminate();
             }, ms);
             timer.unref();
@@ -318,6 +630,7 @@ class CatalogWorker {
 }
 export class PgCatalog {
     #schema;
+    #roles;
     #idleMs;
     #statementMs;
     #log;
@@ -331,8 +644,12 @@ export class PgCatalog {
     #chain = Promise.resolve();
     #idleTimer = null;
     #lastUsed = 0;
+    /** the roles' row security policies (`catalogPolicies`), written once the listener checked the filters: run on the
+     *  instance up now and at every start after, until the schema or the roles are replaced */
+    #policies = [];
     constructor(schema, opts = {}) {
         this.#schema = schema;
+        this.#roles = opts.roles ?? new Map();
         this.#idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
         this.#statementMs = opts.statementMs ?? DEFAULT_STATEMENT_MS;
         this.#log = opts.log ?? ((line) => console.error(line));
@@ -344,12 +661,14 @@ export class PgCatalog {
         return this.#db !== null && this.#db.alive;
     }
     /** Runs raw frontend protocol bytes — one message or several (Parse, Bind, Describe, Execute, Sync in one buffer
-     *  works) — and returns the backend's raw reply, starting the instance when needed. */
-    run(message) {
+     *  works) — and returns the backend's raw reply, starting the instance when needed. `at`: the instant the first
+     *  message runs at, the start of the transaction it begins (`asSession`; catalog-worker.ts `pinnedClock`), in
+     *  MICROSECONDS since the epoch as Postgres's (src/lib/instant.ts), which the catalog reads back exactly. */
+    run(message, at) {
         return this.#enqueue(async () => {
             const db = await this.#ensureStarted();
             const copy = new Uint8Array(message);
-            const reply = await this.#ask(db, { op: "raw", bytes: copy }, "a statement", [copy.buffer]);
+            const reply = await this.#ask(db, { op: "raw", bytes: copy, ...(at !== undefined ? { at } : {}) }, "a statement", [copy.buffer]);
             this.#touch();
             return reply.bytes ?? new Uint8Array(0);
         });
@@ -367,13 +686,36 @@ export class PgCatalog {
     stop() {
         return this.#enqueue(() => this.#close("stopped"));
     }
-    /** Swaps in a new schema (after an apply): the running instance is stopped and the next `run` starts with the new
-     *  DDL. Resolves once the old instance is gone; a caller need not wait for it. */
-    replace(schema) {
+    /** Swaps in a new schema (after an apply), and the roles with it (the roles file moved): the running instance is
+     *  stopped and the next `run` starts with the new DDL. Resolves once the old instance is gone; a caller need not wait for it. */
+    replace(schema, roles = this.#roles) {
         this.#schema = schema;
+        this.#roles = roles;
+        this.#policies = [];
         this.#said.clear();
         return this.#enqueue(() => this.#close("replaced"));
     }
+    /**
+     * THE ROLES' ROW SECURITY POLICIES (`catalogPolicies`), written now (the instance started where needed) and at every
+     * start after, until the next `replace`. A statement the catalog refuses is said, never fatal: the rows are the copy's.
+     */
+    policies(ddl) {
+        return this.#enqueue(async () => {
+            this.#policies = ddl;
+            if (ddl.length === 0)
+                return;
+            const db = await this.#ensureStarted();
+            for (const sql of ddl) {
+                try {
+                    await this.#ask(db, { op: "query", sql }, "a row security policy");
+                }
+                catch (e) {
+                    this.#log(`catalog: a row security policy left out (${errorMessage(e)}): ${sql}`);
+                }
+            }
+            this.#touch();
+        });
+    }
     #enqueue(fn) {
         const result = this.#chain.then(fn);
         // the chain only ORDERS calls: a rejection reaches the caller through `result`, and the next call must still run
@@ -401,11 +743,12 @@ export class PgCatalog {
         if (this.#db !== null && this.#db.alive)
             return this.#db;
         this.#db = null;
-        const schema = this.#schema;
+        const schema = this.#schema, roles = this.#roles;
         const t0 = Date.now();
         const db = new CatalogWorker();
         try {
-            const started = await this.#ask(db, { op: "init", statements: ["SET TimeZone = 'UTC'", ...catalogDdl(schema), ...this.#setup], optional: [...catalogDefaults(schema), ...catalogViews(schema)] }, "its start");
+            const started = await this.#ask(db, { op: "init", statements: [CATALOG_BASE_SQL, ...catalogDdl(schema), ...catalogRoles(schema, roles), ...this.#setup],
+                optional: [...catalogDefaults(schema), ...catalogViews(schema, roles), ...this.#policies] }, "its start");
             // each left-out default or view: one line, once per schema (the instance starts again after every idle stop)
             for (const r of started.refused ?? []) {
                 const line = leftOutLine(r);
@@ -423,7 +766,7 @@ export class PgCatalog {
             throw new Error(`PGlite could not start: ${errorMessage(e)}`, { cause: e });
         }
         this.#db = db;
-        this.#log(`catalog: PGlite started in ${Date.now() - t0} ms with ${schema.tables.length} table(s)`);
+        this.#log(`catalog: PGlite started in ${Date.now() - t0} ms with ${schema.tables.length} table(s)${roles.size > 0 ? ` and ${roles.size} role(s)` : ""}`);
         this.#touch();
         return db;
     }

package/dist/src/api/postgres/encode.js

@@ -82,7 +82,9 @@ export function fieldOf(name, type, format) {
 export class EncodeError extends Error {
     /** the SQLSTATE Postgres raises for the same value (a timestamp past its range is 22008), else XX000: Mason's gap */
     code;
-    constructor(message, code = "XX000") { super(message); this.code = code; }
+    /** the registry entry that refused the value (src/duck/gaps.ts): the request log's `gap`; null for any other error */
+    gap;
+    constructor(message, code = "XX000", gap = null) { super(message); this.code = code; this.gap = gap; }
 }
 const refuse = (type, value, why) => {
     throw new EncodeError(`cannot send ${JSON.stringify(value)} as ${type}: ${why}`);

package/dist/src/api/postgres/explain.js

@@ -1,5 +1,6 @@
 import { parseSql, PostgresSyntaxError } from "./parser.js";
 import { Unsupported } from "./translate.js";
+import { gapMark } from "../../duck/gaps.js";
 const bodyOf = (n) => Object.values(n)[0];
 /** Postgres's defGetBoolean: no value is true; true / false / on / off / 1 / 0 */
 function booleanOf(name, arg, at) {
@@ -84,7 +85,7 @@ export function explainOptions(options) {
             }
             case "generic_plan":
                 if (booleanOf(name, b.arg, at))
-                    throw new Unsupported(`EXPLAIN (GENERIC_PLAN) is not supported by Mason (Mason gap explain-option)`, at, "0A000", "bind the parameters' values and EXPLAIN that: DuckDB plans the statement with them");
+                    throw new Unsupported(`EXPLAIN (GENERIC_PLAN) is not supported by Mason (${gapMark("explain-option")})`, at, "0A000", "bind the parameters' values and EXPLAIN that: Mason plans the statement with them", "explain-option");
                 break;
             case "format": {
                 const v = stringOf(name, b.arg, at);
@@ -93,7 +94,7 @@ export function explainOptions(options) {
                     break;
                 }
                 if (v === "xml" || v === "yaml")
-                    throw new Unsupported(`EXPLAIN (FORMAT ${v.toUpperCase()}) is not supported by Mason (Mason gap explain-option)`, at, "0A000", "write FORMAT TEXT or FORMAT JSON");
+                    throw new Unsupported(`EXPLAIN (FORMAT ${v.toUpperCase()}) is not supported by Mason (${gapMark("explain-option")})`, at, "0A000", "write FORMAT TEXT or FORMAT JSON", "explain-option");
                 throw new Unsupported(`unrecognized value for EXPLAIN option "format": "${v}"`, at, "22023");
             }
             default: throw new Unsupported(`unrecognized EXPLAIN option "${name}"`, at, "42601");

package/dist/src/api/postgres/listener.js

@@ -15,6 +15,7 @@
 import * as fs from "node:fs";
 import { parsePort } from "../../lib/port.js";
 import { plainListener } from "./plain.js";
+import { parseProxyFrom } from "./proxy.js";
 export const DEFAULT_PG_PORT = 5433;
 /** The listener's address from `env`, or the problem with its port (`parsePort`'s words). */
 export function pgListenerAddress(env, apiHost) {
@@ -24,8 +25,8 @@ export function pgListenerAddress(env, apiHost) {
     return { host: env.MASON_PG_HOST || apiHost, port: port.port };
 }
 /** Where and how the listener listens, from `env` (`MASON_PG_HOST`, `MASON_PG_PORT`, `MASON_PG_TLS_CERT`,
- *  `MASON_PG_TLS_KEY`, `MASON_PG_PLAIN`), or why it cannot: a bad port, half a certificate, plain off loopback. Reads no
- *  file, so a start can be refused before anything is made. */
+ *  `MASON_PG_TLS_KEY`, `MASON_PG_PLAIN`, `MASON_PG_PROXY_FROM`), or why it cannot: a bad port, half a certificate, plain
+ *  off loopback, a proxy's address that is no address. Reads no file, so a start can be refused before anything is made. */
 export function pgListenerSettings(env, apiHost) {
     const address = pgListenerAddress(env, apiHost);
     if ("problem" in address)
@@ -36,7 +37,14 @@ export function pgListenerSettings(env, apiHost) {
     const plain = plainListener(address.host, env.MASON_PG_PLAIN, Boolean(cert && key));
     if (plain !== null)
         return plain;
-    return { ...address, tls: cert && key ? { cert, key } : null };
+    const proxyFrom = parseProxyFrom(env.MASON_PG_PROXY_FROM);
+    if (proxyFrom !== null && "problem" in proxyFrom) {
+        return { problem: proxyFrom.problem, kind: "proxy_from",
+            why: "a PROXY header names the client every statement is recorded as, so it is believed only from the addresses this names",
+            fix: "Name the addresses of your TCP proxy or load balancer alone, comma-separated (MASON_PG_PROXY_FROM=10.0.0.0/16,10.1.0.0/16), " +
+                "or unset it to read no PROXY header — docs/POSTGRES-API.md \"Behind a TCP proxy\"" };
+    }
+    return { ...address, tls: cert && key ? { cert, key } : null, ...(proxyFrom !== null ? { proxyFrom } : {}) };
 }
 /** The certificate and key the settings name, read; or why not. */
 export function readPgTls(files) {