Skip to content

Build your personal knowledge base with Trilium Notes

27.9 KB
Raw Blame
import "./setup_restore.css";

import type { DatabaseBackup, ExistingBackupsResponse } from "@triliumnext/commons";
import type { ComponentChildren } from "preact";
import { useCallback, useEffect, useRef, useState } from "preact/hooks";

import { ChunkedUploadError, uploadInChunks } from "./services/chunked_upload";
import { describeDatabaseFile, describeDatabaseFormat } from "./services/database_files";
import { t } from "./services/i18n";
import server from "./services/server";
import { fileAccept, formatSize } from "./services/utils";
import Button from "./widgets/react/Button";
import { Card, CardSection } from "./widgets/react/Card";
import DatabaseFileBadges from "./widgets/react/DatabaseFileBadges";
import FormGroup from "./widgets/react/FormGroup";
import FormTextBox from "./widgets/react/FormTextBox";
import Icon from "./widgets/react/Icon";
import ProgressBar from "./widgets/react/ProgressBar";
import SetupPage from "./widgets/react/SetupPage";
import SlidePages from "./widgets/react/SlidePages";

/**
 * The setup screen's "restore from backup" path, from picking a backup to the restored database
 * being open.
 *
 * One component rather than three wizard states, because the steps are one decision followed by its
 * consequences: which backup, the passphrase it turns out to need, and then waiting. Going back from
 * the passphrase means picking again, which is what the wizard's own back button already means.
 *
 * @module
 */

/** What the restore is waiting on, as far as this screen is concerned. */
type Step = "picking" | "uploading" | "passphrase" | "restoring";

/**
 * Where "Back" goes from each step. A step with no entry here leaves the restore flow altogether,
 * which is what the first one does and what any later step does if it has nothing to return to.
 */
const PREVIOUS_STEP: Partial<Record<Step, Step>> = {
    uploading: "picking",
    passphrase: "picking"
};

/** The steps in the order they are reached, which is what decides the way a slide goes. */
const STEP_ORDER: Step[] = [ "picking", "uploading", "passphrase", "restoring" ];

/** Failures the same backup can still get past, which send the user back to the passphrase rather than to the start. */
const PASSPHRASE_FAILURES = new Set([ "passphrase-required", "wrong-passphrase-or-damaged-header" ]);

