@delali/sirannon-db 0.2.3-next.38 → 0.3.0

package/dist/{chunk-IPDHHIG2.mjs → chunk-DXXCLTFF.mjs}

@@ -1,13 +1,38 @@
 import { startCopyWithoutHoldingWriter } from './chunk-W67A4H2E.mjs';
-import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS } from './chunk-GBM4AU24.mjs';
+import { readLogPosition } from './chunk-2QCPVE67.mjs';
+import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, assertDeadline, withinDeadline } from './chunk-DVS4QSIZ.mjs';
 import { randomHex } from './chunk-V5FUJEYY.mjs';
 import { BackupError, SirannonError } from './chunk-PBRXXISQ.mjs';
-import { existsSync, mkdirSync, rmSync, readdirSync, lstatSync } from 'fs';
-import { resolve, dirname, join } from 'path';
+import { existsSync, mkdirSync, statSync, readdirSync, lstatSync, rmSync } from 'fs';
+import { resolve, dirname, join, basename, extname } from 'path';
 import { open, mkdtemp, rm } from 'fs/promises';
 import { tmpdir } from 'os';
 import { createHash } from 'crypto';
 
+// src/core/backup/report.ts
+var DEFAULT_PIECE_BYTES = 16 * 1024 * 1024;
+function defaultDestinationName() {
+  return `backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.db`;
+}
+function assertPieceBytes(pieceBytes) {
+  if (!Number.isInteger(pieceBytes) || pieceBytes <= 0) {
+    throw new SirannonError(
+      `Piece size must be a positive whole number of bytes, and it was ${pieceBytes}`,
+      "BACKUP_ERROR"
+    );
+  }
+}
+async function readPageSize(conn) {
+  const stmt = await conn.prepare("PRAGMA page_size");
+  const row = await stmt.get();
+  return row ? Number(row.page_size) : 0;
+}
+async function readMainDatabasePath(conn) {
+  const stmt = await conn.prepare("PRAGMA database_list");
+  const rows = await stmt.all();
+  const main = rows.find((row) => row.name === "main");
+  return main?.file ?? "";
+}
 function destinationPieceError(name, index, err) {
   if (err instanceof SirannonError) return err;
   return new SirannonError(
@@ -60,25 +85,6 @@ async function sendFileInPieces(sourcePath, destination, name, pieceBytes, finge
   return { pieceCount: index, bytesWritten, ...digest ? { fingerprint: digest.digest("hex") } : {} };
 }
 
-// src/core/backup/report.ts
-var DEFAULT_PIECE_BYTES = 16 * 1024 * 1024;
-function defaultDestinationName() {
-  return `backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.db`;
-}
-function assertPieceBytes(pieceBytes) {
-  if (!Number.isInteger(pieceBytes) || pieceBytes <= 0) {
-    throw new SirannonError(
-      `Piece size must be a positive whole number of bytes, and it was ${pieceBytes}`,
-      "BACKUP_ERROR"
-    );
-  }
-}
-async function readPageSize(conn) {
-  const stmt = await conn.prepare("PRAGMA page_size");
-  const row = await stmt.get();
-  return row ? Number(row.page_size) : 0;
-}
-
 // src/core/backup/stepped-copy.ts
 var DEFAULT_PAGES_PER_STEP = 256;
 var DEFAULT_RESTART_LIMIT = 3;
@@ -182,11 +188,16 @@ async function copyDatabaseStepwise(conn, options) {
   });
   copy.catch(() => {
   });
+  let copyStopped = false;
+  const stops = () => {
+    copyStopped = true;
+  };
+  copy.then(stops, stops);
   try {
     const final = await Promise.race([copy, stalled]);
     return { pageCount: final.totalPages, restarts };
   } catch (err) {
-    options.onCopyLeftRunning?.(copy);
+    if (!copyStopped) options.onCopyLeftRunning?.(copy);
     throw err;
   } finally {
     if (stallTimer) clearTimeout(stallTimer);
@@ -227,6 +238,7 @@ async function copyToDestinationStaged(conn, request) {
       }
     });
     const copyMs = Date.now() - copyStartedAt;
