feat(files): a file that is not media opens in a viewer — an image, a PDF, text as text

- GET /api/files/{id}/preview: an allow-list on the stored extension (downloads/preview.py) picks image / PDF / text; served inline under `CSP: sandbox; frame-ancestors 'self'`, the type from the table; HTML and SVG arrive as plain text; a text is its first 1 MiB (X-Preview-Truncated), sent as UTF-8 whatever it was written in (BOM, UTF-8, else cp1250); a NUL means binary: 415 - the list says which preview each file gets (asset.preview); FE/BE contract on kinds and header - the viewer (shared dialog shell): ← / → through the list's such files in its order, Save, open in a tab, the file's menu; one stage height for every kind; a no-preview card offers the file - the name, the card's picture and the menu's Preview open it; an image up to 8 MB is its own thumbnail
2026-10-12 15:28:31 +02:00
parent 6707550513
commit fb8fb980e5
26 changed files with 1090 additions and 48 deletions
@@ -0,0 +1,107 @@
+"""What a library file previews as — the single home of the preview allow-list.
+
+A generic file (`media_kind == "file"`; video and audio have their players) previews by its stored
+`container`, the upload's cleaned extension, and ONLY through this table: an image is shown as an
+image, a PDF in the browser's own viewer, and a text format as plain text. Anything else has no
+preview. The served Content-Type comes from here too, never from a guess on the name, and HTML / SVG
+sit in the TEXT list on purpose: rendered on this origin, an uploaded page would run with the
+reader's session. The route adds `CSP: sandbox` on top, so even a mislabelled file (a "png" that is
+really a page) gets no script and no origin.
+
+The serializer hands the kind to the client (`asset.preview`), so the library and the server can
+never disagree on which files open a preview.
+"""
+
+import codecs
+from typing import Literal
+
+from app.downloads import mediakind
+
+PreviewKind = Literal["image", "pdf", "text"]
+
+IMAGE_TYPES: dict[str, str] = {
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "avif": "image/avif",
+    "bmp": "image/bmp",
+}
+
+PDF_TYPE = "application/pdf"
+
+# Read as text: notes, data, subtitles, config and source. HTML and SVG belong here (see above).
+TEXT_EXTS: frozenset[str] = frozenset(
+    {
+        "txt", "text", "md", "markdown", "log", "csv", "tsv", "json", "jsonl", "ndjson", "xml",
+        "yaml", "yml", "toml", "ini", "conf", "cfg", "properties", "env", "srt", "vtt", "ass", "ssa",
+        "sub", "nfo", "cue", "m3u", "m3u8", "html", "htm", "xhtml", "svg", "css", "scss", "less",
+        "js", "mjs", "cjs", "ts", "tsx", "jsx", "py", "rb", "php", "pl", "lua", "go", "rs", "java",
+        "kt", "kts", "swift", "c", "h", "cc", "cpp", "hpp", "cs", "sh", "bash", "zsh", "fish", "ps1",
+        "bat", "cmd", "sql", "r", "dart", "diff", "patch", "tex", "rst", "adoc", "gradle", "dockerfile",
+    }
+)  # fmt: skip
+
+TEXT_TYPE = "text/plain; charset=utf-8"
+
+# A text preview is the file's head: enough to read, never a whole log loaded into a tab.
+TEXT_PREVIEW_BYTES = 1 << 20
+# A NUL byte in the first this-many bytes means the "text" is not text.
+BINARY_SNIFF_BYTES = 8192
+
+
+def kind(media_kind: str | None, container: str | None) -> PreviewKind | None:
+    """The preview a library file gets, or None (a media file plays instead; others download)."""
+    if media_kind != mediakind.FILE:
+        return None
+    ext = (container or "").lower()
+    if ext in IMAGE_TYPES:
+        return "image"
+    if ext == "pdf":
+        return "pdf"
+    if ext in TEXT_EXTS:
+        return "text"
+    return None
+
+
+def media_type(preview: PreviewKind, container: str | None) -> str:
+    """The Content-Type a preview is served with: from this table, never guessed from the name."""
+    if preview == "image":
+        return IMAGE_TYPES[(container or "").lower()]
+    if preview == "pdf":
+        return PDF_TYPE
+    return TEXT_TYPE
+
+
+# A text that is not UTF-8 is read as Central European Windows: what an old Hungarian subtitle or
+# note is written in (its ő and ű are not in Latin-1).
+FALLBACK_ENCODING = "cp1250"
+_BOMS = (
+    (codecs.BOM_UTF8, "utf-8-sig"),
+    (codecs.BOM_UTF16_LE, "utf-16"),
+    (codecs.BOM_UTF16_BE, "utf-16"),
+)
+
+
+def looks_binary(head: bytes) -> bool:
+    """Whether the start of a "text" file is binary after all (a NUL in it)."""
+    return b"\x00" in head[:BINARY_SNIFF_BYTES]
+
+
+def text_utf8(head: bytes) -> bytes | None:
+    """A text file's head as UTF-8, the one charset the preview is served in; None when it is not text.
+    A byte-order mark names its encoding (UTF-16 is full of NULs, so it is read before the binary
+    check); else UTF-8 is kept as it is — a character cut at the size cap included, the reader shows
+    that one as a replacement mark — and anything else is read as `FALLBACK_ENCODING`."""
+    for bom, encoding in _BOMS:
+        if head.startswith(bom):
+            return head.decode(encoding, errors="replace").encode()
+    if looks_binary(head):
+        return None
+    try:
+        head.decode("utf-8")
+    except UnicodeDecodeError as e:  # silent-ok: not UTF-8 is an answer — read it as the fallback
+        if not (e.reason == "unexpected end of data" and e.end == len(head)):
+            return head.decode(FALLBACK_ENCODING, errors="replace").encode()
+    return head
@@ -268,7 +268,8 @@ async def static_cache_headers(request, call_next):
 # Baseline security response headers (SEC-1). A minimal, safe set that needs no per-route tuning:
 # nosniff stops MIME-confusion, the Referrer-Policy keeps the (private) app URL from leaking to
 # external sites the user follows, `frame-ancestors 'none'` blocks click-jacking by refusing to be