export default function RestoreFromBackup({ onBack, onRestored }: {
    /**
     * Leaves the restore for the step of the wizard that led here. Omitted where nothing did: an
     * instance sent straight to this screen by a marker has no earlier step to be shown, so the
     * first step of the restore has nowhere to go back to and offers no way.
     */
    onBack?: () => void;
    onRestored: () => void;
}) {
    const [ step, setStep ] = useState<Step>("picking");
    const [ selection, setSelection ] = useState<Selection | null>(null);
    const [ upload, setUpload ] = useState<UploadState | null>(null);
    const [ error, setError ] = useState<ComponentChildren>(null);
    const [ errorId, setErrorId ] = useState(0);
    const [ wrongPassphrase, setWrongPassphrase ] = useState(false);
    /** Stops the upload in flight, for the one thing that can interrupt it: the user going back. */
    const uploadCancellation = useRef<AbortController | null>(null);
    /**
     * The file a standalone restore is working from, kept so a wrong passphrase can be answered
     * without picking it again. It is a reference to bytes the browser already has, not a copy.
     */
    const localBackup = useRef<File | null>(null);
    /** Where a standalone restore has got to, which it reports rather than being polled for. */
    const [ localProgress, setLocalProgress ] = useState<RestoreStatus | null>(null);
    /**
     * Fetched here rather than by the step that lists them, which is mounted afresh every time it is
     * returned to: asking again would show "looking for backups" for the length of each slide back.
     */
    const [ backups, setBackups ] = useState<DatabaseBackup[] | null>(null);

    useEffect(() => {
        // Standalone keeps no backups worth offering: nothing takes them on a schedule there, and a
        // copy kept beside the database in the browser's own storage is cleared along with it.
        if (window.standaloneApi) {
            setBackups([]);
            return;
        }

        server.get<ExistingBackupsResponse>("database/backups")
            .then((response) => setBackups(response.backups))
            // An unreadable backup directory is not a reason to lose the way in from a file.
            .catch(() => setBackups([]));
    }, []);

    const raiseError = useCallback((headline: string, detail?: string) => {
        setError(<Failure headline={headline} detail={detail} />);
        setErrorId((id) => id + 1);
    }, []);

    /** Sends the restore on its way, or asks for the passphrase first where the backup needs one. */
    const restore = useCallback(async (picked: Selection, passphrase?: string) => {
        setSelection(picked);

        if (picked.encrypted && !passphrase) {
            setStep("passphrase");
            return;
        }

        try {
            await server.post("setup/restore/start", {
                source: picked.source,
                filePath: picked.filePath,
                passphrase
            });
            setStep("restoring");
        } catch (e) {
            setStep("picking");
            raiseError(t("setup.restore-error-could-not-start"), detailOf(e));
        }
    }, [ raiseError ]);

    /**
     * Restores a picked file through the standalone build's own way to the worker that owns the
     * database, which is already on this device: there is nothing to upload, and the request path
     * would serialise the whole database and give up on it besides.
     */
    async function restoreLocally(file: File, passphrase?: string) {
        setSelection({ source: "pending", fileName: file.name });
        localBackup.current = file;
        setStep("restoring");

        const result = await window.standaloneApi?.restore.importBackup({
            backup: file,
            passphrase,
            onProgress: ({ stage, fraction }) => setLocalProgress({ stage, fraction })
        });

        if (result?.status === "restored") {
            onRestored();
        } else if (result?.status === "needs-passphrase") {
            setStep("passphrase");
        } else {
            setStep("picking");
            raiseError(headlineFor(result?.reason), result?.message);
        }
    }

    async function uploadAndRestore(file: File) {
        if (window.standaloneApi) {
            await restoreLocally(file);
            return;
        }

        const cancellation = new AbortController();
        uploadCancellation.current = cancellation;

        setStep("uploading");
        setUpload({ sentBytes: 0, totalBytes: file.size, fraction: 0, bytesPerSecond: 0, reconnecting: false });

        try {
            const uploaded = await uploadInChunks<{ fileName: string; encrypted: boolean }>({
                endpoint: "setup/restore/upload",
                blob: file,
                fileName: file.name,
                signal: cancellation.signal,
                onProgress: ({ sentBytes, totalBytes, fraction, bytesPerSecond, reconnecting }) =>
                    setUpload({ sentBytes, totalBytes, fraction, bytesPerSecond, reconnecting })
            });

            await restore({ source: "pending", fileName: uploaded.fileName, encrypted: uploaded.encrypted });
        } catch (e) {
            setStep("picking");

            // An upload the user walked away from ends in a failure they chose, and being told
            // about it would read as something having gone wrong.
            if (!cancellation.signal.aborted) {
                raiseError(uploadFailureHeadline(e), detailOf(e));
            }
        } finally {
            uploadCancellation.current = null;
        }
    }

    /**
     * Goes back a step, or out of the restore altogether from the step that has nothing before it.
     *
     * An upload in flight is stopped on the way: left running it would finish in the background and
     * pull the user forward into the restore they had just walked away from.
     */
    function goBack() {
        uploadCancellation.current?.abort();
        // Belongs to the attempt being left behind, not to the next one.
        setWrongPassphrase(false);

        const previous = PREVIOUS_STEP[step];
        if (previous) {
            setStep(previous);
        } else {
            onBack?.();
        }
    }

    /**
     * Whether there is anywhere to go back to: an earlier step of the restore, or the step of the
     * wizard that led into it. The replacement itself has neither, and cannot be interrupted anyway.
     */
    const canGoBack = step !== "restoring" && (!!PREVIOUS_STEP[step] || !!onBack);

    function onRestoreFailed(failure: { error?: string; reason?: string }) {
        if (failure.reason && PASSPHRASE_FAILURES.has(failure.reason)) {
            // The backup is still on the server, so only the passphrase has to be given again.
            setWrongPassphrase(true);
            setStep("passphrase");
            return;
        }

        setStep("picking");
        raiseError(headlineFor(failure.reason), failure.error);
    }

    return (
        <SetupPage
            className="restore-from-backup top-aligned"
            title={t("setup.restore-from-backup")}
            description={step === "picking" ? t("setup.restore-from-backup-page-description") : undefined}
            illustration={<Icon icon="bx bx-archive-in" className="illustration-icon" />}
            error={error}
            errorId={errorId}
            // Offered only where there is somewhere to go: not once the database is being replaced,
            // and not from the first step of a restore that is the whole of what the wizard was
            // opened for.
            onBack={canGoBack ? goBack : undefined}
        >
            {/* In the flow rather than filling the page: each step is a different height, and the
                one arriving is what the page should be as tall as. */}
            <SlidePages current={step} order={STEP_ORDER} inFlow>
                {(shown) => (
                    <>
                        {shown === "picking" && (
                            <PickBackup backups={backups} onPick={restore} onUpload={uploadAndRestore} onFailure={raiseError} />
                        )}
                        {shown === "uploading" && upload && <UploadProgress upload={upload} />}
                        {shown === "passphrase" && selection && (
                            <AskPassphrase
                                wrong={wrongPassphrase}
                                onSubmit={(passphrase) => {
                                    setWrongPassphrase(false);

                                    // Standalone still has the file it was given, so answering the
                                    // prompt starts again from it rather than from a server's copy.
                                    const backup = localBackup.current;
                                    void (backup ? restoreLocally(backup, passphrase) : restore(selection, passphrase));
                                }}
                            />
                        )}
                        {shown === "restoring" && (
                            <RestoreProgress
                                reported={localProgress}
                                onRestored={onRestored}
                                onFailed={onRestoreFailed}
                            />
                        )}
                    </>
                )}
            </SlidePages>
        </SetupPage>
    );
}

