@openlup/platform 0.29.0 → 0.30.0

package/src/portability/objects.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+
+export type ObjectTransferFailure = "absent" | "denied" | "unavailable" | "version_conflict" | "integrity_conflict" | "invalid_input";
+
+/** Adapters distinguish missing data from permission and availability failures. */
+export class ObjectTransferError extends Error {
+  constructor(readonly code: ObjectTransferFailure) {
+    super(`object_transfer_${code}`);
+    this.name = "ObjectTransferError";
+  }
+}
+
+export interface TransferObject {
+  key: string;
+  /** Logical immutable source version; never a claim about a target provider's native version ID. */
+  version: string;
+  bytes: number;
+  sha256: string;
+  metadata: Readonly<Record<string, string>>;
+  /** An explicit access classification, never inferred from a public URL. */
+  access: string;
+  lineage?: { sourceId: string; snapshotId: string; sourceVersion: string };
+}
+
+export interface TransferObjectRead {
+  object: TransferObject;
+  body: AsyncIterable<Uint8Array>;
+}
+
+export interface TransferObjectReader {
+  /** Must read the requested version or refuse, never silently read a newer one. */
+  read(key: string, expectedVersion?: string): Promise<TransferObjectRead>;
+}
+
+export interface TransferObjectStore extends TransferObjectReader {
+  /** Atomic publication; an existing key must refuse with version_conflict. */
+  createIfAbsent(object: TransferObject, bytes: Uint8Array): Promise<void>;
+}
+
+export interface TransferObjectInventory {
+  sourceId: string;
+  /** Host prerequisite: complete inventory and stable versioned reads, or a held write fence. */
+  snapshot: { kind: "immutable" | "quiesced"; id: string };
+  objects: readonly TransferObject[];
+}
+
+/** Canonical descriptor encoding also preserves metadata independent of property order. */
+export function encodeTransferObject(object: TransferObject): string {
+  validateTransferObject(object);
+  return JSON.stringify({
+    key: object.key, version: object.version, bytes: object.bytes, sha256: object.sha256,
+    metadata: Object.fromEntries(Object.entries(object.metadata).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)),
+    access: object.access,
+    ...(object.lineage ? { lineage: { sourceId: object.lineage.sourceId, snapshotId: object.lineage.snapshotId, sourceVersion: object.lineage.sourceVersion } } : {}),
+  });
+}
+
+export function validateTransferObject(object: TransferObject): void {
+  if (!object || !text(object.key, 4096) || !text(object.version, 1024)
+    || !Number.isSafeInteger(object.bytes) || object.bytes < 0 || !/^[a-f0-9]{64}$/.test(object.sha256)
+    || !text(object.access, 1024) || !object.metadata || typeof object.metadata !== "object" || Array.isArray(object.metadata)
+    || Object.entries(object.metadata).some(([key, value]) => !text(key, 1024) || typeof value !== "string" || value.length > 8192)
+    || JSON.stringify(object.metadata).length > 65536
+    || (object.lineage !== undefined && (!object.lineage || !text(object.lineage.sourceId, 1024)
+      || !text(object.lineage.snapshotId, 1024) || !text(object.lineage.sourceVersion, 1024)))) {
+    throw new ObjectTransferError("invalid_input");
+  }
+}
+
+/** Bounded in-memory object copy; ceilings are explicit and checked before any destination mutation. */
+export async function copyTransferObjects(input: {
+  inventory: TransferObjectInventory;
+  source: TransferObjectReader;
+  destination: TransferObjectStore;
+  accessMapping: Readonly<Record<string, string>>;
+  maximumObjectBytes: number;
+  maximumTotalBytes: number;
+  /** Called only after destination descriptor and bytes have been read back successfully. */
+  checkpoint?: (object: TransferObject) => Promise<void>;
+}): Promise<{ copied: number; replayed: number; verifiedKeys: string[] }> {
+  const { inventory } = input;
+  if (!inventory || !text(inventory.sourceId, 1024) || !inventory.snapshot
+    || !["immutable", "quiesced"].includes(inventory.snapshot.kind) || !text(inventory.snapshot.id, 1024)
+    || !Array.isArray(inventory.objects) || !input.accessMapping
+    || !ceiling(input.maximumObjectBytes) || !ceiling(input.maximumTotalBytes)) throw new ObjectTransferError("invalid_input");
+  // Snapshot inputs before the first await; a caller cannot change the plan during a copy.
+  const sourceId = inventory.sourceId, snapshotId = inventory.snapshot.id;
+  const keys = new Set<string>();
+  let total = 0;
+  const plan = inventory.objects.map(object => {
+    const source = JSON.parse(encodeTransferObject(object)) as TransferObject;
+    const access = Object.hasOwn(input.accessMapping, source.access) ? input.accessMapping[source.access] : undefined;
+    total += source.bytes;
+    if (keys.has(source.key) || !text(access, 1024) || source.bytes > input.maximumObjectBytes
+      || !Number.isSafeInteger(total) || total > input.maximumTotalBytes) throw new ObjectTransferError("invalid_input");
+    keys.add(source.key);
+    const target: TransferObject = { ...source, access, lineage: { sourceId, snapshotId, sourceVersion: source.version } };
+    return { source, target };
+  });
+  const result = { copied: 0, replayed: 0, verifiedKeys: [] as string[] };
+  for (const { source, target } of plan) {
+    let existing: TransferObjectRead | undefined;
+    try { existing = await input.destination.read(target.key); }
+    catch (error) { if (!failure(error, "absent")) throw normalizeObjectTransferError(error); }
+    if (existing) {
+      await verifyRead(existing, target);
+      result.replayed++;
+    } else {
+      let read: TransferObjectRead;
+      try { read = await input.source.read(source.key, source.version); }
+      catch (error) { throw normalizeObjectTransferError(error); }
+      const bytes = await verifyRead(read, source);
+      let writeFailure: ObjectTransferError | undefined;
+      try { await input.destination.createIfAbsent(target, bytes); }
+      catch (error) {
+        // A competing writer or lost write acknowledgement still requires exact readback.
+        if (!failure(error, "version_conflict") && !failure(error, "unavailable")) throw normalizeObjectTransferError(error);
+        writeFailure = normalizeObjectTransferError(error);
+      }
+      try { await verifyRead(await input.destination.read(target.key), target); }
+      catch (error) { throw failure(error, "absent") && writeFailure ? writeFailure : normalizeObjectTransferError(error); }
+      if (writeFailure) result.replayed++;
+      else result.copied++;
+    }
+    await input.checkpoint?.(JSON.parse(encodeTransferObject(target)) as TransferObject);
+    result.verifiedKeys.push(target.key);
+  }
+  return result;
+}
+
+/** Read exactly the declared bytes and hash; never trust a successful HEAD alone. */
+export async function verifyRead(read: TransferObjectRead, expected: TransferObject): Promise<Uint8Array> {
+  if (encodeTransferObject(read.object) !== encodeTransferObject(expected)) throw new ObjectTransferError("version_conflict");
+  const chunks: Buffer[] = [];
+  const hash = createHash("sha256");
+  let bytes = 0;
+  try {
+    for await (const chunk of read.body) {
+      if (!(chunk instanceof Uint8Array)) throw new ObjectTransferError("integrity_conflict");
+      bytes += chunk.byteLength;
+      if (bytes > expected.bytes) throw new ObjectTransferError("integrity_conflict");
+      const copy = Buffer.from(chunk);
+      chunks.push(copy);
+      hash.update(copy);
+    }
+  } catch (error) { throw normalizeObjectTransferError(error); }
+  if (bytes !== expected.bytes || hash.digest("hex") !== expected.sha256) throw new ObjectTransferError("integrity_conflict");
+  return Buffer.concat(chunks, bytes);
+}
+
+export function normalizeObjectTransferError(error: unknown): ObjectTransferError {
+  return error instanceof ObjectTransferError ? error : new ObjectTransferError("unavailable");
+}
+
+function text(value: unknown, maximum: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maximum
+    && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+}
+function ceiling(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; }
+function failure(error: unknown, code: ObjectTransferFailure): boolean { return error instanceof ObjectTransferError && error.code === code; }

