@mason-data/cli 0.0.0-stage → 0.6.2

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

@@ -0,0 +1,248 @@
+/** A statement, or a part of one, this listener does not answer: named, placed, with a SQLSTATE and the way out. */
+export class Unsupported extends Error {
+    /** 0-based offset into the statement's text, or null when the whole statement is meant */
+    offset;
+    /** `0A000` feature not supported; `42601` syntax; `25006` read only; `22023` an invalid value */
+    sqlstate;
+    hint;
+    constructor(message, offset, sqlstate = "0A000", hint) {
+        super(message);
+        this.offset = offset;
+        this.sqlstate = sqlstate;
+        this.hint = hint;
+    }
+}
+const kindOf = (n) => Object.keys(n)[0] ?? "";
+const bodyOf = (n) => n[kindOf(n)];
+const strings = (nodes) => (nodes ?? []).map((n) => kindOf(n) === "String" ? String(bodyOf(n).sval ?? "") : "");
+const loc = (n) => {
+    if (n === undefined)
+        return null;
+    const b = bodyOf(n); // `{}` (a plain DISTINCT's entry) has no body
+    return typeof b?.location === "number" && b.location >= 0 ? b.location : null;
+};
+/** every node of a kind, anywhere under `n` */
+function collect(n, kind, out = []) {
+    if (Array.isArray(n)) {
+        for (const x of n)
+            collect(x, kind, out);
+        return out;
+    }
+    if (n === null || typeof n !== "object")
+        return out;
+    const o = n;
+    for (const [k, v] of Object.entries(o)) {
+        if (k === kind)
+            out.push({ [k]: v });
+        collect(v, kind, out);
+    }
+    return out;
+}
+const INFORMATION_SCHEMA = "information_schema";
+const PG_CATALOG = "pg_catalog";
+// ------------------------------------------------------------------ entry
+/** A statement other than a SELECT or an EXPLAIN (`duckTranslate` takes those): the session's, or refused by name. */
+function sessionStatement(stmt) {
+    const kind = kindOf(stmt);
+    switch (kind) {
+        case "VariableSetStmt": return setStatement(bodyOf(stmt));
+        case "VariableShowStmt": return { kind: "show", name: String(bodyOf(stmt).name ?? "").toLowerCase() };
+        case "TransactionStmt": {
+            const k = bodyOf(stmt).kind;
+            const tag = k === "TRANS_STMT_BEGIN" ? "BEGIN" : k === "TRANS_STMT_START" ? "START TRANSACTION" : k === "TRANS_STMT_COMMIT" ? "COMMIT" : k === "TRANS_STMT_ROLLBACK" ? "ROLLBACK" : null;
+            if (tag === null)
+                throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no transactions; BEGIN, COMMIT and ROLLBACK are accepted and do nothing`, null);
+            return { kind: "transaction", tag };
+        }
+        case "DiscardStmt": return { kind: "discard" };
+        case "DeallocateStmt": return { kind: "deallocate" };
+        case "InsertStmt":
+        case "UpdateStmt":
+        case "DeleteStmt":
+        case "MergeStmt":
+        case "CopyStmt":
+        case "TruncateStmt":
+        case "CreateStmt":
+        case "DropStmt":
+        case "AlterTableStmt":
+        case "CreateTableAsStmt":
+        case "ViewStmt":
+        case "IndexStmt":
+        case "GrantStmt":
+        case "CreateRoleStmt":
+        case "CreateFunctionStmt":
+        case "CreateSchemaStmt":
+        case "VacuumStmt":
+            throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: this is a read-only copy of the database's tables; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
+        case "PrepareStmt":
+        case "ExecuteStmt": throw new Unsupported(`${kind === "PrepareStmt" ? "PREPARE" : "EXECUTE"} is not supported: use the protocol's prepared statements (every driver does)`, null);
+        default:
+            throw new Unsupported(`${kind.replace(/Stmt$/, "")}: not a statement this listener answers (SELECT, EXPLAIN, a catalog query, SET, SHOW, BEGIN/COMMIT)`, null);
+    }
+}
+/**
+ * ONE STATEMENT CLASSIFIED (docs/DESIGN.md decision D): a SELECT that reads any table outside pg_catalog /
+ * information_schema is DuckDB's (`text`, the parser's slice of the message, for the plan to be made from); one that
+ * reads only the catalog, or no table at all (`SELECT version()`, `SELECT 1`), is the catalog Postgres's. Every other
+ * statement is the session's or refused (`sessionStatement`), but an EXPLAIN, which is the statement it explains.
+ * NOTHING reaches DuckDB but a SELECT Postgres analysed and the rewrite read back (src/duck/plan.ts): DuckDB's `EXPLAIN
+ * ANALYZE` runs the statement under it, and its text, unanalysed, could write to the copy or read the attached source
+ * (a review finding).
+ */
+export function duckTranslate(stmt, text) {
+    const kind = kindOf(stmt);
+    // an EXPLAIN is the statement it explains (src/api/postgres/explain.ts, src/duck/explain.ts): its options read, then
+    // that statement classified as it would be alone, by the server
+    if (kind === "ExplainStmt") {
+        const e = bodyOf(stmt);
+        if (e.query === undefined)
+            throw new Unsupported("EXPLAIN of nothing", null, "42601");
+        return { kind: "explain", query: e.query, options: e.options ?? [] };
+    }
+    if (kind !== "SelectStmt")
+        return sessionStatement(stmt);
+    const s = bodyOf(stmt);
+    const ctes = (s.withClause?.ctes ?? []).map((n) => bodyOf(n));
+    const names = new Set(ctes.map((c) => String(c.ctename ?? "")));
+    const relations = collect(s, "RangeVar").map((n) => bodyOf(n)).filter((r) => r.schemaname !== undefined || !names.has(String(r.relname ?? "")));
+    if (relations.every(isCatalogRelation))
+        return { kind: "catalog" };
+    return { kind: "duckdb", sql: text, names: pgColumnNames(s) };
+}
+/**
+ * THE NAMES POSTGRES GIVES A SELECT'S RESULT COLUMNS (`FigureColname`, src/backend/parser/parse_target.c), where DuckDB
+ * gives others (`count(*)` is `count_star()`, `sum(x)` is `sum(x)`; Postgres says `count`, `sum`): an alias as written,
+ * a column's name, a function's, a cast's inner name or else its type's, `case`, `coalesce` …, and `?column?` for the
+ * rest. A `*` is DuckDB's (its width is known only from the result: `null` there, one star at most). A set operation's
+ * names are its first arm's. Null when the list cannot be named (two stars): DuckDB's names stand.
+ */
+export function pgColumnNames(s) {
+    if (s.op !== undefined && s.op !== "SETOP_NONE" && s.larg !== undefined)
+        return pgColumnNames(s.larg);
+    if (s.valuesLists !== undefined && s.valuesLists.length > 0) {
+        const first = s.valuesLists[0];
+        const width = kindOf(first) === "List" ? (bodyOf(first).items ?? []).length : 0;
+        return Array.from({ length: width }, (_, i) => `column${i + 1}`);
+    }
+    const names = [];
+    let stars = 0;
+    for (const t of s.targetList ?? []) {
+        const rt = bodyOf(t);
+        if (rt.name !== undefined) {
+            names.push(rt.name);
+            continue;
+        }
+        if (rt.val !== undefined && kindOf(rt.val) === "ColumnRef" && (bodyOf(rt.val).fields ?? []).some((f) => kindOf(f) === "A_Star")) {
+            stars++;
+            names.push(null);
+            continue;
+        }
+        names.push(rt.val === undefined ? "?column?" : figureColname(rt.val)[0] ?? "?column?");
+    }
+    return stars > 1 ? null : names;
+}
+const SQL_VALUE_NAMES = {
+    SVFOP_CURRENT_DATE: "current_date", SVFOP_CURRENT_TIME: "current_time", SVFOP_CURRENT_TIME_N: "current_time", SVFOP_CURRENT_TIMESTAMP: "current_timestamp",
+    SVFOP_CURRENT_TIMESTAMP_N: "current_timestamp", SVFOP_LOCALTIME: "localtime", SVFOP_LOCALTIME_N: "localtime", SVFOP_LOCALTIMESTAMP: "localtimestamp",
+    SVFOP_LOCALTIMESTAMP_N: "localtimestamp", SVFOP_CURRENT_ROLE: "current_role", SVFOP_CURRENT_USER: "current_user", SVFOP_USER: "user",
+    SVFOP_SESSION_USER: "session_user", SVFOP_CURRENT_CATALOG: "current_catalog", SVFOP_CURRENT_SCHEMA: "current_schema",
+};
+/** FigureColnameInternal: the name and its strength (0 none, 1 a fallback such as a cast's type or `case`, 2 a real one) */
+function figureColname(n) {
+    const k = kindOf(n);
+    const b = bodyOf(n);
+    switch (k) {
+        case "ColumnRef": {
+            const last = strings(b.fields).filter((x) => x !== "").pop();
+            return last === undefined ? [null, 0] : [last, 2];
+        }
+        case "A_Indirection": {
+            const ind = b.indirection ?? [];
+            const last = ind[ind.length - 1];
+            if (last !== undefined && kindOf(last) === "String")
+                return [String(bodyOf(last).sval ?? ""), 2];
+            return b.arg ? figureColname(b.arg) : [null, 0];
+        }
+        case "FuncCall": {
+            const last = strings(b.funcname).pop();
+            return last === undefined ? [null, 0] : [last, 2];
+        }
+        case "A_Expr": return b.kind === "AEXPR_NULLIF" ? ["nullif", 2] : [null, 0];
+        case "TypeCast": {
+            const inner = b.arg ? figureColname(b.arg) : [null, 0];
+            if (inner[1] > 0)
+                return inner;
+            const typeName = strings(b.typeName?.names).pop();
+            return typeName === undefined ? [null, 0] : [typeName, 1];
+        }
+        case "CollateClause": return b.arg ? figureColname(b.arg) : [null, 0];
+        case "GroupingFunc": return ["grouping", 2];
+        case "SubLink": {
+            if (b.subLinkType === "EXISTS_SUBLINK")
+                return ["exists", 2];
+            if (b.subLinkType === "ARRAY_SUBLINK")
+                return ["array", 2];
+            if (b.subLinkType === "EXPR_SUBLINK" && b.subselect !== undefined && kindOf(b.subselect) === "SelectStmt") {
+                const first = bodyOf(b.subselect).targetList?.[0];
+                if (first !== undefined) {
+                    const rt = bodyOf(first);
+                    if (rt.name !== undefined)
+                        return [rt.name, 2];
+                    if (rt.val !== undefined)
+                        return figureColname(rt.val);
+                }
+            }
+            return [null, 0];
+        }
+        case "CaseExpr": {
+            const d = b.defresult ? figureColname(b.defresult) : [null, 0];
+            return d[1] <= 1 ? ["case", 1] : d;
+        }
+        case "A_ArrayExpr": return ["array", 2];
+        case "RowExpr": return ["row", 2];
+        case "CoalesceExpr": return ["coalesce", 2];
+        case "MinMaxExpr": return [b.op === "IS_LEAST" ? "least" : "greatest", 2];
+        case "SQLValueFunction": {
+            const v = SQL_VALUE_NAMES[String(b.op)];
+            return v === undefined ? [null, 0] : [v, 2];
+        }
+    }
+    // every other expression has no name of its own: Postgres calls it ?column? (a naming rule, not an accepting one)
+    return [null, 0];
+}
+function setStatement(s) {
+    const name = String(s.name ?? "").toLowerCase();
+    if (s.kind === "VAR_RESET" || s.kind === "VAR_SET_DEFAULT")
+        return { kind: "set", name, value: null, local: s.is_local === true };
+    if (s.kind === "VAR_RESET_ALL")
+        return { kind: "set", name: "all", value: null, local: false };
+    if (s.kind === "VAR_SET_MULTI")
+        return { kind: "set", name, value: "", local: s.is_local === true }; // SET SESSION CHARACTERISTICS …
+    if (s.kind !== "VAR_SET_VALUE")
+        throw new Unsupported(`SET ${name}: ${String(s.kind)} is not supported`, s.location ?? null);
+    const parts = (s.args ?? []).map((a) => {
+        if (kindOf(a) === "A_Const")
+            return constText(bodyOf(a));
+        if (kindOf(a) === "TypeCast") {
+            const c = bodyOf(a);
+            if (c.arg !== undefined && kindOf(c.arg) === "A_Const")
+                return constText(bodyOf(c.arg));
+        }
+        throw new Unsupported(`SET ${name}: a value of kind ${kindOf(a)} is not supported (a literal is)`, loc(a));
+    });
+    return { kind: "set", name, value: parts.join(", "), local: s.is_local === true };
+}
+function constText(c) {
+    if (c.sval !== undefined)
+        return String(c.sval.sval ?? "");
+    if (c.ival !== undefined)
+        return String(c.ival.ival ?? 0);
+    if (c.fval !== undefined)
+        return String(c.fval.fval ?? "0");
+    if (c.boolval !== undefined)
+        return c.boolval.boolval ? "on" : "off";
+    if (c.isnull === true)
+        return "";
+    return "";
+}
+const isCatalogRelation = (r) => r.schemaname === PG_CATALOG || r.schemaname === INFORMATION_SCHEMA || (r.schemaname === undefined && String(r.relname ?? "").startsWith("pg_"));

package/dist/src/api/request-log.js

@@ -0,0 +1,50 @@
+/**
+ * ONE ROW OF THE REQUEST LOG, as the Postgres listener builds it (src/api/postgres/server.ts `recordRequest`) and the
+ * run's ledger keeps it (src/duck/requests.ts, `_mason.requests`): every statement answered or refused, and every
+ * refused login. The helpers here say who asked without keeping the credential (`hashCaller`), cap the statement
+ * (`storedPayload`) and name an outcome from its SQLSTATE (`outcomeOf`), read by the listener's refusal line and the
+ * ledger alike.
+ */
+import * as crypto from "node:crypto";
+/** Fail closed on the storage side: never let one request bloat the ledger. */
+export const MAX_STORED_PAYLOAD_BYTES = 64 * 1024;
+/**
+ * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `failed` where the fault is Mason's
+ * or the machine's (classes XX internal, 53 resources, 57 a timeout or a cancel, 58 system), `refused` for the
+ * statement's own, `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log
+ * (src/duck/requests.ts) alike.
+ */
+export function outcomeOf(sqlstate) {
+    if (sqlstate === null || sqlstate === undefined || sqlstate === "")
+        return "ok";
+    return /^(XX|53|57|58)/.test(sqlstate) ? "failed" : "refused";
+}
+/**
+ * The caller's identity WITHOUT the credential: a truncated SHA-256 of what was presented. Distinct callers stay
+ * distinguishable and repeat callers stay correlatable, while the secret itself is never written down — the log must
+ * not become a place where a leaked table hands over working credentials.
+ *
+ * Truncation to 16 hex characters (64 bits) is deliberate: enough that two real callers will not collide, short enough
+ * that the column stays cheap, and far too short to brute-force a high-entropy key back out of.
+ */
+export function hashCaller(presented) {
+    if (presented === null || presented === "")
+        return "";
+    return crypto.createHash("sha256").update(presented).digest("hex").slice(0, 16);
+}
+/**
+ * The statement as it arrived, capped. Stored whole, not redacted: the statements most worth having are the ones that
+ * FAILED, and a normalised one tells nothing about what actually arrived. The cap is a storage bound, not a privacy
+ * one, and `payloadTruncated` says plainly when a row is not the whole story.
+ */
+export function storedPayload(body) {
+    const buf = Buffer.from(body, "utf8");
+    if (buf.byteLength <= MAX_STORED_PAYLOAD_BYTES)
+        return { text: body, truncated: false };
+    // Slice on a character boundary: a half-written UTF-8 sequence would be
+    // stored as a replacement character and misread as corruption in the source.
+    return {
+        text: buf.subarray(0, MAX_STORED_PAYLOAD_BYTES).toString("utf8"),
+        truncated: true,
+    };
+}