@delali/sirannon-db 0.2.3-next.37 → 0.2.3-next.39

package/dist/chunk-U445A3C4.mjs

@@ -0,0 +1,88 @@
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { createHash } from 'crypto';
+
+// src/core/backup/checkpoint.ts
+var CHECKPOINT_ATTEMPTS = 3;
+var CHECKPOINT_RETRY_DELAY_MS = 50;
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function checkpointLog(conn) {
+  let last = { busy: true, framesInLog: 0, framesCheckpointed: 0, emptied: false };
+  for (let attempt = 0; attempt < CHECKPOINT_ATTEMPTS; attempt++) {
+    if (attempt > 0) await delay(attempt * CHECKPOINT_RETRY_DELAY_MS);
+    const stmt = await conn.prepare("PRAGMA wal_checkpoint(TRUNCATE)");
+    const row = await stmt.get();
+    if (!row) return last;
+    const busy = Number(row.busy) !== 0;
+    const framesInLog = Number(row.log);
+    last = {
+      busy,
+      framesInLog,
+      framesCheckpointed: Number(row.checkpointed),
+      emptied: !busy && framesInLog === 0
+    };
+    if (last.emptied) return last;
+  }
+  return last;
+}
+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 assertNoPieceIsMissing(pieces, file) {
+  if (pieces.length === 0) {
+    throw destinationError(`The destination holds no pieces named '${file.name}'`);
+  }
+  for (let expected = 0; expected < file.pieceCount; expected++) {
+    if (pieces[expected]?.index !== expected) {
+      throw destinationError(
+        `The destination is missing piece ${expected} of '${file.name}', so the file cannot be assembled`
+      );
+    }
+  }
+  if (pieces.length > file.pieceCount) {
+    throw destinationError(
+      `The destination holds ${pieces.length} pieces of '${file.name}' where the run wrote ${file.pieceCount}, so a later piece belongs to a different run`
+    );
+  }
+}
+async function listStoredFilePieces(destination, file) {
+  let listed;
+  try {
+    listed = [...await destination.listPieces(file.name)];
+  } catch (err) {
+    throw destinationError(`The destination could not list the pieces of '${file.name}'`, err);
+  }
+  listed.sort((left, right) => left.index - right.index);
+  assertNoPieceIsMissing(listed, file);
+  return listed;
+}
+async function fetchStoredFile(destination, file, pieces, take) {
+  const digest = file.fingerprint === void 0 ? null : createHash("sha256");
+  let bytesFetched = 0;
+  for (const piece of pieces) {
+    let bytes;
+    try {
+      bytes = await destination.readPiece(file.name, piece.index);
+    } catch (err) {
+      throw destinationError(`The destination could not return piece ${piece.index} of '${file.name}'`, err);
+    }
+    digest?.update(bytes);
+    bytesFetched += bytes.byteLength;
+    await take(piece.index, bytes);
+  }
+  const fingerprint = digest?.digest("hex");
+  if (bytesFetched !== file.bytesWritten) {
+    throw destinationError(
+      `The pieces of '${file.name}' hold ${bytesFetched} bytes where the run wrote ${file.bytesWritten}`
+    );
+  }
+  if (fingerprint !== void 0 && fingerprint !== file.fingerprint) {
+    throw destinationError(`The pieces of '${file.name}' do not match the fingerprint the run recorded`);
+  }
+  return { bytesFetched, pieceCount: pieces.length, ...fingerprint === void 0 ? {} : { fingerprint } };
+}
+
+export { checkpointLog, fetchStoredFile, listStoredFilePieces };

package/dist/chunk-W77EEVOT.mjs

