app/lib/media/classify.mjs

Functions

Imports

It imports app/lib/bytes.mjs. Imported by app/db/media.ts, app/lib/carrel/media-adapter.server.ts, app/lib/content/diagram.mjs, app/lib/content/og-card-text.mjs, app/lib/content/pipeline.mjs, app/lib/cover-image.mjs, app/lib/editor/publish.server.ts, app/lib/media/actions.server.ts, app/lib/media/core.server.ts, app/lib/media/rebuild.server.ts, app/lib/media/upload.server.ts, app/lib/publications/export-response.mjs, app/lib/publications/paths.mjs, app/routes/admin.media._index.tsx, app/routes/media.$.ts, workers/media-events.ts.

Source

1import { toHex } from "../bytes.mjs";
2
3const TYPES = new Map([
4  ["png", { kind: "image", mime: "image/png" }],
5  ["jpg", { kind: "image", mime: "image/jpeg" }],
6  ["jpeg", { kind: "image", mime: "image/jpeg" }],
7  ["webp", { kind: "image", mime: "image/webp" }],
8  ["avif", { kind: "image", mime: "image/avif" }],
9  ["gif", { kind: "image", mime: "image/gif" }],
10  ["svg", { kind: "image", mime: "image/svg+xml" }],
11  ["ico", { kind: "image", mime: "image/x-icon" }],
12  ["pdf", { kind: "document", mime: "application/pdf" }],
13  ["webmanifest", { kind: "other", mime: "application/manifest+json" }],
14  // The pronunciation clips under /audio/ (content/dictionary/*.md), generated once, never per visit.
15  ["mp3", { kind: "other", mime: "audio/mpeg" }],
16  // The SIL OFL requires the font licence to be served with the fonts.
17  ["txt", { kind: "document", mime: "text/plain; charset=utf-8" }],
18  // No woff2: fonts live in app/fonts/, so a webfont dropped into public/ should stop the build.
19]);
20
21const RASTER = new Set(["png", "jpg", "jpeg", "webp", "avif", "gif"]);
22
23/**
24 * The "" for no extension is load-bearing: `classify()` throws on it, which stops the build.
25 * Not the display label; that is `extensionLabel` in media-document-card.tsx.
26 *
27 * @param {string} pathOrKey
28 */
29function extensionOf(pathOrKey) {
30  const base = pathOrKey.split("/").pop() ?? "";
31  const dot = base.lastIndexOf(".");
32  return dot === -1 ? "" : base.slice(dot + 1).toLowerCase();
33}
34
35/**
36 * THROWS on an unknown extension: a new file type under `public/` must stop the build, not get a
37 * plausible `kind` nobody chose.
38 *
39 * @param {string} pathOrKey
40 * @returns {{ kind: string, mime: string, extension: string }}
41 */
42export function classify(pathOrKey) {
43  const extension = extensionOf(pathOrKey);
44  const type = TYPES.get(extension);
45  if (!type) {
46    throw new Error(
47      `unclassified asset "${pathOrKey}": extension "${extension || "(none)"}" is not in ` +
48        `app/lib/media/classify.mjs. Add it there, in the same commit as the file.`,
49    );
50  }
51  return { kind: type.kind, mime: type.mime, extension };
52}
53
54// Deploy-time control files: Cloudflare consumes them and never serves them. Named, not a rule, because
55// "skip anything extensionless" would fail open. Do NOT add /fonts/dustin-edwards-ofl.txt: it is served,
56// so it is an asset; if index drift reports it, the repair is the rebuild on /admin/media.
57const NOT_ASSETS = new Map([
58  [
59    "/_headers",
60    "Cloudflare static-asset header rules. Consumed by the uploader at deploy " +
61      "time and never served, so it has no URL to index. Subject of check:headers.",
62  ],
63  [
64    "/_redirects",
65    "Cloudflare static-asset redirect rules. Same deploy-time contract as _headers.",
66  ],
67]);
68
69// A pattern is allowed here because it matches only the slug shape paths.mjs generates. The twins are
70// gitignored build product, not media; llms.txt lists them and check:machine-readable reconciles it.
71const NOT_ASSET_PATTERNS = [
72  {
73    test: /^\/research\/publications\/[a-z0-9-]+\.md$/,
74    why:
75      "A generated markdown twin of a paper, gitignored build product served " +
76      "as an asset. Listed in llms.txt and reconciled by check:machine-readable; " +
77      "not media, and not committed, so not in this manifest.",
78  },
79];
80
81/**
82 * @param {string} pathOrKey
83 * @returns {string | null}
84 */
85export function excludedFromAssets(pathOrKey) {
86  const named = NOT_ASSETS.get(pathOrKey);
87  if (named) return named;
88  return NOT_ASSET_PATTERNS.find((rule) => rule.test.test(pathOrKey))?.why ?? null;
89}
90
91/**
92 * @param {string} pathOrKey
93 */
94export function isRaster(pathOrKey) {
95  return RASTER.has(extensionOf(pathOrKey));
96}
97
98/**
99 * Static assets are indexed under their public path, which starts with `/`; an R2 key never does.
100 *
101 * @param {string} pathOrKey
102 * @returns {"static" | "r2-derived" | "r2"}
103 */
104export function storageOf(pathOrKey) {
105  if (pathOrKey.startsWith("/")) return "static";
106  // `derived/` holds objects the Worker renders from its own data (the CV PDF, app/lib/cv/pdf.server.ts). It is its
107  // own prefix, not `og/`, because build:og prunes every `og/` key no post references.
108  if (pathOrKey.startsWith("og/") || pathOrKey.startsWith("derived/")) return "r2-derived";
109  return "r2";
110}
111
112/**
113 * Typed generically rather than against `Env`: this module is shared with the Node build scripts.
114 * A `static` key resolves to MEDIA, where the miss is loud in the index drift check.
115 *
116 * @template T
117 * @param {{ OG: T, MEDIA: T }} env
118 * @param {string} key
119 * @returns {T}
120 */
121export function bucketFor(env, key) {
122  return storageOf(key) === "r2-derived" ? env.OG : env.MEDIA;
123}
124
125/**
126 * Diagrams are light/dark pairs, so inserting one alone bypasses `:::diagram`; hence `generated`.
127 * `icon` is fetched by the platform (a `<link rel>` or the webmanifest); `brand` is named by
128 * application code. The default is `content`: an unknown asset should be visible in the picker.
129 *
130 * @param {string} pathOrKey
131 * @returns {"content" | "brand" | "generated" | "icon"}
132 */
133export function roleOf(pathOrKey) {
134  if (pathOrKey.startsWith("og/") || pathOrKey.startsWith("derived/")) return "generated";
135  if (pathOrKey.startsWith("/diagrams/")) return "generated";
136
137  // The OG image is brand, not icon: `seo.ts` names it as the default social card.
138  if (/^\/dustin-edwards-(logo(-[a-z]+)*\.svg|favicon\.svg|og-image\.png)$/.test(pathOrKey)) {
139    return "brand";
140  }
141
142  // `favicon.ico` and `site.webmanifest` keep unprefixed names because browsers request them unprompted.
143  if (
144    /^\/(favicon\.ico|site\.webmanifest|dustin-edwards-(apple-touch-icon\.png|android-chrome-[\dx]+\.png|maskable-icon-[\dx]+\.png))$/.test(
145      pathOrKey,
146    )
147  ) {
148    return "icon";
149  }
150
151  return "content";
152}
153
154/**
155 * Roster photos may not be cropped: `fit=cover` cuts faces off group photographs. Keyed on the path,
156 * so if these move to content-addressed R2 keys this must become a stored property.
157 *
158 * @param {string} pathOrKey
159 */
160export function cropSafe(pathOrKey) {
161  return !pathOrKey.startsWith("/phage-hunters/");
162}
163
164/**
165 * 16 hex characters (64 bits) is ample at this corpus size. The key carries `-<w>x<h>` so the Node build
166 * and the Worker produce the same stored HTML without either reading bytes; the digest pins the bytes,
167 * so it cannot go stale. The same image under two names is two objects.
168 *
169 * @param {ArrayBuffer} digest
170 * @param {string} extension
171 * @param {{ width: number, height: number } | null} [dimensions]
172 * @param {string | null} [name]
173 */
174export function contentKey(digest, extension, dimensions = null, name = null) {
175  const hex = toHex(digest);
176  const size =
177    dimensions && dimensions.width > 0 && dimensions.height > 0
178      ? `-${dimensions.width}x${dimensions.height}`
179      : "";
180  const slug = slugifyName(name);
181  return `${ASSET_PREFIX}${slug ? `${slug}-` : ""}${hex.slice(0, 16)}${size}.${extension}`;
182}
183
184export const ASSET_PREFIX = "dustin-edwards-";
185
186/**
187 * Capped at 48 so whoever names the upload cannot decide key length. A name already carrying the
188 * prefix loses it, or re-uploading a downloaded file would double it.
189 *
190 * @param {string | null | undefined} name
191 * @returns {string}
192 */
193function slugifyName(name) {
194  if (typeof name !== "string") return "";
195  return name
196    .replace(/\.[^.]*$/, "")
197    .toLowerCase()
198    .replace(/[^a-z0-9]+/g, "-")
199    .replace(/^-+/, "")
200    .replace(/^(?:dustin-edwards(?:-|$))+/, "")
201    .slice(0, 48)
202    .replace(/-+$/, "");
203}
204
205// The only statement of the key grammar. No character class admits a slash, so static paths, `og/` keys
206// and traversal all fail. Named groups, not indices. The slug is GREEDY so the LAST 16-hex run is the
207// digest. `[1-9]` refuses a leading-zero dimension; the parameter type keeps `contentKey` from writing one.
208const CONTENT_KEY_SHAPE =
209  /^dustin-edwards-(?:(?<slug>[a-z0-9][a-z0-9-]*)-)?(?<digest>[0-9a-f]{16})(?:-(?<width>[1-9]\d{0,4})x(?<height>[1-9]\d{0,4}))?\.[a-z0-9]+$/;
210
211/**
212 * `?w=320` is a transform request, not a different object, so query and fragment come off.
213 *
214 * @param {string} keyOrPath
215 * @returns {string | null}
216 */
217function bareKey(keyOrPath) {
218  if (typeof keyOrPath !== "string") return null;
219  const path = keyOrPath.split(/[?#]/)[0] ?? "";
220  return path.startsWith("/media/") ? path.slice("/media/".length) : path;
221}
222
223/**
224 * Strict: a malformed, zero or oversized segment returns null, which fails the build at the call site
225 * rather than silently dropping the dimensions that prevent layout shift.
226 *
227 * @param {string} keyOrPath
228 * @returns {{ width: number, height: number } | null}
229 */
230export function dimensionsFromKey(keyOrPath) {
231  const key = bareKey(keyOrPath);
232  if (key === null) return null;
233  const match = CONTENT_KEY_SHAPE.exec(key);
234  if (!match || match.groups?.width === undefined) return null;
235  return { width: Number(match.groups.width), height: Number(match.groups.height) };
236}
237
238/**
239 * Nothing outside this module may parse a content key (test/media-key-grammar.test.mjs).
240 *
241 * @param {string} key a bare key, never a `/media/` path
242 * @returns {boolean}
243 */
244export function isContentKey(key) {
245  return typeof key === "string" && CONTENT_KEY_SHAPE.test(key);
246}
247
248/**
249 * @param {string} keyOrPath
250 * @returns {string | null}
251 */
252export function digestFromKey(keyOrPath) {
253  const key = bareKey(keyOrPath);
254  if (key === null) return null;
255  const match = CONTENT_KEY_SHAPE.exec(key);
256  return match?.groups?.digest ?? null;
257}