app/lib/media/core.server.ts

Functions

Imports

It imports app/db/index.ts, app/lib/bytes.mjs, app/lib/error-message.mjs, app/lib/media/classify.mjs, app/lib/media/encoding.mjs. Imported by app/lib/carrel/media-adapter.server.ts, app/lib/media/actions.server.ts, app/lib/media/rebuild.server.ts, app/lib/media/upload.server.ts, app/routes/admin.media._index.tsx, workers/media-events.ts.

Source

1import { listMediaPage } from "~/db";
2
3import { isContentKey } from "./classify.mjs";
4import { WEBP_QUALITY } from "./encoding.mjs";
5import { errorMessage } from "~/lib/error-message.mjs";
6import { bytesToBase64 } from "~/lib/bytes.mjs";
7
8// Content-agnostic: nothing post-shaped is imported here; citations arrive through the resolver seam.
9
10export const MEDIA_PAGE_SIZE = 24;
11
12// A closed set: the width lands in a cache key, and each distinct transform is billed.
13type ThumbWidth = 160 | 320 | 640;
14
15export type MediaObject = {
16  key: string;
17  url: string;
18  size: number;
19  uploaded: string;
20  storage: string;
21  kind: string;
22  role: string;
23  mime: string | null;
24  originalName: string | null;
25  width: number | null;
26  height: number | null;
27  alt: string;
28  caption: string;
29  tags: string;
30  placeholder: string | null;
31  deletable: boolean;
32};
33
34type MediaPage = {
35  objects: MediaObject[];
36  page: number;
37  hasMore: boolean;
38};
39
40export function thumbUrl(key: string, width: ThumbWidth) {
41  // A static asset key already begins with `/`; prefixing `/media/` gives a double slash the R2 route 404s on.
42  if (key.startsWith("/")) return key;
43  return `/media/${key}?w=${width}`;
44}
45
46export function isViewable(kind: string) {
47  return kind === "image";
48}
49
50// Derived from `listMediaPage` and forwarded by spread: a hand-copied options type dropped axes
51// silently, because spreads are exempt from excess-property checks.
52type ListMediaOptions = NonNullable<Parameters<typeof listMediaPage>[1]>;
53
54type MediaRow = Awaited<ReturnType<typeof listMediaPage>>["rows"][number];
55
56/** One index row as the library shows it; Carrel's media adapter reads the same shape. */
57export function mediaObjectOf(row: MediaRow): MediaObject {
58  return {
59    key: row.key,
60    // Static assets live on the assets host, not in the bucket, so `/media/` would 404.
61    url: row.storage === "static" ? row.key : `/media/${row.key}`,
62    size: row.bytes ?? 0,
63    uploaded: row.uploadedAt ?? "",
64    storage: row.storage,
65    kind: row.kind,
66    role: row.role,
67    mime: row.mime,
68    originalName: row.originalName,
69    width: row.width,
70    height: row.height,
71    alt: row.alt,
72    caption: row.caption,
73    tags: row.tags,
74    placeholder: row.placeholder,
75    deletable: row.storage !== "static",
76  };
77}
78
79export async function listMedia(
80  env: Env,
81  options: ListMediaOptions = {},
82): Promise<MediaPage> {
83  const { rows, page, hasMore } = await listMediaPage(env, {
84    ...options,
85    limit: options.limit ?? MEDIA_PAGE_SIZE,
86  });
87
88  return { objects: rows.map(mediaObjectOf), page, hasMore };
89}
90
91// Measured before a key exists, because the key carries the dimensions. Null means the binding answered
92// with no pixel dimensions (an SVG); a binding that throws is NOT that answer, so the throw propagates:
93// read as null it would mint a permanent key with no size, or write empty sizes over measured ones.
94export async function measureDimensions(
95  env: Env,
96  body: ReadableStream | ArrayBuffer,
97): Promise<{ width: number; height: number } | null> {
98  const stream = body instanceof ArrayBuffer ? new Blob([body]).stream() : body;
99  let info: Awaited<ReturnType<Env["IMAGES"]["info"]>>;
100  try {
101    info = await env.IMAGES.info(stream);
102  } catch (error) {
103    throw new Error(
104      `Cloudflare Images could not measure the image: ` +
105        `${errorMessage(error)}`,
106      { cause: error },
107    );
108  }
109  // An SVG has no pixel dimensions: record nothing rather than 0.
110  if ("width" in info && "height" in info) {
111    return { width: info.width, height: info.height };
112  }
113  return null;
114}
115
116const PLACEHOLDER_WIDTH = 20;
117
118// LQIP, not ThumbHash or BlurHash: those need client-side decoding and the public plane ships no
119// framework script. The quality is required: without it the binding emits LOSSLESS WebP.
120export async function placeholderFor(
121  env: Env,
122  body: ReadableStream | ArrayBuffer,
123): Promise<string | null> {
124  const stream = body instanceof ArrayBuffer ? new Blob([body]).stream() : body;
125  try {
126    const result = await env.IMAGES.input(stream)
127      .transform({ width: PLACEHOLDER_WIDTH })
128      .output({ format: "image/webp", quality: WEBP_QUALITY });
129    const buffer = await result.response().arrayBuffer();
130    return `data:image/webp;base64,${bytesToBase64(new Uint8Array(buffer))}`;
131  } catch {
132    return null;
133  }
134}
135
136// No reference check here on purpose: the safety belongs in the action, which has the resolver's answer.
137export async function deleteMediaObject(env: Env, key: string) {
138  await env.MEDIA.delete(key);
139}
140
141export function isManagedKey(key: string) {
142  return isContentKey(key);
143}