@veducio/keja 0.0.0-stage → 0.2.3

package/src/db/client.ts

@@ -0,0 +1,61 @@
+import type { SQL } from "bun";
+import { DependencyNotMet } from "../errors/framework-errors.ts";
+import { processValue } from "../process/slot.ts";
+import { assertOwnedCall } from "../typeid/owned.ts";
+
+const state = processValue("database", () => ({
+  client: null as SQL | null,
+}));
+
+function connected() {
+  if (!state.client) {
+    throw new DependencyNotMet("DBCall", "db");
+  }
+  return state.client;
+}
+
+export const DBCall = new Proxy(function DBCall() {}, {
+  apply(_target, _thisArg, args) {
+    const client = connected();
+    const text = templateText(args[0]);
+    if (text !== null) {
+      assertOwnedCall(text, args.slice(1));
+    }
+    return Reflect.apply(
+      client as unknown as (...values: unknown[]) => unknown,
+      client,
+      args,
+    );
+  },
+  get(_target, property) {
+    const client = connected();
+    const value = Reflect.get(client, property, client);
+    if (property === "unsafe" && typeof value === "function") {
+      return (statement: unknown, ...rest: unknown[]) => {
+        if (typeof statement === "string") {
+          assertOwnedCall(statement, []);
+        }
+        return value.call(client, statement, ...rest);
+      };
+    }
+    return typeof value === "function" ? value.bind(client) : value;
+  },
+}) as unknown as SQL;
+
+export function setDatabase(client: SQL | null) {
+  state.client = client;
+}
+
+function templateText(value: unknown) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const strings = Array.from(value as ArrayLike<unknown>);
+  if (
+    strings.length === 0 ||
+    strings.some((part) => typeof part !== "string")
+  ) {
+    return null;
+  }
+  return strings.join(" ");
+}

package/src/db/migrate.test.ts

@@ -0,0 +1,141 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  applyMigrations,
+  loadMigrations,
+  type MigrationClient,
+  pendingMigrations,
+} from "./migrate.ts";
+
+describe("loadMigrations", () => {
+  it("reads numbered sql files in order", async () => {
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    writeFileSync(path.join(directory, "0002_jobs.sql"), "select 2;\n");
+    writeFileSync(path.join(directory, "0001_init.sql"), "select 1;\n");
+    const files = await loadMigrations(directory);
+    expect(files.map((file) => file.file)).toEqual([
+      "0001_init.sql",
+      "0002_jobs.sql",
+    ]);
+  });
+
+  it("rejects a file that is not 0001_name.sql", async () => {
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    writeFileSync(path.join(directory, "init.sql"), "select 1;\n");
+    await expect(loadMigrations(directory)).rejects.toThrow(
+      "init.sql must use the form 0001_name.sql",
+    );
+  });
+
+  it("rejects two files with the same number", async () => {
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(path.join(directory, "0001_init.sql"), "select 1;\n");
+    writeFileSync(path.join(directory, "0001_again.sql"), "select 1;\n");
+    await expect(loadMigrations(directory)).rejects.toThrow(
+      "0001_again.sql and 0001_init.sql use migration number 0001",
+    );
+  });
+});
+
+describe("pendingMigrations", () => {
+  it("skips an applied file and refuses a changed one", async () => {
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    writeFileSync(path.join(directory, "0001_init.sql"), "select 1;\n");
+    const [file] = await loadMigrations(directory);
+    if (!file) {
+      throw new Error("missing migration");
+    }
+    expect(pendingMigrations([file], [])).toEqual([file]);
+    expect(
+      pendingMigrations([file], [{ id: file.file, checksum: file.checksum }]),
+    ).toEqual([]);
+    expect(() =>
+      pendingMigrations([file], [{ id: file.file, checksum: "stale" }]),
+    ).toThrow("0001_init.sql changed after it was applied");
+  });
+});
+
+describe("applyMigrations", () => {
+  it("runs only migrations that are not recorded", async () => {
+    const ran: string[] = [];
+    const applied = [{ id: "0001_init.sql", checksum: "same" }];
+    const client: MigrationClient = {
+      async unsafe(sql) {
+        ran.push(sql);
+      },
+      async query() {
+        return applied;
+      },
+      async begin(fn) {
+        return fn({
+          async unsafe(sql) {
+            ran.push(sql);
+          },
+          async query() {
+            return [];
+          },
+          async begin(inner) {
+            return inner(client);
+          },
+        });
+      },
+    };
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    writeFileSync(path.join(directory, "0001_init.sql"), "select 1;\n");
+    writeFileSync(path.join(directory, "0002_jobs.sql"), "select 2;\n");
+    const files = await loadMigrations(directory);
+    const first = files[0];
+    if (!first) {
+      throw new Error("missing migration");
+    }
+    applied[0] = { id: first.file, checksum: first.checksum };
+    await expect(applyMigrations(files, client)).resolves.toEqual([
+      "0002_jobs.sql",
+    ]);
+    expect(ran.some((sql) => sql.includes("select 2;"))).toBe(true);
+    expect(ran.some((sql) => sql.includes("select 1;"))).toBe(false);
+  });
+
+  it("rolls back a migration that creates a table without an owned object", async () => {
+    const ran: string[] = [];
+    const client: MigrationClient = {
+      async unsafe(sql) {
+        ran.push(sql);
+      },
+      async query() {
+        return [];
+      },
+      async begin(fn) {
+        return fn({
+          async unsafe(sql) {
+            ran.push(sql);
+            if (sql.includes("keja_owned_object_violations()")) {
+              return [{ table_name: "notes", detail: "missing _id" }];
+            }
+            return [];
+          },
+          async query() {
+            return [];
+          },
+          async begin(inner) {
+            return inner(client);
+          },
+        });
+      },
+    };
+    const directory = mkdtempSync(path.join(tmpdir(), "keja-migrations-"));
+    writeFileSync(
+      path.join(directory, "0001_init.sql"),
+      "create table notes (message text);\n",
+    );
+    await expect(
+      applyMigrations(await loadMigrations(directory), client),
+    ).rejects.toThrow("notes missing _id");
+    expect(ran.some((sql) => sql.includes("insert into keja_migrations"))).toBe(
+      false,
+    );
+  });
+});

