Public: anyone can read this; the crew can change it.
A binary file nothing else opens shows its size, detected type and a hex dump of its first 4 KB #13995
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13965-a-binary-file-nothing-else-opens-shows-i → main 8 commits fork 3 threads · 3 unresolved
10 files
changed +126
−21
docs/design/areas/code.md +2
| @@ -16,3 +16,5 @@ A font specimen (`render/font.ts`): `.font-view` sits in a bare card (`card({ ex | ||
| 16 | 16 | An HTML file's preview (`render/html_preview.ts`): `.html-frame` is a bare sandboxed frame with its own hairline (no card around it) 80vh tall (480px at least, 60vh on a phone). The frame is `color-scheme: light`, so the page inside gets the white canvas it was written for in either theme. |
| 17 | 17 | |
| 18 | 18 | - `.front-matter` — a Markdown file's leading `---` block (`frontTable` in `render/markdown.ts`): a `dl.status-rows` of `.status-row` facts above the prose, keys in `--muted-fg`, keys and values wrapping anywhere so a long value never scrolls the page at 360px. |
| 19 | ||
| 20 | - `.hexdump` — the last-resort view of a binary file (`render/hexdump.ts`): a `pre.card` of offset, sixteen hex bytes and their ASCII in `--mono` 12.5px, scrolling sideways inside its own box so the page never does at 390px. |
docs/features/binary-file.md +7 −4
| @@ -2,11 +2,14 @@ | ||
| 2 | 2 | |
| 3 | 3 | Open the blob page of a binary nothing can render, such as a `.wasm` or an |
| 4 | 4 | unknown blob. Under the page header, which names the file, a note gives its |
| 5 | size and a type word sniffed from its first bytes, with a Download button: | |
| 6 | `12 KB · ZIP archive — not shown, but you can download it.` When no signature | |
| 7 | matches, the word is `binary data`. The bytes are never shown. | |
| 5 | size and a type word sniffed from its first bytes, with Download and Raw links: | |
| 6 | `Binary file · 12 KB · ZIP archive — first 4 KB as hex.` When no signature | |
| 7 | matches, the word is `binary data`. Below it, a hex dump of the first 4 KB (offset, sixteen | |
| 8 | bytes, printable ASCII) in a focusable region named "Hex dump of the first | |
| 9 | bytes". Archives and other files with their own view keep that view. | |
| 8 | 10 | |
| 9 | The terminal's file view says the same: `Binary file, 12 KB, ZIP archive.` | |
| 11 | The terminal's file view shows the same: `Binary file, 12 KB, ZIP archive. | |
| 12 | First 4 KB as hex.` and the dump beneath. | |
| 10 | 13 | |
| 11 | 14 | A binary over the 5 MB read ceiling is not read, so it has no type word; it |
| 12 | 15 | reads "Too large to render" with its size and a download. |
src/tui/screens/workspace.ts +15 −5
| @@ -51,9 +51,10 @@ import type { TreeEntry } from "../../git/read.ts"; | ||
| 51 | 51 | import { parseUnifiedDiff, type Diff } from "../../git/diff.ts"; |
| 52 | 52 | import { renderDiff as renderPatch } from "../ui/diff.ts"; |
| 53 | 53 | import { jsonOutlineText } from "../../web/render/json-big.ts"; |
| 54 | import { fileKind, isEnvExample, isJsonPath, kindByName, HEAD_BYTES, NO_BYTES, RENDER_CAP, sniffType } from "../../web/render/kinds.ts"; | |
| 54 | import { fileKind, isEnvExample, isJsonPath, kindByName, NO_BYTES, RENDER_CAP, sniffType } from "../../web/render/kinds.ts"; | |
| 55 | 55 | import { tailOf, tailSentence } from "../../web/log_tail.ts"; |
| 56 | 56 | import { downloadHref } from "../../web/pages/media.ts"; |
| 57 | import { hexdump, HEX_BYTES } from "../../web/render/hexdump.ts"; | |
| 57 | 58 | import { isModelPath, modelFacts } from "../../web/render/model-facts.ts"; |
| 58 | 59 | import type { RepoFacts, RepoSource } from "../../view/source.ts"; |
| 59 | 60 | import { detectLanguage, highlightLines } from "../../web/highlight.ts"; |
| @@ -1496,11 +1497,20 @@ export function workspaceScreen( | ||
| 1496 | 1497 | if (looksLikeImage(t.path)) picture = read.value.body; |
| 1497 | 1498 | else if (book !== null && typeof book !== "string") sheet = book; |
| 1498 | 1499 | else if (typeof book === "string") note = book; |
| 1499 | else | |
| 1500 | note = | |
| 1500 | else { | |
| 1501 | const known = | |
| 1501 | 1502 | archiveNote(t.path, read.value.body, read.value.size, formatSize) ?? |
| 1502 | (kindByName(t.path) === "psd" ? psdNote(read.value.body, read.value.size, formatSize) : undefined) ?? | |
| 1503 | `Binary file, ${formatSize(read.value.size)}, ${sniffType(read.value.body.subarray(0, HEAD_BYTES))}.`; | |
| 1503 | (kindByName(t.path) === "psd" ? psdNote(read.value.body, read.value.size, formatSize) : undefined); | |
| 1504 | if (known !== undefined) note = known; | |
| 1505 | else { | |
| 1506 | // The page's last resort too: size, type and the first bytes as hex (pure ASCII, so | |
| 1507 | // safe to draw). | |
| 1508 | const head = read.value.body.subarray(0, HEX_BYTES); | |
| 1509 | raw = new TextEncoder().encode( | |
| 1510 | `Binary file, ${formatSize(read.value.size)}, ${sniffType(head)}. First ${formatSize(head.length)} as hex.\n\n${hexdump(head)}\n`, | |
| 1511 | ); | |
| 1512 | } | |
| 1513 | } | |
| 1504 | 1514 | } else { |
| 1505 | 1515 | raw = read.value.body; // .html included: source here, the page preview is web-only |
| 1506 | 1516 | // A big JSON file arrives cut: its first level is drawn, as the page draws it. |
src/web/pages/repo.ts +10
| @@ -90,6 +90,7 @@ import { studioApp } from "../studio/app.ts"; | ||
| 90 | 90 | import { declaresFeature } from "../../actions/features.ts"; |
| 91 | 91 | import { getAppByRepo } from "../../core/apps.ts"; |
| 92 | 92 | import { field, readForm } from "../form.ts"; |
| 93 | import { hexdump, HEX_BYTES } from "../render/hexdump.ts"; | |
| 93 | 94 | import { html, raw, when, type Html } from "../html.ts"; |
| 94 | 95 | import { templateCard } from "../template_card.ts"; |
| 95 | 96 | import { creditLine } from "../credit_line.ts"; |
| @@ -752,6 +753,15 @@ export function blobBody( | ||
| 752 | 753 | why?: string, |
| 753 | 754 | ): { content: Html; lines: number } { |
| 754 | 755 | const encoded = encodeURIComponent(ref); |
| 756 | if (blob.kind === "binary" && why === undefined) { | |
| 757 | const head = blob.body.subarray(0, HEX_BYTES); | |
| 758 | const shown = Math.min(head.length, blob.size); | |
| 759 | return { | |
| 760 | lines: 0, | |
| 761 | content: html`<p class="nb-cap">Binary file · ${fileSize(blob.size)} · ${sniffType(head)} — first ${fileSize(shown)} as hex. <a href="${downloadHref(base, ref, path)}">Download</a> · <a href="${mediaHref(base, ref, path)}">Raw</a></p> | |
| 762 | <pre class="card hexdump" tabindex="0" role="region" aria-label="Hex dump of the first bytes">${hexdump(head)}</pre>`, | |
outdated
A focusable pre with no name: add role="region" aria-label="Hex dump of the first bytes" so keyboard and screen-reader users know what it is. |
||
| 763 | }; | |
| 764 | } | |
| 755 | 765 | if (blob.kind === "binary") { |
| 756 | 766 | return { |
| 757 | 767 | lines: 0, |
src/web/render/hexdump.ts added +29
| @@ -0,0 +1,29 @@ | ||
| 1 | /** | |
| 2 | * The last resort for a file nothing else opens: its first bytes as a hex dump, | |
| 3 | * offset, sixteen bytes, then the printable ASCII. Plain data in, plain text out; | |
| 4 | * the page escapes it where it is drawn. | |
| 5 | */ | |
| 6 | ||
| 7 | /** The most bytes ever dumped, and so the most ever read for it. */ | |
| 8 | export const HEX_BYTES = 4096; | |
| 9 | ||
| 10 | const WIDTH = 16; | |
| 11 | ||
| 12 | /** Offset, hex and ASCII columns for at most `HEX_BYTES` of `head`; one line per 16 bytes. */ | |
| 13 | export function hexdump(head: Uint8Array): string { | |
| 14 | const shown = head.subarray(0, HEX_BYTES); | |
| 15 | const lines: string[] = []; | |
| 16 | for (let at = 0; at < shown.length; at += WIDTH) { | |
| 17 | const row = shown.subarray(at, at + WIDTH); | |
| 18 | let hex = ""; | |
| 19 | let text = ""; | |
| 20 | for (let i = 0; i < WIDTH; i++) { | |
| 21 | const b = row[i]; | |
| 22 | hex += b === undefined ? " " : `${b.toString(16).padStart(2, "0")} `; | |
| 23 | if (i === 7) hex += " "; | |
| 24 | if (b !== undefined) text += b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : "."; | |
| 25 | } | |
| 26 | lines.push(`${at.toString(16).padStart(8, "0")} ${hex} |${text}|`); | |
| 27 | } | |
| 28 | return lines.join("\n"); | |
| 29 | } |
src/web/style/content.ts +1
| @@ -494,6 +494,7 @@ img.img-box, .prose img.img-box, .tell-picture.img-box { display: block; width: | ||
| 494 | 494 | /* A badge or an image in a line of text: a line of height reserved, the width its own. */ |
| 495 | 495 | .prose img.img-inline { display: inline-block; min-height: 20px; width: auto; vertical-align: middle; } |
| 496 | 496 | .nb-img { display: block; max-width: 100%; height: auto; margin: 8px 0; } |
| 497 | .hexdump { font-family: var(--mono); font-size: 12.5px; line-height: 1.5; padding: 12px; margin: 8px 0; overflow-x: auto; max-width: 100%; white-space: pre; } | |
| 497 | 498 | .nb-cap { color: var(--muted-fg); font-size: 12.5px; margin-top: 8px; } |
| 498 | 499 | |
| 499 | 500 | /* A terminal log (render/log.ts): SGR colours as fixed classes, theme tokens only. */ |
test/blob-binary-page.test.ts +4 −3
| @@ -21,7 +21,7 @@ describe("a binary on its blob page", () => { | ||
| 21 | 21 | let app: App; |
| 22 | 22 | let servers: Servers; |
| 23 | 23 | let base = ""; |
| 24 | // A WebAssembly header, a NUL, and a marker that must never reach the page. | |
| 24 | // A WebAssembly header, a NUL, and markup that must reach the page only escaped. | |
| 25 | 25 | const body = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0, 0, 0, ...new TextEncoder().encode("<script>SECRET-BYTES</script>")]); |
| 26 | 26 | |
| 27 | 27 | beforeAll(async () => { |
| @@ -50,9 +50,10 @@ describe("a binary on its blob page", () => { | ||
| 50 | 50 | const res = await fetch(`${base}/alice/p/blob/main/mod.bin`); |
| 51 | 51 | const text = await res.text(); |
| 52 | 52 | expect(res.status).toBe(200); |
| 53 | expect(text).toContain(`${body.length} B · WebAssembly module — not shown, but you can download it.`); | |
| 53 | expect(text).toContain(`${body.length} B · WebAssembly module — first ${body.length} B as hex.`); | |
| 54 | 54 | expect(text).toContain("download=1"); |
| 55 | expect(text).not.toContain("SECRET-BYTES"); | |
| 55 | expect(text).not.toContain("<script>"); | |
| 56 | expect(text).toContain("|.asm....<script>|"); | |
| 56 | 57 | expect(res.headers.get("content-security-policy")).toBeTruthy(); |
| 57 | 58 | expect(res.headers.get("x-content-type-options")).toBe("nosniff"); |
| 58 | 59 | expect(res.headers.get("referrer-policy")).toBeTruthy(); |
test/fuzz-renderers.test.ts +4 −9
| @@ -319,23 +319,18 @@ describe("a file nothing can render", () => { | ||
| 319 | 319 | return b; |
| 320 | 320 | }; |
| 321 | 321 | |
| 322 | test("shows size, a type word and a download, and none of its bytes", () => { | |
| 322 | test("shows size, a type word, a download and a hex dump of the head, escaped", () => { | |
| 323 | 323 | const body = random(4000, 7); |
| 324 | 324 | const name = "weird<name>.blob"; |
| 325 | 325 | const { content } = blobBody("/o/r", "main", name, { kind: "binary", body, size: body.length }); |
| 326 | 326 | const page = content.text; |
| 327 | // The page header already names the file; the note says size and type only (DESIGN principle | |
| 328 | // 1). | |
| 329 | expect(page).toContain("3.9 KB · binary data — not shown, but you can download it."); | |
| 327 | expect(page).toContain("3.9 KB · binary data — first 3.9 KB as hex."); | |
| 330 | 328 | expect(page).not.toContain("weird<name>.blob ·"); |
| 331 | 329 | // The escaped name reaches the page through the download href only. |
| 332 | 330 | expect(page).toContain('href="/o/r/media/main/weird<name>.blob?download=1"'); |
| 333 | expect(page).toContain("download=1"); | |
| 334 | 331 | expect(page).not.toContain("<name>"); |
| 335 | expect(page.length).toBeLessThan(2000); | |
| 336 | // No run of the file's own bytes is in the page. | |
| 337 | const text = new TextDecoder("latin1").decode(body); | |
| 338 | for (let i = 0; i + 16 <= text.length; i += 16) expect(page.includes(text.slice(i, i + 16))).toBe(false); | |
| 332 | // The dump starts at offset zero with the file's own first bytes. | |
| 333 | expect(page).toContain("00000000 01 0f fa b2"); | |
| 339 | 334 | }); |
| 340 | 335 | |
| 341 | 336 | test("a signature gives its word", () => { |
test/render-hexdump.test.ts added +52
| @@ -0,0 +1,52 @@ | ||
| 1 | import { describe, expect, test } from "bun:test"; | |
| 2 | import { hexdump, HEX_BYTES } from "../src/web/render/hexdump.ts"; | |
| 3 | import { sniffType } from "../src/web/render/kinds.ts"; | |
| 4 | import { blobBody } from "../src/web/pages/repo.ts"; | |
| 5 | ||
| 6 | const PNG = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0x0d, 0x49, 0x48, 0x44, 0x52, 0x41]); | |
| 7 | const ZIP = Uint8Array.from([0x50, 0x4b, 0x03, 0x04, 0x14, 0, 0, 0]); | |
| 8 | ||
| 9 | describe("hexdump", () => { | |
| 10 | test("PNG header: offsets, hex, ascii", () => { | |
| 11 | const [first, second] = hexdump(PNG).split("\n"); | |
| 12 | expect(first).toBe("00000000 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 |.PNG........IHDR|"); | |
| 13 | expect(second).toStartWith("00000010 41 "); | |
| 14 | expect(second).toEndWith("|A|"); | |
| 15 | expect(sniffType(PNG)).toBe("PNG image"); | |
| 16 | }); | |
| 17 | test("ZIP header", () => { | |
| 18 | expect(hexdump(ZIP)).toStartWith("00000000 50 4b 03 04 14 00 00 00 "); | |
| 19 | expect(hexdump(ZIP)).toEndWith("|PK......|"); | |
| 20 | expect(sniffType(ZIP)).toBe("ZIP archive"); | |
| 21 | }); | |
| 22 | test("never more than 4 KB, however much is handed", () => { | |
| 23 | const lines = hexdump(new Uint8Array(100_000).fill(7)).split("\n"); | |
| 24 | expect(lines.length).toBe(HEX_BYTES / 16); | |
| 25 | expect(lines.at(-1)).toStartWith("00000ff0"); | |
| 26 | }); | |
| 27 | test("empty has no rows", () => expect(hexdump(new Uint8Array(0))).toBe("")); | |
| 28 | }); | |
| 29 | ||
| 30 | describe("binary blob page body", () => { | |
| 31 | const draw = (body: Uint8Array, size = body.length) => | |
| 32 | String(blobBody("/a/b", "main", "x.bin", { kind: "binary", body, size }).content); | |
| 33 | test("random bytes: size, type, dump and the raw link", () => { | |
| 34 | const body = new Uint8Array(5000); | |
| 35 | crypto.getRandomValues(body); | |
| 36 | body[0] = 0; // never a signature | |
| 37 | body[1] = 1; | |
| 38 | const out = draw(body); | |
| 39 | expect(out).toContain("binary data"); | |
| 40 | expect(out).toContain("00000000 00 01 "); | |
| 41 | expect(out).toContain("00000ff0"); | |
| 42 | expect(out).not.toContain("00001000"); | |
| 43 | expect(out).toContain("/a/b/media/main/x.bin"); | |
| 44 | }); | |
| 45 | test("output is escaped", () => { | |
| 46 | const body = new TextEncoder().encode("<script>alert(1)</script>&\"'\0"); | |
| 47 | const out = draw(body); | |
| 48 | expect(out).not.toContain("<script>"); | |
| 49 | expect(out).toContain("<script>"); | |
| 50 | }); | |
| 51 | test("names a PNG", () => expect(draw(PNG)).toContain("PNG image")); | |
| 52 | }); |
test/tui-workspace-kinds.test.ts +2
| @@ -257,6 +257,8 @@ describe("the workspace opens each kind", () => { | ||
| 257 | 257 | await open(h, "kinds"); |
| 258 | 258 | await openFile(h, "nul.log"); |
| 259 | 259 | expect(h.text()).toContain("Binary file"); |
| 260 | expect(h.text()).toContain("as hex"); | |
| 261 | expect(h.text()).toContain("00000000 "); | |
| 260 | 262 | await openFile(h, "empty.log"); |
| 261 | 263 | expect(h.text()).toContain("alice/kinds"); |
| 262 | 264 | } finally { |
new above
offline
Both doors: the terminal gets no equivalent of this view. Add a src/tui/ screen or extend the file screen with size, type and hex, plus docs/features/<name>.md for the how-to.