package/src/portability/postgresRows.ts

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+
+/** A finite compatible-row utility, not a complete-store migration profile. */
+const TABLES = [
+  "clients", "subscriptions", "subscription_events", "subscription_pause_windows",
+  "subscription_renewal_terms", "subscription_renewal_term_lines", "subscription_renewal_operations",
+  "subscription_cycles", "commerce_orders", "commerce_order_items", "commerce_settlement_intents",
+  "commerce_settlement_transitions", "payment_truth_events", "payment_truth_reconciliation_evidence",
+  "subscription_renewal_outcomes", "outbox_events", "invoicing_duties", "invoicing_fact_revisions",
+  "invoicing_effect_receipts", "invoicing_capture_faults",
+] as const;
+export type CompatiblePostgresTable = typeof TABLES[number];
+export interface TransferPostgresQuery {
+  query<Row extends Record<string, unknown> = Record<string, unknown>>(sql: string, values?: readonly unknown[]): Promise<{ rows: Row[] }>;
+}
+export interface CompatiblePostgresSnapshot {
+  /** Own one read-only, repeatable-read transaction for the complete callback. */
+  withSnapshot<T>(work: (db: TransferPostgresQuery) => Promise<T>): Promise<T>;
+}
+export interface CompatiblePostgresTarget {
+  /** Own one transaction; commit only after the complete callback succeeds. */
+  withTransaction<T>(work: (db: TransferPostgresQuery) => Promise<T>): Promise<T>;
+}
+type Column = { name: string; type: string; key: boolean };
+type TableRows = { table: CompatiblePostgresTable; columns: Column[]; rows: string[] };
+export interface CompatiblePostgresPacket {
+  format: "openlup.compatible-rows.v1";
+  sourceId: string;
+  /** Opaque selected-catalogue identity supplied by the validated host capability. */
+  catalogueId: string;
+  tables: TableRows[];
+  sha256: string;
+}
+export type PostgresTransferFailure = "invalid_input" | "unsupported_table" | "schema_conflict"
+  | "insert_trigger_requires_owner" | "target_conflict" | "limit_exceeded" | "database_unavailable";
+export class PostgresTransferError extends Error {
+  constructor(readonly code: PostgresTransferFailure, readonly table?: string) {
+    super(`postgres_transfer_${code}${table ? `:${table}` : ""}`);
+    this.name = "PostgresTransferError";
+  }
+}
+const LIMIT_ROWS = 10000, LIMIT_BYTES = 64 * 1024 * 1024;
+
+/** Data only: no schema, role, grant, migration ledger, control or provider-internal copy. */
+export async function captureCompatiblePostgresRows(input: {
+  source: CompatiblePostgresSnapshot; sourceId: string; catalogueId: string;
+  tables: readonly CompatiblePostgresTable[]; maximumRows: number; maximumBytes: number;
+}): Promise<CompatiblePostgresPacket> {
+  const { sourceId, catalogueId, maximumRows, maximumBytes } = input;
+  if (!identity(sourceId) || !identity(catalogueId) || !ceiling(maximumRows, LIMIT_ROWS) || !ceiling(maximumBytes, LIMIT_BYTES)) fail("invalid_input");
+  const names = tableNames(input.tables);
+  try {
+    const tables = await input.source.withSnapshot(async db => {
+      const mode = (await db.query("SELECT current_setting('transaction_read_only') AS readonly, current_setting('transaction_isolation') AS isolation")).rows[0];
+      if (mode?.readonly !== "on" || mode.isolation !== "repeatable read") fail("invalid_input");
+      await db.query("SET LOCAL TimeZone = 'UTC'");
+      let count = 0, bytes = 0;
+      const result: TableRows[] = [];
+      for (const table of names) {
+        const columns = await inspect(db, table);
+        const order = columns.filter(column => column.key).map(column => quoted(column.name)).join(",");
+        // PostgreSQL serializes bigint, numeric, bytea and timestamp values.
+        // Retain that JSON text unchanged; a JS numeric round trip is lossy.
+        const rows = (await db.query<{ value: string }>(`SELECT to_jsonb(t)::text AS value FROM public.${quoted(table)} t ORDER BY ${order} LIMIT $1`, [maximumRows + 1])).rows.map(row => row.value);
+        for (const row of rows) { count++; bytes += Buffer.byteLength(row); }
+        if (count > maximumRows || bytes > maximumBytes) fail("limit_exceeded", table);
+        result.push({ table, columns, rows });
+      }
+      return result;
+    });
+    const packet = { format: "openlup.compatible-rows.v1" as const, sourceId, catalogueId, tables };
+    return { ...packet, sha256: digest(packet) };
+  } catch (error) { throw redacted(error); }
+}
+
+/**
+ * Atomic insert and exact replay. A differing row refuses; there is no upsert,
+ * deletion scan, status reset or permission change. Existing parent rows remain
+ * prerequisites, and this utility never authorizes target effect execution.
+ */
+export async function restoreCompatiblePostgresRows(input: {
+  target: CompatiblePostgresTarget; catalogueId: string; packet: CompatiblePostgresPacket;
+}): Promise<{ inserted: number; replayed: number; sha256: string }> {
+  // Own immutable input bytes throughout async validation and writes.
+  let packet: CompatiblePostgresPacket;
+  try { packet = JSON.parse(JSON.stringify(input.packet)) as CompatiblePostgresPacket; validatePacket(packet); }
+  catch (error) { if (error instanceof PostgresTransferError) throw error; fail("invalid_input"); }
+  if (packet.catalogueId !== input.catalogueId) fail("schema_conflict");
+  try {
+    return await input.target.withTransaction(async db => {
+      const mode = (await db.query("SELECT current_setting('session_replication_role') AS mode")).rows[0];
+      if (mode?.mode !== "origin") fail("invalid_input");
+      await db.query("SET LOCAL TimeZone = 'UTC'");
+      // Serializes writers and prevents DDL between inspection and inserts.
+      // Fixed lock ordering avoids deadlock between overlapping packet imports.
+      for (const table of [...packet.tables].sort((a, b) => a.table.localeCompare(b.table))) {
+        await db.query(`LOCK TABLE public.${quoted(table.table)} IN SHARE ROW EXCLUSIVE MODE`);
+      }
+      for (const table of packet.tables) {
+        if (JSON.stringify(await inspect(db, table.table)) !== JSON.stringify(table.columns)) fail("schema_conflict", table.table);
+        const triggers = (await db.query(`SELECT 1 FROM pg_catalog.pg_trigger
+          WHERE tgrelid=$1::regclass AND NOT tgisinternal AND (tgtype & 4) <> 0 AND tgenabled IN ('O','A')`, [`public.${table.table}`])).rows;
+        if (triggers.length) fail("insert_trigger_requires_owner", table.table);
+      }
+      let inserted = 0, replayed = 0;
+      for (const table of packet.tables) {
+        const name = `public.${quoted(table.table)}`;
+        const columns = table.columns.map(column => quoted(column.name)).join(",");
+        const keys = table.columns.filter(column => column.key).map(column => `t.${quoted(column.name)} IS NOT DISTINCT FROM p.${quoted(column.name)}`).join(" AND ");
+        for (const row of table.rows) {
+          const write = await db.query(`INSERT INTO ${name} (${columns}) SELECT ${columns} FROM jsonb_populate_record(NULL::${name}, $1::jsonb)
+            ON CONFLICT DO NOTHING RETURNING 1 AS inserted`, [row]);
+          const read = await db.query<{ identical: boolean }>(`SELECT to_jsonb(t) = $1::jsonb AS identical FROM ${name} t,
+            jsonb_populate_record(NULL::${name}, $1::jsonb) p WHERE ${keys}`, [row]);
+          if (read.rows.length !== 1 || read.rows[0]?.identical !== true) fail("target_conflict", table.table);
+          if (write.rows.length) inserted++; else replayed++;
+        }
+      }
+      return { inserted, replayed, sha256: packet.sha256 };
+    });
+  } catch (error) { throw redacted(error); }
+}
+
+async function inspect(db: TransferPostgresQuery, table: CompatiblePostgresTable): Promise<Column[]> {
+  const rows = (await db.query<{ name: string; type: string; key: boolean; generated: string; identity: string }>(`SELECT a.attname AS name,
+    pg_catalog.format_type(a.atttypid,a.atttypmod) AS type, COALESCE(a.attnum = ANY(i.indkey),false) AS key,
+    a.attgenerated AS generated, a.attidentity AS identity
+    FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid=a.attrelid
+    LEFT JOIN pg_catalog.pg_index i ON i.indrelid=c.oid AND i.indisprimary
+    WHERE a.attrelid=$1::regclass AND c.relkind='r' AND a.attnum>0 AND NOT a.attisdropped ORDER BY a.attnum`, [`public.${table}`])).rows;
+  if (!rows.length || !rows.some(row => row.key) || rows.some(row => row.generated || row.identity || !identifier(row.name))) fail("schema_conflict", table);
+  return rows.map(({ name, type, key }) => ({ name, type, key }));
+}
+function tableNames(tables: readonly CompatiblePostgresTable[]): CompatiblePostgresTable[] {
+  if (!Array.isArray(tables) || !tables.length || new Set(tables).size !== tables.length) fail("invalid_input");
+  for (const table of tables) if (!(TABLES as readonly string[]).includes(table)) fail("unsupported_table");
+  return TABLES.filter(table => tables.includes(table));
+}
+function validatePacket(packet: CompatiblePostgresPacket): void {
+  if (!packet || packet.format !== "openlup.compatible-rows.v1" || !identity(packet.sourceId) || !identity(packet.catalogueId)
+    || !Array.isArray(packet.tables) || !/^[a-f0-9]{64}$/.test(packet.sha256)) fail("invalid_input");
+  const { sha256: _hash, ...payload } = packet;
+  if (digest(payload) !== packet.sha256) fail("invalid_input");
+  const names = tableNames(packet.tables.map(table => table.table));
+  if (names.some((name, index) => name !== packet.tables[index]?.table)) fail("invalid_input");
+  let count = 0, bytes = 0;
+  for (const table of packet.tables) {
+    if (!Array.isArray(table.columns) || !table.columns.length || !table.columns.some(column => column.key)
+      || table.columns.some(column => !identifier(column.name) || !identity(column.type) || typeof column.key !== "boolean")
+      || new Set(table.columns.map(column => column.name)).size !== table.columns.length || !Array.isArray(table.rows)) fail("invalid_input");
+    for (const row of table.rows) {
+      if (typeof row !== "string") fail("invalid_input");
+      // Inspect only field names. Never stringify parsed values back to SQL.
+      const parsed: unknown = JSON.parse(row);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+        || Object.keys(parsed).sort().join("\0") !== table.columns.map(column => column.name).sort().join("\0")) fail("invalid_input");
+      count++; bytes += Buffer.byteLength(row);
+    }
+  }
+  if (count > LIMIT_ROWS || bytes > LIMIT_BYTES) fail("limit_exceeded");
+}
+function digest(value: unknown): string { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function identifier(value: string): boolean { return /^[a-z][a-z0-9_]{0,62}$/.test(value); }
+function quoted(value: string): string { if (!identifier(value)) fail("invalid_input"); return `"${value}"`; }
+function identity(value: unknown): value is string { return typeof value === "string" && value.length > 0 && value.length <= 1024
+  && !Array.from(value).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127); }
+function ceiling(value: number, maximum: number): boolean { return Number.isSafeInteger(value) && value > 0 && value <= maximum; }
+function fail(code: PostgresTransferFailure, table?: string): never { throw new PostgresTransferError(code, table); }
+function redacted(error: unknown): PostgresTransferError { return error instanceof PostgresTransferError ? error : new PostgresTransferError("database_unavailable"); }

