Skip to content

Build your personal knowledge base with Trilium Notes

10.4 KB
Raw Blame
import {
    asFileName,
    defaultBackupName,
    type SetupBackupDefaults,
    type SetupBackupSettings,
    type SetupExistingBackup,
    type SetupExistingBackupStatus
} from "@triliumnext/commons";

import { getBackup } from "./backup.js";
import eventService from "./events.js";
import { getLog } from "./log.js";
import optionService from "./options.js";
import {
    getSetupPlatform,
    hasExistingData,
    isInitialSetup,
    leaveSetupMode,
    markExistingDataDiscarded
} from "./setup_mode.js";
import sqlInit from "./sql_init.js";

/**
 * What becomes of the database an instance was booted away from.
 *
 * Setup normally runs where there is nothing to lose. When the app itself asks for setup there is a
 * whole knowledge base sitting behind the wizard, and the user is asked, before anything else, what
 * should happen to it. That question has exactly three answers, and they are the three functions
 * here: keep it and go back, back it up, or erase it.
 *
 * All three run against a database that is attached but not initialized, which is what setup mode
 * means. That is enough for a backup: options are read straight from the table when becca is not
 * loaded, and the backup itself copies a file. It is deliberately not enough for anything to be
 * written to the database, which nothing here does.
 *
 * @module
 */

/**
 * Backs the existing database up, and says where it went.
 *
 * @param settings what the user answered on the screen before this one; already resolved by
 *                 {@link resolveBackupSettings}, so nothing here has to guess at a missing answer.
 * @throws Error where the platform cannot write a backup, or the write itself failed.
 */
export async function backUpExistingData(
    settings: SetupBackupSettings
): Promise<SetupExistingBackup> {
    requireExistingData();

    const backup = getBackup();
    if (!backup.backupAs) {
        throw new Error("This platform cannot write a backup of the existing database.");
    }

    getLog().info("Setup: backing up the existing database before it is replaced.");
    progress = 0;

    try {
        const written = await backup.backupAs(settings, reportProgress);
        getLog().info(`Setup: the existing database was backed up (${written.fileSize} bytes).`);

        return written;
    } finally {
        progress = null;
    }
}

/**
 * What the instance is already set up to do, which is what the screen offers as its answers.
 *
 * The stored passphrase is reported as a yes or a no and never as itself: a screen that could read
 * it could be made to hand it over, and it is the one thing standing between a stolen backup and
 * the knowledge base inside it.
 */
export async function getExistingBackupDefaults(): Promise<SetupBackupDefaults> {
    const backup = getBackup();

    return {
        storedPassphrase: (await backup.hasStoredPassphrase?.()) ?? false,
        encrypt: isOptionEnabled("backupEnableEncryption"),
        compress: isOptionEnabled("backupEnableCompression")
    };
}

/**
 * Settles what a backup asked for over a request is actually written as.
 *
 * Every field is treated as something a caller may have got wrong or left out rather than as an
 * answer: what arrives here has crossed a request boundary, and the name in particular goes on to
 * become a path. Anything missing falls back to what the instance is configured for, so a caller
 * that asks for nothing at all still gets the backup it would have got before there was anything to
 * ask.
 *
 * @param now the moment to name the backup after, where the caller named nothing usable.
 */
export function resolveBackupSettings(now: Date, requested: unknown): SetupBackupSettings {
    const asked = (typeof requested === "object" && requested !== null
        ? requested
        : {}) as Partial<Record<keyof SetupBackupSettings, unknown>>;

    return {
        // Reduced to a single name that no directory can be escaped from, whatever was sent.
        name: asFileName(typeof asked.name === "string" ? asked.name : "")
            ?? defaultBackupName(now),
        passphrase: typeof asked.passphrase === "string" ? asked.passphrase : "",
        useStoredPassphrase: typeof asked.useStoredPassphrase === "boolean"
            ? asked.useStoredPassphrase
            : isOptionEnabled("backupEnableEncryption"),
        compress: typeof asked.compress === "boolean"
            ? asked.compress
            : isOptionEnabled("backupEnableCompression")
    };
}

/**
 * Reads leniently, the way the backup itself does: setup runs against a database that has not been
 * migrated, so an option added by a newer version may not be there to read at all.
 */
function isOptionEnabled(name: "backupEnableCompression" | "backupEnableEncryption"): boolean {
    return optionService.getOptionOrNull(name) === "true";
}

