@delali/sirannon-db 0.2.3-next.31 → 0.2.3-next.32

package/dist/backup/index.d.ts

@@ -1,6 +1,7 @@
-import { B as BackupDestination, a as BackupRunReport } from '../report-BFsHdkKt.js';
-export { b as BackupPiece, c as BackupProgress, d as BackupToDestinationOptions } from '../report-BFsHdkKt.js';
-export { B as BackupCapabilities } from '../capabilities-DagBnGk8.js';
+import { e as BackupDestination, f as BackupRunReport } from '../types-CwIiWpVr.js';
+export { g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, l as BackupCycle, m as BackupCycleOptions, n as BackupPiece, o as BackupProgress, p as BackupToDestinationOptions, q as DEFAULT_CHAIN_NAME, r as chainLogName, s as readBackupChains } from '../types-CwIiWpVr.js';
+export { B as BackupCapabilities, a as BackupRestorePlan, b as BackupSafeToDeleteOptions, c as backupPiecesSafeToDelete, p as planBackupRestore } from '../chain-queries-CL_R_DuV.js';
+import '../query-types-Cv8N7pXj.js';
 
 /** What one assembled file took to build.
  * @public

package/dist/backup/index.mjs

@@ -1,3 +1,5 @@
+export { backupPiecesSafeToDelete, planBackupRestore } from '../chunk-YNTDOFTN.mjs';
+export { DEFAULT_CHAIN_NAME, chainLogName, readBackupChains } from '../chunk-4H45GMYI.mjs';
 import { SirannonError } from '../chunk-PBRXXISQ.mjs';
 import { createHash } from 'crypto';
 import { open, rm } from 'fs/promises';

package/dist/backup-scheduler/index.d.ts

@@ -1,5 +1,4 @@
-import { e as SQLiteConnection, f as BackupScheduleOptions } from '../types-B1wQuNXV.js';
-import { e as BackupRunRequest, a as BackupRunReport } from '../report-BFsHdkKt.js';
+import { t as SQLiteConnection, u as BackupRunRequest, f as BackupRunReport, v as BackupScheduleOptions } from '../types-CwIiWpVr.js';
 import '../query-types-Cv8N7pXj.js';
 
 declare class BackupManager {

package/dist/backup-scheduler/index.mjs

@@ -1,4 +1,4 @@
-export { BackupScheduler } from '../chunk-23HKRYSM.mjs';
+export { BackupScheduler } from '../chunk-MZM74XYK.mjs';
 import '../chunk-W67A4H2E.mjs';
 import '../chunk-V5FUJEYY.mjs';
 import '../chunk-PBRXXISQ.mjs';

package/dist/chain-queries-CL_R_DuV.d.ts

@@ -0,0 +1,91 @@
+import { h as BackupChainBase, i as BackupChainChange, g as BackupChain, k as BackupChainRecord } from './types-CwIiWpVr.js';
+
+/**
+ * What one runtime supports of the backup operations, so a caller learns
+ * before a run rather than at failure time. A runtime that hands over whole
+ * databases only reports no full copy at all.
+ *
+ * @public
+ */
+interface BackupCapabilities {
+    /** Whether this runtime copies an open database while writes continue. */
+    fullCopy: boolean;
+    /** Whether a full copy reaches the destination without a local file. */
+    streamedCopy: boolean;
+    /** Whether a full copy writes a local file and sends that file on. */
+    stagedCopy: boolean;
+    /** Local disk a full copy needs, which the staged route sets to the size of the backup. */
+    localDiskRequired: 'none' | 'equal-to-backup';
+    /** Whether this runtime repeats a full copy on a schedule. */
+    schedule: boolean;
+}
+
+/** What one restore has to read, and what it will produce.
+ * @public
+ */
+interface BackupRestorePlan {
+    /** The chain to read. */
+    chainId: string;
+    /** The full copy to start from. */
+    base: BackupChainBase;
+    /** The change pieces to apply on top of it, oldest first. */
+    changes: BackupChainChange[];
+    /**
+     * Epoch milliseconds the restored database will reflect. This is when the
+     * last piece in the plan was captured, which is at or before the moment you
+     * asked for.
+     */
+    restoresTo: number;
+}
+/** How far back you still want to be able to restore.
+ * @public
+ */
+interface BackupSafeToDeleteOptions {
+    /**
+     * Epoch milliseconds of the earliest moment a restore must still reach.
+     * Leave it out and the answer covers only the backups no restore could ever
+     * use.
+     */
+    restorableFrom?: number;
+}
+/**
+ * Works out what a restore to a given moment has to read: the newest full copy
+ * finished at or before it, then every change piece captured from that copy up
+ * to it.
+ *
+ * You get back the moment the result will actually reflect, which is when the
+ * last piece was captured. One piece covers every write in the interval it was
+ * taken over, so a restore arrives at a piece boundary, not at the exact
+ * millisecond you named.
+ *
+ * A gap in the chain fails the plan with `BACKUP_CHAIN_BROKEN` and names the
+ * missing piece, because a plan that stopped part-way through would leave a
+ * database nobody could trust.
+ *
+ * @param chains - The chains a destination holds, as {@link readBackupChains} returns them.
+ * @param moment - Epoch milliseconds you want back.
+ * @returns The full copy, the change pieces to apply, and the moment the result reflects.
+ *
+ * @public
+ */
+declare function planBackupRestore(chains: readonly BackupChain[], moment: number): BackupRestorePlan;
+/**
+ * Tells you which backups no restore still needs, so you can delete them
+ * knowing exactly what you give up.
+ *
+ * Two kinds are dead whatever you ask for: a chain whose full copy has gone,
+ * and every change piece after a gap, since nothing can be replayed past the
+ * gap. Name the earliest moment you still want to reach and the answer also
+ * covers the older chains a newer full copy already spans.
+ *
+ * Sirannon lists them and deletes nothing. The destination is yours.
+ *
+ * @param chains - The chains a destination holds, as {@link readBackupChains} returns them.
+ * @param options - How far back you still want to be able to restore.
+ * @returns The records you may delete, oldest first.
+ *
+ * @public
+ */
+declare function backupPiecesSafeToDelete(chains: readonly BackupChain[], options?: BackupSafeToDeleteOptions): BackupChainRecord[];
+
+export { type BackupCapabilities as B, type BackupRestorePlan as a, type BackupSafeToDeleteOptions as b, backupPiecesSafeToDelete as c, planBackupRestore as p };