+    const logPosition = await readLogPosition(request.sourcePath);
     const transferStartedAt = Date.now();
     const sent = await sendFileInPieces(
       stagedPath,
@@ -264,6 +276,7 @@ async function copyToDestinationStaged(conn, request) {
       pieceCount: sent.pieceCount,
       pieceBytes,
       restarts: copy.restarts,
+      ...logPosition ? { logPosition } : {},
       ...sent.fingerprint ? { fingerprint: sent.fingerprint } : {}
     };
   } finally {
@@ -609,6 +622,7 @@ async function copyToDestinationStreamed(conn, request, support) {
       }
     });
     const copyMs = Date.now() - copyStartedAt;
+    const logPosition = await readLogPosition(request.sourcePath);
     const bytesStreamed = await host.finish(streamId);
     copying = false;
     await pumping;
@@ -635,6 +649,7 @@ async function copyToDestinationStreamed(conn, request, support) {
       pieceCount: piecesWritten,
       pieceBytes,
       restarts: copy.restarts,
+      ...logPosition ? { logPosition } : {},
       ...fingerprint ? { fingerprint } : {}
     };
   } catch (err) {
@@ -663,6 +678,20 @@ function once(action) {
     action();
   };
 }
+function removeQuietly(path) {
+  try {
+    rmSync(path, { force: true });
+  } catch {
+  }
+}
+function removeOnceCopyStops(copy, path) {
+  const remove = () => removeQuietly(path);
+  copy.then(remove, remove);
+}
+function backupFailure(destPath, err) {
+  if (err instanceof SirannonError) return err;
+  return new BackupError(`Backup to '${destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
+}
 function hasControlCharacters(s) {
   for (let i = 0; i < s.length; i++) {
     const code = s.charCodeAt(i);
@@ -674,6 +703,15 @@ var BackupManager = class {
   constructor(streaming) {
     this.streaming = streaming;
   }
+  /**
+   * Copies the database behind a connection to a file, while that database
+   * stays open for reads and writes.
+   *
+   * @param conn - Connection the copy runs on, which must be the connection that writes.
+   * @param destPath - Path to write the copy to. A file already there stops the copy.
+   * @param onFirstStep - Called once the copy's first step is done, so the caller can hand the writer back.
+   * @returns What the copy moved, how long it took, and how often it restarted.
+   */
   async backup(conn, destPath, onFirstStep) {
     if (hasControlCharacters(destPath)) {
       throw new BackupError("Backup path contains invalid characters");
@@ -696,15 +734,68 @@ var BackupManager = class {
     if (existsSync(resolved)) {
       throw new BackupError(`Backup destination '${destPath}' already exists`);
     }
+    let pageSize;
     try {
-      await copyDatabaseStepwise(conn, { destPath: resolved, onStep: onFirstStep ? once(onFirstStep) : void 0 });
+      pageSize = await readPageSize(conn);
     } catch (err) {
-      try {
-        rmSync(resolved, { force: true });
-      } catch {
-      }
-      if (err instanceof SirannonError) throw err;
-      throw new BackupError(`Backup to '${destPath}' failed: ${err instanceof Error ? err.message : String(err)}`);
+      throw backupFailure(destPath, err);
+    }
+    const startedAt = Date.now();
+    const copy = await this.copyOrClearUp(conn, resolved, destPath, onFirstStep);
+    const finishedAt = Date.now();
+    return {
+      runId: randomHex(8),
+      destPath: resolved,
+      startedAt,
+      finishedAt,
+      durationMs: finishedAt - startedAt,
+      pageCount: copy.pageCount,
+      pageSize,
+      byteLength: this.fileBytes(resolved, destPath),
+      restarts: copy.restarts
+    };
+  }
+  /**
+   * Reads the size of the file a copy wrote.
+   *
+   * @param resolved - Absolute path of that file.
+   * @param destPath - Path the caller named, which the error states.
+   * @returns Bytes it holds.
+   */
+  fileBytes(resolved, destPath) {
+    try {
+      return statSync(resolved).size;
+    } catch (err) {
+      throw backupFailure(destPath, err);
+    }
+  }
+  /**
+   * Runs the copy, and removes the file it was writing where that copy fails, so
+   * that a database missing its later pages never stays on disk as though the
+   * copy had finished. Sirannon would otherwise count that half-written file
+   * among the copies it keeps, and it would evict a whole copy to make room for
+   * one nothing can restore.
+   *
+   * Sirannon stops waiting on a copy once the stall deadline passes, and SQLite
+   * keeps writing that copy to the file. A removal that raced a live copy would
+   * leave a truncated file in place, and on Windows it would fail outright.
+   * Sirannon therefore removes the file only once the copy stops, while the
+   * caller receives the failure at once and waits for none of that.
+   */
+  async copyOrClearUp(conn, resolved, destPath, onFirstStep) {
+    const abandoned = { copy: null };
+    try {
+      return await copyDatabaseStepwise(conn, {
+        destPath: resolved,
+        onStep: onFirstStep ? once(onFirstStep) : void 0,
+        onCopyLeftRunning: (copy) => {
+          abandoned.copy = copy;
+        }
+      });
+    } catch (err) {
+      if (abandoned.copy) removeOnceCopyStops(abandoned.copy, resolved);
+      else removeQuietly(resolved);
+      throw backupFailure(destPath, err);
     }
   }
   async copyToDestination(conn, request) {
@@ -1004,6 +1095,7 @@ var DEFAULT_MAX_FILES = 5;
 var MINUTE_RESOLUTION_MS = 6e4;
 var SECOND_RESOLUTION_MS = 1e3;
 var DST_LOOKBACK_MS = 3 * 60 * 60 * 1e3;
+var DEFAULT_ON_BACKUP_TIMEOUT_MS = 6e5;
 function toError(value) {
   if (value instanceof Error) {
     return value;
@@ -1063,12 +1155,11 @@ var BackupScheduler = class {
    * Starts repeating backups and returns a function that stops them.
    *
    * @param conn - Connection to the database being copied.
-   * @param options - Cron expression, destination directory, retention, time zone, and failure callback.
-   * @param runExclusive - Runs each copy with the database's writer held so that no write commits mid-copy.
+   * @param request - Cron expression, destination directory, retention, and time zone, along with the callbacks and the database the copies come from.
    * @returns A function that stops the schedule.
    */
-  schedule(conn, options, runExclusive = runDirect) {
-    const { cron: cronExpr, destDir, maxFiles = DEFAULT_MAX_FILES, onError, timezone } = options;
+  schedule(conn, request) {
+    const { cron: cronExpr, destDir, maxFiles = DEFAULT_MAX_FILES, timezone } = request;
     let cron;
     try {
       cron = parseCron(cronExpr);
@@ -1084,6 +1175,8 @@ var BackupScheduler = class {
         throw new BackupError(`Invalid timezone '${timezone}': ${err instanceof Error ? err.message : String(err)}`);
       }
     }
+    const onBackupTimeoutMs = request.onBackupTimeoutMs ?? DEFAULT_ON_BACKUP_TIMEOUT_MS;
+    assertDeadline(onBackupTimeoutMs, "onBackupTimeoutMs");
     const resolvedDir = resolve(destDir);
     if (!existsSync(resolvedDir)) {
       try {
@@ -1094,32 +1187,99 @@ var BackupScheduler = class {
         );
       }
     }
-    return this.run(conn, cron, resolvedDir, maxFiles, timezone, runExclusive, onError);
+    return this.run(conn, { ...request, cron, resolvedDir, maxFiles, timezone, onBackupTimeoutMs });
+  }
+  /**
+   * Works out the database and the file every report names. A caller may supply
+   * either of them, and Sirannon reads the file SQLite has open where the caller
+   * named none. Sirannon puts that question to the connection that writes, so it
+   * asks with nothing else holding the writer.
+   *
+   * @param conn - Connection the copies come from.
+   * @param run - The schedule, which holds whichever of the two the caller named.
+   * @param runExclusive - Runs the question with nothing else holding the writer.
+   * @returns The database identifier and the path of the file the copies come from.
+   * @throws A `BACKUP_ERROR` where the caller named no source file and SQLite has none open.
+   */
+  async namesFor(conn, run, runExclusive) {
+    if (run.databaseId !== void 0 && run.sourcePath !== void 0) {
+      return { databaseId: run.databaseId, sourcePath: run.sourcePath };
+    }
+    let sourcePath = run.sourcePath ?? "";
+    if (sourcePath === "") {
+      await runExclusive(async () => {
+        sourcePath = await readMainDatabasePath(conn);
+      });
+    }
+    if (sourcePath === "") {
+      throw new BackupError(
+        "This schedule names no source file, and SQLite reports no file open on the connection it copies, so no report could name one. Give the schedule a sourcePath."
+      );
+    }
+    return { databaseId: run.databaseId ?? basename(sourcePath, extname(sourcePath)), sourcePath };
+  }
+  /**
+   * Passes one finished copy to the caller's completion callback, and stops
+   * waiting on that callback once its deadline passes.
+   *
+   * @param report - What the copy produced.
+   * @param run - The schedule, which holds the callback and its deadline.
+   */
+  async handToCaller(report, run) {
+    const { onBackup, onBackupTimeoutMs } = run;
+    if (!onBackup) return;
+    const handed = Promise.resolve(onBackup(report));
+    if (onBackupTimeoutMs === 0) {
+      await handed;
+      return;
+    }
+    await withinDeadline(
+      handed,
+      onBackupTimeoutMs,
+      () => new SirannonError(
+        `The onBackup callback for database '${report.databaseId}' did not return within ${onBackupTimeoutMs}ms, so the schedule went on without it. The copy at '${report.destPath}' is on disk and whatever that callback was doing with it has not finished.`,
+        "BACKUP_ERROR"
+      )
+    );
   }
-  run(conn, cron, resolvedDir, maxFiles, timezone, runExclusive, onError) {
+  run(conn, run) {
+    const { cron, resolvedDir, maxFiles, timezone, onError } = run;
+    const runExclusive = run.runExclusive ?? runDirect;
     const tickMs = cron.hasSeconds ? SECOND_RESOLUTION_MS : MINUTE_RESOLUTION_MS;
     let timer = null;
     let stopped = false;
     let running = false;
     let tickState = INITIAL_TICK_STATE;
+    const announce = (err) => {
+      if (!onError) return;
+      try {
+        onError(toError(err));
+      } catch {
+      }
+    };
+    let source = null;
     const runBackup = async () => {
+      let copy = null;
       try {
+        const names = source ?? await this.namesFor(conn, run, runExclusive);
+        source = names;
         const destPath = join(resolvedDir, this.manager.generateFilename());
-        await startCopyWithoutHoldingWriter(
+        copy = await startCopyWithoutHoldingWriter(
           runExclusive,
           (onFirstStep) => this.manager.backup(conn, destPath, onFirstStep)
         );
-        this.manager.rotate(resolvedDir, maxFiles);
+        await this.handToCaller({ ...copy, ...names }, run);
       } catch (err) {
-        if (onError) {
-          try {
-            onError(toError(err));
-          } catch {
-          }
+        announce(err);
+      }
+      if (copy) {
+        try {
+          this.manager.rotate(resolvedDir, maxFiles);
+        } catch (err) {
+          announce(err);
         }
-      } finally {
-        running = false;
       }
+      running = false;
     };
     const scheduleNext = () => {
       if (stopped) {