Study/server/services/backup.ts
Elijah eae109c166 Add HTTP routes, app wiring, V1 migration, backups, templates and API tests
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 08:22:47 -07:00

183 lines
7.2 KiB
TypeScript

/**
* Backups.
* - Automatic: a compact snapshot of the database is written to data/backups once a day
* and the newest few are kept.
* - On demand: a zip with the database snapshot plus every uploaded file and image.
* - Content export: a portable JSON bundle of classes, quizzes, decks and notes.
*/
import fs from 'node:fs';
import path from 'node:path';
import { Zip, ZipPassThrough } from 'fflate';
import { questionToDraft } from '../../shared/content.ts';
import { EXPORT_FORMAT, EXPORT_VERSION, exportDeck, exportQuiz } from '../../shared/importer.ts';
import type { AppContext } from '../http.ts';
import { dayKey, now } from '../util.ts';
import { listCards, listQuestions, type ClassRow, type FolderRow, type NoteRow, type QuizRow } from './content.ts';
export interface BackupInfo {
name: string;
size: number;
createdAt: number;
}
export function listBackups(app: AppContext): BackupInfo[] {
const dir = app.config.backupsDir;
if (!fs.existsSync(dir)) return [];
return fs
.readdirSync(dir)
.filter((f) => f.endsWith('.db'))
.map((name) => {
const st = fs.statSync(path.join(dir, name));
return { name, size: st.size, createdAt: st.mtimeMs };
})
.sort((a, b) => b.createdAt - a.createdAt);
}
export function createSnapshot(app: AppContext, prefix = 'manual'): BackupInfo {
const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
const name = `${prefix}-${stamp}.db`;
const target = path.join(app.config.backupsDir, name);
app.db.snapshot(target);
return { name, size: fs.statSync(target).size, createdAt: now() };
}
/** Writes today's automatic snapshot if it does not exist yet, then prunes old automatic ones. */
export function runDailyBackup(app: AppContext): BackupInfo | null {
const today = dayKey(now(), 'UTC');
const name = `auto-${today}.db`;
const target = path.join(app.config.backupsDir, name);
let created: BackupInfo | null = null;
if (!fs.existsSync(target)) {
// Skip an empty install: there is nothing worth keeping yet.
const hasData = (app.db.get<{ n: number }>('SELECT (SELECT COUNT(*) FROM classes) + (SELECT COUNT(*) FROM ai_providers) AS n')?.n ?? 0) > 0;
if (hasData) {
app.db.snapshot(target);
created = { name, size: fs.statSync(target).size, createdAt: now() };
}
}
const prune = (prefix: string, keep: number) => {
const files = listBackups(app).filter((b) => b.name.startsWith(prefix));
for (const old of files.slice(keep)) fs.rmSync(path.join(app.config.backupsDir, old.name), { force: true });
};
prune('auto-', app.config.backupKeep);
prune('pre-migration-', 5);
prune('manual-', 10);
return created;
}
export function startBackupSchedule(app: AppContext): () => void {
const tick = () => {
try {
const made = runDailyBackup(app);
if (made) app.log('info', `Automatic backup written: ${made.name}`);
} catch (e) {
app.log('error', 'Automatic backup failed', e);
}
};
const first = setTimeout(tick, 30_000);
const timer = setInterval(tick, 6 * 3_600_000);
first.unref?.();
timer.unref?.();
return () => {
clearTimeout(first);
clearInterval(timer);
};
}
/** Streams a zip containing a fresh database snapshot and all uploaded files. One file is in memory at a time. */
export function fullBackupStream(app: AppContext): { stream: ReadableStream<Uint8Array>; filename: string } {
const tmp = path.join(app.config.backupsDir, `.export-${Date.now()}.db`);
app.db.snapshot(tmp);
const entries: { name: string; file: string }[] = [{ name: 'study.db', file: tmp }];
for (const [dir, prefix] of [
[app.config.uploadsDir, 'uploads'],
[app.config.mediaDir, 'media'],
] as const) {
if (!fs.existsSync(dir)) continue;
for (const f of fs.readdirSync(dir)) {
const full = path.join(dir, f);
if (fs.statSync(full).isFile()) entries.push({ name: `${prefix}/${f}`, file: full });
}
}
const manifest = {
format: 'studydesk-backup',
version: 1,
createdAt: new Date().toISOString(),
files: entries.length,
restore: 'Stop the container, copy study.db, uploads/ and media/ into the data folder (replacing what is there), keep your existing secret.key, then start the container.',
};
let index = -1;
let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
const cleanup = () => fs.rmSync(tmp, { force: true });
const zip = new Zip((err, chunk, final) => {
if (err) {
controllerRef?.error(err);
cleanup();
return;
}
controllerRef?.enqueue(chunk);
if (final) {
controllerRef?.close();
cleanup();
}
});
const stream = new ReadableStream<Uint8Array>({
start(controller) {
controllerRef = controller;
const entry = new ZipPassThrough('manifest.json');
zip.add(entry);
entry.push(new TextEncoder().encode(JSON.stringify(manifest, null, 2)), true);
},
pull() {
index += 1;
if (index >= entries.length) {
zip.end();
return;
}
const { name, file } = entries[index];
const entry = new ZipPassThrough(name);
zip.add(entry);
try {
entry.push(new Uint8Array(fs.readFileSync(file)), true);
} catch {
entry.push(new Uint8Array(0), true);
}
},
cancel() {
cleanup();
},
});
return { stream, filename: `studydesk-backup-${new Date().toISOString().slice(0, 10)}.zip` };
}
/** Portable JSON bundle: classes with their folders, quizzes, decks and notes (no progress, no uploads). */
export function exportBundle(app: AppContext, classId?: string) {
const { db } = app;
const classes = classId ? db.all<ClassRow>('SELECT * FROM classes WHERE id = ?', classId) : db.all<ClassRow>('SELECT * FROM classes ORDER BY sort_order, created_at');
return {
format: EXPORT_FORMAT,
version: EXPORT_VERSION,
kind: 'bundle' as const,
exportedAt: new Date().toISOString(),
classes: classes.map((cls) => {
const folders = db.all<FolderRow>('SELECT * FROM folders WHERE class_id = ? ORDER BY sort_order', cls.id);
const folderName = (id: string | null) => folders.find((f) => f.id === id)?.name ?? null;
return {
name: cls.name,
code: cls.code,
description: cls.description,
color: cls.color,
folders: folders.map((f) => f.name),
quizzes: db.all<QuizRow>('SELECT * FROM quizzes WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((q) => ({
...exportQuiz({ title: q.title, description: q.description, questions: listQuestions(db, q.id).map(questionToDraft) }),
folder: folderName(q.folder_id),
})),
decks: db.all<QuizRow>('SELECT * FROM decks WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((d) => ({
...exportDeck({ title: d.title, description: d.description, cards: listCards(db, d.id).map((c) => ({ front: c.front, back: c.back, hint: c.hint, tags: c.tags })) }),
folder: folderName(d.folder_id),
})),
notes: db.all<NoteRow>('SELECT * FROM notes WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((n) => ({ kind: 'note' as const, title: n.title, content: n.content, folder: folderName(n.folder_id) })),
};
}),
};
}