package/dist/{change-tracker-7wXnBjUN.d.ts → change-tracker-NPJjE1Sh.d.ts}

@@ -1,4 +1,4 @@
-import { e as SQLiteConnection } from './types-B1wQuNXV.js';
+import { t as SQLiteConnection } from './types-CwIiWpVr.js';
 import { C as ChangeEvent } from './query-types-Cv8N7pXj.js';
 
 /**

package/dist/chunk-4H45GMYI.mjs

@@ -0,0 +1,118 @@
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
+
+// src/core/backup/chain-records.ts
+function isWholeNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isAtLeastOne(value) {
+  return isWholeNumber(value) && value >= 1;
+}
+function isTextOrAbsent(value) {
+  return value === void 0 || typeof value === "string";
+}
+function isBackupChainPosition(value) {
+  const position = value;
+  return isWholeNumber(position?.logSequence) && isWholeNumber(position.salt1) && isWholeNumber(position.salt2) && isAtLeastOne(position.firstFrame) && isAtLeastOne(position.lastFrame) && position.lastFrame >= position.firstFrame;
+}
+function isBackupChainHead(value) {
+  const head = value;
+  return typeof head?.chainId === "string" && isWholeNumber(head.startedAt) && isTextOrAbsent(head.previousChainId);
+}
+function isBackupChainBase(value) {
+  const base = value;
+  return base?.kind === "full" && typeof base.chainId === "string" && typeof base.name === "string" && typeof base.runId === "string" && isWholeNumber(base.finishedAt) && isWholeNumber(base.pieceCount) && isAtLeastOne(base.pieceBytes) && isWholeNumber(base.bytesWritten) && isTextOrAbsent(base.fingerprint);
+}
+function isBackupChainChange(value) {
+  const change = value;
+  return change?.kind === "change" && typeof change.chainId === "string" && typeof change.name === "string" && typeof change.runId === "string" && isAtLeastOne(change.sequence) && isBackupChainPosition(change.position) && isWholeNumber(change.capturedAt) && isAtLeastOne(change.frameCount) && isWholeNumber(change.pieceCount) && isAtLeastOne(change.pieceBytes) && isWholeNumber(change.bytesWritten) && typeof change.checkpointed === "boolean" && isTextOrAbsent(change.fingerprint);
+}
+
+// src/core/backup/chain.ts
+var DEFAULT_CHAIN_NAME = "sirannon-backup-chain";
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function destinationError(message, err) {
+  if (err instanceof SirannonError) return err;
+  const detail = err instanceof Error ? `: ${err.message}` : "";
+  return new SirannonError(`${message}${detail}`, "BACKUP_DESTINATION_ERROR");
+}
+function chainLogName(chainName, chainId) {
+  return `${chainName}.${chainId}`;
+}
+async function appendRecord(destination, name, index, record) {
+  try {
+    await destination.writePiece(name, index, encoder.encode(JSON.stringify(record)));
+  } catch (err) {
+    throw destinationError(`The destination refused record ${index} of '${name}'`, err);
+  }
+}
+async function readRecords(destination, name) {
+  let listed;
+  try {
+    listed = await destination.listPieces(name);
+  } catch (err) {
+    throw destinationError(`The destination could not list the records of '${name}'`, err);
+  }
+  const ordered = [...listed].sort((left, right) => left.index - right.index);
+  const records = [];
+  for (const piece of ordered) {
+    let bytes;
+    try {
+      bytes = await destination.readPiece(name, piece.index);
+    } catch (err) {
+      throw destinationError(`The destination could not return record ${piece.index} of '${name}'`, err);
+    }
+    try {
+      records.push(JSON.parse(decoder.decode(bytes)));
+    } catch (err) {
+      throw destinationError(`Record ${piece.index} of '${name}' is not a record Sirannon wrote`, err);
+    }
+  }
+  return records;
+}
+function chainRecords(records, name) {
+  const kept = [];
+  for (const record of records) {
+    const kind = record?.kind;
+    if (kind !== "full" && kind !== "change") continue;
+    if (kind === "full" ? isBackupChainBase(record) : isBackupChainChange(record)) {
+      kept.push(record);
+      continue;
+    }
+    const label = kind === "full" ? "full copy" : "change piece";
+    throw destinationError(
+      `A ${label} record of '${name}' is missing fields Sirannon writes into every record it stores, so no restore can use this chain until you put that record back`
+    );
+  }
+  return kept;
+}
+async function appendChainHead(destination, chainName, head, index) {
+  await appendRecord(destination, chainName, index, head);
+}
+async function appendChainRecord(destination, chainName, record, index) {
+  await appendRecord(destination, chainLogName(chainName, record.chainId), index, record);
+}
+async function readChainHeads(destination, chainName) {
+  const records = await readRecords(destination, chainName);
+  return records.filter(isBackupChainHead).reverse();
+}
+async function readBackupChains(destination, chainName = DEFAULT_CHAIN_NAME) {
+  const heads = await readChainHeads(destination, chainName);
+  const chains = [];
+  for (const head of heads) {
+    const logName = chainLogName(chainName, head.chainId);
+    const records = chainRecords(await readRecords(destination, logName), logName);
+    const changes = records.filter((record) => record.kind === "change").sort((left, right) => left.sequence - right.sequence);
+    const base = records.find((record) => record.kind === "full");
+    chains.push({
+      chainId: head.chainId,
+      startedAt: head.startedAt,
+      ...head.previousChainId ? { previousChainId: head.previousChainId } : {},
+      ...base ? { base } : {},
+      changes
+    });
+  }
+  return chains;
+}
+
+export { DEFAULT_CHAIN_NAME, appendChainHead, appendChainRecord, chainLogName, isBackupChainPosition, readBackupChains, readChainHeads };