Study/server/routes/documents.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

174 lines
8.7 KiB
TypeScript

import fs from 'node:fs';
import path from 'node:path';
import crypto from 'node:crypto';
import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod';
import { titleSchema } from '../../shared/content.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { getClass, mapClass, resolveFolder } from '../services/content.ts';
import { deleteDocument, documentPath, enqueue, getDocument, ingestUpload, listChunks, mapDocument, sourceLabel } from '../services/documents.ts';
import { now } from '../util.ts';
import { shareFor } from './library.ts';
const IMAGE_TYPES: Record<string, { ext: string; test: (b: Uint8Array) => boolean }> = {
'image/png': { ext: 'png', test: (b) => b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
'image/jpeg': { ext: 'jpg', test: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
'image/gif': { ext: 'gif', test: (b) => b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 },
'image/webp': { ext: 'webp', test: (b) => b[0] === 0x52 && b[1] === 0x49 && b[8] === 0x57 && b[9] === 0x45 },
};
export function documentRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
const uploadLimit = bodyLimit({
maxSize: app.config.maxUploadBytes + 1024 * 1024,
onError: () => {
throw new HttpError(413, 'too_large', `That file is larger than the ${Math.round(app.config.maxUploadBytes / 1048576)} MB upload limit.`);
},
});
r.post('/documents', uploadLimit, async (c) => {
const form = await c.req.parseBody({ all: true }).catch(() => {
throw badRequest('Upload could not be read');
});
const classId = typeof form.classId === 'string' ? form.classId : '';
const folderId = typeof form.folderId === 'string' && form.folderId ? form.folderId : null;
const raw = form.file ?? form.files;
const files = (Array.isArray(raw) ? raw : [raw]).filter((f): f is File => typeof f === 'object' && f !== null && 'arrayBuffer' in f);
if (!classId) throw badRequest('classId is required');
if (files.length === 0) throw badRequest('Choose a file to upload');
const created = [];
for (const file of files) {
const bytes = new Uint8Array(await file.arrayBuffer());
created.push(mapDocument(ingestUpload(app, { classId, folderId, filename: file.name || 'upload', mime: file.type || undefined, bytes })));
}
return c.json({ documents: created }, 201);
});
/** Pasted notes become a Markdown document, so they are searchable and usable by AI like any upload. */
r.post('/documents/text', async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: titleSchema, text: z.string().trim().min(1).max(2_000_000) }));
const doc = ingestUpload(app, {
classId: body.classId,
folderId: body.folderId,
filename: `${body.title.replace(/[^\w\- ]+/g, '').trim().slice(0, 80) || 'notes'}.md`,
mime: 'text/markdown',
bytes: new TextEncoder().encode(body.text),
title: body.title,
});
return c.json({ document: mapDocument(doc) }, 201);
});
r.get('/documents/:id', (c) => {
const doc = getDocument(db, idParam(c));
const outline = db
.all<{ seq: number; heading: string; page_start: number | null }>(`SELECT MIN(seq) AS seq, heading, MIN(page_start) AS page_start FROM chunks WHERE document_id = ? AND heading != '' GROUP BY heading ORDER BY seq LIMIT 200`, doc.id)
.map((o) => ({ seq: o.seq, heading: o.heading, page: o.page_start }));
return c.json({ document: mapDocument(doc), class: mapClass(getClass(db, doc.class_id)), outline, share: shareFor(app, 'document', doc.id) });
});
r.get('/documents/:id/chunks', (c) => {
const doc = getDocument(db, idParam(c));
const offset = Math.max(0, Number(c.req.query('offset') ?? 0) || 0);
const limit = Math.min(100, Math.max(1, Number(c.req.query('limit') ?? 40) || 40));
const chunks = listChunks(db, doc.id, offset, limit);
return c.json({
chunks: chunks.map((ch) => ({ id: ch.id, seq: ch.seq, text: ch.text, heading: ch.heading, pageStart: ch.pageStart, pageEnd: ch.pageEnd, label: sourceLabel(ch) })),
total: doc.chunk_count,
nextOffset: chunks.length === limit && offset + limit < doc.chunk_count ? offset + limit : null,
});
});
r.get('/documents/:id/status', (c) => {
const doc = getDocument(db, idParam(c));
return c.json({ document: mapDocument(doc) });
});
r.get('/documents/:id/file', (c) => {
const doc = getDocument(db, idParam(c));
const file = documentPath(app, doc);
if (!fs.existsSync(file)) throw new HttpError(404, 'not_found', 'The original file is missing from storage');
const inline = doc.kind === 'pdf' || doc.kind === 'image';
const download = c.req.query('download') === '1';
return new Response(fs.readFileSync(file), {
headers: {
'Content-Type': inline ? doc.mime : 'application/octet-stream',
'Content-Disposition': `${inline && !download ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`,
'X-Content-Type-Options': 'nosniff',
// Uploaded files are untrusted. PDFs and images are served with their verified type (sniffing off);
// everything else is forced to download.
...(inline ? {} : { 'Content-Security-Policy': "default-src 'none'; sandbox" }),
'Cache-Control': 'private, max-age=3600',
},
});
});
r.patch('/documents/:id', async (c) => {
const doc = getDocument(db, idParam(c));
const body = await readBody(c, z.object({ title: titleSchema.optional(), folderId: z.string().nullish() }));
db.run(
'UPDATE documents SET title = ?, folder_id = ?, updated_at = ? WHERE id = ?',
body.title ?? doc.title,
body.folderId === undefined ? doc.folder_id : resolveFolder(db, doc.class_id, body.folderId),
now(),
doc.id,
);
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.post('/documents/:id/reprocess', async (c) => {
const doc = getDocument(db, idParam(c));
const body = (await c.req.json().catch(() => ({}))) as { ocr?: unknown };
db.run(`UPDATE documents SET status = 'pending', error = '', progress = 0, updated_at = ? WHERE id = ?`, now(), doc.id);
enqueue(app, doc.id, { ocr: body.ocr === true });
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.delete('/documents/:id', (c) => {
deleteDocument(app, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ images embedded in questions, cards and notes ------------------------------ */
r.post('/media', bodyLimit({ maxSize: 12 * 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 an image');
const bytes = new Uint8Array(await file.arrayBuffer());
if (bytes.length > 10 * 1024 * 1024) throw new HttpError(413, 'too_large', 'Images can be up to 10 MB.');
// Trust the bytes, not the declared type. SVG is deliberately not accepted (it can carry script).
const match = Object.entries(IMAGE_TYPES).find(([, t]) => t.test(bytes));
if (!match) throw new HttpError(415, 'unsupported_type', 'Use a PNG, JPEG, GIF or WebP image.');
const [mime, { ext }] = match;
const id = `${crypto.randomBytes(16).toString('base64url')}.${ext}`;
fs.writeFileSync(path.join(app.config.mediaDir, id), bytes);
db.run('INSERT INTO media (id, filename, mime, size, created_at) VALUES (?, ?, ?, ?, ?)', id, (file.name || 'image').slice(0, 200), mime, bytes.length, now());
return c.json({ url: `/media/${id}`, markdown: `![${(file.name || 'image').replace(/[[\]]/g, '')}](/media/${id})` }, 201);
});
return r;
}
/**
* Public image route. Images are addressed by an unguessable 128-bit name, which is what lets
* a shared quiz show its pictures to visitors without exposing anything else.
*/
export function mediaRoute(app: AppContext): Hono {
const r = new Hono();
r.get('/:name', (c) => {
const name = c.req.param('name');
if (!/^[A-Za-z0-9_-]{16,40}\.(png|jpg|gif|webp)$/.test(name)) throw new HttpError(404, 'not_found', 'Not found');
const row = app.db.get<{ mime: string }>('SELECT mime FROM media WHERE id = ?', name);
const file = path.join(app.config.mediaDir, name);
if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found');
return new Response(fs.readFileSync(file), {
headers: { 'Content-Type': row.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox" },
});
});
return r;
}