/**
 * A failure as the user needs it: what went wrong in a sentence about backups, with the technical
 * detail kept underneath.
 *
 * The detail is not dropped, because it is what a bug report is made of and what tells two identical-
 * looking failures apart. It is just no longer the whole message: "The file is not a SQLite database"
 * answers a question nobody standing in front of this screen asked.
 */
function Failure({ headline, detail }: { headline: string; detail?: string }) {
    return (
        <>
            <span class="restore-error-headline">{headline}</span>
            {detail && <small class="restore-error-detail selectable-text">{detail}</small>}
        </>
    );
}

/**
 * The sentence for an upload that did not finish.
 *
 * A connection that goes away is waited out rather than reported, so an upload only fails here once
 * there is nothing left to wait for. The two endings differ in what the user should do next: an
 * upload the server no longer holds has to be started again, while anything else is a reason it
 * refused, and telling them to try again would be telling them to repeat it.
 */
function uploadFailureHeadline(e: unknown): string {
    const gone = e instanceof ChunkedUploadError && (e.status === 404 || e.status === 410);

    return gone ? t("setup.restore-error-upload-interrupted") : t("setup.restore-error-upload-failed");
}

/** What a thrown failure has to say for itself, for the detail line under the headline. */
function detailOf(e: unknown): string | undefined {
    const message = e instanceof Error ? e.message : String(e);

    return message || undefined;
}

/**
 * The sentence for a failure, chosen from the reason the server reported rather than from its
 * message, which is fixed English meant for the log.
 *
 * Most of the reasons say the same thing to a user: the file cannot be used. The ones listed here are
 * the ones where that would be misleading, because something other than the backup is at fault or
 * because there is something the user could go and do about it.
 */