-# iframed anywhere (we never embed our own pages; we embed OTHERS, which this does not affect), and
+# iframed anywhere (we embed OTHERS, which this does not affect; the one own answer the app frames, a
+# library file's preview, sets its own `frame-ancestors 'self'` — these are defaults, `setdefault`), and
 # Permissions-Policy turns off powerful features the app never uses. `X-Frame-Options: DENY` duplicates
 # the frame-ancestors intent for legacy engines that never implemented CSP frame-ancestors (belt and
 # suspenders — modern browsers use the CSP directive and ignore the header). A full Content-Security-Policy
@@ -21,7 +21,7 @@ from typing import BinaryIO, Literal
 from urllib.parse import unquote, urlparse

 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from fastapi.responses import FileResponse
+from fastapi.responses import FileResponse, Response
 from pydantic import BaseModel, Field
 from sqlalchemy import func, or_, select
 from sqlalchemy.exc import IntegrityError
@@ -33,7 +33,7 @@ from app.auth import current_user
 from app.collation import collated
 from app.config import settings
 from app.db import get_db, release_read_connection
-from app.downloads import folders, quota, service, storage
+from app.downloads import folders, preview, quota, service, storage
 from app.downloads import upload as uploadmod
 from app.downloads.status import JobStatus
 from app.mailtext import lang_for_user
@@ -117,6 +117,8 @@ def serialize(job: DownloadJob, asset: MediaAsset | None) -> dict:
            "media_kind": asset.media_kind,
            "uploader_url": asset.uploader_url,
            "thumbnail_url": asset.thumbnail_url,
+            # "image" | "pdf" | "text" | null — what `/preview` shows (`downloads/preview.py`).
+            "preview": preview.kind(asset.media_kind, asset.container),
        },
    }

@@ -784,6 +786,56 @@ def get_file(job_id: int, user: User = Depends(current_user), db: Session = Depe
    return response


+# A preview's own headers. `sandbox` leaves the answer no script and an opaque origin, whatever the
+# file turns out to hold; `frame-ancestors 'self'` lets the app's viewer frame a PDF (every other
+# answer keeps the app-wide 'none', main.py), with X-Frame-Options saying the same for old engines.
+PREVIEW_HEADERS = {
+    "Content-Security-Policy": "sandbox; frame-ancestors 'self'",
+    "X-Frame-Options": "SAMEORIGIN",
+}
+# Set on a text preview cut at `preview.TEXT_PREVIEW_BYTES`, so the viewer can say it shows the start.
+TRUNCATED_HEADER = "X-Preview-Truncated"
+
+
+@router.get("/{job_id}/preview")
+def preview_file(
+    job_id: int, user: User = Depends(current_user), db: Session = Depends(get_db)
+) -> Response:
+    """The file shown in the library's viewer: an image or a PDF inline, a text format as plain text
+    (its first `TEXT_PREVIEW_BYTES`). The type comes from `downloads/preview.py`'s allow-list, so
+    an HTML or SVG upload arrives as text, never as a page. Anything else: 415 `file_no_preview`."""
+    job = accessible_job(db, user, job_id)
+    asset, path = _ready_file(db, job)
+    kind = preview.kind(asset.media_kind, asset.container)
+    if kind is None:
+        raise refused(415, "file_no_preview")
+    headers = dict(PREVIEW_HEADERS)
+    if kind == "text":
+        with path.open("rb") as f:
+            head = f.read(preview.TEXT_PREVIEW_BYTES + 1)
+        if len(head) > preview.TEXT_PREVIEW_BYTES:
+            head = head[: preview.TEXT_PREVIEW_BYTES]
+            headers[TRUNCATED_HEADER] = "1"
+        text = preview.text_utf8(head)
+        if text is None:
+            raise refused(415, "file_no_preview")
+        asset.last_access_at = datetime.now(timezone.utc)
+        db.commit()
+        return Response(text, media_type=preview.media_type(kind, asset.container), headers=headers)
+    filename = storage.download_filename(
+        job.display_name or asset.title or asset.source_ref, asset.container, path
+    )
+    asset.last_access_at = datetime.now(timezone.utc)
+    db.commit()
+    return FileResponse(
+        path,
+        filename=filename,
+        media_type=preview.media_type(kind, asset.container),
+        content_disposition_type="inline",
+        headers=headers,
+    )
+
+
@router.get("/{job_id}/sha256")
 def get_sha256(
    job_id: int, user: User = Depends(current_user), db: Session = Depends(get_db)