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>
312 lines
16 KiB
TypeScript
312 lines
16 KiB
TypeScript
import fs from 'node:fs';
|
|
import os from 'node:os';
|
|
import path from 'node:path';
|
|
import { Hono } from 'hono';
|
|
import { bodyLimit } from 'hono/body-limit';
|
|
import { z } from 'zod';
|
|
import { questionToDraft, validateDraft, type ContentDraft } from '../../shared/content.ts';
|
|
import { draftsFromValue, LLM_INSTRUCTIONS } from '../../shared/importer.ts';
|
|
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
|
|
import { appSettingsSchema, deleteSetting, getAppSettings, getSetting, setSetting } from '../settings.ts';
|
|
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 {
|
|
return fs.readdirSync(dir).reduce((n, f) => {
|
|
const st = fs.statSync(path.join(dir, f));
|
|
return n + (st.isFile() ? st.size : 0);
|
|
}, 0);
|
|
} catch {
|
|
return 0;
|
|
}
|
|
}
|
|
|
|
/** Creates library items from reviewed drafts. Used by the importer and by bundle restore. */
|
|
function createFromDraft(app: AppContext, draft: ContentDraft, classId: string, folderId: string | null): { kind: string; id: string; title: string } {
|
|
const { db } = app;
|
|
if (draft.kind === 'quiz') {
|
|
const quiz = createQuiz(db, { classId, folderId, title: draft.title.trim() || 'Imported quiz', description: draft.description ?? '', questions: draft.questions.map(draftQuestionToInput) });
|
|
return { kind: 'quiz', id: quiz.id, title: quiz.title };
|
|
}
|
|
if (draft.kind === 'deck') {
|
|
const deck = createDeck(db, { classId, folderId, title: draft.title.trim() || 'Imported deck', description: draft.description ?? '', cards: draft.cards.map(draftCardToInput) });
|
|
return { kind: 'deck', id: deck.id, title: deck.title };
|
|
}
|
|
const note = createNote(db, { classId, folderId, title: draft.title.trim() || 'Imported note', content: draft.content });
|
|
return { kind: 'note', id: note.id, title: note.title };
|
|
}
|
|
|
|
export function dataRoutes(app: AppContext): Hono {
|
|
const { db } = app;
|
|
const r = new Hono();
|
|
|
|
/* ------------------------------ settings ------------------------------ */
|
|
|
|
r.get('/settings', (c) => {
|
|
const count = (table: string) => db.get<{ n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)?.n ?? 0;
|
|
let dbSize = 0;
|
|
try {
|
|
dbSize = fs.statSync(app.config.dbPath).size;
|
|
} catch {
|
|
/* in-memory */
|
|
}
|
|
return c.json({
|
|
settings: getAppSettings(db, app.config.timezone),
|
|
system: {
|
|
version: APP_VERSION,
|
|
node: process.version,
|
|
dataDir: app.config.dataDir,
|
|
databaseBytes: dbSize,
|
|
uploadBytes: dirSize(app.config.uploadsDir) + dirSize(app.config.mediaDir),
|
|
maxUploadMb: Math.round(app.config.maxUploadBytes / 1048576),
|
|
counts: { classes: count('classes'), quizzes: count('quizzes'), questions: count('questions'), decks: count('decks'), cards: count('cards'), documents: count('documents'), notes: count('notes') },
|
|
timezones: typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : [],
|
|
},
|
|
});
|
|
});
|
|
|
|
r.put('/settings', async (c) => {
|
|
const patch = await readBody(c, appSettingsSchema.partial());
|
|
if (patch.timezone) {
|
|
try {
|
|
new Intl.DateTimeFormat('en-US', { timeZone: patch.timezone });
|
|
} catch {
|
|
throw badRequest('Unknown timezone');
|
|
}
|
|
}
|
|
const next = { ...getAppSettings(db, app.config.timezone), ...patch };
|
|
setSetting(db, 'app', next);
|
|
return c.json({ settings: next });
|
|
});
|
|
|
|
/* ------------------------------ instructions for outside chatbots ------------------------------ */
|
|
|
|
r.get('/llm-instructions', (c) =>
|
|
c.json({
|
|
quiz: getSetting<string | null>(db, 'llm.quiz', null) ?? LLM_INSTRUCTIONS.quiz,
|
|
deck: getSetting<string | null>(db, 'llm.deck', null) ?? LLM_INSTRUCTIONS.deck,
|
|
customized: { quiz: getSetting<string | null>(db, 'llm.quiz', null) !== null, deck: getSetting<string | null>(db, 'llm.deck', null) !== null },
|
|
builtin: LLM_INSTRUCTIONS,
|
|
}),
|
|
);
|
|
|
|
/** Saves an edited copy; `text: null` goes back to the built-in wording. */
|
|
r.put('/llm-instructions', async (c) => {
|
|
const body = await readBody(c, z.object({ kind: z.enum(['quiz', 'deck']), text: z.string().trim().min(20).max(20000).nullable() }));
|
|
if (body.text === null) deleteSetting(db, `llm.${body.kind}`);
|
|
else setSetting(db, `llm.${body.kind}`, body.text);
|
|
return c.json({ ok: true });
|
|
});
|
|
|
|
/* ------------------------------ import ------------------------------ */
|
|
|
|
r.post('/import', bodyLimit({ maxSize: 30 * 1024 * 1024 }), async (c) => {
|
|
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), items: z.array(z.unknown()).min(1).max(200) }));
|
|
getClass(db, body.classId);
|
|
const drafts: ContentDraft[] = [];
|
|
body.items.forEach((raw, i) => {
|
|
const parsed = draftsFromValue(raw).items[0];
|
|
if (!parsed) throw new HttpError(422, 'validation', `Item ${i + 1} is not a quiz, deck or note`);
|
|
const errors = validateDraft(parsed).filter((x) => x.level === 'error');
|
|
if (errors.length > 0) {
|
|
const first = errors[0];
|
|
const where = first.index !== undefined ? `${parsed.kind === 'quiz' ? 'question' : 'card'} ${first.index + 1}` : first.field ?? 'item';
|
|
throw new HttpError(422, 'validation', `"${parsed.title || `Item ${i + 1}`}", ${where}: ${first.message}`, { item: i, issues: errors });
|
|
}
|
|
drafts.push(parsed);
|
|
});
|
|
const created = db.tx(() => drafts.map((d) => createFromDraft(app, d, body.classId, body.folderId ?? null)));
|
|
return c.json({ created }, 201);
|
|
});
|
|
|
|
/** Restores a JSON bundle produced by "Export everything": recreates classes, folders and their contents. */
|
|
r.post('/import/bundle', bodyLimit({ maxSize: 100 * 1024 * 1024 }), async (c) => {
|
|
const body = (await c.req.json().catch(() => {
|
|
throw badRequest('The file is not valid JSON');
|
|
})) as Record<string, unknown>;
|
|
const classes = Array.isArray(body.classes) ? (body.classes as Record<string, unknown>[]) : null;
|
|
if (!classes) throw badRequest('This file is not a Study Desk bundle. Use "Import" inside a class for single quizzes and decks.');
|
|
const existing = new Set(db.all<{ name: string }>('SELECT name FROM classes').map((x) => x.name.toLowerCase()));
|
|
const summary = { classes: 0, quizzes: 0, decks: 0, notes: 0, skipped: [] as string[] };
|
|
db.tx(() => {
|
|
for (const raw of classes) {
|
|
let name = String(raw.name ?? 'Imported class').trim().slice(0, 110) || 'Imported class';
|
|
if (existing.has(name.toLowerCase())) name = `${name} (imported)`;
|
|
existing.add(name.toLowerCase());
|
|
const color = typeof raw.color === 'string' ? raw.color : undefined;
|
|
const cls = createClass(db, { name, code: String(raw.code ?? '').slice(0, 40), description: String(raw.description ?? '').slice(0, 2000), color: color as never });
|
|
summary.classes += 1;
|
|
const folders = new Map<string, string>();
|
|
for (const f of Array.isArray(raw.folders) ? raw.folders : []) {
|
|
const fname = String(typeof f === 'string' ? f : (f as Record<string, unknown>)?.name ?? '').trim();
|
|
if (fname) folders.set(fname, createFolder(db, cls.id, fname).id);
|
|
}
|
|
for (const key of ['quizzes', 'decks', 'notes'] as const) {
|
|
for (const item of Array.isArray(raw[key]) ? (raw[key] as Record<string, unknown>[]) : []) {
|
|
const kind = key === 'quizzes' ? 'quiz' : key === 'decks' ? 'deck' : 'note';
|
|
const draft = draftsFromValue({ ...item, kind }).items[0];
|
|
const title = String(item?.title ?? 'Untitled');
|
|
if (!draft) {
|
|
summary.skipped.push(`${title} (unreadable)`);
|
|
continue;
|
|
}
|
|
// Drop invalid entries rather than failing a whole restore; report what was left out.
|
|
if (draft.kind === 'quiz') {
|
|
const before = draft.questions.length;
|
|
draft.questions = draft.questions.filter((q) => !validateDraft({ ...draft, questions: [q] }).some((x) => x.level === 'error' && x.index !== undefined));
|
|
if (draft.questions.length < before) summary.skipped.push(`${before - draft.questions.length} invalid question(s) in "${title}"`);
|
|
} else if (draft.kind === 'deck') {
|
|
const before = draft.cards.length;
|
|
draft.cards = draft.cards.filter((card) => card.front?.trim() && card.back?.trim());
|
|
if (draft.cards.length < before) summary.skipped.push(`${before - draft.cards.length} empty card(s) in "${title}"`);
|
|
}
|
|
const folderId = typeof item.folder === 'string' ? (folders.get(item.folder) ?? null) : null;
|
|
createFromDraft(app, draft, cls.id, folderId);
|
|
summary[key] += 1;
|
|
}
|
|
}
|
|
}
|
|
});
|
|
return c.json({ summary }, 201);
|
|
});
|
|
|
|
/**
|
|
* 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<Uint8Array>) {
|
|
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<void>((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');
|
|
});
|
|
const file = form.file;
|
|
if (!file || typeof file === 'string') throw badRequest('Choose your V1 study.db file');
|
|
const bytes = new Uint8Array(await file.arrayBuffer());
|
|
if (new TextDecoder().decode(bytes.subarray(0, 15)) !== 'SQLite format 3') throw badRequest('That file is not a SQLite database.');
|
|
const tmp = path.join(os.tmpdir(), `studydesk-v1-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
|
|
fs.writeFileSync(tmp, bytes);
|
|
try {
|
|
const preview = c.req.query('preview') === '1';
|
|
if (!preview) createSnapshot(app, 'pre-v1-import');
|
|
return c.json({ preview, summary: importV1(app, tmp, { dryRun: preview }) });
|
|
} finally {
|
|
fs.rmSync(tmp, { force: true });
|
|
}
|
|
});
|
|
|
|
/* ------------------------------ export + backup ------------------------------ */
|
|
|
|
r.get('/export/all', (c) => {
|
|
c.header('Content-Disposition', `attachment; filename="studydesk-export-${new Date().toISOString().slice(0, 10)}.json"`);
|
|
return c.json(exportBundle(app));
|
|
});
|
|
|
|
r.get('/export/class/:id', (c) => {
|
|
const cls = getClass(db, idParam(c));
|
|
c.header('Content-Disposition', `attachment; filename="${slugify(cls.name)}.class.json"`);
|
|
return c.json(exportBundle(app, cls.id));
|
|
});
|
|
|
|
r.get('/backup/download', () => {
|
|
const { stream, filename } = fullBackupStream(app);
|
|
return new Response(stream, { headers: { 'Content-Type': 'application/zip', 'Content-Disposition': `attachment; filename="${filename}"`, 'Cache-Control': 'no-store' } });
|
|
});
|
|
|
|
r.get('/backups', (c) => c.json({ backups: listBackups(app), directory: app.config.backupsDir }));
|
|
r.post('/backups', (c) => c.json({ backup: createSnapshot(app) }, 201));
|
|
|
|
r.get('/backups/:name', (c) => {
|
|
const name = path.basename(c.req.param('name'));
|
|
const file = path.join(app.config.backupsDir, name);
|
|
if (!name.endsWith('.db') || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Backup not found');
|
|
return new Response(fs.readFileSync(file), { headers: { 'Content-Type': 'application/octet-stream', 'Content-Disposition': `attachment; filename="${name}"`, 'Cache-Control': 'no-store' } });
|
|
});
|
|
|
|
/* ------------------------------ templates ------------------------------ */
|
|
|
|
r.get('/templates', (c) => c.json({ templates: listTemplates(db, c.req.query('kind') || undefined) }));
|
|
|
|
r.post('/templates', async (c) => c.json({ template: createTemplate(db, await readBody(c, templateInputSchema)) }, 201));
|
|
|
|
/** Saves an existing quiz or deck as a reusable template. */
|
|
r.post('/templates/from', async (c) => {
|
|
const body = await readBody(c, z.object({ kind: z.enum(['quiz', 'deck']), id: z.string(), name: z.string().trim().min(1).max(120).optional() }));
|
|
if (body.kind === 'quiz') {
|
|
const quiz = getQuiz(db, body.id);
|
|
return c.json({ template: createTemplate(db, { kind: 'quiz', name: body.name ?? quiz.title, description: quiz.description.slice(0, 1000), payload: { title: quiz.title, description: quiz.description, questions: listQuestions(db, quiz.id).map(questionToDraft) } }) }, 201);
|
|
}
|
|
const deck = getDeck(db, body.id);
|
|
return c.json(
|
|
{ template: createTemplate(db, { kind: 'deck', name: body.name ?? deck.title, description: deck.description.slice(0, 1000), payload: { title: deck.title, description: deck.description, cards: listCards(db, deck.id).map((x) => ({ front: x.front, back: x.back, hint: x.hint, tags: x.tags })) } }) },
|
|
201,
|
|
);
|
|
});
|
|
|
|
/** Creates a new quiz or deck from a content template. */
|
|
r.post('/templates/:id/use', async (c) => {
|
|
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: z.string().trim().max(200).optional() }));
|
|
const tpl = listTemplates(db).find((t) => t.id === idParam(c));
|
|
if (!tpl || tpl.kind === 'generation') throw new HttpError(404, 'not_found', 'Template not found');
|
|
const draft = draftsFromValue({ ...tpl.payload, kind: tpl.kind, title: body.title || tpl.payload.title || tpl.name }).items[0];
|
|
if (!draft) throw badRequest('This template is empty');
|
|
return c.json({ created: createFromDraft(app, draft, body.classId, body.folderId ?? null) }, 201);
|
|
});
|
|
|
|
r.patch('/templates/:id', async (c) => {
|
|
const body = await readBody(c, z.object({ name: z.string().max(120).optional(), description: z.string().max(1000).optional(), payload: z.record(z.string(), z.unknown()).optional() }));
|
|
return c.json({ template: updateTemplate(db, idParam(c), body) });
|
|
});
|
|
|
|
r.post('/templates/:id/reset', (c) => c.json({ template: resetTemplate(db, idParam(c)) }));
|
|
|
|
r.delete('/templates/:id', (c) => {
|
|
deleteTemplate(db, idParam(c));
|
|
return c.json({ ok: true });
|
|
});
|
|
|
|
return r;
|
|
}
|