function headlineFor(reason: string | undefined): string {
    switch (reason) {
        case "database-too-new": return t("setup.restore-error-too-new");
        case "database-too-old": return t("setup.restore-error-too-old");
        case "database-not-initialized": return t("setup.restore-error-unfinished");
        case "swap-failed": return t("setup.restore-error-swap-failed");
        case "swap-failed-reload": return t("setup.restore-error-swap-failed-reload");
        case "check-failed": return t("setup.restore-error-check-failed");
        case "restore-failed": return t("setup.restore-error-failed");
        case "backup-incomplete": return t("setup.restore-error-incomplete");
        case "migration-failed": return t("setup.restore-error-would-not-open");
        case "restore-refused": return t("setup.restore-error-refused");
        case "already-initialized": return t("setup.restore-error-already-initialized");
        default: return t("setup.restore-error-unusable");
    }
}

/** Which backup is being restored, and where it is. */
interface Selection {
    /** `existing` names a backup on this device; `pending` is one the server already holds. */
    source: "pending" | "existing";
    fileName: string;
    /** Only for a backup already on the server. */
    filePath?: string;
    encrypted?: boolean;
}

interface UploadState {
    sentBytes: number;
    totalBytes: number;
    fraction: number;
    /** Averaged over the transfer so far, so it settles rather than jumping about between pieces. */
    bytesPerSecond: number;
    /** Whether the upload is waiting on a connection that has gone away. */
    reconnecting: boolean;
}

/** The backups already here, and the way to a file that is not. */
function PickBackup({ backups, onPick, onUpload, onFailure }: {
    /** What was found, or `null` while that is still being asked. */
    backups: DatabaseBackup[] | null;
    onPick: (selection: Selection) => void;
    onUpload: (file: File) => void;
    onFailure: (headline: string, detail?: string) => void;
}) {
    const fileInput = useRef<HTMLInputElement>(null);
    // The desktop can read the file where it lies; a browser has to be handed it first.
    const nativePicker = window.electronApi?.restore;

    async function pickNatively() {
        const picked = await nativePicker?.pickBackup();
        if (!picked || picked.status === "cancelled") {
            return;
        }
        if (picked.status === "error" || !picked.fileName) {
            onFailure(t("setup.restore-error-could-not-start"), picked.message);
            return;
        }

        // Already waiting on the other side of the bridge, so this goes straight to restoring it.
        onPick({ source: "pending", fileName: picked.fileName, encrypted: picked.encrypted });
    }

    const sorted = [ ...(backups ?? []) ].sort((a, b) => (a.mtime < b.mtime ? 1 : -1));

    return (
        <>
            {/* A row rather than a section of its own: choosing a file and choosing one of the
                backups already here are the same decision, so they read as one list of ways in. */}
            <Card>
                <CardSection
                    className="restore-backup-row restore-choose-file"
                    onAction={nativePicker ? pickNatively : () => fileInput.current?.click()}
                >
                    <Icon icon="bx bx-folder-open" />

                    <div class="restore-backup-details">
                        <div class="restore-backup-name">{t("setup.restore-choose-file")}</div>
                        {/* One line for both ways in: selecting the file is the same act whether it
                            is then uploaded or read where it lies. */}
                        <div class="restore-backup-description">{t("setup.restore-choose-file-description")}</div>
                    </div>

                    <Icon icon="bx bx-chevron-right" />
                </CardSection>

                {/* Outside the row it belongs to: a hidden input inside it would have its own click
                    bubble back to the row that opened it, and open it again. */}
                {!nativePicker && (
                    <input
                        ref={fileInput}
                        type="file"
                        accept={fileAccept(".db,.tnbackup")}
                        class="restore-file-input"
                        onChange={(e) => {
                            const file = (e.target as HTMLInputElement).files?.[0];
                            if (file) {
                                onUpload(file);
                            }
                        }}
                    />
                )}
            </Card>

            {/* Absent until there is something to list, which on a device being set up for the first
                time is the usual case: an empty card would only take up the screen to say that a
                place the user has never been to holds nothing. */}
            {backups === null ? (
                <Card heading={t("setup.restore-existing-backups")}>
                    <CardSection className="restore-loading">
                        <Icon icon="bx bx-loader-circle bx-spin" /> {t("setup.restore-looking-for-backups")}
                    </CardSection>
                </Card>
            ) : sorted.length > 0 && (
                <Card heading={t("setup.restore-existing-backups")}>
                    {sorted.map((backup) => (
                        <CardSection
                            key={backup.filePath}
                            className="restore-backup-row"
                            onAction={() => onPick({
                                source: "existing",
                                fileName: backup.fileName,
                                filePath: backup.filePath,
                                encrypted: backup.encrypted
                            })}
                        >
                            <Icon icon={backup.encrypted ? "bx bx-lock-alt" : "bx bx-data"} />

                            <div class="restore-backup-details">
                                <div class="restore-backup-title">
                                    <span class="restore-backup-name">{backup.fileName}</span>
                                    <DatabaseFileBadges badges={describeDatabaseFormat(backup)} />
                                </div>

                                <div class="restore-backup-description">{describeDatabaseFile(backup)}</div>
                            </div>

                            <Icon icon="bx bx-chevron-right" />
                        </CardSection>
                    ))}
                </Card>
            )}
        </>
    );
}

