@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/{chunk-W4EUTJNT.mjs → chunk-NZGSDALX.mjs}

@@ -1,14 +1,14 @@
-import { verifyBackupRecord } from './chunk-7SC2TZAS.mjs';
-import { BackupManager, BackupScheduler, DEFAULT_PIECE_BYTES, sendFileInPieces } from './chunk-JQWGHSEH.mjs';
-import { DEFAULT_BACKUP_NAME_PREFIX, defaultStagingDir, DEFAULT_CAPTURE_INTERVAL_MS, DEFAULT_FULL_COPY_INTERVAL_MS } from './chunk-LXCGPZPA.mjs';
+import { verifyBackupRecord } from './chunk-DX4WGJL7.mjs';
+import { BackupManager, BackupScheduler, DEFAULT_PIECE_BYTES, sendFileInPieces } from './chunk-NVSQ2T5Q.mjs';
+import { DEFAULT_BACKUP_NAME_PREFIX, defaultStagingDir, DEFAULT_CAPTURE_INTERVAL_MS, DEFAULT_FULL_COPY_INTERVAL_MS } from './chunk-IEKIYO4V.mjs';
 import { WORKER_CANCELLED_CODE, WORKER_COPY_STOPPED_CODE, deserializeError } from './chunk-MVSES6MS.mjs';
-import { readCycleState, writeCycleState, removeCycleState, stagedCapturePath, captureAndCheckpointTurn } from './chunk-KDAHYFW7.mjs';
-import { checkpointLog } from './chunk-U445A3C4.mjs';
-import { logPathFor } from './chunk-E6IMX7RS.mjs';
-import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, reportQuietly } from './chunk-GYCEJNU4.mjs';
-import { DEFAULT_CHAIN_NAME, readBackupChains, appendChainRecord, appendChainHead, readChainHeadAt, readChainHeads } from './chunk-YVF2ZJTE.mjs';
+import { readCycleState, writeCycleState, removeCycleState, stagedCapturePath, captureAndCheckpointTurn } from './chunk-6AOJCNRU.mjs';
+import { checkpointLog } from './chunk-QGVRRKB2.mjs';
+import { logPathFor } from './chunk-KJLNYOOL.mjs';
+import { destinationWithDeadline, DEFAULT_DESTINATION_TIMEOUT_MS, reportQuietly } from './chunk-R7GBXNTO.mjs';
+import { DEFAULT_CHAIN_NAME, readBackupChains, appendChainRecord, appendChainHead, readChainHeadAt, readChainHeads } from './chunk-CZL4D3BM.mjs';
 import { randomHex } from './chunk-QBBLSQHQ.mjs';
-import { SirannonError, ExtensionError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError, ExtensionError } from './chunk-KINDFBQP.mjs';
 import { Worker } from 'worker_threads';
 import { existsSync } from 'fs';
 import { resolve, dirname, join, sep } from 'path';
