app/lib/carrel/media-adapter.server.ts

Functions

Imports

It imports app/db/index.ts, app/db/schema.ts, app/lib/error-message.mjs, app/lib/media/actions.server.ts, app/lib/media/classify.mjs, app/lib/media/core.server.ts, app/lib/media/resolvers.server.ts, app/lib/media/upload-contract.mjs, app/lib/media/upload.server.ts. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// Carrel's media group (site-api v0.2.0) over the site's own media code: list over listMedia, upload
2// over storeUpload, get and delete over the same reference check the admin library's delete runs.
3// Nothing here stores, scans or deletes by a path of its own.
4
5import {
6  MediaId,
7  MediaInUseError,
8  NotFoundError,
9  RefusedError,
10  type MediaAdapter,
11  type MediaItem,
12  type MediaUse,
13} from "@dustinedwards/site-api";
14
15import { claimMediaKeyForDelete, mediaRecord, upsertMediaRecord } from "~/db";
16import type { MediaRef } from "~/db/schema";
17import { errorMessage } from "~/lib/error-message.mjs";
18import { mediaDeleteVerdict, mediaUsage } from "~/lib/media/actions.server";
19import { classify } from "~/lib/media/classify.mjs";
20import {
21  deleteMediaObject,
22  isManagedKey,
23  listMedia,
24  mediaObjectOf,
25  type MediaObject,
26} from "~/lib/media/core.server";
27import type { MediaCitation } from "~/lib/media/resolvers.server";
28import { storeUpload } from "~/lib/media/upload.server";
29import { ALLOWED, MAX_BYTES } from "~/lib/media/upload-contract.mjs";
30
31/**
32 * What the admin library accepts, less SVG: an SVG is served as an attachment and never inserted
33 * inline, so Carrel is not offered it. Computed from ALLOWED, so a type the site drops leaves here too.
34 */
35const CARREL_MEDIA_LIMITS = {
36  maxBytes: MAX_BYTES,
37  types: [...ALLOWED.keys()].filter((type) => type !== "image/svg+xml"),
38};
39
40/** An ISO time, or null for an index row with no upload event or one that does not parse. */
41function isoOrNull(value: string) {
42  const at = Date.parse(value);
43  return value && !Number.isNaN(at) ? new Date(at).toISOString() : null;
44}
45
46/** One library object in the contract's terms. Deletable only where the site's own delete could act. */
47function itemOf(object: MediaObject): MediaItem {
48  return {
49    id: object.key,
50    url: object.url,
51    filename: object.originalName ? object.originalName.slice(0, 300) : null,
52    contentType: object.mime ?? classify(object.key).mime,
53    bytes: object.size,
54    width: object.width && object.width > 0 ? object.width : null,
55    height: object.height && object.height > 0 ? object.height : null,
56    alt: object.alt,
57    uploadedAt: isoOrNull(object.uploaded),
58    deletable: isManagedKey(object.key),
59  };
60}
61
62/**
63 * Every use the check found: each resolver citation, then each recorded reference from an item no
64 * citation already names, since a recorded reference alone refuses the delete too.
65 */
66function usesOf(citations: MediaCitation[], refs: MediaRef[]): MediaUse[] {
67  const uses: MediaUse[] = citations.map((c) => ({
68    type: c.type,
69    id: c.id,
70    title: c.title.slice(0, 1000),
71    detail: c.detail.slice(0, 500),
72  }));
73  const named = new Set(citations.map((c) => `${c.type}:${c.id}`));
74  for (const ref of refs) {
75    if (named.has(`${ref.sourceType}:${ref.sourceId}`)) continue;
76    uses.push({
77      type: ref.sourceType,
78      id: ref.sourceId,
79      title: ref.sourceId,
80      detail: `recorded ${ref.form}${ref.detail ? `, ${ref.detail}` : ""}`.slice(0, 500),
81    });
82  }
83  return uses;
84}
85
86export function carrelMediaAdapter(env: Env): MediaAdapter {
87  return {
88    limits: CARREL_MEDIA_LIMITS,
89
90    async list(query) {
91      const page = query.cursor && /^[1-9]\d{0,8}$/.test(query.cursor) ? Number(query.cursor) : 1;
92      // Bucket rows only: a static asset's key is a repo path, which is not a media id.
93      const listed = await listMedia(env, { page, limit: query.limit, q: query.q, storedOnly: true });
94      return {
95        // A bucket key the id grammar cannot carry is left out rather than failing the whole page.
96        items: listed.objects.filter((o) => MediaId.safeParse(o.key).success).map(itemOf),
97        nextCursor: listed.hasMore ? String(listed.page + 1) : null,
98      };
99    },
100
101    async get(id) {
102      const row = await mediaRecord(env, id);
103      if (!row || row.storage === "static") return null;
104      const usage = await mediaUsage(env, id);
105      if (!usage.complete) {
106        throw new RefusedError(
107          `The detail is refused: the reference scan failed (${usage.failed.join(", ")}), ` +
108            `so this file's uses are unknown.`,
109        );
110      }
111      return { ...itemOf(mediaObjectOf(row)), usedBy: usesOf(usage.citations, usage.refs) };
112    },
113
114    async upload(input) {
115      // A fresh ArrayBuffer, not `bytes.buffer`, which may be a larger allocation than the view.
116      const bytes = new ArrayBuffer(input.bytes.byteLength);
117      new Uint8Array(bytes).set(input.bytes);
118
119      const stored = await storeUpload(env, { bytes, type: input.contentType, name: input.filename });
120      if (!stored.ok) throw new RefusedError(stored.message);
121      // The object landed and its row did not. Keys are content-addressed, so a retry is the repair.
122      if (!stored.recorded) {
123        throw new Error(`${stored.key} was stored but its index row was not written; send the upload again`);
124      }
125      if (input.alt) await upsertMediaRecord(env, { key: stored.key, alt: input.alt });
126
127      const row = await mediaRecord(env, stored.key);
128      if (!row) throw new Error(`${stored.key} was stored and recorded, but its index row cannot be read`);
129      return itemOf(mediaObjectOf(row));
130    },
131
132    async delete(id) {
133      // First, before any scan: an id the index has never held is a 404.
134      const row = await mediaRecord(env, id);
135      if (!row) throw new NotFoundError("No such media.");
136
137      let verdict: Awaited<ReturnType<typeof mediaDeleteVerdict>>;
138      try {
139        verdict = await mediaDeleteVerdict(env, id);
140      } catch (error) {
141        throw new RefusedError(
142          `Nothing was deleted: the reference check could not complete (${errorMessage(error)}).`,
143        );
144      }
145
146      switch (verdict.kind) {
147        case "static":
148        case "unmanaged":
149          throw new RefusedError(
150            `${id} is not an upload: the site derives it, so it is never deleted through this API.`,
151          );
152        case "scan-failed":
153          throw new RefusedError(
154            `Nothing was deleted: the reference scan failed (${verdict.failed.join(", ")}), ` +
155              `so it cannot be confirmed that nothing uses this file.`,
156          );
157        case "cited":
158          throw new MediaInUseError(usesOf(verdict.citations, verdict.refs));
159        case "clear":
160          break;
161      }
162
163      /* One statement claims the row only if nothing cites it now. Row first: an orphan object backfills. */
164      if (!(await claimMediaKeyForDelete(env, id))) {
165        throw new RefusedError(`${id} was cited or removed while this delete was being checked. Try again.`);
166      }
167      await deleteMediaObject(env, id);
168    },
169  };
170}