akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/server/migration/migrationLedger.ts

@@ -0,0 +1,172 @@
+import { type AkanSqlClient, MigrationTables } from "akanjs/service";
+import { MigrationChangeLog } from "./migrationChangeLog";
+import { MigrationError } from "./migrationError";
+
+export type MigrationRunKind = "plan" | "apply" | "verify" | "rollback";
+/** `aborted` is a refusal before any write: the plan no longer hashed to what was approved. */
+export type MigrationRunStatus = "running" | "done" | "failed" | "aborted";
+
+export interface MigrationRun {
+  id: string;
+  migrationId: string;
+  kind: MigrationRunKind;
+  status: MigrationRunStatus;
+  /** The apply run a rollback undoes. */
+  target: string | null;
+  checksum: string;
+  buildId: string | null;
+  params: Record<string, unknown> | null;
+  planHash: string | null;
+  summary: Record<string, unknown> | null;
+  actor: string | null;
+  checkpoint: Record<string, string> | null;
+  startedAt: number;
+  finishedAt: number | null;
+  error: string | null;
+}
+
+export interface MigrationState {
+  /** The last apply that finished and was not rolled back. */
+  applied: MigrationRun | null;
+  /** Applies that failed after committing some of their writes, newest first; a rollback undoes them too. */
+  partial: MigrationRun[];
+}
+
+type MigrationRunRow = Omit<MigrationRun, "params" | "summary" | "checkpoint" | "startedAt" | "finishedAt"> & {
+  params: string | null;
+  summary: string | null;
+  checkpoint: string | null;
+  startedAt: number | string;
+  finishedAt: number | string | null;
+};
+
+export class MigrationLedger {
+  static readonly #columns = MigrationTables.ledger[0]?.columns ?? [];
+  readonly #connection: () => AkanSqlClient;
+
+  constructor(connection: () => AkanSqlClient) {
+    this.#connection = connection;
+  }
+
+  async insert(run: MigrationRun) {
+    const values = MigrationLedger.#toRow(run);
+    await this.#connection()
+      .prepare(
+        `INSERT INTO "${MigrationTables.run}" (${MigrationLedger.#columns.map((column) => `"${column}"`).join(", ")}) VALUES (${MigrationLedger.#columns.map(() => "?").join(", ")})`,
+      )
+      .run(...MigrationLedger.#columns.map((column) => values[column as keyof MigrationRunRow] ?? null));
+    return run;
+  }
+
+  async finish(
+    id: string,
+    {
+      status,
+      planHash = null,
+      summary = null,
+      error = null,
+    }: {
+      status: MigrationRunStatus;
+      planHash?: string | null;
+      summary?: Record<string, unknown> | null;
+      error?: string | null;
+    },
+  ) {
+    await this.#connection()
+      .prepare(
+        `UPDATE "${MigrationTables.run}" SET "status" = ?, "planHash" = COALESCE(?, "planHash"), "summary" = ?, "error" = ?, "finishedAt" = ? WHERE "id" = ?`,
+      )
+      .run(status, planHash, summary ? JSON.stringify(summary) : null, error, Date.now(), id);
+  }
+
+  /** Only while the run is still `running`: one another holder interrupted is never recorded done after all. */
+  async complete(
+    id: string,
+    { planHash = null, summary }: { planHash?: string | null; summary: Record<string, unknown> },
+  ) {
+    const completed = await this.#connection()
+      .prepare(
+        `UPDATE "${MigrationTables.run}" SET "status" = 'done', "planHash" = COALESCE(?, "planHash"), "summary" = ?, "finishedAt" = ? WHERE "id" = ? AND "status" = 'running' RETURNING "id"`,
+      )
+      .get<{ id: string }>(planHash, JSON.stringify(summary), Date.now(), id);
+    if (!completed)
+      throw new MigrationError("locked", `Another migration run interrupted run ${id}, so it is not recorded done`);
+  }
+
+  async saveCheckpoint(id: string, checkpoint: Record<string, string>) {
+    await this.#connection()
+      .prepare(`UPDATE "${MigrationTables.run}" SET "checkpoint" = ? WHERE "id" = ?`)
+      .run(JSON.stringify(checkpoint), id);
+  }
+
+  async get(id: string) {
+    const row = await this.#connection()
+      .prepare(`SELECT * FROM "${MigrationTables.run}" WHERE "id" = ?`)
+      .get<MigrationRunRow>(id);
+    return row ? MigrationLedger.#fromRow(row) : null;
+  }
+
+  /** Oldest first. */
+  async runsOf(migrationId?: string) {
+    const rows = await this.#connection()
+      .prepare(
+        `SELECT * FROM "${MigrationTables.run}"${migrationId ? ` WHERE "migrationId" = ?` : ""} ORDER BY "startedAt", "id"`,
+      )
+      .all<MigrationRunRow>(...(migrationId ? [migrationId] : []));
+    return rows.map(MigrationLedger.#fromRow);
+  }
+
+  /** Only the lock holder calls this, so a run still `running` belongs to a process that died holding the lock. */
+  async interruptRunning() {
+    await this.#connection()
+      .prepare(
+        `UPDATE "${MigrationTables.run}" SET "status" = 'failed', "error" = 'interrupted', "finishedAt" = ? WHERE "status" = 'running'`,
+      )
+      .run(Date.now());
+  }
+
+  async state(runs: MigrationRun[]): Promise<MigrationState> {
+    const reverted = new Set(
+      runs.filter((run) => run.kind === "rollback" && run.status === "done").map((run) => run.target),
+    );
+    const live = runs.filter((run) => run.kind === "apply" && !reverted.has(run.id)).reverse();
+    const failed = live.filter((run) => run.status === "failed");
+    const changed = await Promise.all(
+      failed.map(async (run) => (await MigrationChangeLog.count(this.#connection(), run.id)) > 0),
+    );
+    return {
+      applied: live.find((run) => run.status === "done") ?? null,
+      partial: failed.filter((_, idx) => changed[idx]),
+    };
+  }
+
+  static #toRow(run: MigrationRun): Partial<MigrationRunRow> {
+    return {
+      ...run,
+      params: run.params ? JSON.stringify(run.params) : null,
+      summary: run.summary ? JSON.stringify(run.summary) : null,
+      checkpoint: run.checkpoint ? JSON.stringify(run.checkpoint) : null,
+    };
+  }
+
+  static #fromRow(row: MigrationRunRow): MigrationRun {
+    const json = <T>(text: string | null) => (text ? (JSON.parse(text) as T) : null);
+    return {
+      id: row.id,
+      migrationId: row.migrationId,
+      kind: row.kind,
+      status: row.status,
+      target: row.target ?? null,
+      checksum: row.checksum,
+      buildId: row.buildId ?? null,
+      params: json<Record<string, unknown>>(row.params),
+      planHash: row.planHash ?? null,
+      summary: json<Record<string, unknown>>(row.summary),
+      actor: row.actor ?? null,
+      checkpoint: json<Record<string, string>>(row.checkpoint),
+      startedAt: Number(row.startedAt),
+      finishedAt: row.finishedAt === null ? null : Number(row.finishedAt),
+      error: row.error ?? null,
+    };
+  }
+}

package/server/migration/migrationLock.ts

@@ -0,0 +1,103 @@
+import type { AkanSqlClient } from "akanjs/service";
+import { MigrationError } from "./migrationError";
+
+/**
+ * One run at a time across every replica and channel: a lease in `_akan_meta` holding its holder's token, `updatedAt`
+ * the epoch ms it was last renewed at. A holder that dies is replaced once the lease is `ttlMs` old; a live one renews
+ * well inside that, and every renewal names its token, so a holder that was replaced finds out on its next one.
+ */
+export class MigrationLock {
+  static readonly key = "migration:lock";
+  static readonly ttlMs = 60_000;
+  static readonly renewMs = 15_000;
+  readonly #connection: () => AkanSqlClient;
+  readonly #inBand: boolean;
+  #token: string | null = null;
+  #autocommit: AkanSqlClient | null = null;
+  #renewedAt = 0;
+  #lost: boolean = false;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #renewing: Promise<void> = Promise.resolve();
+
+  /**
+   * `inBand` for SQLite: bun:sqlite runs each statement synchronously, so a run never lets the renewal timer fire, and
+   * a renewal inside the run's transaction is safe, as that transaction keeps every other process off the lease.
+   */
+  constructor(connection: () => AkanSqlClient, { inBand = false }: { inBand?: boolean } = {}) {
+    this.#connection = connection;
+    this.#inBand = inBand;
+  }
+
+  /**
+   * Call outside any transaction: the renewal timer keeps the context it was created in, and a beat renews only on the
+   * connection this acquires on.
+   */
+  async acquire() {
+    const now = Date.now();
+    const token = crypto.randomUUID();
+    const connection = this.#connection();
+    let claimed: { value: string } | null;
+    try {
+      claimed = await connection
+        .prepare(
+          `INSERT INTO "_akan_meta" ("key", "value", "updatedAt") VALUES (?, ?, ?)
+           ON CONFLICT("key") DO UPDATE SET "value" = ?, "updatedAt" = ?
+           WHERE "_akan_meta"."updatedAt" < ?
+           RETURNING "value"`,
+        )
+        .get<{ value: string }>(MigrationLock.key, token, now, token, now, now - MigrationLock.ttlMs);
+    } catch (error) {
+      
+      if (/^SQLITE_BUSY/.test(String((error as { code?: unknown } | null)?.code ?? ""))) return false;
+      throw error;
+    }
+    if (!claimed) return false;
+    this.#token = token;
+    this.#autocommit = connection;
+    this.#renewedAt = now;
+    this.#timer = setInterval(() => {
+      this.#renewing = this.#renewing.then(async () => await this.#renew());
+    }, MigrationLock.renewMs);
+    this.#timer.unref?.();
+    return true;
+  }
+
+  /**
+   * Throws once another run has taken the lease over. Renews when due, or at once with `force`, so a run that stalled
+   * past the TTL finds out before its next write. Off SQLite it leaves renewing to the timer inside any transaction,
+   * whose connection is not the one it acquired on: a renewal there publishes nothing until that commits, holds the
+   * row the timer renews, and under repeatable read fails the whole transaction once the timer has renewed.
+   */
+  async heartbeat({ force = false }: { force?: boolean } = {}) {
+    const due = force || Date.now() - this.#renewedAt >= MigrationLock.renewMs;
+    if (due && (this.#inBand || this.#connection() === this.#autocommit)) await this.#renew();
+    if (this.#lost)
+      throw new MigrationError("locked", "Another migration run took the lock over while this one ran, so it stopped");
+  }
+
+  async release() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = null;
+    await this.#renewing;
+    const held = this.#token;
+    this.#token = null;
+    if (!held) return;
+    await this.#connection()
+      .prepare(`DELETE FROM "_akan_meta" WHERE "key" = ? AND "value" = ?`)
+      .run(MigrationLock.key, held);
+  }
+
+  async #renew() {
+    const held = this.#token;
+    if (!held || this.#lost) return;
+    const now = Date.now();
+    try {
+      const renewed = await this.#connection()
+        .prepare(`UPDATE "_akan_meta" SET "updatedAt" = ? WHERE "key" = ? AND "value" = ? RETURNING "value"`)
+        .get<{ value: string }>(now, MigrationLock.key, held);
+      if (renewed) this.#renewedAt = now;
+      else this.#lost = true;
+    } catch {
+    }
+  }
+}

package/server/migration/migrationParams.ts

@@ -0,0 +1,122 @@
+import { type Cls, type EnumInstance, isEnum, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { deserialize, type FieldToValue, type ParamFieldType } from "akanjs/constant";
+import { MigrationError } from "./migrationError";
+
+export interface MigrationParamOption<Value = unknown> {
+  /** What the value means, shown beside its input on the approval form — so English. */
+  desc?: string;
+  /** For a `String`, the values it may take. */
+  enum?: readonly string[];
+  default?: Value;
+  /** Left out, the value is `null` rather than a refusal. */
+  nullable?: boolean;
+}
+
+export type MigrationParamValue<Type, Option> = Option extends { default: unknown }
+  ? MigrationParamBase<Type, Option>
+  : Option extends { nullable: true }
+    ? MigrationParamBase<Type, Option> | null
+    : MigrationParamBase<Type, Option>;
+
+type MigrationParamBase<Type, Option> = Option extends { enum: readonly (infer Value)[] } ? Value : FieldToValue<Type>;
+
+export interface MigrationParamInfo extends MigrationParamOption {
+  name: string;
+  type: ParamFieldType;
+}
+
+/** One declared param as `list` reports it, enough to build its input. */
+export interface MigrationParamSpec {
+  name: string;
+  type: string;
+  required: boolean;
+  enum?: readonly (string | number)[];
+  default?: unknown;
+  desc?: string;
+}
+
+export class MigrationParams {
+  readonly list: MigrationParamInfo[] = [];
+
+  declare(info: MigrationParamInfo) {
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(info.name))
+      throw new Error(`Migration param "${info.name}" must start with a letter and hold letters, digits and _`);
+    if (this.list.some((existing) => existing.name === info.name))
+      throw new Error(`Migration param "${info.name}" is declared twice`);
+    this.list.push(info);
+  }
+
+  parse(raw: Record<string, string>): Record<string, unknown> {
+    const unknown = Object.keys(raw).find((name) => !this.list.some((info) => info.name === name));
+    if (unknown)
+      throw new MigrationError(
+        "invalidParam",
+        `Unknown param "${unknown}"; this migration takes ${this.list.map(({ name }) => name).join(", ") || "none"}`,
+      );
+    return Object.fromEntries(this.list.map((info) => [info.name, MigrationParams.#value(info, raw[info.name])]));
+  }
+
+  /** Params a run recorded as JSON, as their declared types again: what a rollback hands the script. */
+  revive(stored: Record<string, unknown>): Record<string, unknown> {
+    return Object.fromEntries(
+      this.list.map((info) => {
+        const value = stored[info.name];
+        if (value === undefined || value === null) return [info.name, value ?? info.default ?? null];
+        try {
+          return [info.name, MigrationParams.#deserialize(info, value)];
+        } catch {
+          return [info.name, value];
+        }
+      }),
+    );
+  }
+
+  specs(): MigrationParamSpec[] {
+    return this.list.map((info) => ({
+      name: info.name,
+      type: MigrationParams.#typeName(info),
+      required: !("default" in info) && !info.nullable,
+      ...(MigrationParams.#choices(info) ? { enum: MigrationParams.#choices(info) } : {}),
+      ...("default" in info ? { default: info.default } : {}),
+      ...(info.desc ? { desc: info.desc } : {}),
+    }));
+  }
+
+  static #value(info: MigrationParamInfo, raw: string | undefined) {
+    if (raw === undefined || raw === "") {
+      if ("default" in info) return info.default;
+      if (info.nullable) return null;
+      throw new MigrationError("invalidParam", `Param "${info.name}" is required`);
+    }
+    
+    const input = (info.type as unknown) === Date && /^\d{4}-\d{2}-\d{2}$/.test(raw) ? `${raw}T00:00:00.000Z` : raw;
+    let value: unknown;
+    try {
+      value = MigrationParams.#deserialize(info, input);
+    } catch {
+      throw new MigrationError("invalidParam", `Param "${info.name}" expects ${MigrationParams.#typeName(info)}`);
+    }
+    if (info.enum && !info.enum.includes(value as string))
+      throw new MigrationError("invalidParam", `Param "${info.name}" expects one of ${info.enum.join(", ")}`);
+    return value;
+  }
+
+  static #deserialize(info: MigrationParamInfo, value: unknown) {
+    const enumRef = isEnum(info.type as Cls) ? (info.type as EnumInstance) : undefined;
+    const scalar = (enumRef ? enumRef.type : info.type) as typeof PrimitiveScalar;
+    return deserialize(scalar as never, 0, value, { key: info.name, enum: enumRef });
+  }
+
+  static #choices(info: MigrationParamInfo): readonly (string | number)[] | undefined {
+    if (isEnum(info.type as Cls)) return (info.type as EnumInstance).values as readonly (string | number)[];
+    return info.enum;
+  }
+
+  static #typeName(info: MigrationParamInfo) {
+    const choices = MigrationParams.#choices(info);
+    if (choices) return `one of ${choices.join(", ")}`;
+    return PrimitiveRegistry.has(info.type as Cls)
+      ? PrimitiveRegistry.getName(info.type as typeof PrimitiveScalar)
+      : "a value";
+  }
+}

package/server/migration/migrationPulse.ts

@@ -0,0 +1,39 @@
+import type { MigrationLock } from "./migrationLock";
+
+/** What every table call of a run beats: its lease, and a warning once its own transaction has held SQLite long. */
+export class MigrationPulse {
+  
+  static readonly holdWarnMs = 5_000;
+  readonly lock: MigrationLock;
+  #onLongHold: ((heldMs: number) => void) | null;
+  #heldSince: number | null = null;
+
+  constructor(lock: MigrationLock, onLongHold: ((heldMs: number) => void) | null = null) {
+    this.lock = lock;
+    this.#onLongHold = onLongHold;
+  }
+
+  /** A writer stops once its lease is lost; a reader reads on, as nothing it does clashes with whoever took over. */
+  async beat({ strict, force = false }: { strict: boolean; force?: boolean }) {
+    try {
+      await this.lock.heartbeat({ force });
+    } catch (error) {
+      if (strict) throw error;
+    }
+    if (this.#heldSince === null || !this.#onLongHold) return;
+    const heldMs = Date.now() - this.#heldSince;
+    if (heldMs < MigrationPulse.holdWarnMs) return;
+    this.#onLongHold(heldMs);
+    this.#onLongHold = null;
+  }
+
+  /** Runs `fn` as the span the warning measures: the run's own transaction. */
+  async hold<T>(fn: () => Promise<T>) {
+    this.#heldSince = Date.now();
+    try {
+      return await fn();
+    } finally {
+      this.#heldSince = null;
+    }
+  }
+}