function UploadProgress({ upload }: { upload: UploadState }) {
    return (
        <Card className="restore-progress">
            <CardSection>
                <div class="restore-progress-label">
                    <Icon icon="bx bx-loader-circle bx-spin" /> {t("setup.restore-uploading")}
                </div>

                <ProgressBar value={upload.sentBytes} max={upload.totalBytes} />

                <div class="restore-progress-detail">
                    <span>
                        {t("setup.restore-uploaded-so-far", {
                            sent: formatSize(upload.sentBytes),
                            total: formatSize(upload.totalBytes)
                        })}
                    </span>

                    {/* In place of the speed while the connection is gone, which is where the eye
                        already is and where a rate averaged over a transfer that has stopped would
                        otherwise sit unchanged, saying everything is fine. */}
                    {upload.reconnecting ? (
                        <span class="restore-upload-reconnecting">
                            <Icon icon="bx bx-wifi-off" /> {t("setup.restore-upload-reconnecting")}
                        </span>
                    ) : (
                        // Only once something has actually gone out: before the first piece lands
                        // there is no elapsed time to divide by, and a rate of nothing says nothing.
                        upload.bytesPerSecond > 0 && (
                            <span class="restore-upload-speed">
                                {t("setup.restore-upload-speed", { speed: formatSize(upload.bytesPerSecond) })}
                            </span>
                        )
                    )}
                </div>
            </CardSection>
        </Card>
    );
}

function AskPassphrase({ wrong, onSubmit }: { wrong: boolean; onSubmit: (passphrase: string) => void }) {
    const [ passphrase, setPassphrase ] = useState("");
    const inputRef = useRef<HTMLInputElement>(null);

    // Without `preventScroll` the browser scrolls the page to reveal a field that is still sliding
    // in from off-screen, which drags the heading along with it and fights the animation the whole
    // way. The field is about to be in view on its own.
    useEffect(() => inputRef.current?.focus({ preventScroll: true }), []);

    return (
        <form onSubmit={(e) => {
            e.preventDefault();
            if (passphrase) {
                onSubmit(passphrase);
            }
        }}>
            <Card>
                <CardSection className="restore-passphrase">
                    <FormGroup
                        name="backupPassphrase"
                        label={t("setup.restore-passphrase")}
                        description={t("setup.restore-passphrase-description")}
                        error={wrong ? t("setup.restore-wrong-passphrase") : undefined}
                    >
                        <FormTextBox
                            inputRef={inputRef}
                            type="password"
                            currentValue={passphrase}
                            onChange={setPassphrase}
                            autocomplete="off"
                        />
                    </FormGroup>
                </CardSection>
            </Card>

            <div class="restore-passphrase-actions">
                <Button kind="primary" text={t("setup.restore-continue")} disabled={!passphrase} />
            </div>
        </form>
    );
}