@@ -562,7 +562,7 @@ var BackupCycleStatusRecorder = class {
   latestRun;
   latestSkip;
   latestError;
-  /** Marks a turn as under way and clears the progress the previous turn recorded. */
+  /** Marks a turn as in progress and clears the progress that the previous turn recorded. */
   turnStarted() {
     this.turnRunning = true;
     this.turnStartedAt = Date.now();
@@ -574,24 +574,24 @@ var BackupCycleStatusRecorder = class {
     this.turnStartedAt = 0;
     this.latestProgress = void 0;
   }
-  /** Records how far the turn under way has got. */
+  /** Records the progress of the current turn. */
   progressed(progress) {
     this.latestProgress = progress;
   }
-  /** Records what a finished turn wrote. */
+  /** Records the report of a finished backup. */
   ran(report) {
     this.latestRun = report;
   }
-  /** Records a turn the cycle passed over. */
+  /** Records a skipped turn. */
   skipped(skip) {
     this.latestSkip = skip;
   }
   /**
-   * Records a failure, under the code a caller matches on, along with how far
-   * the run had got and which chain it was extending.
+   * Records a failure with its error code, the progress of the current backup,
+   * and the chain that the cycle extends.
    *
-   * @param err - What the turn failed with.
-   * @param chainId - The chain the cycle was extending, where it held one.
+   * @param err - The error that stops the turn.
+   * @param chainId - The chain that the cycle extends, where it holds one.
    */
   failed(err, chainId) {
     const at = Date.now();
@@ -605,10 +605,10 @@ var BackupCycleStatusRecorder = class {
     };
   }
   /**
-   * Reads everything recorded so far.
+   * Returns everything recorded so far.
    *
-   * @param chainId - The chain the cycle is extending, where it has one.
-   * @returns What the cycle is doing, and what its recent turns produced.
+   * @param chainId - The chain that the cycle extends, where it holds one.
+   * @returns What the cycle is doing now, and the outcome of its recent turns.
    */
   read(chainId) {
     return {
@@ -631,24 +631,24 @@ var BackupTurnLog = class {
   record = new BackupCycleStatusRecorder();
   announced = /* @__PURE__ */ new Set();
   /**
-   * Records a finished run and passes it to the caller.
+   * Records a finished backup and passes its report to the caller.
    *
-   * @param report - What that run produced.
+   * @param report - The report of the backup.
    */
   ran(report) {
     this.record.ran(report);
     reportQuietly(this.audience.onRun, report);
   }
   /**
-   * Records how far the run under way has reached and passes that to the caller.
+   * Records the progress of the current backup and passes it to the caller.
    *
-   * @param progress - The counters that run has reached.
+   * @param progress - The current counters of that backup.
    */
   progressed(progress) {
     this.record.progressed(progress);
     reportQuietly(this.audience.onProgress, progress);
   }
-  /** Marks a turn as under way, and forgets whatever failures the previous turn announced. */
+  /** Marks a turn as in progress, and clears the failures that the previous turn reported. */
   turnStarted() {
     this.announced.clear();
     this.record.turnStarted();
@@ -658,10 +658,10 @@ var BackupTurnLog = class {
     this.record.turnFinished();
   }
   /**
-   * Records a failure as the turn's outcome and passes it to the caller.
+   * Records a failure as the outcome of the turn and passes it to the caller.
    *
-   * @param err - What the turn failed with.
-   * @param chainId - The chain to record it against, where the cycle holds one.
+   * @param err - The error that stops the turn.
+   * @param chainId - The chain to record the failure against, where the cycle holds one.
    */
   failed(err, chainId) {
     this.announced.add(err);
@@ -670,19 +670,19 @@ var BackupTurnLog = class {
     reportQuietly(this.audience.onError, failure);
   }
   /**
-   * Answers whether this turn has already passed one failure to the caller.
+   * Returns whether this turn has already reported a given failure to the caller.
    *
    * @param err - The failure to look for.
-   * @returns Whether the caller has already heard about that failure.
+   * @returns Whether this turn has already reported that failure.
    */
   hasAnnounced(err) {
     return this.announced.has(err);
   }
   /**
-   * Records a turn the cycle passed over and passes it to the caller, stating
-   * how much log this node was still holding as it skipped.
+   * Records a skipped turn and passes it to the caller, with the size of the
+   * write-ahead log on this node at the skip.
    *
-   * @param skip - Why the cycle passed the turn over.
+   * @param skip - The reason that the cycle skips the turn.
    */
   async skipped(skip) {
     const held = await uncapturedLogBytes(this.logPath);
@@ -691,10 +691,10 @@ var BackupTurnLog = class {
     reportQuietly(this.audience.onSkip, passed);
   }
   /**
-   * Reads everything recorded so far.
+   * Returns everything recorded so far.
    *
-   * @param chainId - The chain the cycle is extending, where it has one.
-   * @returns What the cycle is doing, and what its recent turns produced.
+   * @param chainId - The chain that the cycle extends, where it holds one.
+   * @returns What the cycle is doing now, and the outcome of its recent turns.
    */
   read(chainId) {
     return this.record.read(chainId);
@@ -705,10 +705,10 @@ var BackupTurnLog = class {
 var BackupCycleTimer = class {
   handle = null;
   /**
-   * Starts repeating. At an interval of zero or less the cycle takes a turn
-   * only when somebody asks it to.
+   * Starts the timer. At an interval of zero or less, the timer stays off and
+   * the cycle takes a turn only when a caller requests one.
    *
-   * @param intervalMs - Milliseconds between one turn and the next.
+   * @param intervalMs - The number of milliseconds between one turn and the next.
    * @param tick - Called on every interval.
    */
   arm(intervalMs, tick) {
@@ -717,7 +717,7 @@ var BackupCycleTimer = class {
     this.handle = setInterval(tick, intervalMs);
     this.handle.unref?.();
   }
-  /** Stops repeating. */
+  /** Stops the timer. */
   disarm() {
     if (!this.handle) return;
     clearInterval(this.handle);
@@ -727,10 +727,10 @@ var BackupCycleTimer = class {
 var SerialTurns = class {
   inFlight = Promise.resolve();
   /**
-   * Starts an operation once every turn asked for before it has settled.
+   * Starts an operation once every turn requested before it settles.
    *
    * @param op - The turn to take.
-   * @returns Whatever that turn produced.
+   * @returns The result of that turn.
    */
   run(op) {
     const turn = this.inFlight.then(op, op);
@@ -948,10 +948,10 @@ var BackupCycle = class {
     this.preferredNode = request.preferredNode ?? "replica";
   }
   /**
-   * Picks a chain up where the previous run left it, or starts a new one with a
-   * full copy, and then repeats on the interval. A chain picked up takes an
-   * ordinary turn, so the frames written while this node was down reach the
-   * destination rather than waiting for the first interval.
+   * Resumes the chain that the state file records, or starts a new chain with a
+   * full copy, and then repeats the turn on the interval. On a resumed chain,
+   * Sirannon takes an ordinary turn straight away, so it sends the frames written
+   * while this node was down to the destination before the first interval ends.
    */
   async start() {
     await mkdir(this.stagingDir, { recursive: true });
@@ -970,19 +970,19 @@ var BackupCycle = class {
     if (!this.stopped) this.timer.arm(this.intervalMs, () => void this.tick());
   }
   /**
-   * Takes one turn now. A turn sends any capture still waiting, reads the
+   * Takes one turn now. In a turn, Sirannon sends any staged capture, reads the
    * frames written since the previous turn, and then checkpoints the log.
    *
-   * One turn waits at a time. A call made while a turn is under way queues one
-   * behind it, and every call after that joins the queued turn, which reads the
-   * log once it begins and so covers their writes as well. Without that bound,
-   * a caller asking repeatedly during a long full copy would build a queue of
-   * turns with nothing left for any of them to capture.
+   * At most one turn waits in the queue. A call during a turn in progress
+   * queues one turn after it, and every later call returns that queued turn,
+   * which reads the log when it begins and so captures the writes of every one
+   * of those callers. Without that limit, repeated calls during a long full
+   * copy would build a queue of turns with nothing left to capture.
    *
-   * A turn on a node whose group backs up from somewhere else writes nothing
-   * and reports a skip.
+   * On a node whose replication group takes its backups from another node, a
+   * turn writes nothing and reports a skip.
    *
-   * @returns What the turn wrote, or undefined where it wrote nothing.
+   * @returns The report of what the turn writes, or undefined where it writes nothing.
    */
   runOnce() {
     const queued = this.queued;
@@ -996,9 +996,8 @@ var BackupCycle = class {
     return turn;
   }
   /**
-   * Stops the cycle. It captures the log one final time first, so the writes
-   * made since the previous turn reach the destination before the database
-   * closes behind it.
+   * Stops the cycle after one final turn, so that Sirannon sends the writes
+   * made since the previous turn to the destination before the database closes.
    */
   async stop() {
     if (this.stopped) return;
@@ -1017,7 +1016,7 @@ var BackupCycle = class {
     });
   }
   /**
-   * Lists what the destination holds.
+   * Returns every chain at the destination.
    *
    * @returns Every chain, newest first, each with its full copy and its change pieces.
    */
@@ -1025,34 +1024,33 @@ var BackupCycle = class {
     return readBackupChains(this.request.destination, this.chainName);
   }
   /**
-   * Reads what the cycle is doing at this moment, and what its recent turns
-   * produced.
+   * Returns what the cycle is doing now and the outcome of its recent turns.
    *
-   * A caller following a long full copy reads this without having to wait on
-   * the turn, and it answers between turns as well.
+   * It returns straight away, both during a long full copy and between turns.
    *
-   * @returns Whether a turn is under way, how far it has got, and the last run, skip, and failure.
+   * @returns Whether a turn is in progress, the progress of that turn, and the last run, skip, and failure.
    */
   status() {
     return this.turnLog.read(this.state?.chainId);
   }
   /**
-   * Reads one of this chain's backups back out of the destination and compares
-   * it against the record the backup that wrote it left behind.
+   * Reads one backup from the destination and checks it against its record in
+   * the chains at that destination.
    *
-   * @param name - Name the backup is stored under.
-   * @returns The pieces read, the bytes they add up to, and the digest where the backup recorded one.
+   * @param name - The name that Sirannon stores the backup under.
+   * @returns The number of pieces read, their total size in bytes, and the fingerprint where the record holds one.
    */
   async verify(name) {
     return verifyBackupRecord(this.request.destination, await this.chains(), name);
   }
   /**
-   * Runs one turn and passes whatever broke it to the operator. A deeper step
-   * announces some failures itself and then raises them, so this announces a
-   * failure only where no step has announced it already. The operator therefore
-   * hears each failure exactly once. Sirannon empties a log the turn has
-   * outgrown once all of that is done, and the report of writes reaching no
-   * backup replaces whatever failure the turn recorded.
+   * Runs one turn and reports to the operator any error that stops it. Some
+   * deeper steps report a failure themselves before they throw it, so this
+   * reports an error only where no step has reported it already, and the
+   * operator receives each failure once. When the turn captures nothing and the
+   * log has grown past the limit, Sirannon then empties the log, and the
+   * resulting report of the writes that no backup holds replaces any failure
+   * that the turn recorded.
    */
   runTurn(op) {
     return this.turns.run(async () => {
@@ -1072,7 +1070,7 @@ var BackupCycle = class {
       }
     });
   }
-  /** What the stand-down path needs of this cycle to let go of its chain. */
+  /** The callbacks and paths that the stand-down code uses to release the chain of this cycle. */
   get standDownRequest() {
     return {
       request: this.request,
@@ -1087,7 +1085,7 @@ var BackupCycle = class {
       report: (err) => this.report(err)
     };
   }
-  /** Empties a log this turn captured nothing from, past the operator's limit. */
+  /** Empties the log when this turn captures nothing from it and it has grown past the limit that the operator sets. */
   async releaseLogPastLimit() {
     if (this.stopped) return;
     try {
@@ -1097,10 +1095,11 @@ var BackupCycle = class {
     }
   }
   /**
-   * Asks whether this node takes the turn it is starting. A node the group
-   * backs up from somewhere else stands down from its chain and empties its
-   * log instead. A node that could not read its group holds everything where
-   * it is, because the frames it has yet to capture are still in no backup.
+   * Returns whether this node takes the turn that it is starting. Where the
+   * replication group takes its backups from another node, this node stands
+   * down from its chain and empties its log. Where Sirannon cannot read the
+   * group, this node keeps its chain and its log as they are, because no backup
+   * holds the frames that it has yet to capture.
    */
   async takesTheTurn() {
     const decision = await decideBackupTurn(this.request.replicationGroup, this.preferredNode);
@@ -1115,7 +1114,7 @@ var BackupCycle = class {
     }
     return false;
   }
-  /** Passes a skipped turn on, where the cycle has a reason to give for it. */
+  /** Reports a skipped turn when the decision carries a reason for it. */
   async reportSkip(skip) {
     if (skip) await this.turnLog.skipped(skip);
   }
@@ -1144,13 +1143,12 @@ var BackupCycle = class {
     this.state = null;
   }
   /**
-   * Runs one turn. A log that restarted before the capture reached it leaves a
-   * chain nothing can extend, so this starts a fresh one. The caller still gets
-   * the error: those writes are in no backup, and an operator has to hear that.
-   * Where the replacement chain also fails to start, Sirannon records that
-   * second failure against the chain the restart broke, because the cycle holds
-   * no chain of its own by then and an operator reading the status has to know
-   * which one they have lost.
+   * Runs one turn. When the turn fails with `BACKUP_LOG_REWOUND` or
+   * `BACKUP_CHAIN_BROKEN`, no later piece can extend the chain, so this starts a
+   * new chain. The caller still receives the error, because no backup holds the
+   * lost writes. Where the new chain also fails to start, Sirannon records that
+   * second failure against the broken chain, because the cycle holds no chain by
+   * then and the operator needs the status to name the chain that they lost.
    */
   async turnOrStartOver() {
     try {
@@ -1178,15 +1176,15 @@ var BackupCycle = class {
     return last;
   }
   /**
-   * Passes a failure to the operator and records it as the turn's outcome.
+   * Reports a failure to the operator and records it as the outcome of the
+   * turn, against the chain that the cycle holds now.
    *
-   * @param err - What the turn failed with.
-   * @param chainId - The chain to record it against, which defaults to the one the cycle holds now.
+   * @param err - The error that stops the turn.
    */
   report(err) {
     this.turnLog.failed(err, this.state?.chainId);
   }
-  /** Records a failure against a chain the cycle may already have let go of. */
+  /** Records a failure against a chain that the cycle may already have released. */
   reportAgainstChain(err, chainId) {
     this.turnLog.failed(err, chainId);
   }
@@ -1219,10 +1217,10 @@ var BackupCycle = class {
     this.captured = true;
   }
   /**
-   * Sends the capture staged against the chain this cycle holds. A turn offers
-   * a capture the destination has already refused no second time, because that
-   * second offer waits out the destination deadline again and delays every turn
-   * behind it.
+   * Sends the capture staged against the chain that this cycle holds. Once the
+   * destination refuses a capture, Sirannon skips the send for the rest of the
+   * turn, because a second try would wait out the destination deadline again
+   * and delay every turn queued after it.
    */
   async sendWaitingCapture() {
     if (this.sendRefused) return void 0;

package/dist/{chunk-U445A3C4.mjs → chunk-QGVRRKB2.mjs}

@@ -1,4 +1,4 @@
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
 import { createHash } from 'crypto';
 
 // src/core/backup/checkpoint.ts

package/dist/{chunk-GYCEJNU4.mjs → chunk-R7GBXNTO.mjs}

@@ -1,5 +1,5 @@
 import { invokeCallerCallback } from './chunk-QBBLSQHQ.mjs';
-import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { SirannonError } from './chunk-KINDFBQP.mjs';
 
 // src/core/backup/cycle-callbacks.ts
 function reportQuietly(callback, value) {

package/dist/{chunk-7C36BCSN.mjs → chunk-VDN6FHU4.mjs}

@@ -1,4 +1,4 @@
-import { MigrationError } from './chunk-PBRXXISQ.mjs';
+import { MigrationError } from './chunk-KINDFBQP.mjs';
 
 // src/core/migrations/lazy-down.ts
 var LAZY_DOWN_SQL = /* @__PURE__ */ Symbol("sirannon.file-migration.lazy-down");