app/lib/media/upload-contract.mjs

Functions

Imports

It imports app/lib/error-message.mjs, app/lib/media/byte-size.mjs. Imported by app/components/admin/media-upload-actions.tsx, app/components/admin/post-editor.tsx, app/lib/carrel/media-adapter.server.ts, app/lib/media/upload.server.ts, app/lib/operator/upload-media.server.ts, app/routes/admin.media._index.tsx, app/routes/admin.media.upload.ts.

Source

1// The form branch is selected ONLY by `intent=upload-form`, never by sniffing a header: a changed
2// default header would silently hand the editors' `response.json()` an HTML page.
3// Must stay loadable by node:test: never import anything reaching a binding, a `.server` module or React.
4
5import { errorMessage } from "../error-message.mjs";
6import { byteSize } from "./byte-size.mjs";
7
8export const ALLOWED = new Map([
9  ["image/webp", "webp"],
10  ["image/png", "png"],
11  ["image/jpeg", "jpg"],
12  ["image/avif", "avif"],
13  ["image/gif", "gif"],
14]);
15
16// NOT IN THE ALLOWLIST, and refused by name rather than as an unknown type: an SVG can carry script,
17// and /media is this site's own origin. The /media CSP (workers/csp.mjs) is the second wall, for
18// anything that reaches the bucket some other way.
19export const SVG_TYPE = "image/svg+xml";
20
21const SVG_REFUSED =
22  "SVG is not accepted: it can carry script, and /media is this site's own origin. " +
23  "Export it as PNG or WebP.";
24
25// A hint, not a control: drag-drop or a scripted post ignores `accept`. The control is the server check.
26export const ACCEPT_ATTRIBUTE = [...ALLOWED.keys()].join(",");
27
28export const MAX_BYTES = 10 * 1024 * 1024;
29
30export const UPLOAD_FORM_INTENT = "upload-form";
31
32export const UPLOAD_RETURN_PATH = "/admin/media";
33
34/**
35 * @param {unknown} intent the submitted `intent` field, whatever arrived
36 * @returns {boolean}
37 */
38export function isFormUpload(intent) {
39  return intent === UPLOAD_FORM_INTENT;
40}
41
42/**
43 * Both editors destructure `url`, and one inserts it into the markdown: a rename breaks inserts with no
44 * type error.
45 *
46 * @param {string} key
47 */
48export function uploadSuccessBody(key) {
49  return { url: `/media/${key}`, key };
50}
51
52/**
53 * @param {string} message
54 */
55export function uploadErrorBody(message) {
56  return { error: message };
57}
58
59/**
60 * The editors' upload: one file to the JSON branch. Never rejects, so a caller that `void`s it
61 * still shows every failure: the route's own refusal, the status when the body is not the
62 * route's JSON, or the network error.
63 *
64 * @param {File} file
65 * @returns {Promise<{ url: string } | { error: string }>}
66 */
67export async function uploadMedia(file) {
68  try {
69    const form = new FormData();
70    form.set("file", file);
71    const response = await fetch("/admin/media/upload", { method: "POST", body: form });
72    if (!response.ok) {
73      const detail = /** @type {{ error?: string }} */ (await response.json().catch(() => ({})));
74      return uploadErrorBody(detail.error ?? `Upload failed (${response.status}).`);
75    }
76    const { url } = /** @type {{ url: string }} */ (await response.json());
77    return { url };
78  } catch (error) {
79    return uploadErrorBody(`Upload failed: ${errorMessage(error)}`);
80  }
81}
82
83// A code in the URL, not the message, so the address bar never carries prose someone can edit.
84const UPLOAD_ERRORS = {
85  "no-file": "No file was chosen.",
86  "unsupported-type":
87    `That file type is not one this endpoint accepts. Uploads here are images: ` +
88    `${[...ALLOWED.keys()].map((mime) => mime.split("/")[1]).join(", ")}.`,
89  "too-large": `That image is over the ${MAX_BYTES / (1024 * 1024)} MB limit.`,
90  "svg-refused": SVG_REFUSED,
91  "content-mismatch":
92    "That file begins as markup, so it is not the image type it was uploaded " +
93    "as. Markup is not accepted: export the image as PNG or WebP.",
94  "images-unavailable":
95    "The image could not be measured, because Cloudflare Images did not answer. " +
96    "Nothing was stored; try again.",
97};
98
99/**
100 * `no-file` is left to each caller, because its repair differs. Takes the BYTES because the type is a
101 * claim: SVG bytes declared `image/png` would escape the SVG-as-attachment rule and be served inline.
102 *
103 * @param {{ type: string, bytes: ArrayBuffer }} file what arrived, before any store
104 * @returns {{ code: "unsupported-type" | "svg-refused" | "too-large" | "content-mismatch", message: string, status: number } | null}
105 */
106export function validateUpload({ type, bytes }) {
107  const size = bytes.byteLength;
108
109  // Before the generic check, so the refusal says why instead of reading as an oversight.
110  if (type.toLowerCase().split(";")[0]?.trim() === SVG_TYPE) {
111    return { code: "svg-refused", message: SVG_REFUSED, status: 415 };
112  }
113
114  if (!ALLOWED.has(type)) {
115    return {
116      code: "unsupported-type",
117      message: `Unsupported image type "${type || "unknown"}".`,
118      status: 415,
119    };
120  }
121
122  if (size > MAX_BYTES) {
123    return {
124      code: "too-large",
125      message: `Image is ${byteSize(size)}, over the ${MAX_BYTES / (1024 * 1024)} MB limit.`,
126      status: 413,
127    };
128  }
129
130  // Last: the only check that reads the payload.
131  if (beginsAsMarkup(bytes)) {
132    return {
133      code: "content-mismatch",
134      message:
135        `Those bytes begin as markup and the declared type is "${type}". ` +
136        `Markup, SVG included, is not accepted: export the image as PNG or WebP.`,
137      status: 415,
138    };
139  }
140
141  return null;
142}
143
144/**
145 * One byte, `<`: an XML declaration, a doctype, a comment and `<svg` all start with it. The BOM skip
146 * matters: a file saved from a Windows editor carries one.
147 *
148 * @param {ArrayBuffer} bytes
149 * @returns {boolean}
150 */
151export function beginsAsMarkup(bytes) {
152  const view = new Uint8Array(bytes);
153  let at = 0;
154  if (view[0] === 0xef && view[1] === 0xbb && view[2] === 0xbf) at = 3;
155  // A leading NUL is not skipped: that would be UTF-16, which no allowed type is.
156  while (at < view.length && (view[at] === 0x20 || view[at] === 0x09 || view[at] === 0x0a || view[at] === 0x0d)) {
157    at += 1;
158  }
159  return view[at] === 0x3c;
160}
161
162/**
163 * @param {string | null} code
164 * @returns {string | null} the sentence, or null for a code nothing emits
165 */
166export function uploadErrorSentence(code) {
167  if (!code) return null;
168  return Object.prototype.hasOwnProperty.call(UPLOAD_ERRORS, code)
169    ? UPLOAD_ERRORS[/** @type {keyof typeof UPLOAD_ERRORS} */ (code)]
170    : null;
171}
172
173/**
174 * Success carries the key, so a reload repeats a harmless read rather than a second upload.
175 *
176 * @param {{ ok: true, key: string } | { ok: false, code: string }} result
177 */
178export function uploadRedirectTo(result) {
179  const params = result.ok
180    ? `uploaded=${encodeURIComponent(result.key)}`
181    : `upload-error=${encodeURIComponent(result.code)}`;
182  return `${UPLOAD_RETURN_PATH}?${params}`;
183}