@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/fake-grants-read.ts

@@ -0,0 +1,250 @@
+/**
+ * The read-answering half of the `Postgres.Grants` test fake: the `aclexplode`-shaped
+ * queries and the existence/ownership checks, answered from the server model's ACL
+ * (`fake-grants-sql.ts`), never from the statement list (S28). The entry and model shape
+ * are defined HERE so the write half (`fake-grants-write.ts`) can import them without a
+ * cycle.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { AclObject } from './fake-grants-parse.ts';
+
+/** One `aclitem` as the fake stores it: one (object, grantee, grantor) with the words that
+ * grantor granted, `*`-marked when WITH GRANT OPTION. `words` is mutable: grants and
+ * revokes edit it. */
+export interface AclEntry {
+  readonly object: AclObject;
+  readonly grantee: string;
+  readonly grantor: string;
+  words: string[];
+}
+
+/** One relation in the fake's catalog: every relation a table/column statement may name,
+ * with its columns, its `relkind` (default `'r'`) and its owner (default: the executor
+ * role, which no declared seat role owns). A sequence is a row with `relkind: 'S'`. */
+export interface FakeCatalogTable {
+  readonly schema: string;
+  readonly table: string;
+  readonly columns?: ReadonlyArray<string>;
+  readonly relkind?: string;
+  readonly owner?: string;
+}
+
+/** What the read half needs from the factory, keyed per schema so two schemas may hold
+ * same-named relations: `relkinds`/`tableOwners` map `"schema\0table"`, `schemaOwners`
+ * maps the schema to its owning role. */
+export interface FakeGrantsModel {
+  readonly schemas: ReadonlySet<string>;
+  readonly roles: ReadonlySet<string>;
+  readonly databases: ReadonlySet<string>;
+  readonly tables: ReadonlyArray<FakeCatalogTable>;
+  readonly acl: AclEntry[];
+  readonly relkinds: ReadonlyMap<string, string>;
+  readonly tableOwners: ReadonlyMap<string, string>;
+  readonly schemaOwners: ReadonlyMap<string, string>;
+  /** `current_user` — the grantor a write records, and the revoker the column read reports. */
+  readonly executor: string;
+  /** Whether `current_user` is a superuser: one arm of `revokesAsOwner` (a superuser revokes
+   * as the object owner, `revoke.sgml`). */
+  readonly executorSuper: boolean;
+  /** The roles `current_user` is a member of (recursively): a member of the owning role revokes
+   * as that role (`revokesAsOwner`). */
+  readonly executorMemberships: ReadonlySet<string>;
+  /** What `SELECT current_database()` answers. */
+  readonly connected: string;
+}
+
+const aclShapeRow = (marked: string): { privilege: string; grantable: boolean } => ({
+  privilege: marked.replace(/\*$/, ''),
+  grantable: marked.endsWith('*'),
+});
+
+/** Whether a `REVOKE` from the executor is performed as the object's owner (`select_best_grantor`
+ * acl.c@REL_18_6): a superuser, the owner itself, or a member of the owning role. Gates the
+ * column read's `grantor === owner` arm; the write path removes the owner's grant under it. */
+export const revokesAsOwner = (model: FakeGrantsModel, owner: string): boolean =>
+  model.executorSuper || model.executor === owner || model.executorMemberships.has(owner);
+
+/** Explode the model into aclexplode-shaped rows, filtered to one read's object shape
+ * and grantee set. */
+const rows = <R>(
+  acl: ReadonlyArray<AclEntry>,
+  pickObject: (object: AclObject) => boolean,
+  pickGrantee: (grantee: string) => boolean,
+  shape: (entry: AclEntry, word: string) => R,
+): R[] => {
+  const out: R[] = [];
+  for (const entry of acl) {
+    if (!pickObject(entry.object) || !pickGrantee(entry.grantee)) continue;
+    for (const word of entry.words) out.push(shape(entry, word));
+  }
+  return out;
+};
+
+const granteeFilter =
+  (role: string) =>
+  (grantee: string): boolean =>
+    grantee === role || grantee === 'PUBLIC';
+
+/** Answer the reads the family issues: the two existence checks, the schema/table/column/
+ * default `aclexplode` reads, and the two ownership reads. `undefined` when the text is no
+ * read this fake answers — the caller applies it as a write. */
+export const answerRead = <A extends object>(
+  text: string,
+  params: ReadonlyArray<unknown>,
+  model: FakeGrantsModel,
+): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
+  const { acl, schemas, roles, databases, tables } = model;
+
+  if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+    return Effect.succeed(
+      (roles.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.startsWith('SELECT 1 AS present FROM pg_namespace')) {
+    return Effect.succeed(
+      (schemas.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.startsWith('SELECT 1 AS present FROM pg_database')) {
+    return Effect.succeed(
+      (databases.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.startsWith('SELECT current_database()')) {
+    return Effect.succeed([{ database: model.connected }] as unknown as ReadonlyArray<A>);
+  }
+
+  const jsonNames = (value: unknown): unknown => {
+    if (typeof value !== 'string') {
+      throw new Error(
+        `fake-grants-read: existence param must be a JSON string, got ${typeof value}`,
+      );
+    }
+    return JSON.parse(value) as unknown;
+  };
+
+  const [schema, role] = [params[0] as string, params[1] as string];
+  if (
+    text.includes('c.relname AS table') &&
+    text.includes('pg_class c') &&
+    text.includes('json_array_elements_text') &&
+    !text.includes('pg_attribute')
+  ) {
+    const want = new Set(jsonNames(params[1]) as ReadonlyArray<string>);
+    return Effect.succeed(
+      tables
+        .filter((t) => t.schema === schema && want.has(t.table))
+        .map((t) => ({ table: t.table })) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.includes('a.attname AS column') && text.includes('json_array_elements($2::json)')) {
+    const pairs = jsonNames(params[1]) as ReadonlyArray<readonly [string, string]>;
+    const want = new Set(pairs.map(([table, column]) => `${table}\u0000${column}`));
+    return Effect.succeed(
+      tables
+        .filter((t) => t.schema === schema)
+        .flatMap((t) =>
+          (t.columns ?? [])
+            .filter((c) => want.has(`${t.table}\u0000${c}`))
+            .map((c) => ({ table: t.table, column: c })),
+        ) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.includes('aclexplode(n.nspacl)')) {
+    return Effect.succeed(
+      rows(
+        acl,
+        (o) =>
+          o.schema === schema &&
+          o.table === undefined &&
+          o.column === undefined &&
+          o.defaultFor === undefined,
+        granteeFilter(role),
+        (entry, marked) => ({ public: entry.grantee === 'PUBLIC', ...aclShapeRow(marked) }),
+      ) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.includes('aclexplode(c.relacl)')) {
+    // The relkind comes back shaped exactly as the query TEXT dictates: the production
+    // SQL casts `c.relkind::text` (OID 25, a string); without the cast the `"char"` OID 18
+    // column decodes to raw bytes on the socket transport (`PgTypes` has no OID 18 codec),
+    // so this fake hands back the same `Uint8Array` the real wire would — one byte per
+    // relkind letter — to keep a regression test honest.
+    const relkindFor = (object: AclObject): unknown => {
+      const relkind = model.relkinds.get(`${object.schema}\u0000${object.table ?? ''}`) ?? 'r';
+      if (text.includes('c.relkind::text')) return relkind;
+      return new Uint8Array(relkind.split('').map((ch) => ch.charCodeAt(0)));
+    };
+    return Effect.succeed(
+      rows(
+        acl,
+        (o) =>
+          o.schema === schema &&
+          o.table !== undefined &&
+          o.column === undefined &&
+          o.defaultFor === undefined,
+        granteeFilter(role),
+        (entry, marked) => ({
+          table: entry.object.table,
+          relkind: relkindFor(entry.object),
+          public: entry.grantee === 'PUBLIC',
+          ...aclShapeRow(marked),
+        }),
+      ) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.includes('aclexplode(v.attacl)')) {
+    return Effect.succeed(
+      rows(
+        acl,
+        (o) => o.schema === schema && o.column !== undefined,
+        granteeFilter(role),
+        (entry, marked) => {
+          const owner =
+            model.tableOwners.get(`${entry.object.schema}\u0000${entry.object.table ?? ''}`) ??
+            model.executor;
+          return {
+            table: entry.object.table,
+            column: entry.object.column,
+            public: entry.grantee === 'PUBLIC',
+            grantor: entry.grantor,
+            owner,
+            revoker: model.executor,
+            revoker_as_owner: revokesAsOwner(model, owner),
+            ...aclShapeRow(marked),
+          };
+        },
+      ) as unknown as ReadonlyArray<A>,
+    );
+  }
+  if (text.includes('aclexplode(d.defaclacl)')) {
+    // The defaults read selects ONLY the declared role's words — never PUBLIC's.
+    return Effect.succeed(
+      rows(
+        acl,
+        (o) => o.schema === schema && o.defaultFor !== undefined,
+        (grantee) => grantee === role,
+        (entry, marked) => ({ for_role: entry.object.defaultFor, ...aclShapeRow(marked) }),
+      ) as unknown as ReadonlyArray<A>,
+    );
+  }
+
+  // The ownership reads: `nspowner` answers per schema, `relowner` per relation, all
+  // relkinds — from the catalog and the owner maps, never from ACL rows (a fresh owned
+  // object carries none).
+  if (text.includes('nspowner')) {
+    const owns = model.schemaOwners.get(schema) === role;
+    return Effect.succeed([{ role_owns: owns }] as unknown as ReadonlyArray<A>);
+  }
+  if (text.includes('relowner')) {
+    const owned = tables
+      .filter(
+        (t) => t.schema === schema && model.tableOwners.get(`${schema}\u0000${t.table}`) === role,
+      )
+      .map((t) => ({ table: t.table }));
+    return Effect.succeed(owned as unknown as ReadonlyArray<A>);
+  }
+
+  return undefined;
+};

package/src/postgres/fake-grants-sql.ts

@@ -0,0 +1,207 @@
+/**
+ * The server-model half of the `Postgres.Grants` test fake: an in-memory ACL the way
+ * PostgreSQL 18 packs it — one entry per (object, grantee, grantor) pair holding that
+ * grantor's granted words — plus the ten statements the parser (`fake-grants-parse.ts`)
+ * reduces, applied with the server rules the plan's convergence depends on. The
+ * `aclexplode`-shaped reads are answered by `fake-grants-read.ts` from the same model; the
+ * grant/revoke semantics (the "revokes as owner" rule included) live in
+ * `fake-grants-write.ts`.
+ *
+ * ★ `REVOKE ALL ON <table>` ALSO clears that grantee's column entries on the table
+ *   (measured on PG 18.6 — the plan's convergence proof depends on the model answering
+ *   the same), and `REVOKE ALL ON ALL TABLES IN SCHEMA` skips the relkinds the server
+ *   skips — a sequence keeps its grants (measured, `grants-plan.ts`).
+ * ★ A statement naming a relation or column the catalog does not know fails `42P01` /
+ *   `42703`, the way the server refuses a missing object.
+ */
+import * as Effect from 'effect/Effect';
+import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { type AclEntry, type FakeCatalogTable, answerRead } from './fake-grants-read.ts';
+import { parseGrantStatement } from './fake-grants-parse.ts';
+import { grantWords, revoke } from './fake-grants-write.ts';
+import { relkindIsPublicRevocable } from './grants-words.ts';
+
+export type { AclEntry, FakeCatalogTable };
+
+export interface RecordedStatement {
+  readonly text: string;
+  readonly params: ReadonlyArray<unknown>;
+}
+
+export interface FakeGrants extends PgExecutor {
+  readonly statements: ReadonlyArray<RecordedStatement>;
+  /** Each `transaction` call, in order — the statement list that committed together. */
+  readonly transactions: ReadonlyArray<ReadonlyArray<string>>;
+  /** Mutable on purpose: a test seeds a "competing" grant the same way `fake-sql.ts`'s
+   * `databases` map is seeded before the reconcile ever runs. */
+  readonly acl: AclEntry[];
+}
+
+export interface FakeGrantsOptions {
+  /** Schemas the existence check (`pg_namespace`) answers yes for. */
+  readonly schemas?: ReadonlyArray<string>;
+  /** Roles the existence check (`pg_roles`) answers yes for. */
+  readonly roles?: ReadonlyArray<string>;
+  /** Databases the existence check (`pg_database`) answers yes for. */
+  readonly databases?: ReadonlyArray<string>;
+  /** The catalog: every relation a table/column statement may name, with its columns,
+   * relkind and owner (see `fake-grants-read.ts#FakeCatalogTable`). */
+  readonly tables?: ReadonlyArray<FakeCatalogTable>;
+  /** The role that owns each seeded schema; unset means the executor owns it. */
+  readonly schemaOwner?: string;
+  /** Seed grants, each carrying its own grantor (the third-grantor survival cases). */
+  readonly acl?: ReadonlyArray<Omit<AclEntry, 'words'> & { readonly words: ReadonlyArray<string> }>;
+  /** The role the statements run AS — the grantor recorded on every write, and
+   * `current_user` on the column read (default `postgres`, the owner the fixtures assume). */
+  readonly executor?: string;
+  /** Whether the executor is a superuser (default `true`: `postgres` is). A superuser, the
+   * owner itself, or a member of the owning role revokes as the owner — `revoke.sgml`'s rule,
+   * modelled by `revokesAsOwner` (fake-grants-read.ts) on both the read and the write. */
+  readonly executorSuper?: boolean;
+  /** The roles the executor is a member of (recursively): a member of a table's owning role
+   * revokes that table's grants as the owner, the same as a superuser. */
+  readonly executorMemberships?: ReadonlyArray<string>;
+  /** What `current_database()` answers (default `agents`, the declaration the fixtures use). */
+  readonly connected?: string;
+}
+
+const failSql = (code: string, message: string, operation: string) =>
+  Effect.fail(
+    new SqlError({
+      reason: new SqlSyntaxError({
+        cause: Object.assign(new Error(message), { code }),
+        message,
+        operation,
+      }),
+    }),
+  );
+
+export const makeFakeGrants = (options: FakeGrantsOptions = {}): FakeGrants => {
+  const statements: RecordedStatement[] = [];
+  const transactions: string[][] = [];
+  const schemas = new Set(options.schemas ?? []);
+  const roles = new Set(options.roles ?? []);
+  const databases = new Set(options.databases ?? []);
+  const tables = options.tables ?? [];
+  const executor = options.executor ?? 'postgres';
+  const executorSuper = options.executorSuper ?? true;
+  const executorMemberships = new Set(options.executorMemberships ?? []);
+  const connected = options.connected ?? 'agents';
+  const acl: AclEntry[] = (options.acl ?? []).map((seed) => ({ ...seed, words: [...seed.words] }));
+
+  // The catalog as pg_class really holds it: relkind and owner per (schema, table), the
+  // schema owned by `schemaOwner` or the executor. Default table owner is the schema
+  // owner — a CREATE inside a namespace makes its creator the relation's owner too.
+  const schemaOwner = options.schemaOwner ?? executor;
+  const relkinds = new Map<string, string>();
+  const tableOwners = new Map<string, string>();
+  for (const t of tables) {
+    relkinds.set(`${t.schema}\u0000${t.table}`, t.relkind ?? 'r');
+    tableOwners.set(`${t.schema}\u0000${t.table}`, t.owner ?? schemaOwner);
+  }
+  const schemaOwners = new Map<string, string>();
+  for (const schema of schemas) schemaOwners.set(schema, schemaOwner);
+  const model = {
+    schemas,
+    roles,
+    databases,
+    tables,
+    acl,
+    relkinds,
+    tableOwners,
+    schemaOwners,
+    executor,
+    executorSuper,
+    executorMemberships,
+    connected,
+  };
+
+  const knownTable = (schema: string, table: string) =>
+    tables.find((t) => t.schema === schema && t.table === table);
+
+  /** Apply one parsed write, validating its target against the catalog first. */
+  const applyWrite = (text: string): Effect.Effect<ReadonlyArray<never>, SqlError> => {
+    const parsed = parseGrantStatement(text);
+    if (parsed === undefined) {
+      throw new Error(`fake-grants-sql: unrecognised statement: ${text}`);
+    }
+    if (parsed.object.table !== undefined) {
+      const known = knownTable(parsed.object.schema, parsed.object.table);
+      if (known === undefined) {
+        return failSql(
+          '42P01',
+          `relation "${parsed.object.table}" does not exist`,
+          text.slice(0, 30),
+        );
+      }
+      if (
+        parsed.object.column !== undefined &&
+        !(known.columns ?? []).includes(parsed.object.column)
+      ) {
+        return failSql(
+          '42703',
+          `column "${parsed.object.column}" does not exist`,
+          text.slice(0, 30),
+        );
+      }
+    }
+    const operation = text.slice(0, 30);
+    if (parsed.allTables === true) {
+      // `ON ALL TABLES IN SCHEMA` reaches only the revocable relkinds — a sequence keeps
+      // its grants (measured on PG 18.6, `grants-plan.ts`).
+      for (const table of tables.filter(
+        (t) => t.schema === parsed.object.schema && relkindIsPublicRevocable(t.relkind ?? 'r'),
+      )) {
+        const tableObject = { schema: parsed.object.schema, table: table.table };
+        const tableError = revoke(model, tableObject, parsed.grantee, operation);
+        if (tableError !== undefined) return Effect.fail(tableError);
+        for (const column of table.columns ?? []) {
+          const columnError = revoke(model, { ...tableObject, column }, parsed.grantee, operation);
+          if (columnError !== undefined) return Effect.fail(columnError);
+        }
+      }
+      return Effect.succeed([]);
+    }
+    if (parsed.kind === 'grant') {
+      grantWords(model, parsed.object, parsed.grantee, parsed.words, parsed.option);
+      return Effect.succeed([]);
+    }
+    const error = revoke(model, parsed.object, parsed.grantee, operation);
+    if (error !== undefined) return Effect.fail(error);
+    // A table-level `REVOKE ALL` also clears that grantee's column entries on the table
+    // (measured on PG 18.6 — a table revoke reaches its columns, unlike `ON ALL TABLES`).
+    if (parsed.object.table !== undefined && parsed.object.column === undefined) {
+      const known = knownTable(parsed.object.schema, parsed.object.table);
+      for (const column of known?.columns ?? []) {
+        const columnError = revoke(
+          model,
+          { schema: parsed.object.schema, table: parsed.object.table, column },
+          parsed.grantee,
+          operation,
+        );
+        if (columnError !== undefined) return Effect.fail(columnError);
+      }
+    }
+    return Effect.succeed([]);
+  };
+
+  const unsafe = <A extends object>(
+    text: string,
+    params: ReadonlyArray<unknown> = [],
+  ): Effect.Effect<ReadonlyArray<A>, SqlError> =>
+    Effect.suspend(() => {
+      statements.push({ text, params });
+      const read = answerRead<A>(text, params, model);
+      if (read !== undefined) return read;
+      return applyWrite(text) as unknown as Effect.Effect<ReadonlyArray<A>, SqlError>;
+    });
+
+  const transaction = (sqls: readonly string[]): Effect.Effect<void, SqlError> =>
+    Effect.gen(function* () {
+      transactions.push([...sqls]);
+      for (const sql of sqls) yield* unsafe(sql).pipe(Effect.asVoid);
+    });
+
+  return { unsafe, transaction, statements, transactions, acl };
+};

package/src/postgres/fake-grants-write.ts

@@ -0,0 +1,90 @@
+/**
+ * The write-semantics half of the `Postgres.Grants` test fake, extracted from
+ * `fake-grants-sql.ts` (the factory and the statement parser) to keep both files under the
+ * cap: how one `GRANT`/`REVOKE` edits the in-memory ACL with the server's rule that a
+ * superuser, the owner itself, or a member of the owning role performs the command AS the
+ * owner (`select_best_grantor`, acl.c@REL_18_6; `revoke.sgml@REL_18_6`).
+ *
+ * ★ THE EFFECTIVE GRANTOR. `effectiveGrantor` names the role a write is recorded as: the
+ *   owner when the executor acts as owner, otherwise the executor. A relation (table, column)
+ *   is owned by its `relowner`; a schema by its `nspowner`; a default ACL has no owner, so the
+ *   executor's own grants are the only ones its writes touch.
+ * ★ `GRANT` records the words on the effective grantor's entry, upgrading a base word to its
+ *   `*` (WITH GRANT OPTION) form rather than keeping both — one `aclitem` per pair.
+ * ★ `REVOKE ALL` removes the effective grantor's entry only: a third grantor's grant to the
+ *   same grantee SURVIVES silently (the survival `PostgresGrantsRepairRefused` surfaces), and
+ *   a grantee that re-granted onward fails like the server without CASCADE (`2BP01`).
+ */
+import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import type { AclObject } from './fake-grants-parse.ts';
+import { type FakeGrantsModel, revokesAsOwner } from './fake-grants-read.ts';
+
+const sameObject = (a: AclObject, b: AclObject): boolean =>
+  a.schema === b.schema &&
+  a.table === b.table &&
+  a.column === b.column &&
+  a.defaultFor === b.defaultFor;
+
+/** The role a `GRANT`/`REVOKE` from the executor on `object` is performed AS (see the header). */
+export const effectiveGrantor = (model: FakeGrantsModel, object: AclObject): string => {
+  if (object.table !== undefined) {
+    const owner = model.tableOwners.get(`${object.schema}\u0000${object.table}`) ?? model.executor;
+    return revokesAsOwner(model, owner) ? owner : model.executor;
+  }
+  if (object.defaultFor === undefined) {
+    const owner = model.schemaOwners.get(object.schema) ?? model.executor;
+    return revokesAsOwner(model, owner) ? owner : model.executor;
+  }
+  return model.executor;
+};
+
+/** Add words to the (object, grantee, effective-grantor) entry, upgrading a base word to its
+ * `*` form rather than keeping both. */
+export const grantWords = (
+  model: FakeGrantsModel,
+  object: AclObject,
+  grantee: string,
+  words: ReadonlyArray<string>,
+  option: boolean,
+): void => {
+  const grantor = effectiveGrantor(model, object);
+  const acl = model.acl;
+  let entry = acl.find(
+    (e) => sameObject(e.object, object) && e.grantee === grantee && e.grantor === grantor,
+  );
+  if (entry === undefined) {
+    entry = { object, grantee, grantor, words: [] };
+    acl.push(entry);
+  }
+  for (const word of words) {
+    const base = word.replace(/\*$/, '');
+    entry.words = entry.words.filter((w) => w.replace(/\*$/, '') !== base);
+    entry.words.push(option ? `${word}*` : word);
+  }
+};
+
+/** Remove the effective grantor's grants for (object, grantee); a third grantor's entry
+ * survives by the keying, and a grantee that re-granted onward fails without CASCADE. */
+export const revoke = (
+  model: FakeGrantsModel,
+  object: AclObject,
+  grantee: string,
+  operation: string,
+): SqlError | undefined => {
+  const grantor = effectiveGrantor(model, object);
+  const acl = model.acl;
+  const own = acl.filter(
+    (e) => sameObject(e.object, object) && e.grantee === grantee && e.grantor === grantor,
+  );
+  if (own.length > 0 && acl.some((e) => sameObject(e.object, object) && e.grantor === grantee)) {
+    return new SqlError({
+      reason: new SqlSyntaxError({
+        cause: Object.assign(new Error('dependent privileges exist'), { code: '2BP01' }),
+        message: 'dependent privileges exist',
+        operation,
+      }),
+    });
+  }
+  for (const entry of own) acl.splice(acl.indexOf(entry), 1);
+  return undefined;
+};