package/src/db/migrate.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { ProjectError, projectError } from "../errors/framework-errors.ts";
+import { ownedObjectSql, ownedObjectViolations } from "./owned-sql.ts";
+
+const migrationFile = /^(\d{4,})_([A-Za-z0-9][A-Za-z0-9_-]*)\.sql$/;
+
+export type MigrationFile = {
+  id: string;
+  number: number;
+  file: string;
+  sql: string;
+  checksum: string;
+};
+
+export type AppliedMigration = {
+  id: string;
+  checksum: string;
+};
+
+export type MigrationClient = {
+  unsafe(sql: string): Promise<unknown>;
+  query(sql: string): Promise<AppliedMigration[]>;
+  begin<T>(fn: (tx: MigrationClient) => Promise<T>): Promise<T>;
+};
+
+export async function loadMigrations(directory: string) {
+  if (!existsSync(directory)) {
+    throw projectError("missingMigrations", `Missing ${directory}`);
+  }
+  const names = await readdir(directory);
+  const files: MigrationFile[] = [];
+  for (const name of names) {
+    const parsed = parseMigrationFile(name);
+    if (!parsed || !(await stat(path.join(directory, name))).isFile()) {
+      throw projectError(
+        "invalidMigrationFile",
+        `${name} must use the form 0001_name.sql`,
+      );
+    }
+    const sql = await readFile(path.join(directory, name), "utf8");
+    files.push({
+      id: parsed.id,
+      number: parsed.number,
+      file: name,
+      sql,
+      checksum: createHash("sha256").update(sql).digest("hex"),
+    });
+  }
+  files.sort(
+    (left, right) =>
+      left.number - right.number || left.file.localeCompare(right.file),
+  );
+  const seen = new Map<string, string>();
+  for (const file of files) {
+    const previous = seen.get(file.id);
+    if (previous) {
+      throw projectError(
+        "duplicateMigration",
+        `${previous} and ${file.file} use migration number ${file.id}`,
+      );
+    }
+    seen.set(file.id, file.file);
+  }
+  return files;
+}
+
+export function pendingMigrations(
+  files: readonly MigrationFile[],
+  applied: readonly AppliedMigration[],
+) {
+  const checksums = new Map(applied.map((item) => [item.id, item.checksum]));
+  const pending: MigrationFile[] = [];
+  for (const file of files) {
+    const checksum = checksums.get(file.file);
+    if (checksum === undefined) {
+      pending.push(file);
+      continue;
+    }
+    if (checksum !== file.checksum) {
+      throw projectError(
+        "migrationChanged",
+        `${file.file} changed after it was applied`,
+      );
+    }
+  }
+  return pending;
+}
+
+export async function applyMigrations(
+  files: readonly MigrationFile[],
+  client: MigrationClient,
+) {
+  await client.unsafe(ownedObjectSql);
+  await client.unsafe(
+    `create table if not exists keja_migrations (
+      id text primary key,
+      checksum text not null,
+      applied_at timestamptz not null default now()
+    )`,
+  );
+  const applied = await client.query(
+    "select id, checksum from keja_migrations",
+  );
+  const pending = pendingMigrations(files, applied);
+  for (const file of pending) {
+    try {
+      await client.begin(async (tx) => {
+        await tx.unsafe(file.sql);
+        const violations = ownedObjectViolations(
+          await tx.unsafe(
+            "select table_name, detail from keja_owned_object_violations()",
+          ),
+        );
+        if (violations.length > 0) {
+          throw projectError("ownedObjects", violations.join("; "));
+        }
+        await tx.unsafe(
+          `insert into keja_migrations (id, checksum) values ('${sqlLiteral(file.file)}', '${sqlLiteral(file.checksum)}')`,
+        );
+      });
+    } catch (error) {
+      if (error instanceof ProjectError) {
+        throw error;
+      }
+      const detail =
+        error instanceof Error ? error.message : "migration failed";
+      throw projectError("migrationFailed", `${file.file} failed: ${detail}`);
+    }
+  }
+  return pending.map((file) => file.file);
+}
+
+export function parseMigrationFile(file: string) {
+  const match = migrationFile.exec(file);
+  if (!match) {
+    return null;
+  }
+  return { id: match[1], number: Number(match[1]), name: match[2] };
+}
+
+function sqlLiteral(value: string) {
+  return value.replaceAll("'", "''");
+}

