All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Settings → Data → Import gets "Restore a full backup" in place of the V1 import row. The zip from "Download backup" is uploaded and replaces the database, every setting and the uploaded files on the running server: - the staged database is upgraded to this schema (newer backups are refused), saved keys are re-encrypted for this server's key, interrupted jobs are marked, and the restoring session is carried over; - a pre-restore snapshot is written, running generations stop, and the file is swapped under the open DB handle (DB.replaceWith); uploads and media are copied into place and background work restarts. The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
222 lines
10 KiB
TypeScript
222 lines
10 KiB
TypeScript
/**
|
|
* Restoring a full backup zip ("Download backup" in Settings → Data) into the running app.
|
|
*
|
|
* 1. The zip is unpacked into a staging folder inside the data folder, one file at a time
|
|
* (only study.db, secret.key, manifest.json, uploads/* and media/* are accepted).
|
|
* 2. The staged database is opened and upgraded to this version's schema (a backup from a
|
|
* newer version is refused), saved AI keys are re-encrypted for this server's key, jobs that
|
|
* were running when the backup was taken are marked interrupted, and the signed-in session
|
|
* is carried over so the person restoring stays signed in.
|
|
* 3. A snapshot of the current database is written to the backups folder, running generations
|
|
* stop, and the database file is swapped under the open handle (`DB.replaceWith`).
|
|
* 4. Uploaded files and images from the backup are copied into place (files already here that
|
|
* the backup does not have are left alone), and background work restarts on the new data.
|
|
*/
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { Unzip, UnzipInflate, type UnzipFile } from 'fflate';
|
|
import { decryptSecret, encryptSecret } from '../crypto.ts';
|
|
import { DB, migrate } from '../db.ts';
|
|
import { badRequest, type AppContext } from '../http.ts';
|
|
import { cancelAllGenerations, tidyDrafts } from '../ai/generate.ts';
|
|
import { forgetMcpSessions, warmMcpServers } from '../ai/mcp.ts';
|
|
import { createSnapshot } from './backup.ts';
|
|
import { resumeQueue } from './documents.ts';
|
|
import { notifyChange } from './events.ts';
|
|
import { resetVectorCache, scheduleIndexing } from './semantic.ts';
|
|
|
|
export interface RestoreSummary {
|
|
backupCreatedAt: string | null;
|
|
classes: number;
|
|
quizzes: number;
|
|
decks: number;
|
|
notes: number;
|
|
documents: number;
|
|
attempts: number;
|
|
files: number;
|
|
/** Saved keys (AI providers, MCP, web search) re-encrypted for this server. */
|
|
keysMoved: number;
|
|
/** Saved keys that could not be read: the backup's secret.key or APP_SECRET is not available. */
|
|
keysUnreadable: number;
|
|
/** The snapshot of the database as it was before the restore. */
|
|
safetySnapshot: string;
|
|
/** Generations that were running and were stopped. */
|
|
stoppedJobs: number;
|
|
}
|
|
|
|
const ACCEPTED = /^(?:study\.db|secret\.key|manifest\.json|(?:uploads|media)\/[^/\\]+)$/;
|
|
/** An encrypted value: `v1.<12-byte iv>.<16-byte tag>.<ciphertext>` in base64url. */
|
|
const SEALED = /v1\.[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]+/g;
|
|
|
|
/** Unpacks the accepted entries of a zip file into `dir` without holding the whole zip in memory. */
|
|
async function unpack(zipFile: string, dir: string, maxBytes: number): Promise<string[]> {
|
|
const written: string[] = [];
|
|
let failure: Error | null = null;
|
|
let total = 0;
|
|
const unzip = new Unzip((file: UnzipFile) => {
|
|
const name = file.name.replace(/\\/g, '/');
|
|
if (!ACCEPTED.test(name) || name.split('/').some((p) => p === '..' || p === '.' || p === '')) return;
|
|
const target = path.join(dir, ...name.split('/'));
|
|
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
const fd = fs.openSync(target, 'w');
|
|
file.ondata = (err, chunk, final) => {
|
|
if (failure) return;
|
|
if (err) failure = err;
|
|
else {
|
|
total += chunk.length;
|
|
if (total > maxBytes) failure = badRequest('The backup is larger than this server accepts.');
|
|
else fs.writeSync(fd, chunk);
|
|
}
|
|
if (final || failure) {
|
|
fs.closeSync(fd);
|
|
if (final && !failure) written.push(name);
|
|
}
|
|
};
|
|
file.start();
|
|
});
|
|
unzip.register(UnzipInflate);
|
|
for await (const chunk of fs.createReadStream(zipFile, { highWaterMark: 1 << 20 })) {
|
|
unzip.push(chunk as Uint8Array);
|
|
if (failure) break;
|
|
}
|
|
if (!failure) unzip.push(new Uint8Array(0), true);
|
|
if (failure) throw failure;
|
|
return written;
|
|
}
|
|
|
|
/** The 32-byte key in a backup's secret.key, or null when missing or damaged. */
|
|
function readKey(file: string): Buffer | null {
|
|
try {
|
|
const raw = Buffer.from(fs.readFileSync(file, 'utf8').trim(), 'base64');
|
|
return raw.length === 32 ? raw : null;
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Re-encrypts every sealed value in the staged database (wherever it is stored: provider
|
|
* columns, settings JSON) from the backup's key to this server's key. Values this server can
|
|
* already read are left as they are.
|
|
*/
|
|
function rekey(db: DB, from: Buffer | null, to: Buffer): { moved: number; unreadable: number } {
|
|
let moved = 0;
|
|
let unreadable = 0;
|
|
const tables = db.all<{ name: string; sql: string | null }>("SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'");
|
|
const virtual = tables.filter((t) => /^CREATE VIRTUAL TABLE/i.test(t.sql ?? '')).map((t) => t.name);
|
|
for (const t of tables) {
|
|
if (virtual.includes(t.name) || virtual.some((v) => t.name.startsWith(`${v}_`)) || /WITHOUT ROWID/i.test(t.sql ?? '')) continue;
|
|
const quoted = `"${t.name.replace(/"/g, '""')}"`;
|
|
const columns = db.all<{ name: string; type: string }>(`PRAGMA table_info(${quoted})`).filter((c) => /TEXT|^$/i.test(c.type));
|
|
for (const col of columns) {
|
|
const c = `"${col.name.replace(/"/g, '""')}"`;
|
|
const rows = db.all<{ rid: number; v: string }>(`SELECT rowid AS rid, ${c} AS v FROM ${quoted} WHERE typeof(${c}) = 'text' AND ${c} LIKE '%v1.%'`);
|
|
for (const row of rows) {
|
|
let changed = false;
|
|
const next = row.v.replace(SEALED, (sealed) => {
|
|
if (decryptSecret(sealed, to) !== null) return sealed;
|
|
const plain = from ? decryptSecret(sealed, from) : null;
|
|
if (plain === null) {
|
|
unreadable += 1;
|
|
return sealed;
|
|
}
|
|
moved += 1;
|
|
changed = true;
|
|
return encryptSecret(plain, to);
|
|
});
|
|
if (changed) db.run(`UPDATE ${quoted} SET ${c} = ? WHERE rowid = ?`, next, row.rid);
|
|
}
|
|
}
|
|
}
|
|
return { moved, unreadable };
|
|
}
|
|
|
|
/** Copies the signed-in session into the restored database so the person restoring stays signed in. */
|
|
function carrySession(from: DB, to: DB, tokenHash: string | null): void {
|
|
if (!tokenHash) return;
|
|
const row = from.get<Record<string, unknown>>('SELECT * FROM sessions WHERE token_hash = ?', tokenHash);
|
|
if (!row) return;
|
|
const known = new Set(to.all<{ name: string }>('PRAGMA table_info(sessions)').map((c) => c.name));
|
|
const cols = Object.keys(row).filter((k) => known.has(k));
|
|
to.run(`INSERT OR REPLACE INTO sessions (${cols.join(', ')}) VALUES (${cols.map(() => '?').join(', ')})`, ...cols.map((k) => row[k] as string | number | null));
|
|
}
|
|
|
|
export async function restoreFullBackup(app: AppContext, zipFile: string, opts: { sessionHash?: string | null; maxBytes?: number } = {}): Promise<RestoreSummary> {
|
|
const { config } = app;
|
|
const stage = path.join(config.dataDir, `.restore-${Date.now()}`);
|
|
fs.mkdirSync(stage, { recursive: true });
|
|
try {
|
|
const names = await unpack(zipFile, stage, opts.maxBytes ?? 20 * 1024 ** 3);
|
|
if (!names.includes('study.db')) throw badRequest('This is not a Study Desk full backup: it has no study.db. Use "Download backup" to make one.');
|
|
const manifest = (() => {
|
|
try {
|
|
return JSON.parse(fs.readFileSync(path.join(stage, 'manifest.json'), 'utf8')) as { format?: string; createdAt?: string };
|
|
} catch {
|
|
return null;
|
|
}
|
|
})();
|
|
if (manifest && manifest.format !== 'studydesk-backup') throw badRequest('This zip is not a Study Desk full backup.');
|
|
const stagedDb = path.join(stage, 'study.db');
|
|
const head = Buffer.alloc(16);
|
|
const fd = fs.openSync(stagedDb, 'r');
|
|
fs.readSync(fd, head, 0, 16, 0);
|
|
fs.closeSync(fd);
|
|
if (head.toString('latin1', 0, 15) !== 'SQLite format 3') throw badRequest('The database in this backup is damaged.');
|
|
|
|
// Upgrade the backup to this version's schema, then prepare it while it is still offline.
|
|
const staged = new DB(stagedDb);
|
|
try {
|
|
migrate(staged);
|
|
} catch (e) {
|
|
staged.close();
|
|
throw badRequest(e instanceof Error && /newer version/.test(e.message) ? 'This backup was made by a newer version of Study Desk. Update this server first.' : 'The database in this backup could not be opened.');
|
|
}
|
|
let keys: { moved: number; unreadable: number };
|
|
const count = (table: string) => staged.get<{ n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)?.n ?? 0;
|
|
let counts: Pick<RestoreSummary, 'classes' | 'quizzes' | 'decks' | 'notes' | 'documents' | 'attempts'>;
|
|
try {
|
|
keys = staged.tx(() => rekey(staged, readKey(path.join(stage, 'secret.key')), config.secretKey));
|
|
tidyDrafts(staged);
|
|
carrySession(app.db, staged, opts.sessionHash ?? null);
|
|
counts = { classes: count('classes'), quizzes: count('quizzes'), decks: count('decks'), notes: count('notes'), documents: count('documents'), attempts: count('attempts') };
|
|
} finally {
|
|
staged.close();
|
|
}
|
|
|
|
// Point of no return: keep a copy of what is here now, stop work, and swap.
|
|
const safety = createSnapshot(app, 'pre-restore');
|
|
const stoppedJobs = cancelAllGenerations();
|
|
forgetMcpSessions();
|
|
app.db.replaceWith(stagedDb);
|
|
|
|
let files = 0;
|
|
for (const [sub, target] of [
|
|
['uploads', config.uploadsDir],
|
|
['media', config.mediaDir],
|
|
] as const) {
|
|
const from = path.join(stage, sub);
|
|
if (!fs.existsSync(from)) continue;
|
|
fs.mkdirSync(target, { recursive: true });
|
|
for (const f of fs.readdirSync(from)) {
|
|
const dest = path.join(target, f);
|
|
fs.rmSync(dest, { force: true });
|
|
fs.renameSync(path.join(from, f), dest);
|
|
files += 1;
|
|
}
|
|
}
|
|
|
|
resetVectorCache();
|
|
resumeQueue(app);
|
|
scheduleIndexing(app);
|
|
warmMcpServers(app);
|
|
for (const topic of ['library', 'drafts', 'documents'] as const) notifyChange(topic);
|
|
app.log('info', `Full backup restored (${counts.classes} classes, ${files} files); previous database kept as ${safety.name}`);
|
|
return { backupCreatedAt: manifest?.createdAt ?? null, ...counts, files, keysMoved: keys.moved, keysUnreadable: keys.unreadable, safetySnapshot: safety.name, stoppedJobs };
|
|
} finally {
|
|
try {
|
|
fs.rmSync(stage, { recursive: true, force: true });
|
|
} catch (e) {
|
|
app.log('warn', `Could not remove the restore staging folder ${stage}`, e instanceof Error ? e.message : e);
|
|
}
|
|
}
|
|
}
|