@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/grants-diff.ts

@@ -0,0 +1,101 @@
+/**
+ * The offline half of `Postgres.Grants`' diff engine: the read-back projection
+ * (`attributesOf`) and the plan-time comparison (`grantsDiffer`). Pure — no client, no
+ * `Effect` — so `reconcile`'s read-back and the engine's `diff` project and compare one
+ * way. The repair and revocation statement lists live in `grants-plan.ts`.
+ */
+import type { PostgresGrantsAttributes } from './grants-attrs.ts';
+import type { DeclaredGrants, DeclaredNames } from './grants-declare.ts';
+import { liveColumnWords, liveDefaultWords, liveTableWords, wordsDiffer } from './grants-plan.ts';
+import type { LiveGrants } from './grants-read.ts';
+import { relkindIsPublicRevocable } from './grants-words.ts';
+
+/** The read-back projection: live catalog words, restricted to the names this declaration
+ * (or, for `read`, the last one) claims — plus the one-directional PUBLIC fact and the
+ * ownership facts. The PUBLIC-tables fact is scoped to the relkinds the bulk revoke
+ * statement actually reaches; an owned object records an empty word list (the ACL rows say
+ * nothing; ownership carries the privileges). */
+export const attributesOf = (live: LiveGrants, names: DeclaredNames): PostgresGrantsAttributes => ({
+  role: names.role,
+  database: names.database,
+  schema: names.schema,
+  schemaPrivileges: live.schema.role,
+  tables: names.tables.map((table) => ({
+    table,
+    privileges: liveTableWords(live, table),
+  })),
+  columns: names.columns.map(({ table, column }) => ({
+    table,
+    column,
+    privileges: liveColumnWords(live, table, column),
+  })),
+  defaults: names.defaults.map((forRole) => ({
+    forRole,
+    privileges: liveDefaultWords(live, forRole),
+  })),
+  publicSchemaRevoked: live.schema.public.length === 0,
+  publicTablesRevoked:
+    live.tables.every(
+      (table) => !relkindIsPublicRevocable(table.relkind) || table.public.length === 0,
+    ) && live.columns.every((column) => column.public.length === 0),
+  schemaOwnedByRole: live.schemaOwnedByRole,
+  ownedTables: names.tables.filter((table) => live.ownedTables.includes(table)),
+});
+
+/** The engine's plan-time comparison: the new declaration against the recorded (or freshly
+ * read) attributes. PUBLIC is one-directional — a declaration that does not revoke
+ * PUBLIC leaves whatever it holds alone, so live PUBLIC privileges with
+ * `revokeFromPublic: false` are never drift. Everything else is full equality, grant-option
+ * marks included; a changed NAME SET (a table added to or removed from the declaration)
+ * answers `true` so one reconcile re-records the projection in the new shape. Owned objects
+ * are skipped exactly as the repair skips them: their word list is meaningless (the owner
+ * holds everything implicitly), so only a name-set change on one can answer `true`. */
+export const grantsDiffer = (declared: DeclaredGrants, live: PostgresGrantsAttributes): boolean => {
+  if (
+    declared.role !== live.role ||
+    declared.database !== live.database ||
+    declared.schema !== live.schema
+  ) {
+    return true;
+  }
+  if (declared.publicSchemaRevoked && !live.publicSchemaRevoked) return true;
+  if (declared.publicTablesRevoked && !live.publicTablesRevoked) return true;
+  if (!live.schemaOwnedByRole && wordsDiffer(declared.schemaPrivileges, live.schemaPrivileges)) {
+    return true;
+  }
+  if (declared.tables.length !== live.tables.length) return true;
+  const ownedTables = new Set(live.ownedTables);
+  if (
+    declared.tables.some(
+      (table, index) =>
+        table.table !== (live.tables[index]?.table ?? null) ||
+        (!ownedTables.has(table.table) &&
+          wordsDiffer(table.privileges, live.tables[index]?.privileges ?? [])),
+    )
+  ) {
+    return true;
+  }
+  if (declared.columns.length !== live.columns.length) return true;
+  if (
+    declared.columns.some(
+      (column, index) =>
+        column.table !== (live.columns[index]?.table ?? null) ||
+        column.column !== (live.columns[index]?.column ?? null) ||
+        (!ownedTables.has(column.table) &&
+          wordsDiffer(column.privileges, live.columns[index]?.privileges ?? [])),
+    )
+  ) {
+    return true;
+  }
+  if (declared.defaults.length !== live.defaults.length) return true;
+  if (
+    declared.defaults.some(
+      (entry, index) =>
+        entry.forRole !== (live.defaults[index]?.forRole ?? null) ||
+        wordsDiffer(entry.privileges, live.defaults[index]?.privileges ?? []),
+    )
+  ) {
+    return true;
+  }
+  return false;
+};

