@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/cjs/execution/migration-runner.d.ts

@@ -0,0 +1,128 @@
+import { PoolManager } from './pool';
+import { DbEntry } from '../config/db-config';
+import { MigrationRunPayload, MigrationResultPayload } from '../protocol/messages';
+import { InFlightRequest } from './types';
+import { AgentMessage, Role } from '../protocol/envelope';
+export declare class MigrationInProgressError extends Error {
+    /** Error catalog code. Not a SQLSTATE: `safePgCode` requires exactly 5. */
+    readonly code = "migration_in_progress";
+    constructor(message: string);
+}
+export declare class MigrationStrategyConflictError extends Error {
+    readonly code = "migration_strategy_conflict";
+    constructor(message: string);
+}
+/**
+ * The plan could not be verified: something in it does not parse, contains
+ * more than one statement, or is a statement form the agent cannot prove runs
+ * inside a transaction block. The run is refused rather than guessed at.
+ */
+export declare class MigrationPlanUnsafeError extends Error {
+    readonly code = "migration_plan_unsafe";
+    constructor(message: string);
+}
+/**
+ * The migration stopped partway with statements already committed.
+ *
+ * `MigrationRunner.run` never *resolves* with `status: 'partial'`: a caller
+ * that only inspects a returned value can therefore never mistake a
+ * half-applied schema for a success. The per-statement detail is on
+ * {@link MigrationPartiallyAppliedError.result} for a caller that wants to
+ * report it.
+ */
+export declare class MigrationPartiallyAppliedError extends Error {
+    readonly code = "migration_partial";
+    readonly result: MigrationResultPayload;
+    readonly pg_error_code?: string;
+    constructor(message: string, result: MigrationResultPayload);
+}
+/** The run exceeded its overall deadline and was abandoned. */
+export declare class MigrationTimeoutError extends Error {
+    readonly code = "migration_timeout";
+    constructor(message: string);
+}
+/**
+ * Absolute ceiling on one migration statement, in milliseconds. A caller
+ * cannot raise it, and it can never exceed the agent-wide statement ceiling in
+ * `pool.ts` — nothing is allowed to turn `statement_timeout` off.
+ */
+export declare const MAX_MIGRATION_STATEMENT_TIMEOUT_MS: number;
+/** Absolute ceiling on the whole migration run, in milliseconds. */
+export declare const MAX_MIGRATION_DEADLINE_MS: 1800000;
+/** How long a migration statement may wait for a lock before it is cancelled. */
+export declare const MIGRATION_LOCK_TIMEOUT_MS = 10000;
+export interface MigrationBudget {
+    /** `statement_timeout` applied to every statement of the run. */
+    statementTimeoutMs: number;
+    /** Wall-clock budget for the whole run, enforced by the runner. */
+    deadlineMs: number;
+    /** `lock_timeout` applied to every statement of the run. */
+    lockTimeoutMs: number;
+}
+/**
+ * Turn a caller-supplied `timeout_ms` into the three server-side budgets.
+ *
+ * The number is never trusted: it is floored to an integer, and clamped to
+ * {@link MAX_MIGRATION_STATEMENT_TIMEOUT_MS} / {@link MAX_MIGRATION_DEADLINE_MS}.
+ * `0`, a negative number, `NaN` and `Infinity` all mean "use the server
+ * default" — never "no timeout", which is how a remote caller would otherwise
+ * be able to remove the ceiling by asking for zero.
+ */
+export declare function resolveMigrationBudget(requestedTimeoutMs?: number): MigrationBudget;
+export interface MigrationRunnerOptions {
+    poolManager: PoolManager;
+    /**
+     * Per-installation secret the advisory lock key is derived from. Defaults to
+     * the agent token in the machine config, which is generated once per install
+     * and never leaves the host.
+     */
+    lockSecret?: string;
+}
+export interface MigrationContext {
+    dbEntry: DbEntry;
+    request_id: string;
+    project: string;
+    user: {
+        id: string;
+        role: Role;
+    };
+    db_alias: string;
+    /** Called for each statement status change. */
+    onProgress?: (event: AgentMessage) => void | Promise<void>;
+    abortSignal?: AbortSignal;
+    registerInFlight?: (req: InFlightRequest) => void;
+    unregisterInFlight?: (request_id: string) => void;
+}
+/**
+ * Advisory lock key for SW migrations.
+ *
+ * Keyed with HMAC-SHA256 over a per-installation secret. The previous version
+ * hashed the project name with a bare MD5, so anybody who could guess (or was
+ * told) a project name could compute the lock key, take the lock from another
+ * session, and deny migrations for that project indefinitely. A keyed MAC is
+ * not derivable by a third party with database access, because the secret never
+ * reaches the database.
+ */
+export declare function advisoryLockKey(projectName: string, secret: string): {
+    key1: number;
+    key2: number;
+};
+export declare class MigrationRunner {
+    private readonly poolManager;
+    private readonly injectedLockSecret?;
+    private resolvedLockSecret;
+    constructor(opts: MigrationRunnerOptions);
+    /**
+     * The installation secret the lock key is keyed with.
+     *
+     * An explicit option wins (tests, embedders). Otherwise the agent token from
+     * the machine config is used: it is per-installation, secret, and stable
+     * across processes, which is exactly what mutual exclusion between two agents
+     * needs. If the machine config cannot be read the fallback is a random
+     * per-process secret — still unguessable from outside, so the lock key cannot
+     * be pre-taken by anyone with database access.
+     */
+    private lockSecret;
+    run(payload: MigrationRunPayload, ctx: MigrationContext): Promise<MigrationResultPayload>;
+}
+//# sourceMappingURL=migration-runner.d.ts.map

package/dist/cjs/execution/migration-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.d.ts","sourceRoot":"","sources":["../../../src/execution/migration-runner.ts"],"names":[],"mappings":"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"}