diff --git a/PROGRESS.md b/PROGRESS.md index b69fe9c..0c5d137 100644 --- a/PROGRESS.md +++ b/PROGRESS.md @@ -204,6 +204,12 @@ sheet on phones. The drawer is resizable for both (drag the edge, 340-760 px, do reset, remembered per browser). Checked in the browser at 1440, 1100 and 375 px wide, with a live answer streamed on a share link. +Settings → Data → Import now restores a full backup zip in place of the V1 import row (the +`/api/import/v1` endpoint stays for the V1 cutover; see docs/MIGRATION.md). The restore replaces +the database, settings and files without a restart, re-encrypts saved keys for this server, keeps +a `pre-restore-*` snapshot and keeps the person signed in. Tests: `tests/restore.test.ts`; +round trip on the rev1 copy: 1 MB backup restored in 75 ms, same library, still signed in. + Tests: `tests/revision5.test.ts`. Live check on the rev1 copy with DeepSeek flash: a visitor's 10-card set was written, named ("Heparin, Furosemide, and Dosage Calculations"), saved and listed once with the New tag; cards were single facts with no hints. The rev1 copy's 401 was its @@ -212,7 +218,7 @@ stored DeepSeek connection still holding the old key; it was updated from `.env` ## Verification status Baseline: 162 tests passed, TypeScript passed and production web/server builds passed. -Added six regression tests. Full `npm run check` passes: **289 tests** (rationale layout, 2026-11-16; 285 after varied openers; 281 after generation steps; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript +Added six regression tests. Full `npm run check` passes: **291 tests** (full-backup restore, 2026-11-16; 289 after rationale layout; 285 after varied openers; 281 after generation steps; 280 after the check loop and second review; 274 after the fifth revision; 261 after share-link generation, 2026-11-15; 257 after the fourth revision; 247 after the third, 208 after the second, 181 on 2026-11-12), TypeScript and both production builds. The Docker `test` stage runs the same 181 tests on Node 24. Tests were run with loopback access for the mock provider. The earlier agent manually exercised quiz completion/results, flashcards, streak effects, diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index bd2ec55..9996912 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -94,6 +94,29 @@ cannot read an included file fails rather than silently substituting an empty fi Avoid changing or deleting source files while making a full ZIP; filesystem content is not transactional with SQLite. +## Restoring a full backup in the app + +Settings → Data → **Restore a full backup** uploads a ZIP from "Download backup" and replaces +everything on the running server: content, progress, uploads, AI models and all settings. No +restart is needed. Steps (`server/services/restore.ts`): + +- The ZIP is unpacked into a staging folder inside the data folder. Only `study.db`, + `secret.key`, `manifest.json`, `uploads/*` and `media/*` are accepted. +- The staged database is upgraded to this version's schema. A backup from a newer version is + refused. +- Saved API keys are re-encrypted from the backup's `secret.key` to this server's key, so a + backup from another install keeps its AI connections. Keys sealed with an `APP_SECRET` this + server does not have are reported as unreadable and must be entered again. +- A `pre-restore-*` snapshot of the current database is written, running generations stop, and + the database file is swapped under the open handle. +- Files from the backup are copied over the uploads and media folders. Files already there are + left in place. +- The person restoring stays signed in. Later sign-ins use the backup's password. + +The upload is the raw ZIP body (up to 20 GB). A proxy may cap uploads well below that (Cloudflare's +free plan allows 100 MB per request). For a larger backup, restore through the server's own +address on the local network, or use the manual drill below. + ## Restore drill 1. Download a full ZIP and verify it opens. Stop the V2 container before restoring. diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 175ed06..928a36e 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -6,7 +6,10 @@ a separate data folder. It never upgrades a production V1 database in place. 1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself, stop V1 first; copying only a live WAL-mode `.db` can omit recent writes. 2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume. -3. In V2 Settings → Data → V1 import, select the **backup copy** and preview it. +3. Settings no longer shows the V1 import (its place went to restoring a full V2 backup), but + the endpoint remains. While signed in, preview the **backup copy** with + `POST /api/import/v1?preview=1` (multipart field `file`, header `X-Requested-With: studydesk`), + then import it without `?preview=1`. 4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted SQLite file read-only and creates new IDs in one transaction. A failed import rolls back. 5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and diff --git a/server/ai/generate.ts b/server/ai/generate.ts index 8d9ca1d..5be98cb 100644 --- a/server/ai/generate.ts +++ b/server/ai/generate.ts @@ -615,6 +615,14 @@ export function cancelGeneration(draftId: string): void { running.delete(draftId); } +/** Stops every running generation (before a full backup replaces the database). */ +export function cancelAllGenerations(): number { + const n = running.size; + for (const c of running.values()) c.abort(); + running.clear(); + return n; +} + /** Listeners for a running job's progress labels (the assistant shows them on its tool step). */ const progressListeners = new Map void>(); diff --git a/server/ai/mcp.ts b/server/ai/mcp.ts index 0909f8c..8dccfe6 100644 --- a/server/ai/mcp.ts +++ b/server/ai/mcp.ts @@ -366,6 +366,11 @@ function forget(serverId: string): void { sessions.delete(serverId); } +/** Drops every open MCP session (after a restore the servers and their credentials may differ). */ +export function forgetMcpSessions(): void { + sessions.clear(); +} + export class McpError extends Error { expired: boolean; /** The server answered 401: the credentials are missing, wrong or expired. */ diff --git a/server/auth.ts b/server/auth.ts index 3871745..8283b84 100644 --- a/server/auth.ts +++ b/server/auth.ts @@ -97,6 +97,12 @@ function createSession(app: AppContext, c: Context): void { setCookie(c, COOKIE, token, { httpOnly: true, sameSite: 'Lax', secure, path: '/', maxAge: Math.floor(SESSION_MS / 1000) }); } +/** The stored hash of this request's session token, or null when there is no session cookie. */ +export function sessionHash(c: Context): string | null { + const token = getCookie(c, COOKIE); + return token ? sha256(token) : null; +} + export function isAuthenticated(app: AppContext, c: Context): boolean { const token = getCookie(c, COOKIE); if (!token) return false; diff --git a/server/db.ts b/server/db.ts index 8de0056..f3e315e 100644 --- a/server/db.ts +++ b/server/db.ts @@ -14,7 +14,7 @@ function bind(params: Param[]): (string | number | bigint | null | Uint8Array)[] * exactly what a one-user app in one container needs, with no native add-on to build. */ export class DB { - readonly raw: DatabaseSync; + private handle: DatabaseSync; readonly path: string; private statements = new Map(); private txDepth = 0; @@ -23,11 +23,53 @@ export class DB { constructor(file: string) { this.path = file; - this.raw = new DatabaseSync(file); - this.raw.exec('PRAGMA journal_mode = WAL'); - this.raw.exec('PRAGMA synchronous = NORMAL'); - this.raw.exec('PRAGMA foreign_keys = ON'); - this.raw.exec('PRAGMA busy_timeout = 5000'); + this.handle = DB.open(file); + } + + private static open(file: string): DatabaseSync { + const raw = new DatabaseSync(file); + raw.exec('PRAGMA journal_mode = WAL'); + raw.exec('PRAGMA synchronous = NORMAL'); + raw.exec('PRAGMA foreign_keys = ON'); + raw.exec('PRAGMA busy_timeout = 5000'); + return raw; + } + + /** The node:sqlite handle. Changes when a full backup is restored (`replaceWith`). */ + get raw(): DatabaseSync { + return this.handle; + } + + /** + * Swaps the database file for `file` (a complete, closed SQLite file in the same folder) under + * this same object, so every part of the app keeps working with the restored data. If the + * swap fails, the current database is reopened untouched. + */ + replaceWith(file: string): void { + if (this.txDepth > 0) throw new Error('A database transaction is still open.'); + if (this.path === ':memory:') throw new Error('An in-memory database cannot be replaced.'); + this.statements.clear(); + try { + this.handle.exec('PRAGMA wal_checkpoint(TRUNCATE)'); + } catch { + /* closing writes it anyway */ + } + this.handle.close(); + try { + const aside = `${this.path}.replaced`; + fs.rmSync(aside, { force: true }); + fs.renameSync(this.path, aside); + try { + fs.renameSync(file, this.path); + } catch (e) { + fs.renameSync(aside, this.path); + throw e; + } + for (const ext of ['-wal', '-shm']) fs.rmSync(`${this.path}${ext}`, { force: true }); + fs.rmSync(aside, { force: true }); + } finally { + this.handle = DB.open(this.path); + } } private stmt(sql: string): StatementSync { diff --git a/server/routes/data.ts b/server/routes/data.ts index 298c429..a6322d0 100644 --- a/server/routes/data.ts +++ b/server/routes/data.ts @@ -11,10 +11,14 @@ import { appSettingsSchema, deleteSetting, getAppSettings, getSetting, setSettin import { createSnapshot, exportBundle, fullBackupStream, listBackups } from '../services/backup.ts'; import { createClass, createDeck, createFolder, createNote, createQuiz, draftCardToInput, draftQuestionToInput, getClass, getDeck, getQuiz, listCards, listQuestions } from '../services/content.ts'; import { createTemplate, deleteTemplate, listTemplates, resetTemplate, templateInputSchema, updateTemplate } from '../services/templates.ts'; +import { restoreFullBackup } from '../services/restore.ts'; import { importV1 } from '../services/v1import.ts'; +import { sessionHash } from '../auth.ts'; import { slugify } from '../util.ts'; export const APP_VERSION = '2.0.0'; +/** The largest full backup that can be restored through the app. */ +const RESTORE_MAX_BYTES = 20 * 1024 ** 3; function dirSize(dir: string): number { try { @@ -176,7 +180,45 @@ export function dataRoutes(app: AppContext): Hono { return c.json({ summary }, 201); }); - /** Migration from a V1 database file. `?preview=1` only reports what would be imported. */ + /** + * Restores a full backup zip (from "Download backup"): the database with every setting, and the + * uploaded files. The zip is the raw request body, streamed to disk. See services/restore.ts. + */ + r.post('/backup/restore', async (c) => { + const max = RESTORE_MAX_BYTES; + const declared = Number(c.req.header('content-length') ?? 0); + if (declared > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.'); + const body = c.req.raw.body; + if (!body) throw badRequest('Choose a backup zip'); + const tmp = path.join(app.config.dataDir, `.restore-upload-${Date.now()}.zip`); + try { + let size = 0; + const out = fs.createWriteStream(tmp); + try { + for await (const chunk of body as unknown as AsyncIterable) { + size += chunk.length; + if (size > max) throw new HttpError(413, 'too_large', 'The backup is larger than this server accepts.'); + if (!out.write(chunk)) await new Promise((r) => out.once('drain', r)); + } + } finally { + await new Promise((resolve, reject) => out.end((err?: Error | null) => (err ? reject(err) : resolve()))); + } + if (size < 22) throw badRequest('Choose a backup zip'); + const head = Buffer.alloc(4); + const fd = fs.openSync(tmp, 'r'); + fs.readSync(fd, head, 0, 4, 0); + fs.closeSync(fd); + if (head.readUInt32LE(0) !== 0x04034b50) throw badRequest('That file is not a zip. Choose a file made with "Download backup".'); + return c.json({ summary: await restoreFullBackup(app, tmp, { sessionHash: sessionHash(c) }) }); + } finally { + fs.rmSync(tmp, { force: true }); + } + }); + + /** + * Migration from a V1 database file. `?preview=1` only reports what would be imported. Not in + * Settings any more (full-backup restore took its place); see docs/MIGRATION.md. + */ r.post('/import/v1', bodyLimit({ maxSize: 500 * 1024 * 1024 }), async (c) => { const form = await c.req.parseBody().catch(() => { throw badRequest('Upload could not be read'); diff --git a/server/services/restore.ts b/server/services/restore.ts new file mode 100644 index 0000000..6b3937b --- /dev/null +++ b/server/services/restore.ts @@ -0,0 +1,222 @@ +/** + * 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>.` 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 { + 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>('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 { + 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; + 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); + } + } +} diff --git a/server/services/semantic.ts b/server/services/semantic.ts index f207bad..fb23180 100644 --- a/server/services/semantic.ts +++ b/server/services/semantic.ts @@ -251,6 +251,12 @@ interface VectorCache { } let cache: VectorCache | null = null; +/** Drops the in-memory vectors (after a restore replaced the database). */ +export function resetVectorCache(): void { + cache = null; + queryCache.clear(); +} + function loadVectors(db: DB, key: string): VectorCache | null { const sig = db.get<{ n: number; m: number | null }>('SELECT COUNT(*) AS n, MAX(chunk_id) AS m FROM chunk_vectors WHERE model_key = ?', key)!; if (sig.n === 0) return null; diff --git a/tests/restore.test.ts b/tests/restore.test.ts new file mode 100644 index 0000000..b074867 --- /dev/null +++ b/tests/restore.test.ts @@ -0,0 +1,101 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { DatabaseSync } from 'node:sqlite'; +import { strToU8, unzipSync, zipSync } from 'fflate'; +import { afterEach, describe, expect, it } from 'vitest'; +import { decryptSecret, encryptSecret } from '../server/crypto.ts'; +import { getSetting, setSetting } from '../server/settings.ts'; +import { createTestApp, type TestApp } from './helpers.ts'; + +const apps: TestApp[] = []; +async function newApp(): Promise { + const app = await createTestApp(); + apps.push(app); + return app; +} +afterEach(() => { + for (const app of apps.splice(0)) { + try { + app.ctx.db.close(); + } catch { + /* already closed */ + } + fs.rmSync(app.dir, { recursive: true, force: true }); + } +}); + +async function backupOf(app: TestApp): Promise { + const res = await app.raw('GET', '/api/backup/download'); + expect(res.status).toBe(200); + return new Uint8Array(await res.arrayBuffer()); +} + +const restore = (app: TestApp, zip: Uint8Array) => app.raw('POST', '/api/backup/restore', { headers: { 'content-type': 'application/zip' }, body: zip }); + +describe('restoring a full backup', () => { + it('replaces the data, settings and files, moves saved keys to this server and keeps the session', async () => { + const source = await newApp(); + await source.api('POST', '/api/classes', { name: 'Backed up class' }); + setSetting(source.ctx.db, 'test.sealed', { apiKey: encryptSecret('test-only-key', source.ctx.config.secretKey) }); + setSetting(source.ctx.db, 'test.plain', 'kept'); + fs.writeFileSync(path.join(source.ctx.config.uploadsDir, 'lecture.txt'), 'Uploaded lecture'); + const zip = await backupOf(source); + + const target = await newApp(); + await target.api('POST', '/api/classes', { name: 'Replaced class' }); + fs.writeFileSync(path.join(target.ctx.config.uploadsDir, 'local-only.txt'), 'Left alone'); + // Two installs have different keys, so the sealed key must be re-encrypted to be readable. + expect(target.ctx.config.secretKey.equals(source.ctx.config.secretKey)).toBe(false); + + const res = await restore(target, zip); + const body = (await res.json()) as { summary: Record }; + expect(res.status).toBe(200); + expect(body.summary).toMatchObject({ classes: 1, files: 1, keysMoved: 1, keysUnreadable: 0 }); + expect(String(body.summary.safetySnapshot)).toMatch(/^pre-restore-/); + + // Still signed in, now looking at the restored library. + const classes = await target.api('GET', '/api/classes'); + expect(classes.status).toBe(200); + expect(classes.body.classes.map((c: { name: string }) => c.name)).toEqual(['Backed up class']); + expect(getSetting(target.ctx.db, 'test.plain', '')).toBe('kept'); + const sealed = getSetting<{ apiKey: string }>(target.ctx.db, 'test.sealed', { apiKey: '' }).apiKey; + expect(decryptSecret(sealed, target.ctx.config.secretKey)).toBe('test-only-key'); + expect(fs.readFileSync(path.join(target.ctx.config.uploadsDir, 'lecture.txt'), 'utf8')).toBe('Uploaded lecture'); + expect(fs.existsSync(path.join(target.ctx.config.uploadsDir, 'local-only.txt'))).toBe(true); + + // The database as it was before is kept as a snapshot, and no staging files are left. + const before = new DatabaseSync(path.join(target.ctx.config.backupsDir, String(body.summary.safetySnapshot)), { readOnly: true }); + expect((before.prepare('SELECT name FROM classes').all() as { name: string }[]).map((r) => r.name)).toEqual(['Replaced class']); + before.close(); + expect(fs.readdirSync(target.ctx.config.dataDir).filter((f) => f.startsWith('.restore'))).toEqual([]); + + // The swapped handle keeps working for writes. + expect((await target.api('POST', '/api/classes', { name: 'After restore' })).status).toBe(201); + }); + + it('refuses files that are not a usable backup and leaves the data untouched', async () => { + const app = await newApp(); + await app.api('POST', '/api/classes', { name: 'Untouched' }); + + const notZip = await restore(app, strToU8('just some text, not a zip file at all')); + expect(notZip.status).toBe(400); + const noDb = await restore(app, zipSync({ 'notes.txt': strToU8('hello') })); + expect(noDb.status).toBe(400); + expect(((await noDb.json()) as { error: { message: string } }).error.message).toMatch(/no study\.db/); + + // A backup from a newer version (a migration this server does not know) is refused. + const files = unzipSync(await backupOf(app)); + const tmp = path.join(app.dir, 'newer.db'); + fs.writeFileSync(tmp, files['study.db']!); + const newer = new DatabaseSync(tmp); + newer.prepare('INSERT INTO schema_migrations (id, name, applied_at) VALUES (999999, ?, ?)').run('from_the_future', Date.now()); + newer.close(); + files['study.db'] = new Uint8Array(fs.readFileSync(tmp)); + const future = await restore(app, zipSync(files)); + expect(future.status).toBe(400); + expect(((await future.json()) as { error: { message: string } }).error.message).toMatch(/newer version/); + + const classes = await app.api('GET', '/api/classes'); + expect(classes.body.classes.map((c: { name: string }) => c.name)).toEqual(['Untouched']); + }); +}); diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts index 09f0db2..a33d066 100644 --- a/web/src/lib/api.ts +++ b/web/src/lib/api.ts @@ -79,12 +79,13 @@ export function errorMessage(e: unknown, fallback = 'Something went wrong.'): st return fallback; } -/** Uploads with progress (fetch cannot report upload progress). */ -export function uploadWithProgress(url: string, form: FormData, onProgress: (fraction: number) => void): Promise { +/** Uploads with progress (fetch cannot report upload progress). A Blob or File is sent as the raw body. */ +export function uploadWithProgress(url: string, form: FormData | Blob, onProgress: (fraction: number) => void): Promise { return new Promise((resolve, reject) => { const xhr = new XMLHttpRequest(); xhr.open('POST', url); xhr.setRequestHeader('X-Requested-With', 'studydesk'); + if (form instanceof Blob) xhr.setRequestHeader('Content-Type', form.type || 'application/octet-stream'); xhr.upload.onprogress = (e) => { if (e.lengthComputable) onProgress(e.loaded / e.total); }; diff --git a/web/src/pages/SettingsPage.tsx b/web/src/pages/SettingsPage.tsx index f8ddd91..ddfbeef 100644 --- a/web/src/pages/SettingsPage.tsx +++ b/web/src/pages/SettingsPage.tsx @@ -6,11 +6,11 @@ import { toast } from 'sonner'; import { shareUrl } from '@/features/dialogs'; import { TemplateSettings } from '@/features/TemplateSettings'; import { WebSearchSettings } from '@/features/WebSearchSettings'; -import { api, errorMessage } from '@/lib/api'; +import { api, ApiError, errorMessage, uploadWithProgress } from '@/lib/api'; import { qk, useRefresh } from '@/lib/queries'; import type { AppSettings, ShareAiSettings, ShareListItem, Template } from '@/lib/types'; import { copyText, cx, downloadFile, formatBytes, formatDateTime, plural, timeAgo, useDocumentTitle, useTheme } from '@/lib/util'; -import { Badge, Button, Callout, ClassDot, EmptyState, Field, IconButton, Input, PageHeader, PageLoading, Section, Segmented, Select, Skeleton, Switch, useConfirm } from '@/ui'; +import { Badge, Button, Callout, ClassDot, EmptyState, Field, IconButton, Input, PageHeader, PageLoading, ProgressBar, Section, Segmented, Select, Skeleton, Switch, useConfirm } from '@/ui'; const AiSettings = lazy(() => import('@/features/AiSettings')); @@ -284,17 +284,19 @@ function ShareAiSafety() { /* ------------------------------ data ------------------------------ */ -interface V1Summary { +interface RestoreSummary { + backupCreatedAt: string | null; classes: number; - folders: number; - decks: number; - cards: number; quizzes: number; - questions: number; + decks: number; + notes: number; + documents: number; attempts: number; - scheduledCards: number; - activityDays: number; - skipped: string[]; + files: number; + keysMoved: number; + keysUnreadable: number; + safetySnapshot: string; + stoppedJobs: number; } function DataSettings() { @@ -303,10 +305,9 @@ function DataSettings() { const settings = useQuery({ queryKey: qk.settings, queryFn: () => api.get('/api/settings') }); const backups = useQuery({ queryKey: ['backups'], queryFn: () => api.get<{ backups: { name: string; size: number; createdAt: number }[]; directory: string }>('/api/backups') }); const bundleRef = useRef(null); - const v1Ref = useRef(null); + const restoreRef = useRef(null); const [busy, setBusy] = useState(''); - const [v1File, setV1File] = useState(null); - const [v1Preview, setV1Preview] = useState(null); + const [restoreProgress, setRestoreProgress] = useState(null); const importBundle = async (file: File) => { setBusy('bundle'); @@ -322,25 +323,31 @@ function DataSettings() { setBusy(''); } }; - const v1 = async (file: File, preview: boolean) => { - setBusy(preview ? 'v1preview' : 'v1'); + const restore = async (file: File) => { + const ok = await confirm({ + title: 'Restore this backup?', + message: `Everything on this server is replaced with ${file.name}: classes, quizzes, flashcards, documents, progress, AI models and every setting. A snapshot of what is here now is saved first under Database snapshots. You stay signed in.`, + confirmLabel: 'Replace everything', + danger: true, + }); + if (!ok) return; + setBusy('restore'); + setRestoreProgress(0); try { - const form = new FormData(); - form.append('file', file); - const res = await api.upload<{ summary: V1Summary }>(`/api/import/v1${preview ? '?preview=1' : ''}`, form); - if (preview) { - setV1File(file); - setV1Preview(res.summary); - } else { - await refresh(); - setV1File(null); - setV1Preview(null); - toast.success(`Migrated ${plural(res.summary.classes, 'class', 'classes')} from V1`); - } + const res = await uploadWithProgress<{ summary: RestoreSummary }>('/api/backup/restore', file, (f) => setRestoreProgress(f)); + const s = res.summary; + const made = s.backupCreatedAt ? ` from ${new Date(s.backupCreatedAt).toLocaleString()}` : ''; + toast.success(`Backup${made} restored: ${plural(s.classes, 'class', 'classes')}, ${plural(s.quizzes, 'quiz', 'quizzes')}, ${plural(s.decks, 'deck')}, ${plural(s.files, 'file')}.`, { + description: s.keysUnreadable ? `${plural(s.keysUnreadable, 'saved API key')} could not be read on this server; enter them again in Settings → AI.` : undefined, + duration: 10_000, + }); + // Every screen's data changed: start fresh. + setTimeout(() => window.location.assign('/settings/data'), 1500); } catch (e) { - toast.error(errorMessage(e)); + toast.error(e instanceof ApiError && e.status === 413 ? 'The backup is too large to upload here. If a proxy such as Cloudflare limits uploads, restore it on the server instead (see the deployment guide).' : errorMessage(e)); } finally { setBusy(''); + setRestoreProgress(null); } }; const sys = settings.data?.system; @@ -385,42 +392,19 @@ function DataSettings() {
-
Migrate from Study Desk V1
-
- Upload the V1 database file (study.db from the old container's data folder). Classes, groups, decks, quizzes, attempt history, flashcard schedules and your activity are copied in. The V1 file is only read, never changed. -
+
Restore a full backup
+
Replaces everything on this server with a backup zip from "Download backup": content, progress, uploaded files, AI models and all settings. A snapshot of the current database is saved first.
- (e.target.files?.[0] && v1(e.target.files[0], true), (e.target.value = ''))} /> -
- {v1Preview && v1File && ( - -
- {plural(v1Preview.classes, 'class', 'classes')} - {plural(v1Preview.folders, 'group')} → folders - {plural(v1Preview.quizzes, 'quiz', 'quizzes')} · {plural(v1Preview.questions, 'question')} - {plural(v1Preview.decks, 'deck')} · {plural(v1Preview.cards, 'card')} - {plural(v1Preview.attempts, 'quiz attempt')} - {plural(v1Preview.scheduledCards, 'card schedule')} -
-
- - -
-
+ {restoreProgress !== null && ( +
+ +
{restoreProgress < 1 ? `Uploading… ${Math.round(restoreProgress * 100)}%` : 'Restoring… this can take a minute for large backups.'}
+
)}