package/src/db/owned-sql.ts

@@ -0,0 +1,202 @@
+export const ownedObjectSql = `
+create or replace function keja_is_typeid(value text)
+returns boolean
+language sql
+immutable
+as $$
+  select value ~ '^[a-z]([a-z_]{0,61}[a-z])?_[0-9a-hjkmnp-tv-z]{26}$'
+$$;
+
+create or replace function keja_is_object_type(value text)
+returns boolean
+language sql
+immutable
+as $$
+  select value ~ '^v[0-9]+(\\.[a-z]([a-z_]{0,61}[a-z])?)+$'
+$$;
+
+create or replace function keja_is_tenant(value text)
+returns boolean
+language sql
+immutable
+as $$
+  select value is not null and length(btrim(value)) > 0
+$$;
+
+create or replace function keja_timestamps(created_at timestamptz, updated_at timestamptz)
+returns boolean
+language sql
+immutable
+as $$
+  select updated_at >= created_at
+$$;
+
+create or replace function keja_owned_object_violations()
+returns table(table_name text, detail text)
+language plpgsql
+stable
+as $keja$
+declare
+  rel record;
+  id_type text;
+  object_type text;
+  tenant_type text;
+  archived_type text;
+  created_type text;
+  updated_type text;
+  id_required boolean;
+  object_required boolean;
+  tenant_required boolean;
+  archived_required boolean;
+  created_required boolean;
+  updated_required boolean;
+  primary_key text;
+  checks text;
+begin
+  for rel in
+    select c.oid, c.relname
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'public'
+      and c.relkind = 'r'
+      and c.relname <> 'keja_migrations'
+  loop
+    select t.typname, a.attnotnull
+      into id_type, id_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_id'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select t.typname, a.attnotnull
+      into object_type, object_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_object'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select t.typname, a.attnotnull
+      into tenant_type, tenant_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_tenant'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select t.typname, a.attnotnull
+      into archived_type, archived_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_archived'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select t.typname, a.attnotnull
+      into created_type, created_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_createdAt'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select t.typname, a.attnotnull
+      into updated_type, updated_required
+    from pg_attribute a
+    join pg_type t on t.oid = a.atttypid
+    where a.attrelid = rel.oid
+      and a.attname = '_updatedAt'
+      and a.attnum > 0
+      and not a.attisdropped;
+
+    select string_agg(a.attname, ',' order by array_position(i.indkey, a.attnum))
+      into primary_key
+    from pg_index i
+    join pg_attribute a
+      on a.attrelid = i.indrelid
+     and a.attnum = any(i.indkey)
+    where i.indrelid = rel.oid
+      and i.indisprimary;
+
+    select string_agg(pg_get_constraintdef(pg_constraint.oid), ' ')
+      into checks
+    from pg_constraint
+    where conrelid = rel.oid
+      and contype = 'c';
+
+    table_name := rel.relname;
+    if id_type is null then
+      detail := 'missing _id';
+      return next;
+    elsif id_type <> 'text' or id_required is not true or primary_key is distinct from '_id' then
+      detail := '_id must be a text primary key';
+      return next;
+    elsif checks is null or checks !~* 'keja_is_typeid[[:space:]]*\\([[:space:]]*"?_id"?' then
+      detail := '_id must be checked with keja_is_typeid';
+      return next;
+    elsif object_type is null then
+      detail := 'missing _object';
+      return next;
+    elsif object_type <> 'text' or object_required is not true then
+      detail := '_object must be text not null';
+      return next;
+    elsif checks !~* 'keja_is_object_type[[:space:]]*\\([[:space:]]*"?_object"?' then
+      detail := '_object must be checked with keja_is_object_type';
+      return next;
+    elsif tenant_type is null then
+      detail := 'missing _tenant';
+      return next;
+    elsif tenant_type <> 'text' or tenant_required is not true then
+      detail := '_tenant must be text not null';
+      return next;
+    elsif checks !~* 'keja_is_tenant[[:space:]]*\\([[:space:]]*"?_tenant"?' then
+      detail := '_tenant must be checked with keja_is_tenant';
+      return next;
+    elsif archived_type is null then
+      detail := 'missing _archived';
+      return next;
+    elsif archived_type <> 'bool' or archived_required is not true then
+      detail := '_archived must be boolean not null';
+      return next;
+    elsif created_type is null then
+      detail := 'missing _createdAt';
+      return next;
+    elsif created_type <> 'timestamptz' or created_required is not true then
+      detail := '_createdAt must be timestamptz not null';
+      return next;
+    elsif updated_type is null then
+      detail := 'missing _updatedAt';
+      return next;
+    elsif updated_type <> 'timestamptz' or updated_required is not true then
+      detail := '_updatedAt must be timestamptz not null';
+      return next;
+    elsif checks !~* 'keja_timestamps[[:space:]]*\\([[:space:]]*"_createdAt"[[:space:]]*,[[:space:]]*"_updatedAt"' then
+      detail := '_createdAt and _updatedAt must be checked with keja_timestamps';
+      return next;
+    end if;
+  end loop;
+end;
+$keja$;
+`;
+
+export function ownedObjectViolations(value: unknown) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object") {
+      return [];
+    }
+    const row = item as { table_name?: unknown; detail?: unknown };
+    if (typeof row.table_name !== "string" || typeof row.detail !== "string") {
+      return [];
+    }
+    return [`${row.table_name} ${row.detail}`];
+  });
+}

package/src/db/postgres.ts

@@ -0,0 +1,90 @@
+import type { SQL } from "bun";
+import { ProjectError, projectError } from "../errors/framework-errors.ts";
+import { setDatabase } from "./client.ts";
+import {
+  type AppliedMigration,
+  applyMigrations,
+  loadMigrations,
+  type MigrationClient,
+} from "./migrate.ts";
+
+export function readDatabaseUrl(value: string | undefined) {
+  const url = value?.trim() ?? "";
+  if (url === "") {
+    throw projectError("databaseUrl", "DATABASE_URL is required");
+  }
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "postgres:" || parsed.protocol === "postgresql:") {
+      return url;
+    }
+  } catch {
+    throw projectError(
+      "databaseUrl",
+      "DATABASE_URL must be a postgres connection string",
+    );
+  }
+  throw projectError(
+    "databaseUrl",
+    "DATABASE_URL must be a postgres connection string",
+  );
+}
+
+export async function connectDatabase(databaseUrl: string) {
+  const sql = await openClient(databaseUrl);
+  try {
+    await sql`select 1`;
+  } catch (error) {
+    await sql.close();
+    throw asDatabaseError(error);
+  }
+  setDatabase(sql);
+  return sql;
+}
+
+export async function migrateDatabase(directory: string, databaseUrl: string) {
+  const sql = await openClient(databaseUrl);
+  try {
+    const applied = await applyMigrations(
+      await loadMigrations(directory),
+      adapter(sql),
+    );
+    return { migrations: directory, applied };
+  } catch (error) {
+    throw asDatabaseError(error);
+  } finally {
+    await sql.close();
+  }
+}
+
+async function openClient(databaseUrl: string) {
+  const { SQL } = await import("bun");
+  try {
+    return new SQL(readDatabaseUrl(databaseUrl));
+  } catch (error) {
+    throw asDatabaseError(error);
+  }
+}
+
+function asDatabaseError(error: unknown): never {
+  if (error instanceof ProjectError) {
+    throw error;
+  }
+  const detail =
+    error instanceof Error ? error.message : "Database connection failed";
+  throw projectError("databaseInit", detail);
+}
+
+function adapter(sql: SQL): MigrationClient {
+  return {
+    unsafe(statement) {
+      return sql.unsafe(statement);
+    },
+    query(statement: string) {
+      return sql.unsafe(statement) as Promise<AppliedMigration[]>;
+    },
+    begin(fn) {
+      return sql.begin((tx) => fn(adapter(tx)));
+    },
+  };
+}