/**
 * Starts the backup and answers at once, leaving the outcome to be polled for.
 *
 * The write itself runs for minutes on a large knowledge base, and a request held open that long
 * does not survive every platform: on standalone it rides the service worker, whose fetches the
 * browser reclaims after a few minutes however patient the caller is. So the caller that would have
 * waited on {@link backUpExistingData} starts it here and follows it through
 * {@link getExistingBackupStatus} instead.
 *
 * A backup already running is joined rather than doubled. What can be refused outright (no
 * existing database, a platform with nowhere to write) still throws from here, so the starting
 * request carries the reason.
 *
 * @param now the moment to name the backup after, where `requested` named nothing usable.
 * @param requested what the user answered on the screen before this one, as it arrived.
 */
export function startBackUpExistingData(now: Date, requested?: unknown): void {
    if (status.state === "running") {
        return;
    }

    requireExistingData();
    if (!getBackup().backupAs) {
        throw new Error("This platform cannot write a backup of the existing database.");
    }

    status = { state: "running", fraction: null };
    backUpExistingData(resolveBackupSettings(now, requested))
        .then((written) => {
            status = { state: "done", fraction: 1, result: written };
        })
        .catch((e) => {
            status = { state: "failed", fraction: null, error: messageOf(e) };
        });
}

/** Where the latest backup stands, for the screen polling its way through it. */
export function getExistingBackupStatus(): SetupExistingBackupStatus {
    return status.state === "running" ? { ...status, fraction: progress } : status;
}

let status: SetupExistingBackupStatus = { state: "idle", fraction: null };

/**
 * How far through the backup is, from 0 to 1, or `null` when none is running.
 *
 * Read by the screen that is waiting on it. A backup of a large knowledge base runs for minutes,
 * most of it inside one write that says nothing, and a screen with nothing to show for that long is
 * indistinguishable from one that has stopped.
 */
export function getExistingBackupProgress(): number | null {
    return progress;
}

let progress: number | null = null;
/** The last tenth that was logged, so a long write leaves a trail without flooding the log. */
let loggedTenth = -1;

function reportProgress(fraction: number): void {
    progress = fraction;

    const tenth = Math.floor(fraction * 10);
    if (tenth > loggedTenth) {
        loggedTenth = tenth;
        getLog().info(`Setup: backing up the existing database [${Math.round(fraction * 100)}%]`);
    }
    if (fraction >= 1) {
        loggedTenth = -1;
    }
}

/**
 * Erases the existing database, which is the point of no return.
 *
 * Deliberately late: the user answers for a backup on the way into the wizard, but nothing is
 * touched until they pick a path that replaces the database, and this is what those paths call
 * first. Up to here every screen can still be left through Cancel with the knowledge base intact.
 *
 * The one path that does not call it is restoring a backup, and for a reason worth keeping: a
 * restore validates the file and only then swaps the database, so a backup that turns out to be
 * unusable leaves the user with what they already had. Erasing first would throw that away.
 */
export async function deleteExistingData(): Promise<void> {
    requireExistingData();

    getLog().info("Setup: erasing the existing database at the user's request.");
    await getSetupPlatform().removeDatabase();
    markExistingDataDiscarded();
    getLog().info("Setup: the existing database is gone.");
}

/**
 * The same, for callers that do not know whether there is anything to erase.
 *
 * Which is every path that creates a database: it runs identically on a first run, where there
 * never was one, and on an instance the app sent here, where there is one right up until this call.
 */
export async function discardExistingData(): Promise<void> {
    if (hasExistingData()) {
        await deleteExistingData();
    }
}

/**
 * Abandons setup and opens the database that was there all along.
 *
 * The way out of every screen in this part of the wizard, including the one that warns about
 * erasure. Nothing has been touched up to this point, so there is nothing to undo: the instance
 * stops answering as uninitialized and comes up as it would have.
 */
export async function keepExistingData(): Promise<void> {
    requireExistingData();

    getLog().info("Setup: leaving the existing database as it was.");
    await getSetupPlatform().removeMarker();
    leaveSetupMode();

    await sqlInit.initDbConnection();
    eventService.emit(eventService.DB_INITIALIZED);
}

/**
 * Refuses everything here on an instance that has nothing to lose.
 *
 * These operations only make sense between an app asking for setup and the wizard getting past the
 * question, and each of them is destructive or irreversible in its own way. A first run reaching
 * them means something is wrong, not that there is an empty database to erase.
 *
 * The second case is the same thing later on: once the user has picked a path and the database has
 * gone, a screen still offering to back it up or to go back to it is a screen acting on something
 * that is no longer there.
 */
function requireExistingData(): void {
    if (isInitialSetup()) {
        throw new Error("There is no existing database: this instance is being set up for the first time.");
    }
    if (!hasExistingData()) {
        throw new Error("The existing database has already been discarded during this setup.");
    }
}

function messageOf(e: unknown): string {
    return e instanceof Error ? e.message : String(e);
}