@mason-data/cli 0.8.0 → 0.9.0

package/README.md

@@ -114,7 +114,10 @@ again and remove `mason/models/`.
 | `mason usage [--since 7d] [--step 1h]` | What Mason did over time, from a sample a minute kept `MASON_HISTORY_DAYS` days: the statements and their p95, the rows and bytes sent, the synced data's size and rows, the stalest table, the stream's lag, the memory; then each synced table's own size. |
 | `mason stop` | Stops Mason for this project. The synced data and the state stay: the next `mason start` resumes in seconds. |
 | `mason destroy` | Removes this project's synced data (its file) and Mason's state in `.mason/`, stopping Mason first if it runs — and, when a table was replicated, its slot (and its publication, when Mason made it) on the database. Your files, `.mason/config.json` and the users stay: the next `mason start` syncs the tables again. |
-| `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, `GET /metrics` (Prometheus, numbers only), a clean stop on SIGTERM. `mason serve --help` lists every setting with its default. |
+| `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, `GET /metrics` (Prometheus, numbers only), a clean stop on SIGTERM. `mason serve --help` lists every setting with its default; `MASON_PROJECT_READONLY=1`, for a project folder deployed as committed, refuses every edit of its files there (`mason add`, `mason remove`, the page's Add and Remove), with "edit the files and deploy them". |
+| `mason login` | Signs this machine in to a hosted Mason service (`MASON_CLOUD_URL`, else `https://app.masondata.ai`): it prints a page and a code (on stderr, at once, so a coding agent can pass them on), opens the page in a browser on a terminal, waits until the code is approved, then says who is signed in and their organisations. The login is kept in `~/.config/mason/credentials.json` (0600), never in a project; refused while `MASON_TOKEN` is set, which every command uses first. [`docs/HOSTED-API.md`](../docs/HOSTED-API.md) is the API. |
+| `mason logout` | Revokes this machine's login to that service and removes it. When the service cannot be reached, the login is still removed, and it says it was NOT revoked and how to revoke it. |
+| `mason deploy [--replica <org>/<name>] [--dry-run] [--timeout 10m]` | Sends this project's files (the YAML under `mason/`: never `.env` or `.mason/`) to a replica on the hosted service (`--replica`, else `MASON_REPLICA`), after checking the project as `mason start` does, without connecting to any database, then waits until the replica runs it (exit 0), Mason there refuses it (its failure printed as it came, exit 1), or the timeout (exit 124: the deploy goes on, its id said). `--dry-run` prints each file, its size and its sha256, and sends nothing. The login is `MASON_TOKEN`, else `mason login`'s. |
 
 Every command documents itself: `mason --help` lists them, and `mason <command> --help` (or `mason help <command>`) says
 how to use one, with examples. Every command but `help` and `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
@@ -263,9 +266,15 @@ seeds it again.
 `mason doctor` checks all of this and says what is missing.
 
 - Node 22.13 or later. The SQL parser (`libpg-query`), the catalog (`PGlite`) and the engine (DuckDB) ship as
-  WebAssembly or prebuilt binaries: no native build, no Python or compiler needed.
-- Memory: the engine may use half the container's memory limit by default, else half the machine's RAM
-  (`MASON_DUCKDB_MEMORY=4GB` sets it; `mason doctor` says it). Sizing a server:
+  WebAssembly or prebuilt binaries: no native build, no Python or compiler needed. Mason's CI and the `mason-data`
+  image run Node 26.
+- On Node 24 Mason runs, but a bug in Node 24's V8 (nodejs/node#66366, fixed in Node 26) can now and then abort it
+  with `Check failed: jit_page_->allocations_.erase(addr) == 1`, as a process exits or when the catalog's worker stops
+  after idling. `mason start` starts a run that died after it was ready again (not under `--attach`), and `mason status`
+  shows the restart. To avoid it, use Node 26, or a 22.x release from 22.13.
+- Memory: by default the engine may use half the container's memory limit, else of the machine's RAM, or what leaves
+  2.5 GiB beside it when that is less, never under 128 MiB (`MASON_DUCKDB_MEMORY=4GB` sets it; `mason doctor` says
+  it). Under 3 GiB, with it unset, Mason starts and warns that the system may stop it. Sizing a server:
   [deploy/mason-data/README.md#memory](https://github.com/embeddable-hq/mason-data/blob/main/deploy/mason-data/README.md#memory).
 - Postgres 13 or later. Each table needs a primary key, or a `key:` in the sources file (polling only).
 

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

@@ -7,18 +7,65 @@
  *
  * Messages in: `{ id, op: "init", statements, optional? }` (start PGlite and run the DDL; the reply names the refused
  * statement, or the optional ones refused),
- * `{ id, op: "raw", bytes }` (frontend protocol bytes in, backend bytes out), `{ id, op: "query", sql }` (rows as
+ * `{ id, op: "raw", bytes, at? }` (frontend protocol bytes in, backend bytes out; `at`: the instant the FIRST message
+ * runs at, in microseconds since the epoch, `pinnedClock`), `{ id, op: "query", sql }` (rows as
  * objects, for the server's own lookups and the tests), `{ id, op: "close" }`. Every reply carries the id:
  * `{ id, ok: true, bytes | rows }` or `{ id, ok: false, message }`.
  */
 import { parentPort } from "node:worker_threads";
 import { PGlite } from "@electric-sql/pglite";
 import { citext } from "@electric-sql/pglite/contrib/citext";
+import { instantWallMs, nowMicros } from "../../lib/instant.js";
 const port = parentPort;
 if (port === null)
     throw new Error("catalog-worker.ts runs on a worker thread only");
 const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
 let db = null;
+/**
+ * THE CATALOG'S CLOCK IS THE SESSION'S TRANSACTION'S (GitHub issue 253, review r3 of PR 333): `bytes`' first message
+ * (`asSession`'s, which begins the request's transaction) runs with the wall clock PGlite reads held at `at`, the
+ * session's instant, and the rest with the real one. Postgres's transaction start is the instant its first message
+ * arrived (`xactStartTimestamp`), and every reader of it — now(), CURRENT_TIMESTAMP and the other keywords, a
+ * relative word (`'now'`, `'today'`) however it is spelt, computed or bound — reads that one value, so the catalog's
+ * transaction instant IS the session's and no statement is rewritten for it. `statement_timestamp()` and
+ * `clock_timestamp()` read the real clock, as on Postgres. PGlite's wall clock is `Date.now()`
+ * (emscripten's `clock_time_get(CLOCK_REALTIME)`), on this thread alone; the requests are one at a time.
+ * The instant is MICROSECONDS, as Postgres's (src/lib/instant.ts, GitHub issues 372, 363): `at` is handed to PGlite
+ * as the value it reads back as exactly that microsecond (`instantWallMs`), and the real clock after it is this
+ * thread's microsecond clock (`nowMicros`), floored at `at`: the two threads' clocks may disagree inside a
+ * millisecond, and `statement_timestamp()` must never read earlier than the transaction's start, as on Postgres.
+ */
+async function pinnedClock(instance, bytes, at) {
+    // a frame: its type byte, then its length (its own four bytes included)
+    const first = 1 + new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1);
+    const wall = Date.now;
+    const pinned = instantWallMs(at);
+    let head, tail;
+    try {
+        Date.now = () => pinned;
+        head = new Uint8Array(await instance.execProtocolRaw(bytes.subarray(0, first))); // a copy: PGlite may reuse its buffer
+        Date.now = () => instantWallMs(Math.max(at, nowMicros(wall)));
+        tail = await instance.execProtocolRaw(bytes.subarray(first));
+    }
+    finally {
+        Date.now = wall;
+    }
+    const out = new Uint8Array(head.length + tail.length);
+    out.set(head, 0);
+    out.set(tail, head.length);
+    return out;
+}
+/** a request run at no instant of a session's (the DDL, a parameter's input function): the real clock, in microseconds */
+async function microsClock(instance, bytes) {
+    const wall = Date.now;
+    try {
+        Date.now = () => instantWallMs(nowMicros(wall));
+        return await instance.execProtocolRaw(bytes);
+    }
+    finally {
+        Date.now = wall;
+    }
+}
 port.on("message", (m) => {
     void (async () => {
         try {
@@ -63,7 +110,7 @@ port.on("message", (m) => {
                 case "raw": {
                     if (db === null)
                         throw new Error("the catalog is not started");
-                    const bytes = await db.execProtocolRaw(m.bytes);
+                    const bytes = m.at === undefined ? await microsClock(db, m.bytes) : await pinnedClock(db, m.bytes, m.at);
                     const copy = new Uint8Array(bytes); // PGlite may reuse its buffer: a copy of our own is transferred
                     port.postMessage({ id: m.id, ok: true, bytes: copy }, [copy.buffer]);
                     return;

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

@@ -38,7 +38,7 @@ import { runnable } from "../../lib/runnable.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 { PG_API_TYPE_SPELLING, typeNameParts } from "./schema.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
@@ -117,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;
@@ -130,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);`);
@@ -170,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
@@ -190,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),
@@ -374,11 +430,77 @@ export function unwrapRole(frames) {
     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 placeholder parameter a session's settings ride in, for one request of its (`asSession`): named anew by each
- *  process, so no name a tool writes is it — `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. */
-export const SESSION_SETTINGS = `mason_${randomBytes(8).toString("hex")}.session`;
+/** 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
@@ -397,30 +519,40 @@ export function currentSettingSql() {
     ];
 }
 /**
- * A SESSION'S CATALOG REQUEST WITH ITS SETTINGS: `SET <SESSION_SETTINGS> = '<its settings as JSON>'` before the request's
- * frames and `RESET` 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 settings, and none of this
- * session's runs without them. A Sync is added before the RESET where the request has none (ignore_till_sync: a
- * setting left set would be every session's). `settings` are the listener's `sessionSetting`, never read here. The
- * catalog's search_path is pinned in the same SET (`public, pg_catalog`): the overrides of `current_setting` and
- * `version()` win only while public comes first, and the request must never depend on what the catalog was left with.
+ * 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, settings) {
+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));
-    return Buffer.concat([frame("Q", cstr(`SET search_path = public, pg_catalog; SET ${SESSION_SETTINGS} = ${quoteLiteral(json)}`)), own, ...(synced ? [] : [frame("S")]), frame("Q", cstr(`RESET ${SESSION_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 SETs' and the RESET's own replies (two CommandCompletes and a
- *  ReadyForQuery first, a CommandComplete and a ReadyForQuery last). A SET the catalog refused is a Mason bug, said. */
+/** 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 ok = frames[0]?.type === "C" && frames[1]?.type === "C" && frames[2]?.type === "Z";
+    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 (!ok || n < 5 || frames[n - 1].type !== "Z" || frames[n - 2].type !== "C") {
+    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(3, n - 2);
+    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
@@ -529,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);
         });
@@ -613,7 +747,7 @@ export class PgCatalog {
         const t0 = Date.now();
         const db = new CatalogWorker();
         try {
-            const started = await this.#ask(db, { op: "init", statements: ["SET TimeZone = 'UTC'", ...catalogDdl(schema), ...catalogRoles(schema, roles), ...this.#setup],
+            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 ?? []) {

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) {