package/src/scheduler/advisoryLock.ts

@@ -55,19 +55,34 @@ export function createPgAdvisoryLock(
   closeClient: () => Promise<void> = () => client.end?.() ?? Promise.resolve(),
 ): AdvisoryLock {
   let closePromise: Promise<void> | null = null;
+  // PostgreSQL grants reentrant session locks. Reserve the actual key locally
+  // before querying so pending/held acquisitions, including hash collisions, skip.
+  const reserved = new Set<number>();
   return {
     durability: "cluster",
     async tryAcquire(jobId) {
       const key = advisoryLockKey(jobId);
-      const { rows } = await client.query<{ locked: boolean }>(
-        "SELECT pg_try_advisory_lock($1) AS locked",
-        [key],
-      );
-      return rows[0]?.locked === true;
+      if (reserved.has(key)) return false;
+      reserved.add(key);
+      try {
+        const { rows } = await client.query<{ locked: boolean }>(
+          "SELECT pg_try_advisory_lock($1) AS locked",
+          [key],
+        );
+        const acquired = rows[0]?.locked === true;
+        if (!acquired) reserved.delete(key);
+        return acquired;
+      } catch (error) {
+        reserved.delete(key);
+        throw error;
+      }
     },
     async release(jobId) {
       const key = advisoryLockKey(jobId);
       await client.query("SELECT pg_advisory_unlock($1)", [key]);
+      // A failed unlock keeps the reservation: another query on this session
+      // could otherwise reenter the still-held PostgreSQL lock.
+      reserved.delete(key);
     },
     close() {
       closePromise ??= closeClient();

package/src/scheduler/nodeScheduler.ts

@@ -30,12 +30,13 @@ export interface CronScheduler {
 interface RegisteredTimer {
   jobId: string;
   stop: () => void;
+  stopped: boolean;
 }
 
 export interface NodeSchedulerAdapter extends SchedulerPort {
   readonly jobs: readonly ScheduledJobDeclaration[];
-  /** Stop all registered node-cron timers (graceful shutdown). */
-  stopAll(): void;
+  /** Fence/stop current timers synchronously, then await admitted callbacks and lock release. Later registration remains supported. */
+  stopAll(): Promise<void>;
 }
 
 export interface CreateNodeSchedulerOptions {
@@ -92,6 +93,7 @@ export function createNodeScheduler(options: CreateNodeSchedulerOptions): NodeSc
     });
   const scheduleById = new Map(jobs.map((job) => [job.jobId, job.schedule]));
   const timers: RegisteredTimer[] = [];
+  const active = new Set<Promise<void>>();
 
   return {
     jobs,
@@ -106,18 +108,36 @@ export function createNodeScheduler(options: CreateNodeSchedulerOptions): NodeSc
         );
       }
       const guarded = withAdvisoryLock(input.jobId, lock, input.handler, onError);
-      const timer = options.cron.schedule(schedule, guarded, { timezone: options.timezone });
-      timers.push({ jobId: input.jobId, stop: timer.stop });
+      const registration: RegisteredTimer = { jobId: input.jobId, stop: () => {}, stopped: false };
+      const timer = options.cron.schedule(schedule, () => {
+        if (registration.stopped) return Promise.resolve();
+        // Own the callback before acquisition starts, including a pending acquisition.
+        const running = Promise.resolve().then(guarded);
+        active.add(running);
+        void running.then(() => active.delete(running), () => active.delete(running));
+        return running;
+      }, { timezone: options.timezone });
+      registration.stop = timer.stop;
+      timers.push(registration);
     },
     verifyInvocation(req: HttpRequest) {
       // Self-hosted invocations still present the shared CRON_SECRET; reuse the canonical check.
       return verifyCronAuth(req, env);
     },
-    stopAll() {
-      for (const timer of timers) {
-        timer.stop();
+    async stopAll() {
+      const stopped = timers.splice(0);
+      for (const timer of stopped) timer.stopped = true;
+      const admitted = [...active];
+      const failures: unknown[] = [];
+      for (const timer of stopped) {
+        try { timer.stop(); } catch (error) { failures.push(error); }
       }
-      timers.length = 0;
+      const results = await Promise.allSettled(admitted);
+      for (const result of results) {
+        if (result.status === "rejected") failures.push(result.reason);
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1) throw new AggregateError(failures, "node_scheduler_shutdown_failed");
     },
   };
 }