/** What the server says about the restore it is running. */
interface RestoreStatus {
    stage: string;
    /** How far through the current stage, where that stage can say; absent where it cannot. */
    fraction?: number;
    error?: string;
    reason?: string;
}

function RestoreProgress({ reported, onRestored, onFailed }: {
    /** Where the restore has got to, where it says so itself; polled when it does not. */
    reported?: RestoreStatus | null;
    onRestored: () => void;
    onFailed: (failure: { error?: string; reason?: string }) => void;
}) {
    const [ stage, setStage ] = useState<string>("staging");
    const [ fraction, setFraction ] = useState<number | null>(null);
    const polled = !reported;

    useEffect(() => {
        // A restore that reports itself is already telling this component everything it knows, and
        // there is nothing on the other end to ask besides.
        if (!polled) {
            return;
        }

        const interval = setInterval(async () => {
            let restore;
            try {
                ({ restore } = await server.get<{ restore: RestoreStatus | null }>("setup/restore/status"));
            } catch {
                // The database is detached for the moment it takes to exchange the files, which any
                // request landing in that moment cannot be answered through. The next one can.
                return;
            }

            if (!restore) {
                return;
            }
            if (restore.stage === "done") {
                clearInterval(interval);
                onRestored();
                return;
            }
            if (restore.stage === "failed") {
                clearInterval(interval);
                onFailed(restore);
                return;
            }

            setStage(restore.stage);
            setFraction(restore.fraction ?? null);
        }, 1000);

        return () => clearInterval(interval);
    }, [ polled, onRestored, onFailed ]);

    const shownStage = reported?.stage ?? stage;
    const shownFraction = (reported ? reported.fraction : fraction) ?? null;

    // Only what is happening now, rather than the four steps as a list. Preparing the backup is the
    // one that takes any time; the rest go by too quickly to be read, so a list of them mostly shows
    // the user three things they will never see happen.
    return (
        <div class="restore-current-step">
            <div class="restore-step-name">{stageLabel(shownStage)}</div>

            {/* Only where the step can say how far it has got. The ones that cannot show nothing,
                rather than an empty bar that never moves. */}
            {shownFraction !== null && (
                <div class="restore-stage-progress">
                    <ProgressBar value={shownFraction} max={1} />
                    <span>{Math.floor(shownFraction * 100)}%</span>
                </div>
            )}

            <small class="restore-do-not-close">{t("setup.restore-do-not-close")}</small>
        </div>
    );
}

/**
 * What to call the stage the restore says it is at.
 *
 * Spelled out rather than composed into a key. Built as `restore-stage-${stage}`, a stage nobody
 * wrote a sentence for printed its own key at the user: `done` is reported by the browser-only
 * restore in the moment between the last step and the reload, and that moment is the one the user
 * is watching hardest.
 *
 * `done` is not a step at all but what follows the last one, so it says what is about to happen
 * instead of naming something already finished. A failure says nothing here, because the screen it
 * is about to be replaced by says it properly.
 */
export function stageLabel(stage: string): string {
    switch (stage) {
        case "validating": return t("setup.restore-stage-validating");
        case "swapping": return t("setup.restore-stage-swapping");
        case "migrating": return t("setup.restore-stage-migrating");
        case "done": return t("setup.redirecting");
        case "failed": return "";
        // Staging both as itself and as the answer for a stage this does not know: whatever it is
        // called, a restore that has not ended is one still working on the backup.
        default: return t("setup.restore-stage-staging");
    }
}