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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13965-a-binary-file-nothing-else-opens-shows-i → main 8 commits fork 3 threads · 3 unresolved

  • Merged. scout/13965-a-binary-file-nothing-else-opens-shows-i was merged into main as 61a2423.

Review

Sign in to review this change.
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
1616 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.
1717
1818 - `.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 @@
22
33 Open the blob page of a binary nothing can render, such as a `.wasm` or an
44 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.
810
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.
1013
1114 A binary over the 5 MB read ceiling is not read, so it has no type word; it
1215 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";
5151 import { parseUnifiedDiff, type Diff } from "../../git/diff.ts";
5252 import { renderDiff as renderPatch } from "../ui/diff.ts";
5353 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";
5555 import { tailOf, tailSentence } from "../../web/log_tail.ts";
5656 import { downloadHref } from "../../web/pages/media.ts";
57 import { hexdump, HEX_BYTES } from "../../web/render/hexdump.ts";
5758 import { isModelPath, modelFacts } from "../../web/render/model-facts.ts";
5859 import type { RepoFacts, RepoSource } from "../../view/source.ts";
5960 import { detectLanguage, highlightLines } from "../../web/highlight.ts";
@@ -1496,11 +1497,20 @@ export function workspaceScreen(
14961497 if (looksLikeImage(t.path)) picture = read.value.body;
14971498 else if (book !== null && typeof book !== "string") sheet = book;
14981499 else if (typeof book === "string") note = book;
1499 else
1500 note =
1500 else {
1501 const known =
15011502 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 }
15041514 } else {
15051515 raw = read.value.body; // .html included: source here, the page preview is web-only
15061516 // 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";
9090 import { declaresFeature } from "../../actions/features.ts";
9191 import { getAppByRepo } from "../../core/apps.ts";
9292 import { field, readForm } from "../form.ts";
93 import { hexdump, HEX_BYTES } from "../render/hexdump.ts";
9394 import { html, raw, when, type Html } from "../html.ts";
9495 import { templateCard } from "../template_card.ts";
9596 import { creditLine } from "../credit_line.ts";
@@ -752,6 +753,15 @@ export function blobBody(
752753 why?: string,
753754 ): { content: Html; lines: number } {
754755 const encoded = encodeURIComponent(ref);
756 if (blob.kind === "binary" && why === undefined) {

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.

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 }
755765 if (blob.kind === "binary") {
756766 return {
757767 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:
494494 /* A badge or an image in a line of text: a line of height reserved, the width its own. */
495495 .prose img.img-inline { display: inline-block; min-height: 20px; width: auto; vertical-align: middle; }
496496 .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; }
497498 .nb-cap { color: var(--muted-fg); font-size: 12.5px; margin-top: 8px; }
498499
499500 /* 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", () => {
2121 let app: App;
2222 let servers: Servers;
2323 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.
2525 const body = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0, 0, 0, ...new TextEncoder().encode("<script>SECRET-BYTES</script>")]);
2626
2727 beforeAll(async () => {
@@ -50,9 +50,10 @@ describe("a binary on its blob page", () => {
5050 const res = await fetch(`${base}/alice/p/blob/main/mod.bin`);
5151 const text = await res.text();
5252 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.`);
5454 expect(text).toContain("download=1");
55 expect(text).not.toContain("SECRET-BYTES");
55 expect(text).not.toContain("<script>");
56 expect(text).toContain("|.asm....&lt;script&gt;|");
5657 expect(res.headers.get("content-security-policy")).toBeTruthy();
5758 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
5859 expect(res.headers.get("referrer-policy")).toBeTruthy();
test/fuzz-renderers.test.ts +4 −9
@@ -319,23 +319,18 @@ describe("a file nothing can render", () => {
319319 return b;
320320 };
321321
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", () => {
323323 const body = random(4000, 7);
324324 const name = "weird<name>.blob";
325325 const { content } = blobBody("/o/r", "main", name, { kind: "binary", body, size: body.length });
326326 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.");
330328 expect(page).not.toContain("weird&lt;name&gt;.blob ·");
331329 // The escaped name reaches the page through the download href only.
332330 expect(page).toContain('href="/o/r/media/main/weird&lt;name&gt;.blob?download=1"');
333 expect(page).toContain("download=1");
334331 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");
339334 });
340335
341336 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("&lt;script&gt;");
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", () => {
257257 await open(h, "kinds");
258258 await openFile(h, "nul.log");
259259 expect(h.text()).toContain("Binary file");
260 expect(h.text()).toContain("as hex");
261 expect(h.text()).toContain("00000000 ");
260262 await openFile(h, "empty.log");
261263 expect(h.text()).toContain("alice/kinds");
262264 } finally {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs