Files
MikrotikManager/backend/src/db/controlled-migrations.ts
T

147 lines
10 KiB
TypeScript

import { createHash, randomUUID } from "node:crypto"
import { readdir, readFile } from "node:fs/promises"
import type { PoolClient } from "pg"
import { acquireDatabaseSchemaControl } from "./database-schema-control.js"
import type { DatabaseSchemaIntent, DatabaseSchemaTerminal } from "./database-schema-control-model.js"
import { canonical, exactHistory, observation, REVIEWED_PREDECESSORS, REVIEWED_SUCCESSOR_MANIFEST } from "./controlled-migration-history.js"
import { analyzeMigration, MIGRATION_MANIFEST, migrationManifestDigest, validateMigrationFileSet, type MigrationReview } from "./migration-manifest.js"
import { PARTITION_WRITER_ADVISORY_KEY } from "../services/partition-write-transaction.js"
import { acquireDatabaseRequestDrain, releaseDatabaseRequestDrain, SYSTEM_DATABASE_OPERATION_LOCK } from "./operation-lock.js"
import { assertReviewedMigrationMarkerGuard } from "./partition-guard-inheritance.js"
import { assertDatabaseRestoreQuarantineOpen } from "./database-restore-quarantine.js"
/** Opt-in internal dispatcher only. Default startup remains on the old path.
* Control DDL/enrollment, imports, data verification and READY are absent. */
export const CONTROLLED_MIGRATIONS_SQL = Object.freeze({
history: `SELECT id::text AS id, intent, terminal FROM mmapp_control.database_schema_intents ORDER BY id LIMIT ${MIGRATION_MANIFEST.length + 1}`,
namespaces: "SELECT nspname AS name FROM pg_catalog.pg_namespace WHERE nspname !~ '^pg_' AND nspname <> 'information_schema' ORDER BY nspname",
publicObjects: "SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_depend WHERE refclassid = 'pg_catalog.pg_namespace'::pg_catalog.regclass AND refobjid = 'public'::pg_catalog.regnamespace) OR EXISTS (SELECT 1 FROM pg_catalog.pg_extension WHERE extnamespace = 'public'::pg_catalog.regnamespace) AS present",
markerTable: "SELECT c.relkind::text AS kind, c.relpersistence::text AS persistence, c.relrowsecurity AS rls, c.relforcerowsecurity AS force_rls, EXISTS (SELECT 1 FROM pg_catalog.pg_trigger t WHERE t.tgrelid = c.oid AND NOT t.tgisinternal) AS user_triggers FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'public' AND c.relname = 'schema_migrations'",
markers: `SELECT id FROM public.schema_migrations ORDER BY id LIMIT ${MIGRATION_MANIFEST.length + 1}`,
marker: "INSERT INTO public.schema_migrations (id) VALUES ($1)",
})
export class ControlledMigrationsError extends Error {
readonly code = "CONTROLLED_MIGRATIONS_REFUSED"
constructor(message: string, readonly outcomeUnknown = false, options?: ErrorOptions) { super(message, options) }
}
const refuse = (message: string): never => { throw new ControlledMigrationsError(message) }
const digest = (value: string) => createHash("sha256").update(value).digest("hex")
function requireCommitAck(result: unknown): void {
const terminal = Array.isArray(result) ? result.at(-1) : result
if (!terminal || typeof terminal !== "object" || Reflect.get(terminal, "command") !== "COMMIT") refuse("Application COMMIT command acknowledgement unavailable")
}
interface ExactFile { pin: MigrationReview; sql: string }
async function exactFiles(): Promise<ExactFile[]> {
const directory = new URL("../../drizzle/", import.meta.url)
const entries = (await readdir(directory, { withFileTypes: true })).filter(entry => entry.name.toLowerCase().endsWith(".sql"))
if (entries.some(entry => !entry.isFile())) refuse("Migration SQL must be ordinary pinned files")
validateMigrationFileSet(entries.map(entry => entry.name))
// Read ONCE and validate those SAME bytes. Never execute a second unchecked
// read after inventory validation, and never expose the source to a caller.
return Promise.all(MIGRATION_MANIFEST.map(async pin => {
const bytes = await readFile(new URL(pin.file, directory))
analyzeMigration(pin.file, bytes, pin)
return { pin, sql: new TextDecoder("utf-8", { fatal: true }).decode(bytes) }
}))
}
async function baseline(client: PoolClient, prefix: number, expectedGuarded?: boolean): Promise<boolean> {
const namespaces = (await client.query(CONTROLLED_MIGRATIONS_SQL.namespaces)).rows
if (canonical(namespaces) !== canonical([{ name: "mmapp_control" }, { name: "public" }])) refuse("Unexpected database namespace scope")
if (prefix === 0) {
const rows = (await client.query(CONTROLLED_MIGRATIONS_SQL.publicObjects)).rows
if (rows.length !== 1 || rows[0].present !== false) refuse("Legacy or unmarked application state cannot be enrolled")
return false
}
const table = (await client.query(CONTROLLED_MIGRATIONS_SQL.markerTable)).rows
const ordinary = { kind: "r", persistence: "p", rls: false, force_rls: false, user_triggers: false }
const guarded = canonical(table) !== canonical([ordinary])
if (expectedGuarded !== undefined && expectedGuarded !== guarded) refuse("Migration marker protection changed")
if (guarded) {
if (prefix < REVIEWED_PREDECESSORS[0].length || migrationManifestDigest() !== REVIEWED_SUCCESSOR_MANIFEST ||
canonical(table) !== canonical([{ ...ordinary, user_triggers: true }])) {
refuse("Ordinary or exact reviewed guarded migration marker table required")
}
await assertReviewedMigrationMarkerGuard(client)
}
const markers = (await client.query(CONTROLLED_MIGRATIONS_SQL.markers)).rows
const expected = MIGRATION_MANIFEST.slice(0, prefix).map(pin => ({ id: pin.file.slice(0, -4) }))
if (canonical(markers) !== canonical(expected)) refuse("Migration markers disagree with exact controlled prefix")
return guarded
}
/** Fixed production pool + fixed pinned source path; no caller-supplied SQL,
* pool, execution callback, receipt, or verifier. Tests may replace module I/O
* in their isolated loader; that is not a production admission interface. */
export async function executeControlledSqlMigrations() {
const files = await exactFiles(), manifest = migrationManifestDigest()
const { pool } = await import("./index.js")
const control = await acquireDatabaseSchemaControl(pool)
let app: PoolClient | undefined, released = false, activeIntent: DatabaseSchemaIntent | undefined
let applicationSqlSent = false, completedFiles = 0
try {
app = await pool.connect()
await app.query("SET lock_timeout = '10s'")
await app.query("SET statement_timeout = '120s'")
await app.query("SET synchronous_commit = on")
await acquireDatabaseRequestDrain(app)
// Take the global key before the partition key: restore holds the former
// while its SQL backend takes the latter.
const maintenance = await app.query<{ acquired: boolean }>(
"SELECT pg_catalog.pg_try_advisory_lock($1::bigint) AS acquired", [SYSTEM_DATABASE_OPERATION_LOCK])
if (maintenance.rows.length !== 1 || maintenance.rows[0].acquired !== true) refuse("Application database maintenance lease unavailable")
// Exclusive SESSION lock fences every adopted partition writer for the
// whole DDL sequence, including self-managed files and marker gaps.
await app.query("SELECT pg_catalog.pg_advisory_lock($1::bigint)", [PARTITION_WRITER_ADVISORY_KEY])
await app.query("SET search_path = public, pg_catalog")
const current = (await control.read()).state
const history = (await app.query(CONTROLLED_MIGRATIONS_SQL.history)).rows
completedFiles = await exactHistory(history, current, manifest)
const fileHashes = new Set(MIGRATION_MANIFEST.map(pin => pin.sha256))
const legacy = history.find(row => !fileHashes.has((row.intent as DatabaseSchemaIntent).artifactSha256))
if (legacy) {
if (!(legacy.terminal as DatabaseSchemaTerminal).legacyRelease) refuse("Authenticated legacy migration release required")
await assertDatabaseRestoreQuarantineOpen(app)
}
const guarded = await baseline(app, completedFiles)
for (const { pin, sql } of files.slice(completedFiles)) {
const id = randomUUID()
const started = await control.transition({ type: "begin", id, kind: "migration", manifestSha256: manifest, artifactSha256: pin.sha256 })
activeIntent = started.state.intent!
// These writes are reached only after the durable intent COMMIT ACK.
applicationSqlSent = true
if (pin.transaction === "owner-transaction") {
await app.query("BEGIN")
await app.query(sql)
await app.query(CONTROLLED_MIGRATIONS_SQL.marker, [pin.file.slice(0, -4)])
requireCommitAck(await app.query("COMMIT"))
} else {
// Do not wrap, split, strip or rewrite the audited BEGIN...COMMIT.
requireCommitAck(await app.query(sql))
if (!pin.selfMarker) await app.query(CONTROLLED_MIGRATIONS_SQL.marker, [pin.file.slice(0, -4)])
}
await baseline(app, completedFiles + 1, guarded)
await control.transition({ type: "terminal", id, outcome: "observed-success", observationSha256: await observation(activeIntent, pin) })
activeIntent = undefined; completedFiles++
}
await baseline(app, completedFiles, guarded)
const unlocked = await app.query("SELECT pg_catalog.pg_advisory_unlock($1::bigint) AS unlocked", [PARTITION_WRITER_ADVISORY_KEY])
if (unlocked.rows.length !== 1 || unlocked.rows[0].unlocked !== true) refuse("Application schema lease release unconfirmed")
const maintenanceUnlocked = await app.query("SELECT pg_catalog.pg_advisory_unlock($1::bigint) AS unlocked", [SYSTEM_DATABASE_OPERATION_LOCK])
if (maintenanceUnlocked.rows.length !== 1 || maintenanceUnlocked.rows[0].unlocked !== true) refuse("Application database maintenance lease release unconfirmed")
await releaseDatabaseRequestDrain(app)
for (const setting of ["search_path", "synchronous_commit", "lock_timeout", "statement_timeout"]) await app.query("RESET " + setting)
app.release(false); released = true
await control.close()
return Object.freeze({ completedFiles, manifestSha256: manifest, ready: false as const, schemaAndDataVerified: false as const })
} catch (cause) {
if (activeIntent) {
// If intent/terminal COMMIT itself lost ACK the store is poisoned; this
// best-effort record fails closed and the unresolved intent survives.
try { await control.transition({ type: "terminal", id: activeIntent.id, outcome: "interrupted-unknown", observationSha256: digest(JSON.stringify({ format: "controlled-migration-unknown-v1", intent: activeIntent })) }) } catch { /* never retry application SQL */ }
}
if (app && !released) { released = true; app.release(true) }
try { await control.close() } catch { /* preserve unknown outcome */ }
throw new ControlledMigrationsError("Controlled migration stopped; automatic replay forbidden", applicationSqlSent, { cause })
}
}