rampway 0.3.0 → 0.3.1

package/build/src/velocious/run-store.d.ts

@@ -0,0 +1,297 @@
+/**
+ * @param {string} id - Run id.
+ * @returns {void}
+ */
+export function registerActiveDeploymentRun(id: string): void;
+/**
+ * @param {string} id - Run id.
+ * @returns {void}
+ */
+export function unregisterActiveDeploymentRun(id: string): void;
+/**
+ * @param {number} staleRunTimeoutMs - Lease duration.
+ * @returns {number} Heartbeat interval strictly below the lease.
+ */
+export function heartbeatIntervalMs(staleRunTimeoutMs: number): number;
+/**
+ * @param {{activeRunIds: Set<string>, nowMs: number, run: {id: string, heartbeatAtMs: number|null, requestedAtMs: number}, staleRunTimeoutMs: number}} args - Lease data.
+ * @returns {boolean} Whether ownership expired.
+ */
+export function isRunLeaseExpired({ activeRunIds: localIds, nowMs, run, staleRunTimeoutMs }: {
+    activeRunIds: Set<string>;
+    nowMs: number;
+    run: {
+        id: string;
+        heartbeatAtMs: number | null;
+        requestedAtMs: number;
+    };
+    staleRunTimeoutMs: number;
+}): boolean;
+/**
+ * @param {{id: string, mountIdentifier: string, ownerToken: string}} args - Fence identifiers.
+ * @returns {Record<string, unknown>} Update conditions.
+ */
+export function terminalTransitionConditions({ id, mountIdentifier, ownerToken }: {
+    id: string;
+    mountIdentifier: string;
+    ownerToken: string;
+}): Record<string, unknown>;
+/**
+ * Includes the observed heartbeat so a concurrent renewal defeats stale reconciliation.
+ *
+ * @param {{mountIdentifier: string, run: Pick<DeploymentRunRow, 'heartbeatAtMs'|'id'|'ownerToken'|'status'>}} args - Fence data.
+ * @returns {Record<string, unknown>} Update conditions.
+ */
+export function reconciliationConditions({ mountIdentifier, run }: {
+    mountIdentifier: string;
+    run: Pick<DeploymentRunRow, "heartbeatAtMs" | "id" | "ownerToken" | "status">;
+}): Record<string, unknown>;
+/** Rampway-owned durable deployment state stored through Velocious's database abstraction. */
+export default class DeploymentRunStore {
+    /**
+     * @param {object} args - Store options.
+     * @param {any} args.configuration - Velocious configuration.
+     * @param {string} [args.databaseIdentifier] - Database identifier.
+     * @param {string} args.mountIdentifier - Authenticated mount scope.
+     * @param {number} args.staleRunTimeoutMs - Lease duration.
+     */
+    constructor({ configuration, databaseIdentifier, mountIdentifier, staleRunTimeoutMs }: {
+        configuration: any;
+        databaseIdentifier?: string | undefined;
+        mountIdentifier: string;
+        staleRunTimeoutMs: number;
+    });
+    configuration: any;
+    databaseIdentifier: string;
+    mountIdentifier: string;
+    staleRunTimeoutMs: number;
+    /** @type {Promise<void>|null} */
+    readyPromise: Promise<void> | null;
+    /** @returns {Promise<void>} */
+    ensureReady(): Promise<void>;
+    /**
+     * @param {string} id - Run id.
+     * @returns {Promise<DeploymentRunRow|null>} Run.
+     */
+    findRunById(id: string): Promise<DeploymentRunRow | null>;
+    /**
+     * @param {string} key - Idempotency key.
+     * @returns {Promise<DeploymentRunRow|null>} Run.
+     */
+    findRunByKey(key: string): Promise<DeploymentRunRow | null>;
+    /**
+     * Serializes admission by target then by mount-global idempotency key.
+     *
+     * @param {{idempotencyKey: string, project: string, revision: string, stage: string}} args - Run request.
+     * @returns {Promise<{outcome: string, run: DeploymentRunRow|null}>} Admission result.
+     */
+    createRunIfPossible({ idempotencyKey, project, revision, stage }: {
+        idempotencyKey: string;
+        project: string;
+        revision: string;
+        stage: string;
+    }): Promise<{
+        outcome: string;
+        run: DeploymentRunRow | null;
+    }>;
+    /** @param {{id: string, startedAtMs: number}} args - Transition. @returns {Promise<void>} */
+    markRunning({ id, startedAtMs }: {
+        id: string;
+        startedAtMs: number;
+    }): Promise<void>;
+    /** @param {{id: string, heartbeatAtMs: number}} args - Heartbeat. @returns {Promise<void>} */
+    heartbeat({ id, heartbeatAtMs }: {
+        id: string;
+        heartbeatAtMs: number;
+    }): Promise<void>;
+    /** @param {{id: string, ownerToken: string, finishedAtMs: number, result: any}} args - Transition. @returns {Promise<void>} */
+    markSucceeded({ id, ownerToken, finishedAtMs, result }: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        result: any;
+    }): Promise<void>;
+    /** @param {{id: string, ownerToken: string, finishedAtMs: number, error: any}} args - Transition. @returns {Promise<void>} */
+    markFailed({ id, ownerToken, finishedAtMs, error }: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        error: any;
+    }): Promise<void>;
+    /** @param {{id: string, ownerToken: string, finishedAtMs: number, error: any}} args - Transition. @returns {Promise<void>} */
+    markReconciliationRequired({ id, ownerToken, finishedAtMs, error }: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        error: any;
+    }): Promise<void>;
+    /** @param {{event: string, payload: any, runId: string|null}} args - Audit event. @returns {Promise<void>} */
+    addAuditEvent({ event, payload, runId }: {
+        event: string;
+        payload: any;
+        runId: string | null;
+    }): Promise<void>;
+    /**
+     * @param {{runId: string}} args - Query.
+     * @returns {Promise<Array<Record<string, any>>>} Events.
+     */
+    listAuditEvents({ runId }: {
+        runId: string;
+    }): Promise<Array<Record<string, any>>>;
+    /**
+     * @param {any} db - Open Velocious database connection.
+     * @param {DeploymentRunRow} run - Observed stale run.
+     * @returns {Promise<boolean>} Whether this reconciler won.
+     */
+    _reconcileExpiredRun(db: any, run: DeploymentRunRow): Promise<boolean>;
+    /**
+     * Reconciles an expired pending/running owner before returning durable state.
+     *
+     * @param {any} db - Open Velocious database connection.
+     * @param {DeploymentRunRow|null} run - Observed run.
+     * @returns {Promise<DeploymentRunRow|null>} Current durable run.
+     */
+    _reconcileExpiredRunIfNeeded(db: any, run: DeploymentRunRow | null): Promise<DeploymentRunRow | null>;
+    /** @param {{data: Record<string, any>, id: string, ownerToken: string}} args - Transition. @returns {Promise<void>} */
+    _transition({ data, id, ownerToken }: {
+        data: Record<string, any>;
+        id: string;
+        ownerToken: string;
+    }): Promise<void>;
+    /**
+     * @param {string} kind - Lock kind.
+     * @param {string} value - Scoped value.
+     * @returns {string} Lock name.
+     */
+    _lockName(kind: string, value: string): string;
+    /**
+     * @param {any} db - Connection.
+     * @param {string} id - Run id.
+     * @returns {Promise<DeploymentRunRow|null>} Run.
+     */
+    _findRunById(db: any, id: string): Promise<DeploymentRunRow | null>;
+    /**
+     * @param {any} db - Connection.
+     * @param {string} key - Idempotency key.
+     * @returns {Promise<DeploymentRunRow|null>} Run.
+     */
+    _findRunByKey(db: any, key: string): Promise<DeploymentRunRow | null>;
+    /**
+     * @param {any} db - Connection.
+     * @param {{project: string, stage: string}} args - Target.
+     * @returns {Promise<DeploymentRunRow|null>} Run.
+     */
+    _findBlockingRun(db: any, { project, stage }: {
+        project: string;
+        stage: string;
+    }): Promise<DeploymentRunRow | null>;
+    /**
+     * @param {Record<string, any>} row - Database row.
+     * @returns {DeploymentRunRow} Run.
+     */
+    _row(row: Record<string, any>): DeploymentRunRow;
+    /**
+     * @param {string} context - Context.
+     * @param {unknown} error - Failure.
+     * @returns {void}
+     */
+    _emitFrameworkError(context: string, error: unknown): void;
+    /**
+     * @template T
+     * @param {(db: any) => Promise<T>} callback - Work.
+     * @returns {Promise<T>} Result.
+     */
+    _withDb<T>(callback: (db: any) => Promise<T>): Promise<T>;
+}
+export type DeploymentRunRow = {
+    id: string;
+    mountIdentifier: string;
+    project: string;
+    stage: string;
+    revision: string;
+    idempotencyKey: string;
+    status: string;
+    result: any;
+    error: any;
+    requestedAtMs: number;
+    startedAtMs: number | null;
+    finishedAtMs: number | null;
+    ownerToken: string | null;
+    heartbeatAtMs: number | null;
+};
+export type DeploymentRunStoreContract = {
+    findRunById: (id: string) => Promise<DeploymentRunRow | null>;
+    findRunByKey: (key: string) => Promise<DeploymentRunRow | null>;
+    createRunIfPossible: (args: {
+        idempotencyKey: string;
+        project: string;
+        revision: string;
+        stage: string;
+    }) => Promise<{
+        outcome: string;
+        run: DeploymentRunRow | null;
+    }>;
+    markRunning: (args: {
+        id: string;
+        startedAtMs: number;
+    }) => Promise<void>;
+    heartbeat: (args: {
+        id: string;
+        heartbeatAtMs: number;
+    }) => Promise<void>;
+    markSucceeded: (args: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        result: any;
+    }) => Promise<void>;
+    markFailed: (args: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        error: any;
+    }) => Promise<void>;
+    markReconciliationRequired: (args: {
+        id: string;
+        ownerToken: string;
+        finishedAtMs: number;
+        error: any;
+    }) => Promise<void>;
+    addAuditEvent: (args: {
+        event: string;
+        payload: any;
+        runId: string | null;
+    }) => Promise<void>;
+};
+export const AUDIT_TABLE: "rampway_deployment_api_audit_events";
+/**
+ * @typedef {object} DeploymentRunRow
+ * @property {string} id
+ * @property {string} mountIdentifier
+ * @property {string} project
+ * @property {string} stage
+ * @property {string} revision
+ * @property {string} idempotencyKey
+ * @property {string} status
+ * @property {any} result
+ * @property {any} error
+ * @property {number} requestedAtMs
+ * @property {number|null} startedAtMs
+ * @property {number|null} finishedAtMs
+ * @property {string|null} ownerToken
+ * @property {number|null} heartbeatAtMs
+ */
+/**
+ * @typedef {object} DeploymentRunStoreContract
+ * @property {(id: string) => Promise<DeploymentRunRow|null>} findRunById
+ * @property {(key: string) => Promise<DeploymentRunRow|null>} findRunByKey
+ * @property {(args: {idempotencyKey: string, project: string, revision: string, stage: string}) => Promise<{outcome: string, run: DeploymentRunRow|null}>} createRunIfPossible
+ * @property {(args: {id: string, startedAtMs: number}) => Promise<void>} markRunning
+ * @property {(args: {id: string, heartbeatAtMs: number}) => Promise<void>} heartbeat
+ * @property {(args: {id: string, ownerToken: string, finishedAtMs: number, result: any}) => Promise<void>} markSucceeded
+ * @property {(args: {id: string, ownerToken: string, finishedAtMs: number, error: any}) => Promise<void>} markFailed
+ * @property {(args: {id: string, ownerToken: string, finishedAtMs: number, error: any}) => Promise<void>} markReconciliationRequired
+ * @property {(args: {event: string, payload: any, runId: string|null}) => Promise<void>} addAuditEvent
+ */
+export const RUNS_TABLE: "rampway_deployment_runs";
+//# sourceMappingURL=run-store.d.ts.map

package/build/src/velocious/run-store.d.ts.map

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