package/src/postgres/grants-errors.ts

@@ -0,0 +1,215 @@
+/**
+ * `Postgres.Grants`' failures as typed tags, following the `Postgres.Schema` pattern (S21).
+ *
+ * ⛔ NONE OF THESE IS A STATUS-CODE OR MESSAGE MATCH. Every one is raised by this family's
+ *   own code from a fact it already checked (a byte count, a vocabulary, a live catalog
+ *   row, a re-planned statement list) — never from sniffing a driver error's text. The one
+ *   driver error this family EXPECTS (a grant naming a relation or column that does not
+ *   exist, a revoke that would need CASCADE) propagates as the raw `SqlError` on purpose:
+ *   the docs page names the cases.
+ */
+import * as Data from 'effect/Data';
+
+/** A declared privilege word is outside the vocabulary its prop draws from — e.g. `TRUNCATE`
+ * on a column grant (table-wide only at REL_18_6) or `EXECUTE` anywhere (this family never
+ * leaves the table/schema/column words). */
+export class PostgresGrantsPrivilegeRefused extends Data.TaggedError(
+  'PostgresGrantsPrivilegeRefused',
+)<{
+  readonly prop: string;
+  readonly word: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: "${this.prop}" declares "${this.word}", which is not in the vocabulary ` +
+      'PostgreSQL 18 grants on that object class (see grants-attrs.ts for the three sets, traced ' +
+      'to acl.h at REL_18_6). Column grants take select/insert/update/references only — TRUNCATE, ' +
+      'TRIGGER and MAINTAIN are table-wide.'
+    );
+  }
+}
+
+/** A declared name would be silently truncated (same rule as `PostgresDatabaseNameRefused`):
+ * roles, schemas, tables and columns are all `NameData`. */
+export class PostgresGrantsNameRefused extends Data.TaggedError('PostgresGrantsNameRefused')<{
+  readonly name: string;
+  readonly byteLength: number;
+  readonly limit: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: the name "${this.name}" is ${String(this.byteLength)} UTF-8 bytes, over the ` +
+      `${String(this.limit)}-byte limit (NAMEDATALEN 64, minus the terminator). PostgreSQL would ` +
+      'accept the statement and silently truncate the name with only a NOTICE, so this plan refuses ' +
+      'it instead of granting on an object no later read will ever find again.'
+    );
+  }
+}
+
+/** Two declaration entries name the same object (one table twice, one column pair twice,
+ * one `forRole` twice) — silently merging them would hide which entry the operator meant.
+ * The same refusal fires when one word list declares a base word both plain and
+ * `*`-marked: the server keeps ONE aclitem per grantee per grantor, so those two states
+ * can never both hold and the set would never converge. */
+export class PostgresGrantsDuplicateObject extends Data.TaggedError(
+  'PostgresGrantsDuplicateObject',
+)<{
+  readonly prop: string;
+  readonly name: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: "${this.prop}" declares "${this.name}" twice. Merge the entries into one — ` +
+      'the declaration must state each object at most once, and each privilege word in exactly one ' +
+      'form: plain, or WITH GRANT OPTION (`select` and `select*` cannot both hold, the server keeps ' +
+      'one aclitem per grantee per grantor).'
+    );
+  }
+}
+
+/** A logical id's `role`, `database` or `schema` changed. Those three name WHAT the grant set
+ * is about; changing one is a different grant set, not an edit of this one. */
+export class PostgresGrantsRetargetRefused extends Data.TaggedError(
+  'PostgresGrantsRetargetRefused',
+)<{
+  readonly prop: string;
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: the declared ${this.prop} changed from "${this.from}" to "${this.to}". A ` +
+      'retarget is refused at plan — declare a new logical id for the new target and delete the old ' +
+      'one (its retain policy keeps the grants until a destroy revokes them).'
+    );
+  }
+}
+
+/** `current_database()` is not the database the declaration names. The handlers open the
+ * declared database (`withPg`'s override — the family connection stays on the maintenance
+ * database); this fires when that open did not land there. Granting in the wrong database
+ * would succeed silently and read back as drift forever. */
+export class PostgresGrantsDatabaseMismatch extends Data.TaggedError(
+  'PostgresGrantsDatabaseMismatch',
+)<{
+  readonly declared: string;
+  readonly connected: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: the declaration names database "${this.declared}" but ` +
+      `current_database() is "${this.connected}". The handlers open the declared database and ` +
+      'prove it before any GRANT or REVOKE — a mismatch means that open did not land there.'
+    );
+  }
+}
+
+/** `reconcile` refuses to repair into a schema the catalogs do not have: grants belong to an
+ * existing container (`Postgres.Schema` creates one; this family never creates anything). */
+export class PostgresGrantsSchemaMissing extends Data.TaggedError('PostgresGrantsSchemaMissing')<{
+  readonly schema: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: schema "${this.schema}" is not in pg_namespace. Grants are written into a ` +
+      'schema that already exists — declare a Postgres.Schema (or create it by hand) before the ' +
+      'grant set that scopes to it.'
+    );
+  }
+}
+
+/** `reconcile` refuses to apply into a database `pg_database` does not have. `read` and `delete`
+ * treat a missing database as absence (first create / no-op), but a reconcile names a container
+ * it must write into — probing first turns what would be an untyped connect failure
+ * (`ConnectionError` over psql, `UnknownError` 3D000 over the socket) into a typed refusal. */
+export class PostgresGrantsDatabaseMissing extends Data.TaggedError(
+  'PostgresGrantsDatabaseMissing',
+)<{
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: database "${this.database}" is not in pg_database. Grants are written into ` +
+      'a database that already exists — declare a Postgres.Database (or create it by hand) before ' +
+      'the grant set that scopes to it.'
+    );
+  }
+}
+
+/** The grantee role, or a default-privileges `forRole` creator, is not in `pg_roles` —
+ * checked before any statement runs, the way `Postgres.Schema` checks its `AUTHORIZATION`
+ * owner. */
+export class PostgresGrantsRoleMissing extends Data.TaggedError('PostgresGrantsRoleMissing')<{
+  readonly role: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: role "${this.role}" is not in pg_roles. GRANT and ALTER DEFAULT PRIVILEGES ` +
+      'would fail against it — create the role (a group role per seat, membership owned by a human) ' +
+      'before declaring its grants.'
+    );
+  }
+}
+
+/** A declared table is not a relation in the schema. The resource refuses before any
+ * statement, because a GRANT/REVOKE on a missing relation would surface as a raw 42P01
+ * after earlier statements had already landed — and the state row would stay `creating`. */
+export class PostgresGrantsTableMissing extends Data.TaggedError('PostgresGrantsTableMissing')<{
+  readonly schema: string;
+  readonly table: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: table "${this.schema}"."${this.table}" does not exist. The declaration ` +
+      'names a relation before it is created; create the table (or fix the name) before granting.'
+    );
+  }
+}
+
+/** A declared column is not an attribute of its table. The resource refuses before any
+ * statement, matching the table-missing guard. */
+export class PostgresGrantsColumnMissing extends Data.TaggedError('PostgresGrantsColumnMissing')<{
+  readonly schema: string;
+  readonly table: string;
+  readonly column: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: column "${this.column}" of "${this.schema}"."${this.table}" does not ` +
+      'exist. Declare the column (or fix its name) before granting on it.'
+    );
+  }
+}
+
+/** The repair ran clean, but the immediate re-read (S10) still plans statements: a grant this
+ * family cannot revoke survived (its grantor still holds the grant option, or the executing
+ * role is neither the owner nor that grantor). Re-planning forever would hide it as silent
+ * drift, so it fails loud with the surviving statements. */
+export class PostgresGrantsRepairRefused extends Data.TaggedError('PostgresGrantsRepairRefused')<{
+  readonly schema: string;
+  readonly role: string;
+  readonly remaining: ReadonlyArray<string>;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Grants: the repair on schema "${this.schema}" for role "${this.role}" re-read as ` +
+      `still drifted; these statements would run again: ${this.remaining.join(' ; ')}. A grant made ` +
+      'by another role survives this resource\u2019s REVOKE (only its grantor or the object\u2019s ' +
+      'owner can revoke it) — revoke it as that grantor or the owner, or declare the privilege so ' +
+      'the set matches.'
+    );
+  }
+}
+
+export type PostgresGrantsError =
+  | PostgresGrantsPrivilegeRefused
+  | PostgresGrantsNameRefused
+  | PostgresGrantsDuplicateObject
+  | PostgresGrantsRetargetRefused
+  | PostgresGrantsDatabaseMismatch
+  | PostgresGrantsDatabaseMissing
+  | PostgresGrantsSchemaMissing
+  | PostgresGrantsRoleMissing
+  | PostgresGrantsTableMissing
+  | PostgresGrantsColumnMissing
+  | PostgresGrantsRepairRefused;

package/src/postgres/grants-existence-guards.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Existence guards: every declared table and column must exist before any statement runs.
+ * Missing objects fail typed `PostgresGrantsTableMissing` / `PostgresGrantsColumnMissing`
+ * without touching catalogs. A dotted table name must not collide with a dotted column
+ * name: the existence query compares the pair, not `relname || '.' || attname`.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PostgresGrantsProps } from './grants-attrs.ts';
+import { makeFakeGrants } from './fake-grants-sql.ts';
+import { PostgresGrantsColumnMissing, PostgresGrantsTableMissing } from './grants-errors.ts';
+import { reconcileWithClient } from './grants-ops.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const isWrite = (text: string): boolean => /^(GRANT|REVOKE|ALTER)/.test(text);
+
+const catalog = {
+  schemas: ['app'],
+  roles: ['postgres', 'seat_writer'],
+  tables: [{ schema: 'app', table: 'widgets', columns: ['id'] }],
+};
+
+const baseProps: PostgresGrantsProps = {
+  role: 'seat_writer',
+  database: 'agents',
+  schema: 'app',
+  schemaUsage: true,
+};
+
+describe('reconcile: declared objects must exist before statements run', () => {
+  test('a missing table fails as PostgresGrantsTableMissing without writing', async () => {
+    const fake = makeFakeGrants(catalog);
+    const error = await fails(
+      reconcileWithClient(
+        fake,
+        {
+          ...baseProps,
+          tables: [
+            { table: 'widgets', privileges: ['select'] },
+            { table: 'ghost', privileges: ['select'] },
+          ],
+        },
+        undefined,
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsTableMissing);
+    expect((error as PostgresGrantsTableMissing).table).toBe('ghost');
+    expect(fake.statements.map((s) => s.text).filter(isWrite)).toEqual([]);
+  });
+
+  test('a missing column fails as PostgresGrantsColumnMissing without writing', async () => {
+    const fake = makeFakeGrants(catalog);
+    const error = await fails(
+      reconcileWithClient(
+        fake,
+        {
+          ...baseProps,
+          tables: [{ table: 'widgets', privileges: ['select'] }],
+          columnGrants: [{ table: 'widgets', column: 'qty', privileges: ['update'] }],
+        },
+        undefined,
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsColumnMissing);
+    expect((error as PostgresGrantsColumnMissing).column).toBe('qty');
+    expect(fake.statements.map((s) => s.text).filter(isWrite)).toEqual([]);
+  });
+
+  test('a real table and column proceed past the guards', async () => {
+    const fake = makeFakeGrants(catalog);
+    await run(
+      reconcileWithClient(
+        fake,
+        {
+          ...baseProps,
+          tables: [{ table: 'widgets', privileges: ['select'] }],
+          columnGrants: [{ table: 'widgets', column: 'id', privileges: ['update'] }],
+        },
+        undefined,
+      ),
+    );
+    expect(fake.statements.map((s) => s.text).some(isWrite)).toBe(true);
+  });
+});
+
+describe('column existence compares the (table, column) pair', () => {
+  test('table `a.b` column `c` does not make table `a` column `b.c` look present', async () => {
+    const fake = makeFakeGrants({
+      ...catalog,
+      tables: [
+        { schema: 'app', table: 'a.b', columns: ['c'] },
+        { schema: 'app', table: 'a', columns: ['id'] },
+      ],
+    });
+    const error = await fails(
+      reconcileWithClient(
+        fake,
+        {
+          ...baseProps,
+          tables: [{ table: 'a', privileges: ['select'] }],
+          columnGrants: [{ table: 'a', column: 'b.c', privileges: ['select'] }],
+        },
+        undefined,
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresGrantsColumnMissing);
+    expect((error as PostgresGrantsColumnMissing).table).toBe('a');
+    expect((error as PostgresGrantsColumnMissing).column).toBe('b.c');
+    expect(fake.statements.map((s) => s.text).filter(isWrite)).toEqual([]);
+  });
+});

package/src/postgres/grants-existence.ts

@@ -0,0 +1,101 @@
+/**
+ * Pre-statement existence guards for `Postgres.Grants`: every declared table and column
+ * must exist in the schema before any GRANT/REVOKE runs. A missing object would fail
+ * as a raw 42P01/42703 after earlier statements had already landed, leaving the state
+ * row `creating` and the resume failing OwnedBySomeoneElse.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import type { DeclaredGrants } from './grants-declare.ts';
+import { PostgresGrantsColumnMissing, PostgresGrantsTableMissing } from './grants-errors.ts';
+
+/** One JSON string, never a JS array: the psql transport accepts only string parameters
+ * (`psql-executor.ts`). `json_array_elements_text` expands that array to text
+ * (`func.sgml@REL_18_6`). */
+const TABLES_PRESENT_SQL = `SELECT
+    c.relname AS table
+  FROM pg_class c
+  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    AND c.relname::text IN (SELECT json_array_elements_text($2::json))`;
+
+const findMissingTable = (
+  pg: PgExecutor,
+  schema: string,
+  tables: ReadonlyArray<string>,
+): Effect.Effect<string | undefined, SqlError> =>
+  tables.length === 0
+    ? Effect.succeed(undefined)
+    : Effect.map(
+        pg.unsafe<{ readonly table: string }>(TABLES_PRESENT_SQL, [schema, JSON.stringify(tables)]),
+        (rows) => {
+          const present = new Set(rows.map((row) => row.table));
+          return tables.find((table) => !present.has(table));
+        },
+      );
+
+/** Pairs, not `relname || '.' || attname`. A table named `a.b` with column `c` and a
+ * table named `a` with column `b.c` are the same concatenated string and one of them
+ * would read as present. `->>` yields text (`func.sgml@REL_18_6`); the parameter is
+ * one JSON string so the psql transport accepts it. */
+const COLUMNS_PRESENT_SQL = `SELECT
+    c.relname AS table,
+    a.attname AS column
+  FROM pg_attribute a
+  JOIN pg_class c ON c.oid = a.attrelid
+  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    AND a.attnum > 0
+    AND NOT a.attisdropped
+    AND (c.relname, a.attname) IN (
+      SELECT x->>0, x->>1 FROM json_array_elements($2::json) x
+    )`;
+
+const findMissingColumn = (
+  pg: PgExecutor,
+  schema: string,
+  columns: ReadonlyArray<{ readonly table: string; readonly column: string }>,
+): Effect.Effect<{ readonly table: string; readonly column: string } | undefined, SqlError> =>
+  columns.length === 0
+    ? Effect.succeed(undefined)
+    : Effect.map(
+        pg.unsafe<{ readonly table: string; readonly column: string }>(COLUMNS_PRESENT_SQL, [
+          schema,
+          JSON.stringify(columns.map(({ table, column }) => [table, column])),
+        ]),
+        (rows) => {
+          const present = new Set(rows.map((row) => `${row.table}\u0000${row.column}`));
+          return columns.find(({ table, column }) => !present.has(`${table}\u0000${column}`));
+        },
+      );
+
+/** Fail typed before any statement if a declared table or column does not exist. */
+export const requireDeclaredObjectsExist = (
+  pg: PgExecutor,
+  declared: DeclaredGrants,
+): Effect.Effect<void, PostgresGrantsTableMissing | PostgresGrantsColumnMissing | SqlError> =>
+  Effect.gen(function* () {
+    const missingTable = yield* findMissingTable(
+      pg,
+      declared.schema,
+      declared.tables.map((table) => table.table),
+    );
+    if (missingTable !== undefined) {
+      return yield* Effect.fail(
+        new PostgresGrantsTableMissing({ schema: declared.schema, table: missingTable }),
+      );
+    }
+    const missingColumn = yield* findMissingColumn(
+      pg,
+      declared.schema,
+      declared.columns.map((column) => ({ table: column.table, column: column.column })),
+    );
+    if (missingColumn !== undefined) {
+      return yield* Effect.fail(
+        new PostgresGrantsColumnMissing({
+          schema: declared.schema,
+          table: missingColumn.table,
+          column: missingColumn.column,
+        }),
+      );
+    }
+  });