@@ -0,0 +1,156 @@
+import { checkpointLog } from './chunk-U445A3C4.mjs';
+import { readLogFileHeader, sameLog, cursorChecksum, scanLogFrames, copyLogRange } from './chunk-2QCPVE67.mjs';
+import { logFrameOffset } from './chunk-DVS4QSIZ.mjs';
+import { isBackupChainPosition } from './chunk-YVF2ZJTE.mjs';
+import { randomHex } from './chunk-V5FUJEYY.mjs';
+import { SirannonError } from './chunk-PBRXXISQ.mjs';
+import { readFile, mkdir, writeFile, rename, rm, readdir } from 'fs/promises';
+import { dirname, join } from 'path';
+
+var STATE_FILE_NAME = "cycle.json";
+function isWholeNumber(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isCursor(value) {
+  const cursor = value;
+  return isWholeNumber(cursor?.logSequence) && isWholeNumber(cursor.salt1) && isWholeNumber(cursor.salt2) && isWholeNumber(cursor.lastFrame) && isWholeNumber(cursor.checksum1) && isWholeNumber(cursor.checksum2) && typeof cursor.checkpointed === "boolean";
+}
+function isPendingCapture(value) {
+  const pending = value;
+  return typeof pending?.name === "string" && typeof pending.runId === "string" && isWholeNumber(pending.sequence) && pending.sequence >= 1 && isBackupChainPosition(pending.position) && isCursor(pending.cursor) && isWholeNumber(pending.startedAt) && isWholeNumber(pending.capturedAt) && isWholeNumber(pending.copyMs) && isWholeNumber(pending.frameCount) && isWholeNumber(pending.byteLength) && isWholeNumber(pending.pageSize);
+}
+function isCycleState(value) {
+  const state = value;
+  return typeof state?.chainName === "string" && typeof state.chainId === "string" && isWholeNumber(state.chainStartedAt) && (state.headIndex === void 0 || isWholeNumber(state.headIndex)) && isWholeNumber(state.records) && (state.cursor === null || isCursor(state.cursor)) && (state.pending === null || isPendingCapture(state.pending)) && typeof state.closedCleanly === "boolean";
+}
+function cycleStatePath(stagingDir) {
+  return join(stagingDir, STATE_FILE_NAME);
+}
+async function readCycleState(stagingDir) {
+  try {
+    const text = await readFile(cycleStatePath(stagingDir), "utf8");
+    const state = JSON.parse(text);
+    return isCycleState(state) ? state : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function writeCycleState(stagingDir, state) {
+  const path = cycleStatePath(stagingDir);
+  await mkdir(dirname(path), { recursive: true });
+  const staged = `${path}.writing`;
+  await writeFile(staged, JSON.stringify(state), "utf8");
+  await rename(staged, path);
+}
+async function removeCycleState(stagingDir) {
+  await rm(cycleStatePath(stagingDir), { force: true });
+}
+
+// src/core/backup/cycle-capture.ts
+var STAGED_CAPTURE_PREFIX = "capture-";
+var STAGED_CAPTURE_SUFFIX = ".wal";
+function stagedCapturePath(stagingDir, sequence) {
+  return join(stagingDir, `${STAGED_CAPTURE_PREFIX}${sequence}${STAGED_CAPTURE_SUFFIX}`);
+}
+function rewoundError(request, detail) {
+  return new SirannonError(
+    `The write-ahead log of '${request.sourcePath}' ${detail}, so the frames written before it did are in no backup. Another connection checkpointed the log, or the database file was replaced. Route every write and every checkpoint through Sirannon, and take a fresh full copy so a new chain starts from a known state.`,
+    "BACKUP_LOG_REWOUND"
+  );
+}
+async function captureLogFrames(request) {
+  const startedAt = Date.now();
+  const cursor = request.cursor;
+  const header = await readLogFileHeader(request.logPath);
+  const holdsEveryCapturedFrame = cursor !== null && header !== void 0 && sameLog(header, cursor);
+  const newLogAllowed = cursor === null || cursor.checkpointed || request.expectNewLog;
+  if (!holdsEveryCapturedFrame && !newLogAllowed && cursor) {
+    throw rewoundError(
+      request,
+      header ? `restarted at checkpoint sequence ${header.logSequence} while the chain reaches frame ${cursor.lastFrame} of sequence ${cursor.logSequence}` : `holds no frames while the chain reaches frame ${cursor.lastFrame} of sequence ${cursor.logSequence}`
+    );
+  }
+  if (!header) return void 0;
+  const from = cursor && holdsEveryCapturedFrame ? { frame: cursor.lastFrame, checksum: cursorChecksum(cursor) } : { frame: 0, checksum: header.checksum };
+  const scan = await scanLogFrames(request.logPath, header, from);
+  if (scan.lastCommitFrame <= from.frame) {
+    if (from.frame > 0 && scan.lastCommitFrame < from.frame) {
+      throw rewoundError(
+        request,
+        `now ends at frame ${scan.lastCommitFrame} while the chain reaches frame ${from.frame}`
+      );
+    }
+    return void 0;
+  }
+  const firstFrame = from.frame + 1;
+  const startOffset = firstFrame === 1 ? 0 : logFrameOffset(firstFrame, header.frameBytes);
+  const byteLength = await copyLogRange(
+    request.logPath,
+    startOffset,
+    scan.endOffset,
+    stagedCapturePath(request.stagingDir, request.sequence)
+  );
+  const capturedAt = Date.now();
+  return {
+    name: `${request.namePrefix}-${request.chainId}-${String(request.sequence).padStart(6, "0")}.wal`,
+    runId: randomHex(8),
+    sequence: request.sequence,
+    position: {
+      logSequence: header.logSequence,
+      salt1: header.salt1,
+      salt2: header.salt2,
+      firstFrame,
+      lastFrame: scan.lastCommitFrame
+    },
+    cursor: {
+      logSequence: header.logSequence,
+      salt1: header.salt1,
+      salt2: header.salt2,
+      lastFrame: scan.lastCommitFrame,
+      checksum1: scan.checksum.first,
+      checksum2: scan.checksum.second,
+      checkpointed: false
+    },
+    startedAt,
+    capturedAt,
+    copyMs: capturedAt - startedAt,
+    frameCount: scan.lastCommitFrame - from.frame,
+    byteLength,
+    pageSize: header.pageSize
+  };
+}
+async function captureAndCheckpointTurn(turn) {
+  const { request, state, stagingDir } = turn;
+  await request.runExclusive(async () => {
+    const captured = await captureLogFrames({
+      sourcePath: request.sourcePath,
+      logPath: turn.logPath,
+      stagingDir,
+      chainId: state.chainId,
+      namePrefix: turn.namePrefix,
+      sequence: state.records,
+      cursor: state.cursor,
+      expectNewLog: state.closedCleanly
+    });
+    if (captured) {
+      state.pending = captured;
+      await writeCycleState(stagingDir, state);
+    }
+    const checkpointed = (await checkpointLog(request.acquireWriter())).emptied;
+    const cursor = captured?.cursor ?? state.cursor;
+    if (cursor) cursor.checkpointed = checkpointed;
+    state.closedCleanly = false;
+    await writeCycleState(stagingDir, state);
+  });
+}
+async function discardStagedChain(stagingDir) {
+  await removeCycleState(stagingDir);
+  const entries = await readdir(stagingDir).catch(() => []);
+  for (const entry of entries) {
+    if (entry.startsWith(STAGED_CAPTURE_PREFIX) && entry.endsWith(STAGED_CAPTURE_SUFFIX)) {
+      await rm(join(stagingDir, entry), { force: true });
+    }
+  }
+}
+
+export { captureAndCheckpointTurn, discardStagedChain, readCycleState, removeCycleState, stagedCapturePath, writeCycleState };

package/dist/client/index.d.ts

@@ -1,17 +1,17 @@
 export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
 import { C as ConflictResolver, R as ReplicationBatch } from '../types-CjhxcjhA.js';
 export { a as ConflictContext, b as ConflictResolution } from '../types-CjhxcjhA.js';
-import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-D4VmfTHw.js';
-import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-CGBpjZUB.js';
-export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-CGBpjZUB.js';
+import { C as ClientOptions, B as BulkLoadDurability } from '../server-options-DeK6ZG8u.js';
+import { D as DatabaseClient, T as Transport, L as LiveHandlers, R as RemoteSubscription, a as RemoteSubscriptionBuilder, S as SubscribeOptions, b as RegistryDigestSource } from '../client-base-C-B8u5Lm.js';
+export { c as LoadAllOptions, d as RemoteDatabase, e as RemoteError, f as SQL_REFUSED_MESSAGE, g as ServerCapabilities, h as ServerCapabilityCheck } from '../client-base-C-B8u5Lm.js';
 import { a as LiveQuery, b as LiveQueryState, c as LiveUpdate } from '../types-BCejqzNA.js';
-import { k as DeviceSyncPort, D as Database } from '../database-955qag_W.js';
+import { k as DeviceSyncPort, D as Database } from '../database-BlhUdJAO.js';
 import { C as ChangeEvent, P as Params, R as ReadConcern, W as WriteConcern } from '../query-types-Cv8N7pXj.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-BfiujBsE.js';
+import { Q as QueryResponse, E as ExecuteResponse, T as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-QekTGoKn.js';
 import '../operation-registry-C1FmwQWR.js';
-import '../types-Xb0L3o3w.js';
-import '../chain-queries-D5aZ-8v2.js';
-import '../change-tracker-DXHPFe9J.js';
+import '../types-DApb7dvw.js';
+import '../database-backup-C090lMHc.js';
+import '../change-tracker-uG9gWvsY.js';
 
 /**
  * @public

package/dist/client/topology.d.ts

@@ -1,11 +1,11 @@
 import { a as ReadConcernLevel } from '../query-types-Cv8N7pXj.js';
-import { C as ClientOptions } from '../server-options-D4VmfTHw.js';
-import { T as Transport, D as DatabaseClient } from '../client-base-CGBpjZUB.js';
+import { C as ClientOptions } from '../server-options-DeK6ZG8u.js';
+import { T as Transport, D as DatabaseClient } from '../client-base-C-B8u5Lm.js';
 import '../operation-registry-C1FmwQWR.js';
 import '../types-CjhxcjhA.js';
-import '../types-Xb0L3o3w.js';
+import '../types-DApb7dvw.js';
 import '../types-BCejqzNA.js';
-import '../protocol-BfiujBsE.js';
+import '../protocol-QekTGoKn.js';
 
 interface TopologyRouting {
     _getReadEndpoint(databaseId?: string, readConcern?: ReadConcernLevel): Promise<string>;

package/dist/{client-base-CGBpjZUB.d.ts → client-base-C-B8u5Lm.d.ts}

@@ -1,8 +1,8 @@
-import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-D4VmfTHw.js';
+import { B as BulkLoadDurability, a as BulkLoadResult, C as ClientOptions } from './server-options-DeK6ZG8u.js';
 import { R as ResultOp, a as LiveQuery } from './types-BCejqzNA.js';
 import { O as OperationRef, b as OperationArguments } from './operation-registry-C1FmwQWR.js';
 import { P as Params, R as ReadConcern, W as WriteConcern, C as ChangeEvent, Q as QueryOptions } from './query-types-Cv8N7pXj.js';
-import { Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-BfiujBsE.js';
+import { Q as QueryResponse, E as ExecuteResponse, T as TransactionResponse, B as BatchResponse, L as LoadResponse } from './protocol-QekTGoKn.js';
 
 /**
  * Message a client raises when the server accepts no SQL over the network.

package/dist/core/index.d.ts

@@ -1,15 +1,15 @@
-export { B as BackupCapabilities, a as BackupRestorePlan, b as BackupSafeToDeleteOptions, c as backupPiecesSafeToDelete, p as planBackupRestore } from '../chain-queries-D5aZ-8v2.js';
-import { i as SQLiteConnection, F as SynchronousLevel, a as SQLiteDriver, D as DatabaseOptions, L as LifecycleConfig, M as Migration, G as MigrationResult, R as RollbackResult } from '../types-Xb0L3o3w.js';
-export { A as AfterQueryHook, H as AppliedMigration, I as AppliedMigrationEntry, g as BackupChain, e as BackupChainBase, f as BackupChainChange, l as BackupChainPosition, h as BackupChainRecord, n as BackupCycleOptions, j as BackupDestination, o as BackupGroupMembership, p as BackupGroupSource, q as BackupNodePreference, r as BackupPiece, s as BackupProgress, k as BackupRunReport, E as BackupScheduleOptions, t as BackupSkip, u as BackupSkipReason, v as BackupToDestinationOptions, J as BatchSummary, b as BeforeConnectHook, B as BeforeQueryHook, K as BeforeSubscribeHook, O as CDCMetrics, P as ClusterReadEndpointInfo, C as ClusterStatusInfo, Q as ConnectionHookContext, U as ConnectionMetrics, w as DEFAULT_CHAIN_NAME, d as DatabaseCloseHook, V as DatabaseCopyRequest, W as DatabaseCopyStep, c as DatabaseOpenHook, X as DriverCapabilities, Y as DriverWorkerEntry, Z as HookConfig, _ as MIGRATION_NAME_RE, $ as MetricsConfig, a0 as MigrationBaseline, a1 as MigrationSource, N as NodeHealth, a2 as NodeHealthReason, a3 as NodeHealthState, a4 as OpenOptions, a5 as QueryHookContext, a6 as QueryMetrics, a7 as RunResult, a8 as SQLiteStatement, S as SirannonOptions, T as Transaction, a9 as WriterWorkerOptions, y as readBackupChains } from '../types-Xb0L3o3w.js';
-import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-D4VmfTHw.js';
-export { A as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, c as ClusterStatusAuthorizer, d as CorsOptions, R as ReplicationStatusInfo, e as RequestContext, f as ServerExecutionTarget, g as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-D4VmfTHw.js';
-export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-DXHPFe9J.js';
-import { D as Database } from '../database-955qag_W.js';
-export { C as ConnectionPool, a as ConnectionPoolOptions, b as DatabaseBackups, c as DatabaseLifecycle, H as HookDispose, d as HookEvent, e as HookEventContextMap, f as HookHandler, g as HookRegistry, M as MetricsCollector, S as SubscribeHookContext, h as execute, i as executeBatch, q as query, j as queryOne } from '../database-955qag_W.js';
+export { B as BackupCapabilities, a as BackupChainLocation, b as BackupRestorePlan, c as BackupSafeToDeleteOptions, d as backupPiecesSafeToDelete, p as planBackupRestore } from '../database-backup-C090lMHc.js';
+import { I as SQLiteConnection, U as SynchronousLevel, S as SQLiteDriver, D as DatabaseOptions, V as LifecycleConfig, M as Migration, W as MigrationResult, X as RollbackResult } from '../types-DApb7dvw.js';
+export { A as AfterQueryHook, Y as AppliedMigration, Z as AppliedMigrationEntry, g as BackupChain, h as BackupChainBase, i as BackupChainChange, j as BackupChainPosition, k as BackupChainRecord, m as BackupCycleError, n as BackupCycleOptions, o as BackupCycleStatus, B as BackupDestination, p as BackupFileReport, q as BackupGroupMembership, r as BackupGroupSource, s as BackupLogPosition, t as BackupNodePreference, u as BackupPiece, v as BackupProgress, f as BackupRunReport, O as BackupScheduleOptions, w as BackupSkip, x as BackupSkipReason, y as BackupToDestinationOptions, z as BackupVerifyResult, _ as BatchSummary, c as BeforeConnectHook, b as BeforeQueryHook, $ as BeforeSubscribeHook, a0 as CDCMetrics, a1 as ClusterReadEndpointInfo, H as ClusterStatusInfo, a2 as ConnectionHookContext, a3 as ConnectionMetrics, C as DEFAULT_CHAIN_NAME, e as DatabaseCloseHook, a4 as DatabaseCopyRequest, a5 as DatabaseCopyStep, d as DatabaseOpenHook, P as DriverCapabilities, a6 as DriverWorkerEntry, a7 as HookConfig, a8 as MIGRATION_NAME_RE, a9 as MetricsConfig, aa as MigrationBaseline, ab as MigrationSource, N as NodeHealth, ac as NodeHealthReason, ad as NodeHealthState, ae as OpenOptions, af as QueryHookContext, ag as QueryMetrics, ah as RunResult, ai as SQLiteStatement, a as SirannonOptions, T as Transaction, aj as WriterWorkerOptions, F as readBackupChains } from '../types-DApb7dvw.js';
+import { B as BulkLoadDurability, a as BulkLoadResult } from '../server-options-DeK6ZG8u.js';
+export { A as AuthenticateHook, b as BulkLoadOptions, C as ClientOptions, c as ClusterStatusAuthorizer, d as CorsOptions, R as ReplicationStatusInfo, e as RequestContext, f as ServerExecutionTarget, g as ServerExecutionTargetResolver, S as ServerOptions, W as WSHandlerOptions } from '../server-options-DeK6ZG8u.js';
+export { C as ChangeTracker, a as ChangeTrackerOptions } from '../change-tracker-uG9gWvsY.js';
+import { D as Database } from '../database-BlhUdJAO.js';
+export { C as ConnectionPool, a as ConnectionPoolOptions, b as DatabaseBackups, c as DatabaseLifecycle, H as HookDispose, d as HookEvent, e as HookEventContextMap, f as HookHandler, g as HookRegistry, M as MetricsCollector, S as SubscribeHookContext, h as execute, i as executeBatch, q as query, j as queryOne } from '../database-BlhUdJAO.js';
 export { B as BackupError, C as CDCError, a as ConnectionPoolError, D as DatabaseAlreadyExistsError, b as DatabaseNotFoundError, E as ExtensionError, F as ForbiddenSqlError, H as HookDeniedError, M as MaxDatabasesError, c as MigrationError, Q as QueryError, R as ReadOnlyError, d as RequestDeniedError, S as SirannonError, T as TransactionError, W as WriteOverloadError } from '../errors-Dei4GdBb.js';
 export { a as LiveQuery, L as LiveQueryOptions, b as LiveQueryState, c as LiveUpdate, R as ResultOp } from '../types-BCejqzNA.js';
 import { B as BaselineFileOption } from '../baseline-D93hcIEE.js';
-export { S as Sirannon } from '../sirannon-DaGUawHs.js';
+export { S as Sirannon } from '../sirannon-C9cTgFrw.js';
 export { C as ChangeEvent, b as ChangeOperation, E as ExecuteResult, P as Params, Q as QueryOptions, R as ReadConcern, a as ReadConcernLevel, S as Subscription, c as SubscriptionBuilder, W as WriteConcern, d as WriteConcernLevel } from '../query-types-Cv8N7pXj.js';
 export { D as DatabaseOperations, b as OperationArguments, O as OperationRef, a as OperationRegistry, c as OperationStatement, R as ReadOperation, W as WriteOperation, o as operationName, d as operationRef } from '../operation-registry-C1FmwQWR.js';
 import '../types-CjhxcjhA.js';