package/src/env/required-env.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  readOpenApiServers,
+  readRequiredEnv,
+  requiredEnv,
+  validateOpenApiServer,
+} from "./required-env.ts";
+
+describe("requiredEnv", () => {
+  it("accepts a usable host and ports", () => {
+    expect(
+      readRequiredEnv({
+        HOST: "127.0.0.1",
+        HTTP_PORT: "3000",
+        HTTP_SERVICE_PORT: "3001",
+      }),
+    ).toEqual({
+      host: "127.0.0.1",
+      httpPort: 3000,
+      httpServicePort: 3001,
+    });
+  });
+
+  it("rejects a blank host and an out of range port", () => {
+    expect(requiredEnv[0].validate(" ")).toBe("HOST is required");
+    expect(requiredEnv[1].validate("70000")).toBe(
+      "HTTP_PORT must be an integer from 1 to 65535",
+    );
+    expect(requiredEnv[2].validate("0")).toBe(
+      "HTTP_SERVICE_PORT must be an integer from 1 to 65535",
+    );
+  });
+
+  it("reads optional openapi servers and rejects a bad url", () => {
+    expect(validateOpenApiServer("OPENAPI_SERVER", undefined)).toBeNull();
+    expect(validateOpenApiServer("OPENAPI_SERVER", " ")).toBeNull();
+    expect(
+      readOpenApiServers({
+        OPENAPI_SERVER: "http://127.0.0.1:3500",
+        OPENAPI_SERVICE_SERVER: "https://service.example/api",
+      }),
+    ).toEqual({
+      openapiServer: "http://127.0.0.1:3500",
+      openapiServiceServer: "https://service.example/api",
+    });
+    expect(validateOpenApiServer("OPENAPI_SERVER", "notaurl")).toBe(
+      "OPENAPI_SERVER must be an absolute http or https URL",
+    );
+    expect(() =>
+      readOpenApiServers({ OPENAPI_SERVICE_SERVER: "ftp://files.example" }),
+    ).toThrow("OPENAPI_SERVICE_SERVER must be an absolute http or https URL");
+  });
+
+  it("defines a validator for every required variable", () => {
+    expect(requiredEnv.map((requirement) => requirement.name)).toEqual([
+      "HOST",
+      "HTTP_PORT",
+      "HTTP_SERVICE_PORT",
+    ]);
+    for (const requirement of requiredEnv) {
+      expect(typeof requirement.validate).toBe("function");
+    }
+  });
+});