Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import {
type BackupContainerErrorReason,
FIXED_HEADER_BYTES,
getInfo,
isBackupContainerError,
type ProgressCallback,
readBackupContainer
} from "@triliumnext/backup-container";
import {
cls,
type DatabaseRejection,
events as eventService,
getBackup,
getLog,
getSql,
leaveSetupMode,
sql_init as sqlInit,
utils as coreUtils
} from "@triliumnext/core";
import fs from "fs";
import path from "path";
import type ServerBackupService from "../backup_provider.js";
import config from "./config.js";
import dataDir from "./data_dir.js";
import { validateDatabaseFile } from "./database_validation.js";
/**
* Puts a backup in place of this instance's database.
*
* The database is open before the restore starts and has to be open after it, so the file cannot
* simply be written over: the connection is detached, the file is exchanged, and a new connection is
* attached to what is now there. On Windows that order is not a preference — an open handle prevents
* the file from being renamed at all.
*
* Everything that can be checked is checked before the exchange, on a copy nothing is attached to,
* because the alternative is finding out afterwards: the migration is what would otherwise notice an
* unusable database, and a migration that cannot proceed ends the process outright.
*
* The database being replaced is kept aside until the restored one has migrated and opened. Until
* then a marker sits next to it, so an interruption in the middle — a power cut, a killed process —
* is recognised at the next start and undone, rather than leaving an instance that cannot open its
* own document.
*
* Only ever run during setup, where nothing else holds the database: the share connection is opened
* on `dbReady`, which has not resolved, and sessions are not persisted until the database is
* initialized.
*
* @module
*/
/**
* Prefix every line of a restore carries, so the whole of one can be picked out of a log by
* searching for it.
*/
const LOG_PREFIX = "Backup restore: ";
/** Notes something that happened, for a log a user can be asked for and can hand over unread. */
export function logRestore(message: string): void {
getLog().info(`${LOG_PREFIX}${withoutPaths(message)}`);
}
/** Notes something that went wrong. Reserved for actual failures; oddities that are handled use {@link logRestore}. */
export function logRestoreError(message: string): void {
getLog().error(`${LOG_PREFIX}${withoutPaths(message)}`);
}
/**
* Takes the filesystem out of anything on its way to the log.
*
* The backend log is meant to be postable for diagnostics without being censored first, and the data
* directory carries the user's name on most platforms. Our own lines never name a file, but the
* errors we quote back are not ours: a filesystem error states the full path it failed on. This is
* the same treatment the backup service gives its own failures.
*/
function withoutPaths(text: string): string {
let scrubbed = text;
// Longest first, so a path inside the data directory is not reduced to the data directory and a
// leftover fragment of itself. Each is scrubbed both as configured and as resolved, since an
// error quotes back whichever form the call that failed was given.
for (const [ directory, name ] of [
[ dataDir.DOCUMENT_PATH, "<database>" ],
[ dataDir.TMP_DIR, "<temporary files>" ],
[ dataDir.BACKUP_DIR, "<backup location>" ],
[ dataDir.TRILIUM_DATA_DIR, "<data directory>" ]
] as const) {
for (const form of pathForms(directory)) {
scrubbed = coreUtils.replaceAll(scrubbed, form, name);
}
}
return scrubbed;
}
/**
* The spellings of a configured location that could turn up in an error, longest first.
*
* A data directory may be configured relatively — `TRILIUM_DATA_DIR=data` is what the development
* scripts use — so the resolved form is what a filesystem error names, while our own calls pass the
* configured one. A bare word is dropped: replacing "data" as a substring turns every "database" in
* a sentence into "<data directory>base".
*/
function pathForms(directory: string): string[] {
const resolved = path.resolve(directory);
const looksLikePath = directory.includes(path.sep) || directory.includes("/");
return resolved === directory || !looksLikePath
? [ resolved ]
: [ resolved, directory ].sort((a, b) => b.length - a.length);
}
/**
* How much of the way through a step has to pass before it is worth another line.
*
* A log is read after the fact, so what it needs from a step that runs for minutes is a trail
* proving it was moving, not a running total. Every tenth is ten or eleven lines however long the
* step takes, which is enough to tell a slow unwrap from a stalled one.
*/
const PROGRESS_LOG_STEP = 10;
/**
* How often the container module is asked to report.
*
* Half the rate the screen polls at, so what it is shown is never much older than it is, and far
* below the rate the module would report at left alone.
*/
const PROGRESS_INTERVAL_MS = 500;
/**
* Passes the container module's progress on to both places that want it, each at its own rate.
*
* The screen is polled about once a second and wants the latest position every time, so every report
* reaches it. The log wants the opposite: its reader comes to it afterwards and needs a trail, not a
* running total, so a line is written only when the position has actually moved on a tenth. Writing
* every report to both would make a stall indistinguishable from progress in the one place where
* that distinction is all there is.
*/
export function reportStepProgress(activity: string): ProgressCallback {
let lastLogged = -1;
return (fraction) => {
if (progress) {
progress = { ...progress, fraction };
}
const percent = Math.floor(fraction * 100);
const step = Math.floor(percent / PROGRESS_LOG_STEP);
if (step > lastLogged) {
lastLogged = step;
logRestore(`${activity} [${percent}%]`);
}
};
}
/** How big a file is, counting one that cannot be measured as nothing rather than failing over it. */
export function sizeOf(filePath: string): number {
return fs.statSync(filePath, { throwIfNoEntry: false })?.size ?? 0;
}
/** What a size is worth saying in a log line: the number, in units a person reads at a glance. */
export function describeSize(bytes: number): string {
const units = [ "bytes", "KiB", "MiB", "GiB" ];
let size = bytes;
let unit = 0;
while (size >= 1024 && unit < units.length - 1) {
size /= 1024;
unit++;
}
return `${unit === 0 ? size : size.toFixed(1)} ${units[unit]}`;
}
/** How long something took, for the steps that can take long enough to be worth asking about. */
function describeElapsed(since: number): string {
return `${((Date.now() - since) / 1000).toFixed(1)}s`;
}
/** What the restore is doing, in the order it does it. */
export type RestoreStage =
/** Getting the backup into a plain database file: unwrapping a container, or taking the upload. */
| "staging"
/** Reading that file to see whether it can be this instance's database. */
| "validating"
/** Detaching, exchanging the files, and attaching again. Over in moments. */
| "swapping"
/** Opening the restored database, which for an older one includes migrating it. */
| "migrating"
| "done"
| "failed";
/** Why a restore stopped, in terms the setup screen turns into something the user can act on. */
export type RestoreFailureReason =
| DatabaseRejection
| BackupContainerErrorReason
/** The files could not be exchanged; the original database is back in place. */
| "swap-failed"
/** The restored database is in place but would not open. */
| "migration-failed"
/** The restore never started, e.g. setup was busy with something else. */
| "restore-refused";
export interface RestoreProgress {
stage: RestoreStage;
/** The name of the backup being restored, so a reloaded page can say what is going on. */
fileName: string;
/**
* How far through the current step, from 0 to 1.
*
* Absent for the steps that cannot say — checking a database reads it from beginning to end with
* nothing to report along the way, and exchanging the files is over in moments. It belongs to the
* step rather than to the restore, and starts again with each one.
*/
fraction?: number;
/** Set when `stage` is `failed`. */
error?: string;
/** Set when `stage` is `failed`. */
reason?: RestoreFailureReason;
}
export interface RestoreRequest {
/** Where the backup is now. */
path: string;
/** What to call it when reporting on it. */
fileName: string;
/**
* Whether the restore may take the file rather than copy it. True for an upload's temporary file,
* whose only purpose is this; false for a backup in the backup directory, which must survive.
*/
consumable: boolean;
/** Required for an encrypted backup. */
passphrase?: string;
}
let progress: RestoreProgress | null = null;
/** How the running or last restore is getting on, or `null` if none has been started. */
export function getRestoreProgress(): RestoreProgress | null {
return progress;
}
/**
* Restores `request` over this instance's database, reporting its way through
* {@link getRestoreProgress}.
*
* Callers hold the setup lock for the whole call: a second setup operation starting midway through
* would build a database over the one being restored, and neither would report anything wrong.
*
* @throws RestoreFailure carrying the reason, which is also left in the progress for the client that
* is polling rather than waiting.
*/
export async function restoreDatabase(request: RestoreRequest): Promise<void> {
const startedAt = Date.now();
// Refused against a live database, and said here rather than left to the route that calls it.
// Every other way of replacing a database refuses on its own account too — `createInitialDatabase`
// and `createDatabaseForSync` both do — and this was the one that did not, which made
// `checkAppNotInitialized` the single thing standing between a running instance and a restore
// over the top of it. The standalone build has had the same check on its own restore all along.
if (sqlInit.isDbInitialized()) {
throw new RestoreFailure("restore-refused", "This instance already has a database; a restore only runs from the setup screen.");
}
// The name is left out on purpose: it is the user's, and everything worth knowing about the file
// is stated below in terms that are not.
logRestore(`starting, from ${request.consumable ? "a backup this instance was given" : "a backup already on this device"}`);
// Read here rather than taken from the staging that follows, which consumes a backup this
// instance was given: by the time the restore has finished there may be no file left to ask.
const wasEncrypted = readBackupFormat(request.path)?.encrypted ?? false;
// Announced through `report` like every other step, so that a log can be read by looking for the
// steps alone and the first one is not the exception that is missing.
progress = { stage: "staging", fileName: request.fileName };
report("staging");
try {
// The whole restore runs in one execution context: what follows the swap writes to the
// database, and the request that started this is long since answered.
await cls.init(async () => {
const candidate = await stageBackup(request);
report("validating");
const validatedAt = Date.now();
const validation = validateDatabaseFile(candidate);
if (!validation.valid) {
throw new RestoreFailure(validation.rejection, validation.message);
}
logRestore(`checked in ${describeElapsed(validatedAt)}: database version ${validation.dbVersion}`
+ `, ${validation.needsMigration ? "needs migrating" : "already current"}`);
report("swapping");
swapInDatabase(candidate);
report("migrating");
await openRestoredDatabase(validation.needsMigration);
});
await adoptBackupPassphrase(request, wasEncrypted);
report("done");
logRestore(`finished in ${describeElapsed(startedAt)}`);
} catch (e) {
// Read before the progress is overwritten with the failure, which would otherwise report
// every failure as having happened at the 'failed' step.
const failedAt = progressStage();
const failure = asFailure(e);
progress = {
stage: "failed",
fileName: request.fileName,
error: failure.message,
reason: failure.reason
};
logRestoreError(`failed at the '${failedAt}' step after ${describeElapsed(startedAt)}`
+ ` (${failure.reason}): ${failure.message}`);
throw failure;
} finally {
// Whatever happened, the temporary files are of no further use. Tidying up is never allowed
// to throw from here: an exception raised in a `finally` replaces the one on its way out, so
// a directory that would not delete used to bury the reason the restore actually failed —
// and with it the client's only way of telling a wrong passphrase from a broken backup.
removeQuietly(stagingDirectory(), { recursive: true });
}
}
/**
* Brings the stored backup passphrase into line with the database that has just been restored.
*
* The passphrase lives outside the database — an OS keyring on the desktop, nowhere at all
* elsewhere — so it is the one thing about how this instance backs up that a restore does not
* replace. Left alone, an instance restored from someone else's backup goes on encrypting with the
* password of the database it used to hold: the backups look fine, and the password the user
* expects does not open them.
*
* Never allowed to fail the restore. The database is already in place and open by this point, and a
* keyring that would not answer is not a reason to tell the user their restore did not work.
*
* @param wasEncrypted whether the backup was locked, which is what decides there is a password here
* worth taking on at all.
*/
export async function adoptBackupPassphrase(
request: RestoreRequest,
wasEncrypted: boolean
): Promise<void> {
// A backup with no lock on it brings no password to take on, and the stored one is not an
// answer: it was the previous database's.
const passphrase = wasEncrypted ? request.passphrase ?? null : null;
try {
await (getBackup() as ServerBackupService).adoptPassphrase(passphrase);
logRestore(passphrase
? "the backup password is now the one that opened this backup"
: "let go of the backup password, which belonged to the previous database");
} catch (e) {
logRestoreError(`the backup password could not be brought up to date: ${messageOf(e)}`);
}
}
/**
* Records a failure that happened *instead of* a restore rather than during one, e.g. one that was
* refused before it could start.
*
* Without this such a failure is reported nowhere: {@link restoreDatabase} never ran, so it left no
* progress behind, and a client polling for one waits on a run that is never going to begin.
*/
export function reportRestoreFailure(fileName: string, error: unknown): void {
progress = {
stage: "failed",
fileName,
error: messageOf(error),
reason: error instanceof RestoreFailure ? error.reason : "restore-refused"
};
}
/**
* Undoes a restore that was interrupted between the database being moved aside and the restored one
* opening.
*
* Runs at startup, before the database is opened, and before core is initialized — so it says what it
* did through the console rather than the log, which does not exist yet.
*/
export function recoverInterruptedRestore(document: string = dataDir.DOCUMENT_PATH): void {
if (!fs.existsSync(markerFor(document))) {
return;
}
const setAside = setAsideFor(document);
if (fs.existsSync(setAside)) {
console.info(`${LOG_PREFIX}a restore was interrupted partway; putting the previous database back.`);
removeDatabaseFiles(document);
fs.renameSync(setAside, document);
console.info(`${LOG_PREFIX}the previous database is back in place.`);
} else {
// Nothing was set aside, so either the exchange had not started or it had finished: the
// database in place is the one to open either way.
console.info(`${LOG_PREFIX}a restore was interrupted; the database in place is intact.`);
}
fs.rmSync(markerFor(document), { force: true });
}
/**
* Moves `document` aside and puts `candidate` in its place, which is the whole of the exchange as far
* as the filesystem is concerned.
*
* Separate from the detaching and attaching around it so that what happens to the files can be
* exercised on its own, and so the order is stated in one place: aside first, sidecars after it,
* candidate last.
*/
export function exchangeDatabaseFiles(candidate: string, document: string): void {
const setAside = setAsideFor(document);
fs.rmSync(setAside, { force: true });
if (fs.existsSync(document)) {
fs.renameSync(document, setAside);
}
// The sidecars belong to the database that was just moved away; left behind, SQLite would read
// them as this one's.
removeSidecars(document);
moveInto(candidate, document);
}
/** A failure with a reason attached, so the setup screen can tell the cases apart. */
export class RestoreFailure extends Error {
constructor(readonly reason: RestoreFailureReason, message: string) {
super(message);
this.name = "RestoreFailure";
}
}
/** What a backup file is, read from its header rather than from what it is called. */
export interface BackupFormat {
/** Whether it is a container rather than a plain copy of a database. */
container: boolean;
/** Whether a passphrase is needed to unwrap it. */
encrypted: boolean;
}
/**
* Identifies a backup file from its first few dozen bytes, which is where a container states what it
* is, in the clear and without the passphrase.
*
* Goes by the header rather than the extension: a container renamed to `.db` is still a container,
* and a database renamed to `.tnbackup` is still a database.
*
* @returns what the file is, or `null` when it cannot be read at all.
*/
export function readBackupFormat(filePath: string): BackupFormat | null {
const head = Buffer.alloc(FIXED_HEADER_BYTES);
let descriptor: number | undefined;
try {
descriptor = fs.openSync(filePath, "r");
fs.readSync(descriptor, head, 0, head.length, 0);
} catch {
return null;
} finally {
if (descriptor !== undefined) {
fs.closeSync(descriptor);
}
}
const container = getInfo(head);
// A version this build cannot open is left to the reader to refuse, which it does by name; here
// it is only ever a file this path has no way to unwrap.
const readable = container.isValid && container.isSupported;
return { container: readable, encrypted: readable && container.isEncrypted };
}
/**
* Produces the plain database file the rest of the restore works on.
*
* An uploaded database is used where it lies: it exists only to be restored, and copying it would
* mean writing gigabytes a second time to no purpose. A container is unwrapped, and a backup from the
* backup directory is copied, since that one has to stay where it is.
*/
export async function stageBackup(request: RestoreRequest): Promise<string> {
const format = readBackupFormat(request.path);
if (!format) {
throw new RestoreFailure("not-a-database", "The backup could not be read.");
}
const sourceBytes = sizeOf(request.path);
logRestore(`the backup is ${format.container ? "a container" : "a plain database"}`
+ `${format.encrypted ? ", encrypted" : ""}, ${describeSize(sourceBytes)}`);
if (!format.container) {
if (request.consumable) {
logRestore("using the backup where it lies, since it is ours to spend");
return request.path;
}
const candidate = freshCandidatePath();
const copiedAt = Date.now();
await fs.promises.copyFile(request.path, candidate);
logRestore(`copied the backup aside in ${describeElapsed(copiedAt)}, since the original has to survive`);
return candidate;
}
// Asked before the file is read rather than after: an encrypted container without a passphrase
// fails the same way either way, but only one of them takes minutes to get there.
if (format.encrypted && !request.passphrase) {
throw new RestoreFailure("passphrase-required", "The backup is encrypted.");
}
const candidate = freshCandidatePath();
const source = fs.createReadStream(request.path);
const destination = fs.createWriteStream(candidate);
const unwrappedAt = Date.now();
try {
const unwrapped = await readBackupContainer(source, destination, {
passphrase: request.passphrase,
// The step that runs for minutes on a large backup, and the only one that can say how far
// through it is. Without this the log jumps from the format to the finished size, which
// reads the same whether it took a moment or is still going.
onProgress: reportStepProgress("unwrapping the backup"),
progressIntervalMs: PROGRESS_INTERVAL_MS
});
logRestore(`unwrapped a version ${unwrapped.version} container in ${describeElapsed(unwrappedAt)}`
+ `: ${describeSize(unwrapped.bytesWritten)} of database`
+ `${unwrapped.compressed ? `, from ${describeSize(sourceBytes)} compressed` : ""}`);
} finally {
// Both streams are closed here rather than left to the reader, which only ends them once it
// gets as far as its pipeline: a wrong passphrase is refused before that, from the header, so
// on a failure the two handles are still open. Windows will not let an open file be deleted
// or replaced, which turns one wrong password into a staging directory that cannot be
// cleared and an uploaded backup that cannot be overwritten by the next attempt.
await closeStream(source);
await closeStream(destination);
}
if (request.consumable) {
await fs.promises.rm(request.path, { force: true });
}
return candidate;
}
/**
* Exchanges the database file for `candidate`, leaving the old one aside under a marker until the
* restored one has opened.
*
* Detaching, moving and attaching are one step as far as anything outside is concerned: either the
* instance ends up on the restored database or back on the one it had.
*/
function swapInDatabase(candidate: string): void {
const document = dataDir.DOCUMENT_PATH;
// States nobody put the instance in on purpose. None of them stops the restore, and each one
// explains a shape the files could otherwise only be found in afterwards.
if (fs.existsSync(markerFor(document))) {
logRestore("a marker from an earlier restore was still in place; it is being replaced");
}
if (fs.existsSync(setAsideFor(document))) {
logRestore("a database set aside by an earlier restore was still there; it is being replaced");
}
if (fs.existsSync(`${document}-wal`) || fs.existsSync(`${document}-shm`)) {
logRestore("the database has sidecar files, so it was not closed cleanly; they go with it");
}
// Written before anything moves: from here until the restored database opens, an interruption
// leaves files that only this marker explains.
fs.writeFileSync(markerFor(document), "");
logRestore(`detaching the database being replaced (${describeSize(sizeOf(document))})`);
getSql().detachConnection();
try {
exchangeDatabaseFiles(candidate, document);
logRestore(`exchanged the files; the restored database is ${describeSize(sizeOf(document))}`);
getSql().attachFromFile(document, config.General.readOnly);
logRestore("attached to the restored database");
} catch (e) {
logRestoreError(`the exchange failed, putting the previous database back: ${messageOf(e)}`);
putBack(setAsideFor(document), document);
attachQuietly(document);
throw new RestoreFailure("swap-failed", messageOf(e));
}
}
/**
* Brings the restored database up: migrates it where it is older than this version, opens it, and
* announces it, which is what starts everything that waits on a database being there.
*
* Announced here rather than through `setDbAsInitialized`, which does nothing when the database says
* it is already initialized — and a restored one does, since it was initialized before it was backed
* up. Mirrors what the "create new document" path does for the same reason.
*/
async function openRestoredDatabase(needsMigration: boolean): Promise<void> {
const document = dataDir.DOCUMENT_PATH;
const openedAt = Date.now();
// The one step that can run for minutes without anything to show for it, since migrating takes a
// backup of its own first. Said in advance so a log that stops here is not read as a hang.
logRestore(needsMigration
? "opening the restored database, which is being migrated first and may take a while"
: "opening the restored database");
// Whatever asked this instance into setup has had its answer, and until this is said the
// instance keeps reporting that it has nothing to open, which is what `initDbConnection` checks.
leaveSetupMode();
try {
await sqlInit.initDbConnection();
} catch (e) {
logRestoreError(`the restored database would not open, putting the previous one back: ${messageOf(e)}`);
putBack(setAsideFor(document), document);
attachQuietly(document);
throw new RestoreFailure("migration-failed", messageOf(e));
}
logRestore(`the restored database is open after ${describeElapsed(openedAt)}`);
eventService.emit(eventService.DB_INITIALIZED);
// The restore is over, so neither the previous database nor the marker has anything left to say.
removeQuietly(setAsideFor(document));
removeQuietly(markerFor(document));
}
/** Where the database being replaced waits until the restored one has opened. */
function setAsideFor(document: string): string {
return `${document}.pre-restore`;
}
/** Says that an exchange is under way, for a start that finds the pieces of an interrupted one. */
function markerFor(document: string): string {
return `${document}.restore-in-progress`;
}
/**
* Moves the restore on to its next step, and says so.
*
* Every step is logged as it is entered, so a restore that stops says where it stopped even when
* nothing threw — a process killed mid-swap leaves its last step as the last thing in the log.
*/
function report(stage: RestoreStage): void {
if (progress) {
// The position belonged to the step that has just ended, and would otherwise be read as this
// one's — a step with nothing to report showing the last one's bar, frozen where it stopped.
progress = { ...progress, stage, fraction: undefined };
}
logRestore(`step '${stage}'`);
}
/** The step the restore had reached, for saying where it was when something went wrong. */
function progressStage(): RestoreStage | "unknown" {
return progress?.stage ?? "unknown";
}
/**
* Deletes something that is no longer wanted, and carries on if it will not go.
*
* Every use of this is cleaning up after something else, on a path that is already reporting its own
* outcome. A leftover temporary file is worth a line in the log; it is not worth replacing the answer
* the caller was about to give, and on Windows a file another process has briefly opened — a virus
* scanner, an indexer — is a failure that says nothing about the operation at hand.
*/
export function removeQuietly(target: string, options: { recursive?: boolean } = {}): void {
try {
// `recursive` is spelled out rather than passed through: `fs.rmSync` merges the options over
// its defaults, so a property that is present and undefined replaces the default rather than
// leaving it alone, and every call that omitted it failed its own type check.
fs.rmSync(target, { force: true, recursive: options.recursive === true });
} catch (e) {
logRestoreError(`a temporary file would not go away: ${messageOf(e)}`);
}
}
/**
* Releases a stream's file handle and waits for the operating system to agree that it is released.
*
* Waiting is the point: `destroy()` only asks, and the handle is still open until `close` fires.
* Anything that then tries to delete or replace the file on Windows fails until it does.
*/
function closeStream(stream: NodeJS.EventEmitter & { closed: boolean; destroy(): void }): Promise<void> {
if (stream.closed) {
return Promise.resolve();
}
return new Promise((resolve) => {
stream.once("close", () => resolve());
stream.destroy();
});
}
function stagingDirectory(): string {
return path.join(dataDir.TMP_DIR, "restore");
}
function freshCandidatePath(): string {
const directory = stagingDirectory();
fs.mkdirSync(directory, { recursive: true });
return path.join(directory, "candidate.db");
}
/**
* Moves a file to where it is wanted, falling back to a copy across filesystem boundaries — which is
* where a relocated temporary directory can put it.
*/
function moveInto(source: string, destination: string): void {
try {
fs.renameSync(source, destination);
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== "EXDEV") {
throw e;
}
// Worth saying: it turns the last step from instant into another full write of the database,
// which is otherwise a mysteriously slow finish on an instance with a relocated temp
// directory.
logRestore("the temporary files are on another filesystem, so the last step is a copy rather than a rename");
const copiedAt = Date.now();
fs.copyFileSync(source, destination);
fs.rmSync(source, { force: true });
logRestore(`copied into place in ${describeElapsed(copiedAt)}`);
}
}
/** Puts the database that was set aside back, for a restore that got no further. */
function putBack(setAside: string, document: string): void {
if (!fs.existsSync(setAside)) {
logRestore("nothing had been set aside yet, so there is nothing to put back");
return;
}
try {
removeDatabaseFiles(document);
fs.renameSync(setAside, document);
logRestore("the previous database is back in place");
} catch (e) {
// Nothing else can be done from here, and the marker is still in place: the next start
// finds it and puts the database back before anything opens it.
logRestoreError(`the previous database could not be put back, leaving it to the next start: ${messageOf(e)}`);
}
}
/** Re-attaches after a rollback. A failure here is reported, not raised: the caller is already failing. */
function attachQuietly(document: string): void {
try {
getSql().attachFromFile(document, config.General.readOnly);
logRestore("re-attached to the previous database");
} catch (e) {
logRestoreError(`the database could not be re-opened after the failed restore: ${messageOf(e)}`);
}
}
function removeDatabaseFiles(document: string): void {
fs.rmSync(document, { force: true });
removeSidecars(document);
}
function removeSidecars(document: string): void {
fs.rmSync(`${document}-wal`, { force: true });
fs.rmSync(`${document}-shm`, { force: true });
}
function asFailure(e: unknown): RestoreFailure {
if (e instanceof RestoreFailure) {
return e;
}
if (isBackupContainerError(e)) {
return new RestoreFailure(e.reason, e.message);
}
return new RestoreFailure("swap-failed", messageOf(e));
}
function messageOf(e: unknown): string {
return e instanceof Error ? e.message : String(e);
}