app/lib/media.server.ts

Functions

Imports

It imports app/db/schema.ts, app/lib/people.server.ts, app/lib/projects.server.ts, app/lib/roles.ts, app/lib/sites.server.ts. Imported by app/components/media/detail-panel.tsx, app/routes/editor.tsx, app/routes/media.api.ts, app/routes/media.bulk.ts, app/routes/media.tsx.

Source

1// The media library (stage 3), over the site API's media group (site-api v0.2.0). Files stay in the
2// site's own storage and are served by the site: Carrel lists them, uploads to them and asks for
3// deletes, and nothing about serving an image depends on Carrel. The site's reference check decides
4// every delete; Carrel shows its answer.
5//
6// Roles, checked here so the page and any later tool meet the same rule: a Reader browses, an Editor
7// also uploads (and inserts into a post), edits alt text and tags, and moves files to the trash and
8// back (all reversible), and only the Owner deletes for good or empties the trash.
9//
10// The writes (site-api v0.4.0) are each optional per site: the site's meta says which it offers
11// (`mediaAlt`, `mediaTags`, `mediaTrash`), and the screens hide what it does not. A 501 means the same.
12
13import type { MediaBulkInput, MediaDetail, MediaItem, MediaList, MediaUploadLimits, MediaUse } from "@dustinedwards/site-api";
14import { SiteApiError } from "@dustinedwards/site-api/client";
15import { drizzle } from "drizzle-orm/d1";
16
17import { changes } from "~/db/schema";
18import type { Viewer } from "~/lib/people.server";
19import type { SiteProject } from "~/lib/projects.server";
20import { can, type Action } from "~/lib/roles";
21import { absoluteMediaUrl, siteClient, siteConnection } from "~/lib/sites.server";
22
23function requireCan(project: SiteProject, action: Action) {
24  if (!can(project.role, action)) throw new Response("Forbidden", { status: 403 });
25}
26
27/** A file as Carrel's screens show it: the site's item, plus the absolute address a browser loads. */
28export type MediaView = MediaItem & { src: string };
29
30/** Who did it: the person, and the AI client when it came through the AI door (credited in the record). */
31export type MediaActor = { viewer: Viewer; client?: string };
32
33/**
34 * One row in the authorship record per media action that the site carried out (migration 0007): the
35 * same change id Carrel sent the site, so the two histories join. A refused action writes nothing.
36 */
37type MediaAction = "media-upload" | "media-delete" | "media-alt" | "media-tags" | "media-trash" | "media-restore";
38
39async function record(
40  env: Env,
41  project: SiteProject,
42  actor: MediaActor,
43  action: MediaAction,
44  mediaId: string,
45  changeId: string,
46  versions: { before?: string | null; after?: string | null } = {},
47) {
48  await drizzle(env.DB).insert(changes).values({
49    id: changeId,
50    projectId: project.id,
51    itemId: mediaId,
52    personId: actor.viewer.id,
53    action,
54    versionBefore: versions.before ?? null,
55    versionAfter: versions.after ?? null,
56    client: actor.client ?? null,
57  });
58}
59
60function view(project: SiteProject, env: Env, item: MediaItem): MediaView {
61  const connection = siteConnection(env, project.site);
62  const origin = connection.state === "connected" ? connection.origin : "";
63  return { ...item, src: origin ? absoluteMediaUrl(origin, item.url) : item.url };
64}
65
66/** Which writes the site offers beyond upload and delete (site-api v0.4.0); a site lacking one never sees its screen. */
67export type MediaOffers = { alt: boolean; tags: boolean; trash: boolean };
68
69/** What the site accepts and which writes it offers, from its meta. null when the site offers no media (a v0.1.0 site). */
70export async function mediaMeta(env: Env, project: SiteProject, fetcher?: typeof fetch): Promise<{ limits: MediaUploadLimits; offers: MediaOffers } | null> {
71  requireCan(project, "read");
72  const { capabilities } = await siteClient(env, project.site, fetcher).meta();
73  if (!capabilities.media || !capabilities.mediaUpload) return null;
74  return {
75    limits: capabilities.mediaUpload,
76    offers: { alt: capabilities.mediaAlt === true, tags: capabilities.mediaTags === true, trash: capabilities.mediaTrash === true },
77  };
78}
79
80/** What the site accepts, from its meta. null when the site offers no media (a v0.1.0 site). */
81export async function mediaLimits(env: Env, project: SiteProject, fetcher?: typeof fetch): Promise<MediaUploadLimits | null> {
82  return (await mediaMeta(env, project, fetcher))?.limits ?? null;
83}
84
85/** A tag as the site spells it: lower case words joined by single hyphens, at most 32 characters. null when it cannot be one. */
86export function cleanMediaTag(raw: string): string | null {
87  const tag = raw.trim().toLowerCase().replace(/[\s_]+/g, "-");
88  return tag.length > 0 && tag.length <= 32 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(tag) ? tag : null;
89}
90
91/** A typed list of tags as a file's whole tag set: the content kit's, so Carrel and a site's own admin read tags alike. */
92export { parseMediaTags } from "@dustinedwards/site-api/admin";
93
94export async function listMedia(
95  env: Env,
96  project: SiteProject,
97  query: { q?: string; tag?: string; trashed?: "only"; cursor?: string; limit?: number },
98  fetcher?: typeof fetch,
99): Promise<{ items: MediaView[]; nextCursor: MediaList["nextCursor"] }> {
100  requireCan(project, "read");
101  const list = await siteClient(env, project.site, fetcher).media.list(query);
102  return { items: list.items.map((i) => view(project, env, i)), nextCursor: list.nextCursor };
103}
104
105/** One file with every place the site's reference check finds it. null when the site has no such file. */
106export async function mediaDetail(env: Env, project: SiteProject, id: string, fetcher?: typeof fetch): Promise<(MediaDetail & { src: string }) | null> {
107  requireCan(project, "read");
108  try {
109    const detail = await siteClient(env, project.site, fetcher).media.get(id);
110    return { ...detail, src: view(project, env, detail).src };
111  } catch (error) {
112    if (error instanceof SiteApiError && (error.status === 404 || error.status === 400)) return null;
113    throw error;
114  }
115}
116
117export type UploadOutcome = { ok: true; item: MediaView } | { ok: false; message: string };
118
119/**
120 * Uploads one file to the site. Carrel checks the site's own limits first, so a file the site would
121 * refuse is not sent at all; the site API checks them again, and the bytes, before the site's code.
122 */
123export async function uploadMedia(
124  env: Env,
125  project: SiteProject,
126  actor: MediaActor,
127  file: { name: string; type: string; size: number; bytes: () => Promise<ArrayBuffer> },
128  alt: string,
129  fetcher?: typeof fetch,
130): Promise<UploadOutcome> {
131  requireCan(project, "edit");
132  const limits = await mediaLimits(env, project, fetcher);
133  if (!limits) return { ok: false, message: "This site has no media library yet." };
134  const type = file.type.split(";")[0]!.trim().toLowerCase();
135  if (!limits.types.includes(type)) {
136    return { ok: false, message: `${file.name} is ${type || "an unknown type"}; this site accepts ${limits.types.map((t) => t.split("/")[1]).join(", ")}.` };
137  }
138  if (file.size > limits.maxBytes) {
139    return { ok: false, message: `${file.name} is ${megabytes(file.size)}; this site accepts files up to ${megabytes(limits.maxBytes)}.` };
140  }
141  if (file.size === 0) return { ok: false, message: `${file.name} is empty.` };
142  const changeId = crypto.randomUUID();
143  try {
144    const item = await siteClient(env, project.site, fetcher).media.upload({
145      bytes: new Uint8Array(await file.bytes()),
146      contentType: type,
147      filename: file.name.replace(/[/\\]/g, "-").slice(0, 200),
148      alt: alt.trim().slice(0, 2000),
149      changeId,
150    });
151    await record(env, project, actor, "media-upload", item.id, changeId);
152    return { ok: true, item: view(project, env, item) };
153  } catch (error) {
154    if (error instanceof SiteApiError && error.body) return { ok: false, message: `The site refused ${file.name}: ${error.body.message}` };
155    throw error;
156  }
157}
158
159export type DeleteOutcome = { ok: true } | { ok: false; message: string; usedBy: MediaUse[] };
160
161/** Asks the site to delete a file. The site's reference check decides; a file in use is refused, with every use named. */
162export async function deleteMedia(env: Env, project: SiteProject, actor: MediaActor, id: string, fetcher?: typeof fetch): Promise<DeleteOutcome> {
163  requireCan(project, "delete_media");
164  const changeId = crypto.randomUUID();
165  try {
166    await siteClient(env, project.site, fetcher).media.delete(id, changeId);
167    await record(env, project, actor, "media-delete", id, changeId);
168    return { ok: true };
169  } catch (error) {
170    if (error instanceof SiteApiError && error.body) {
171      return { ok: false, message: error.body.message, usedBy: error.body.usedBy ?? [] };
172    }
173    throw error;
174  }
175}
176
177// ---------- the writes (site-api v0.4.0)
178
179/** One write's outcome. `conflict` is a stale version (the file changed on the site since it was read). */
180export type WriteOutcome = { ok: true; version: string; recorded: boolean } | { ok: false; conflict: boolean; message: string };
181
182const CONFLICT = "This file changed on the site since you opened it. The page now shows what the site holds; make the change again if you still want it.";
183
184/** A failed write said plainly: stale is a conflict, a 501 is "not offered", a refusal carries the site's own words. */
185function writeFailure(error: unknown): WriteOutcome {
186  if (error instanceof SiteApiError) {
187    if (error.status === 409) return { ok: false, conflict: true, message: CONFLICT };
188    if (error.status === 501) return { ok: false, conflict: false, message: "This site does not offer that." };
189    if (error.status === 404) return { ok: false, conflict: false, message: "The site has no such file. It may have been deleted." };
190    if (error.body) return { ok: false, conflict: false, message: `The site refused: ${error.body.message}` };
191  }
192  throw error;
193}
194
195async function writeOne(
196  env: Env,
197  project: SiteProject,
198  actor: MediaActor,
199  action: Exclude<MediaAction, "media-upload" | "media-delete">,
200  id: string,
201  expectedVersion: string,
202  send: (changeId: string) => Promise<{ version: string }>,
203): Promise<WriteOutcome> {
204  requireCan(project, "edit");
205  const changeId = crypto.randomUUID();
206  let result: { version: string };
207  try {
208    result = await send(changeId);
209  } catch (error) {
210    return writeFailure(error);
211  }
212  // The site has done it; a record that cannot be written is reported, never allowed to hide that.
213  let recorded = true;
214  try {
215    await record(env, project, actor, action, id, changeId, { before: expectedVersion, after: result.version });
216  } catch (error) {
217    recorded = false;
218    console.error(JSON.stringify({ record: "failed", mediaId: id, action, changeId, error: String(error) }));
219  }
220  return { ok: true, version: result.version, recorded };
221}
222
223export function setMediaAlt(env: Env, project: SiteProject, actor: MediaActor, id: string, alt: string, expectedVersion: string, fetcher?: typeof fetch) {
224  return writeOne(env, project, actor, "media-alt", id, expectedVersion, (changeId) =>
225    siteClient(env, project.site, fetcher).media.setAlt(id, { alt: alt.trim().slice(0, 2000), expectedVersion, changeId }),
226  );
227}
228
229export function setMediaTags(env: Env, project: SiteProject, actor: MediaActor, id: string, tags: string[], expectedVersion: string, fetcher?: typeof fetch) {
230  return writeOne(env, project, actor, "media-tags", id, expectedVersion, (changeId) =>
231    siteClient(env, project.site, fetcher).media.setTags(id, { tags, expectedVersion, changeId }),
232  );
233}
234
235/** Moves a file to the site's trash. Reversible, so an Editor may; the site keeps the file until the trash is emptied. */
236export function trashMedia(env: Env, project: SiteProject, actor: MediaActor, id: string, expectedVersion: string, fetcher?: typeof fetch) {
237  return writeOne(env, project, actor, "media-trash", id, expectedVersion, (changeId) =>
238    siteClient(env, project.site, fetcher).media.trash(id, { expectedVersion, changeId }),
239  );
240}
241
242export function restoreMedia(env: Env, project: SiteProject, actor: MediaActor, id: string, expectedVersion: string, fetcher?: typeof fetch) {
243  return writeOne(env, project, actor, "media-restore", id, expectedVersion, (changeId) =>
244    siteClient(env, project.site, fetcher).media.restore(id, { expectedVersion, changeId }),
245  );
246}
247
248export type BulkOp = MediaBulkInput["op"];
249const MAX_MEDIA_BULK = 100;
250
251/** One file's outcome in a bulk action: this file was done, or left as it was and why. */
252export type FileResult = { id: string; ok: boolean; message: string; usedBy?: MediaUse[] };
253
254const ACTION_OF: Record<BulkOp, MediaAction> = {
255  trash: "media-trash",
256  restore: "media-restore",
257  delete: "media-delete",
258  "add-tags": "media-tags",
259  "remove-tags": "media-tags",
260};
261
262const DONE_OF: Record<BulkOp, string> = {
263  trash: "Moved to the trash.",
264  restore: "Restored to the library.",
265  delete: "Deleted from the site.",
266  "add-tags": "Tags added.",
267  "remove-tags": "Tags removed.",
268};
269
270/**
271 * One action on several files, in one request to the site. The role is checked once before the site
272 * hears anything (deleting is the Owner's, the rest an Editor's). The site answers file by file: a
273 * stale version or a file a post uses refuses that file alone, and every file gets an outcome. Each
274 * file the site carried out is its own row in the authorship record, under the change id sent for it.
275 */
276export async function bulkMedia(
277  env: Env,
278  project: SiteProject,
279  actor: MediaActor,
280  op: BulkOp,
281  items: readonly { id: string; version?: string | null }[],
282  tags: readonly string[] = [],
283  fetcher?: typeof fetch,
284): Promise<FileResult[]> {
285  requireCan(project, op === "delete" ? "delete_media" : "edit");
286  if (items.length === 0) throw new Response("Choose at least one file.", { status: 400 });
287  if (items.length > MAX_MEDIA_BULK) throw new Response(`At most ${MAX_MEDIA_BULK} files at a time.`, { status: 400 });
288  if ((op === "add-tags" || op === "remove-tags") && tags.length === 0) throw new Response("Name at least one tag.", { status: 400 });
289
290  const unique = [...new Map(items.map((i) => [i.id, i])).values()];
291  const results: FileResult[] = [];
292  const sendable: { id: string; version: string | null; changeId: string }[] = [];
293  for (const item of unique) {
294    // A write needs the version the person saw; without one the site could not tell a stale write from a fresh one.
295    if (op !== "delete" && !item.version) results.push({ id: item.id, ok: false, message: "Carrel does not know this file's version, so nothing was sent. Reload the page and try again." });
296    else sendable.push({ id: item.id, version: item.version ?? null, changeId: crypto.randomUUID() });
297  }
298  if (sendable.length === 0) return results;
299
300  let answer;
301  try {
302    answer = await siteClient(env, project.site, fetcher).media.bulk({
303      op,
304      ...(op === "add-tags" || op === "remove-tags" ? { tags: [...tags] } : {}),
305      items: sendable.map((s) => ({ id: s.id, changeId: s.changeId, ...(op !== "delete" && s.version ? { expectedVersion: s.version } : {}) })),
306    });
307  } catch (error) {
308    if (error instanceof SiteApiError && error.status === 501) throw new Response("This site does not offer that.", { status: 501 });
309    throw error;
310  }
311
312  const sent = new Map(sendable.map((s) => [s.id, s]));
313  for (const outcome of answer.results) {
314    if (outcome.ok) {
315      let message = DONE_OF[op];
316      try {
317        await record(env, project, actor, ACTION_OF[op], outcome.id, outcome.changeId, { before: sent.get(outcome.id)?.version ?? null, after: outcome.version ?? null });
318      } catch (error) {
319        console.error(JSON.stringify({ record: "failed", mediaId: outcome.id, action: ACTION_OF[op], changeId: outcome.changeId, error: String(error) }));
320        message += " The authorship record for it could not be saved.";
321      }
322      results.push({ id: outcome.id, ok: true, message });
323    } else {
324      results.push({
325        id: outcome.id,
326        ok: false,
327        message: outcome.error === "version-conflict" ? "This file changed on the site since you opened the library. It was left as it was." : outcome.message,
328        ...(outcome.usedBy && outcome.usedBy.length > 0 ? { usedBy: outcome.usedBy } : {}),
329      });
330    }
331  }
332  return results;
333}
334
335/** The files in the trash, for the Trash view and the empty-trash confirm. `more` when the trash holds past one request's reach. */
336export async function listTrash(env: Env, project: SiteProject, fetcher?: typeof fetch): Promise<{ items: MediaItem[]; more: boolean }> {
337  requireCan(project, "read");
338  const list = await siteClient(env, project.site, fetcher).media.list({ trashed: "only", limit: MAX_MEDIA_BULK + 1 });
339  return { items: list.items.slice(0, MAX_MEDIA_BULK), more: list.items.length > MAX_MEDIA_BULK || list.nextCursor !== null };
340}
341
342export type EmptyOutcome = { deleted: string[]; refused: { id: string; message: string; usedBy: MediaUse[] }[]; more: boolean; unrecorded: number };
343
344/**
345 * Deletes for good every file in the trash (up to the site's limit per request), each through the
346 * site's own reference check: a file a post still uses is refused and stays in the trash. The Owner's alone.
347 * The site records file n under `<change id>-<n>` in the order it lists the trash, so Carrel lists the
348 * same trash first to write the same ids into the authorship record.
349 */
350export async function emptyMediaTrash(env: Env, project: SiteProject, actor: MediaActor, fetcher?: typeof fetch): Promise<EmptyOutcome> {
351  requireCan(project, "delete_media");
352  const before = await listTrash(env, project, fetcher);
353  const changeId = crypto.randomUUID();
354  let answer;
355  try {
356    answer = await siteClient(env, project.site, fetcher).media.emptyTrash({ changeId });
357  } catch (error) {
358    if (error instanceof SiteApiError && error.status === 501) throw new Response("This site does not offer that.", { status: 501 });
359    throw error;
360  }
361  let unrecorded = 0;
362  for (const id of answer.deleted) {
363    const n = before.items.findIndex((i) => i.id === id);
364    const rowId = n >= 0 ? `${changeId}-${n + 1}` : `${changeId}:${id}`;
365    try {
366      await record(env, project, actor, "media-delete", id, rowId);
367    } catch (error) {
368      unrecorded += 1;
369      console.error(JSON.stringify({ record: "failed", mediaId: id, action: "media-delete", changeId: rowId, error: String(error) }));
370    }
371  }
372  return { deleted: answer.deleted, refused: answer.refused.map((r) => ({ ...r, usedBy: r.usedBy ?? [] })), more: answer.more, unrecorded };
373}
374
375function megabytes(bytes: number): string {
376  return bytes >= 1024 * 1024 ? `${(bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "")} MB` : `${Math.ceil(bytes / 1024)} KB`;
377}