Files in the browser: the media route and the kind registry

The foundation for rendering files on the blob page (#7329, #7330).

The media route

GET /:owner/:name/media/:ref/*path serves a file's bytes under a real media type, for <img>, <video>, <audio>, <object> and fetch().

(png, jpeg, gif, webp, avif, bmp, ico, svg, pdf, mp3, ogg/oga, wav, flac, m4a, aac, mp4, m4v, webm, mov, stl, 3mf, glb). The extension proposes a type and the file's first bytes confirm it; a mismatch, or any other file, is application/octet-stream. Never HTML, never script.

Content-Security-Policy: sandbox; default-src 'none'; img-src 'self' data:; media-src 'self'; style-src 'unsafe-inline', so an SVG with a <script> is drawn and never runs.

under sandbox, so application/pdf, and only that type, is sent default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; frame-ancestors 'self' (no sandbox), still nosniff and inline. It is chosen by the confirmed type, so a file named .pdf without %PDF- bytes, and any ?download=1, keep the sandbox policy. A PDF is never served as HTML.

X-Frame-Options: SAMEORIGIN: the blob page may embed it, no other site.

<object type="application/pdf"> on the media URL, with an "Open the PDF" link and a Download button inside it for a browser that cannot draw it. That page, and no other, passes objectSrc: true to page(), which adds object-src 'self' to its policy; it is sent only when the page really draws the PDF, never for ?view=source, and never site-wide. The PDF is drawn for a repository on this forge, not for a browsed origin (the media route is not there). Like audio and video it is streamed, drawn by name at any size up to its cap; the media route confirms the bytes.

at its media URL a same-origin document. The viewers run a PDF's script in their own engine (PDFium's in Chrome, pdf.js's scripting sandbox in Firefox), which has no access to this origin's DOM, cookies or fetch, and the response's default-src 'none' forbids the document any load. That is the viewers' documented isolation, not something this route enforces; it is why the exception is one type, chosen by confirmed %PDF- bytes, and why a .pdf of HTML, an SVG, and every download keep sandbox.

(bytes=-N) is the last N bytes; past the end is 416. A list of ranges is answered whole, which the RFC allows. If-Range is honoured.

full commit id as :ref is private, max-age=31536000, immutable; a branch or tag is private, max-age=0 and revalidates.

that is not there.

held whole. Streams take permits from their own gate (mediaGate, FORGE_MEDIA_CONCURRENCY, default 16), so a page of videos never takes the plumbing permits every page needs. The permit is taken before the stream exists; a stream gives it back when it ends, when its reader hangs up, or when nothing has been pulled for 30 s (MEDIA_IDLE_MS), so a reader that never reads cannot hold one for good. With 32 requests already waiting (MEDIA_QUEUE_MAX) the next is a 503 with Retry-After: 5. A file of 1 MB or less never waits: it is read through the pooled reader.

size. The blob page's Download button points here.

The kind registry

fileKind(path, firstBytes) answers image | svg | pdf | audio | video | csv | model3d | config | markdown | patch | text | binary. RENDER_CAP is the largest file each kind draws inline; over it, the page offers Download.

kinds.ts is plain data with no web dependency: the editor and the terminal ask it whether a path is Markdown, as the blob page does.

renderBlob asks rendererFor in render/renderers.ts. A kind in RENDERERS is drawn by its module; a kind with none yet keeps the source or binary view it always had. A file too large for the page to read is drawn only by a media kind (MEDIA_KINDS), whose renderer never reads the body (the browser fetches the media route), and only up to that kind's cap. A page with no media route (a live browse of another forge, /origins/…) draws no media kind. Where a renderer exists the header offers Rendered | Source; every file's header has the Raw and Download buttons.

Audio and video (#7333)

An audio file is <audio controls preload="metadata"> and a video <video controls playsinline preload="metadata">, each with a <source> on the media route and the registry's type (render/audio.ts, render/video.ts, render/player.ts). Range on the media route is what seeks. A .mov also offers itself as video/mp4, which is what most QuickTime files are inside, for browsers that refuse video/quicktime.

(MEDIA_PLAY_JS) hides the player and shows "Your browser can't play this format" with Download, already in the markup.

Download, so an undecodable file is never a dead end.

returned by claimedMedia): one table names each format.

says so, names the format and size, and prints the media route on the forge's address (src/tui/ui/media-note.ts).

kinds (image, svg, pdf, audio, video, model3d — MEDIA_KINDS in render/renderers.ts) are drawn from the media route alone, so they are bounded by RENDER_CAP, not by that ceiling: past it the page reads only the first HEAD_BYTES (blobHead in src/git/read.ts, which stops cat-file once they are in) and the size, fileKind decides, and the renderer gets an empty body and the media address. A .pdf whose bytes are text keeps the over-cap note. Where the source gave no bytes (a mirrored origin), the extension decides (claimedMedia) and the media route confirms the bytes, serving a contradicted file as application/octet-stream, and the player shows the note.

page's own diff (parseUnifiedDiff into renderDiff). A git format-patch mail header (From, Subject, Date) shows above it as a plain list of rows. Text with no diff --git file in it (a plain diff -u, notes) is not parsed and falls back to the text view. The terminal's file view draws the same parse with its pull diff (tui/ui/diff.ts); v shows the source.

1 MB ceiling: over it the page says "over the render cap" and offers Download.

Adding a renderer

Write src/web/render/<kind>.ts exporting a Renderer (plain data in: path, size, body, and media, the media route's address; HTML out), and name it once in RENDERERS (render/renderers.ts); rendererFor picks it. Point any element that needs the bytes at input.media, never at an inline copy, so repository content only ever runs under the media route's sandbox. render/markdown.ts is the example.

3D models

An .stl (ASCII or binary), .obj, .3mf, .glb or .gltf file's page shows the part, ready to turn (src/web/render/model3d.ts, #7335).

fingers to pan; with the view focused, the arrow keys pan.

in the file's own axes. STL and OBJ units are taken as millimetres; glTF is metres by its spec, so its box is multiplied by 1000. A .3mf print project takes its units from the model's unit attribute (millimetre by default; micron, centimetre, inch, foot and metre are scaled to mm), and is stood Z-up like an STL. Its build items and transforms are applied. A 3MF is refused, with a sentence, Source and Download kept, when it is zip64, has an encrypted entry, holds more than 5 million triangles, inflates to more than 64 MB of XML (INFLATE_LIMIT), or is a production-extension model whose objects live in other files (it names an object that is not there).

a grid sits under it, and every part wears one neutral material. An STL is stood Z-up, the way a printer reads it.

file's bar. Up to 100 MB (RENDER_CAP.model3d) a part is drawn, even one too large for the page to read whole; over it, the page offers Download.

route to fetch from, so a model keeps its source or binary view there.

button. A file that is not its format says why in the head and keeps them too.

come from the media route with fetch(), and STL and OBJ are parsed in the browser by render/mesh.ts; glTF goes through three.js's loader. A .gltf whose buffers are separate files finds them beside it on the media route. Only those are fetched: every URI a glTF names goes through withinModelDir (render/gltf-uri.ts), and one that is not same-origin with a path under the model's own directory (../, an encoded dot or slash, an absolute path, another host, data: or blob:) is sent to about:blank and never requested, so a public model cannot make its readers' browsers call anything else on the forge.

the part, so the file view of a binary or too-large model says what the page shows: 3D model · STL over 12 triangles · 20 × 20 × 20 mm, and under it Download: <forge>/<owner>/<repo>/media/<ref>/<path>?download=1 (render/model-facts.ts, the same parsers). Up to 2 MB (FACTS_CAP) the bytes are read; over it, the model is named and sized. A glTF's facts come from its JSON (vertex counts, position bounds in metres, before node transforms). An ASCII STL or OBJ is text, so it opens as its source, as the web's Source view does.

its MIT licence, in src/web/render/vendor/three/ (its README lists the files and their hashes). model3d-client.ts is bundled with it into /assets/model3d-<hash>.js (648 KB, 166 KB gzipped, immutable), named by a hash of its sources so the page knows the address without a build. The frame names it in data-module, and the shell loads it with its own nonce only when a figure asks, on a full load or when the code browser swaps the file in.

Images and SVG (#7331)

render/image.ts draws the image and svg kinds as an <img> at the media route; an SVG is never inlined. The picture fits the pane; a click shows it at 100% and the pane scrolls or drags to pan. A checkerboard sits behind it for transparency. The header line carries the pixel size (read in the browser from naturalWidth/naturalHeight by a few lines in the shell script, so no new request), the file size and the format. Animated GIF and WebP play, since the browser draws the original bytes. Over RENDER_CAP the page shows the "too large" notice and Download.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs