"""What a file in a session directory actually is. Five extension tables used to answer this question, and they disagreed: one in ``content_store``, one in ``content_publish``'s schema, and three in the webclient. A ``.md`` report came back "unknown" and got a download link, while ``mimetypes`` — which reads the host's ``/etc/mime.types`` — served a TypeScript ``.ts`` file as ``video/mp2t`` because the extension is shared with MPEG transport streams. Detection order: 1. A strong binary signature in the file's opening kilobytes. Text cannot start with the PNG or RIFF magic, so the signature wins over the extension: a file saved under the wrong name still reaches the right viewer. 2. The extension table, which answers everything without a telltale header. 3. For a file with no usable extension: does it look like text? 4. Otherwise unknown. The values in ``CONTENT_TYPES`` are what ``content_publish`` accepts and what the webclient branches on; adding one means adding a viewer branch there too. """ from __future__ import annotations from pathlib import Path CONTENT_TYPES = ( "stl", "model", "html", "svg", "pdf", "image", "video", "audio", "text", "unknown", ) # Enough for every signature below, including a Matroska track entry. _SAMPLE_BYTES = 4096 # (content type, MIME). `stl` and `model` share one viewer: the file's own # extension decides which three.js loader opens it. _EXTENSION_TYPES: dict[str, tuple[str, str]] = { # 3D models ".stl": ("stl", "model/stl"), ".glb": ("model", "model/gltf-binary"), ".gltf": ("model", "model/gltf+json"), # Documents ".html": ("html", "text/html"), ".htm": ("html", "text/html"), ".svg": ("svg", "image/svg+xml"), ".pdf": ("pdf", "application/pdf"), # Images ".png": ("image", "image/png"), ".jpg": ("image", "image/jpeg"), ".jpeg": ("image", "image/jpeg"), ".gif": ("image", "image/gif"), ".webp": ("image", "image/webp"), ".bmp": ("image", "image/bmp"), ".avif": ("image", "image/avif"), ".ico": ("image", "image/x-icon"), # Video ".mp4": ("video", "video/mp4"), ".webm": ("video", "video/webm"), ".mov": ("video", "video/quicktime"), ".mkv": ("video", "video/x-matroska"), ".m4v": ("video", "video/x-m4v"), ".ogv": ("video", "video/ogg"), # Audio ".mp3": ("audio", "audio/mpeg"), ".wav": ("audio", "audio/wav"), ".ogg": ("audio", "audio/ogg"), ".oga": ("audio", "audio/ogg"), ".opus": ("audio", "audio/ogg"), ".m4a": ("audio", "audio/mp4"), ".flac": ("audio", "audio/flac"), ".aac": ("audio", "audio/aac"), ".weba": ("audio", "audio/webm"), # Text and source. `.ts` belongs here, not to video: without an MPEG # transport-stream signature a .ts file is TypeScript. ".txt": ("text", "text/plain"), ".text": ("text", "text/plain"), ".log": ("text", "text/plain"), ".md": ("text", "text/markdown"), ".markdown": ("text", "text/markdown"), ".csv": ("text", "text/csv"), ".tsv": ("text", "text/tab-separated-values"), ".json": ("text", "application/json"), ".jsonl": ("text", "application/json"), ".ndjson": ("text", "application/json"), ".yaml": ("text", "application/yaml"), ".yml": ("text", "application/yaml"), ".xml": ("text", "text/xml"), ".ini": ("text", "text/plain"), ".cfg": ("text", "text/plain"), ".conf": ("text", "text/plain"), ".toml": ("text", "text/plain"), ".py": ("text", "text/x-python"), ".js": ("text", "text/javascript"), ".mjs": ("text", "text/javascript"), ".cjs": ("text", "text/javascript"), ".ts": ("text", "text/plain"), ".tsx": ("text", "text/plain"), ".jsx": ("text", "text/javascript"), ".css": ("text", "text/css"), ".scss": ("text", "text/plain"), ".sass": ("text", "text/plain"), ".less": ("text", "text/plain"), ".sh": ("text", "text/x-sh"), ".bash": ("text", "text/x-sh"), ".zsh": ("text", "text/x-sh"), ".sql": ("text", "text/plain"), ".scad": ("text", "text/plain"), ".srt": ("text", "text/plain"), ".vtt": ("text", "text/vtt"), ".diff": ("text", "text/plain"), ".patch": ("text", "text/plain"), ".tex": ("text", "text/plain"), ".c": ("text", "text/x-csrc"), ".h": ("text", "text/x-chdr"), ".cpp": ("text", "text/x-c++src"), ".hpp": ("text", "text/x-c++hdr"), ".java": ("text", "text/x-java"), ".go": ("text", "text/plain"), ".rs": ("text", "text/plain"), ".rb": ("text", "text/plain"), ".php": ("text", "text/plain"), ".kt": ("text", "text/plain"), ".swift": ("text", "text/plain"), # Opaque containers: no viewer, but the MIME still matters for the download # and keeps the text heuristic from calling a small archive "text". ".zip": ("unknown", "application/zip"), ".tar": ("unknown", "application/x-tar"), ".gz": ("unknown", "application/gzip"), ".tgz": ("unknown", "application/gzip"), ".7z": ("unknown", "application/x-7z-compressed"), ".rar": ("unknown", "application/vnd.rar"), ".docx": ("unknown", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"), ".xlsx": ("unknown", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"), ".pptx": ("unknown", "application/vnd.openxmlformats-officedocument.presentationml.presentation"), ".odt": ("unknown", "application/vnd.oasis.opendocument.text"), ".ods": ("unknown", "application/vnd.oasis.opendocument.spreadsheet"), ".rtf": ("unknown", "application/rtf"), ".epub": ("unknown", "application/epub+zip"), } # MIME families a browser can render itself. `video/` and `audio/` used to be # missing here, so every media file was sent as an attachment and the player # got a download instead of a stream. _INLINE_PREFIXES = ("image/", "audio/", "video/", "text/") _INLINE_MIMES = frozenset({"application/pdf", "application/json"}) _VIDEO_CODECS = (b"V_VP8", b"V_VP9", b"V_AV1", b"V_MPEG4", b"V_MPEGH", b"V_THEORA") _AUDIO_CODECS = (b"A_OPUS", b"A_VORBIS", b"A_AAC", b"A_FLAC", b"A_MPEG") def _read_head(path: str | Path | None) -> bytes: if path is None: return b"" try: with Path(path).open("rb") as handle: return handle.read(_SAMPLE_BYTES) except OSError: return b"" def _mpeg_audio_frame(head: bytes) -> bool: """An MP3 without an ID3 tag starts with a frame header, not with a magic. The check is deliberately narrow — reserved layer and invalid bitrate are rejected — so ordinary binary data does not read as audio. """ if len(head) < 4 or head[0] != 0xFF or (head[1] & 0xE0) != 0xE0: return False layer = (head[1] >> 1) & 0x03 bitrate = (head[2] >> 4) & 0x0F return layer != 0 and bitrate != 0x0F def _mpeg_transport_stream(head: bytes) -> bool: """MPEG-TS: 188-byte packets, each starting with 0x47.""" if len(head) < 377: return False return head[0] == 0x47 and head[188] == 0x47 and head[376] == 0x47 def _matroska(head: bytes) -> tuple[str, str] | None: """WebM/MKV, audio or video by the tracks it declares.""" is_webm = b"webm" in head[:64] if any(codec in head for codec in _VIDEO_CODECS): return "video", "video/webm" if is_webm else "video/x-matroska" if any(codec in head for codec in _AUDIO_CODECS): return "audio", "audio/webm" if is_webm else "audio/x-matroska" return None def _signature(head: bytes) -> tuple[str, str] | None: """A binary format the opening bytes give away, or None.""" if not head: return None if head.startswith(b"%PDF-"): return "pdf", "application/pdf" if head.startswith(b"\x89PNG\r\n\x1a\n"): return "image", "image/png" if head.startswith(b"\xff\xd8\xff"): return "image", "image/jpeg" if head.startswith((b"GIF87a", b"GIF89a")): return "image", "image/gif" if head.startswith(b"RIFF") and len(head) >= 12: kind = head[8:12] if kind == b"WEBP": return "image", "image/webp" if kind == b"WAVE": return "audio", "audio/wav" if kind == b"AVI ": return "video", "video/x-msvideo" if head.startswith(b"OggS"): return ("video", "video/ogg") if b"theora" in head[:1024] else ("audio", "audio/ogg") if head.startswith(b"fLaC"): return "audio", "audio/flac" if head.startswith(b"ID3"): return "audio", "audio/mpeg" if _mpeg_audio_frame(head): return "audio", "audio/mpeg" if head.startswith(b"\x1a\x45\xdf\xa3"): return _matroska(head) if len(head) >= 12 and head[4:8] == b"ftyp": brand = head[8:12] if brand in {b"M4A ", b"M4B ", b"M4P ", b"mp4a"}: return "audio", "audio/mp4" if brand in {b"avif", b"avis"}: return "image", "image/avif" return "video", "video/mp4" if head.startswith(b"glTF"): return "model", "model/gltf-binary" if _mpeg_transport_stream(head): return "video", "video/mp2t" return None def _looks_like_text(head: bytes) -> bool: """True when the sample decodes as text rather than as arbitrary bytes.""" if not head or b"\x00" in head: return False try: text = head.decode("utf-8") except UnicodeDecodeError: # A UTF-8 sequence cut at the sample boundary, or a legacy encoding; # latin-1 always decodes, and the printable ratio still separates # prose from compressed data. text = head.decode("latin-1") if not text: return False printable = sum(1 for ch in text if ch.isprintable() or ch in "\n\r\t\f\v") return printable / len(text) >= 0.9 def detect(filename: str, path: str | Path | None = None) -> tuple[str, str]: """Return ``(content_type, mime)`` for a file. ``path`` is read for its signature; without it only the name is used. """ suffix = Path(filename).suffix.lower() head = _read_head(path) found = _signature(head) if found is not None: return found known = _EXTENSION_TYPES.get(suffix) if known is not None: return known if _looks_like_text(head): return "text", "text/plain" return "unknown", "application/octet-stream" def content_type_of(filename: str, path: str | Path | None = None) -> str: return detect(filename, path)[0] def mime_of(filename: str, path: str | Path | None = None) -> str: return detect(filename, path)[1] def normalize_content_type(value: str | None) -> str | None: """An explicitly requested type, or None when the caller should detect. A model naming a type we do not have a viewer for is not an error; it is a missing hint, so detection answers instead of the value being stored as is. """ if not value: return None value = value.strip().lower() if value in CONTENT_TYPES and value != "unknown": return value return None def is_inline_mime(mime: str) -> bool: """Whether a browser can show this response in place instead of saving it.""" return mime.startswith(_INLINE_PREFIXES) or mime in _INLINE_MIMES