app/lib/media/actions.server.ts

Functions

Imports

It imports app/db/index.ts, app/db/schema.ts, app/lib/admin/bulk-tag.ts, app/lib/error-message.mjs, app/lib/media/classify.mjs, app/lib/media/core.server.ts, app/lib/media/rebuild.server.ts, app/lib/media/resolvers.server.ts, app/lib/media/tags.mjs. Imported by app/lib/carrel/media-adapter.server.ts, app/routes/admin.media._index.tsx.

Source

1import {
2  claimMediaKeyForDelete,
3  mediaCounts,
4  mediaRecord,
5  mediaRefsFor,
6  mediaRoleCounts,
7  restoreMediaRecord,
8  setMediaTags,
9  trashMediaRecord,
10  upsertMediaRecord,
11} from "~/db";
12import type { MediaRef } from "~/db/schema";
13import { applyBulkTag } from "~/lib/admin/bulk-tag";
14import { errorMessage } from "~/lib/error-message.mjs";
15import { storageOf } from "./classify.mjs";
16import { deleteMediaObject, isManagedKey } from "./core.server";
17import { rebuildMediaIndex } from "./rebuild.server";
18import { resolveCitations, type MediaCitation } from "./resolvers.server";
19import { normaliseTags, parseTags } from "./tags.mjs";
20
21/*
22 * One handler per intent of the media library's action. The route keeps the dispatch and, for the
23 * three destructive intents, the typed confirmation: check:destructive reads both off the route's
24 * own action, so a handler here runs only once the route has let it.
25 */
26
27/** `refused` marks a result that changed nothing or failed, which the page announces as an alert. */
28type Message = { message: string; refused?: boolean };
29
30export async function bulkTagMedia(
31  env: Env,
32  form: FormData,
33  intent: "bulk-add-tag" | "bulk-remove-tag",
34): Promise<Message> {
35  const keys = form.getAll("key").map(String).filter(Boolean);
36  if (keys.length === 0) return { message: "Nothing selected.", refused: true };
37
38  const wanted = normaliseTags(String(form.get("tag") ?? ""))[0];
39  if (!wanted) return { message: "Enter a tag first.", refused: true };
40  const adding = intent === "bulk-add-tag";
41
42  // Rows already in the target state are skipped, so updated_at is not touched for nothing.
43  const { done, skipped, failed } = await applyBulkTag({
44    ids: keys,
45    wanted,
46    adding,
47    missing: "no row",
48    read: async (key) => {
49      const row = await mediaRecord(env, key);
50      return row ? { item: row, tags: parseTags(row.tags) } : null;
51    },
52    write: (key, _row, tags) => setMediaTags(env, key, tags),
53  });
54
55  return {
56    message:
57      `${adding ? "Tagged" : "Untagged"} ${done} of ${keys.length}` +
58      (skipped > 0 ? `, ${skipped} already ${adding ? "tagged" : "untagged"}` : "") +
59      "." +
60      (failed.length > 0 ? ` Failed on ${failed.join("; ")}` : ""),
61    refused: failed.length > 0,
62  };
63}
64
65export async function setMediaTagsFromForm(env: Env, form: FormData): Promise<Message> {
66  const key = String(form.get("key") ?? "");
67  const tags = String(form.get("tags") ?? "").trim();
68
69  /* An empty field does not clear; clearing needs `clear`, so an accident cannot wipe every tag. */
70  const clearing = form.get("clear") !== null;
71  if (!tags && !clearing) {
72    return {
73      message:
74        `Nothing changed for ${key}. The tag field was empty, and an empty ` +
75        `field does not clear tags. Remove them one at a time, or press ` +
76        `Clear all.`,
77      refused: true,
78    };
79  }
80
81  const saved = await setMediaTags(env, key, clearing ? "" : tags);
82  return {
83    message: saved.length
84      ? `Tags saved for ${key}: ${saved.join(", ")}.`
85      : `Tags cleared for ${key}.`,
86  };
87}
88
89export async function bulkTrashMedia(env: Env, form: FormData): Promise<Message> {
90  const keys = form.getAll("key").map(String).filter(Boolean);
91  if (keys.length === 0) return { message: "Nothing selected.", refused: true };
92  let moved = 0;
93  let already = 0;
94  const failed: string[] = [];
95  for (const key of keys) {
96    try {
97      const result = await trashMediaRecord(env, key);
98      if (result.moved) moved += 1;
99      else already += 1;
100    } catch (error) {
101      failed.push(`${key}: ${errorMessage(error)}`);
102    }
103  }
104  return {
105    message:
106      `Moved ${moved} of ${keys.length} to the trash` +
107      (already > 0 ? `, ${already} already there` : "") +
108      ". Every address still works and no published page changes." +
109      (failed.length > 0 ? ` Failed on ${failed.join("; ")}` : ""),
110    refused: failed.length > 0,
111  };
112}
113
114export async function trashMedia(env: Env, form: FormData): Promise<Message> {
115  const key = String(form.get("key") ?? "");
116  const { moved } = await trashMediaRecord(env, key);
117  return {
118    message: moved
119      ? `${key} moved to the trash. Its address still works and any page using it is unchanged; this hides it from the library.`
120      : `${key} was already in the trash.`,
121  };
122}
123
124export async function restoreMedia(env: Env, form: FormData): Promise<Message> {
125  const key = String(form.get("key") ?? "");
126  const { restored } = await restoreMediaRecord(env, key);
127  return {
128    message: restored
129      ? `${key} restored to the library.`
130      : `${key} was not in the trash.`,
131  };
132}
133
134/** Empties the trash the route has confirmed, keeping every key a post cites. */
135export async function emptyMediaTrash(env: Env, keys: string[]): Promise<Message> {
136  /* The same scan as the single delete: media_refs alone misses a citation the pipeline has not recorded. */
137  const resolution = await resolveCitations(env, keys.filter(isManagedKey));
138  if (!resolution.complete) {
139    return {
140      message:
141        `Nothing was deleted: the reference scan failed (${resolution.failed.join(", ")}), ` +
142        `so it cannot be confirmed that nothing cites these files.`,
143      refused: true,
144    };
145  }
146  const deleted: string[] = [];
147  const refused: string[] = [];
148  for (const key of keys) {
149    // Static rows have no object to remove, so emptying leaves them binned.
150    if (!isManagedKey(key)) {
151      refused.push(`${key} (static, nothing to delete)`);
152      continue;
153    }
154    if ((resolution.citations.get(key) ?? []).length > 0) {
155      refused.push(`${key} (a post cites it)`);
156      continue;
157    }
158    const claimed = await claimMediaKeyForDelete(env, key);
159    if (!claimed) {
160      refused.push(`${key} (something cites it)`);
161      continue;
162    }
163    try {
164      await deleteMediaObject(env, key);
165      deleted.push(key);
166    } catch (error) {
167      refused.push(`${key} (${errorMessage(error)})`);
168    }
169  }
170  return {
171    message:
172      `Emptied ${deleted.length} of ${keys.length}.` +
173      (refused.length ? ` Kept: ${refused.join("; ")}.` : ""),
174  };
175}
176
177export async function setMediaAlt(env: Env, form: FormData): Promise<Message> {
178  const key = String(form.get("key") ?? "");
179  if (!isManagedKey(key)) return { message: "Not a managed media key.", refused: true };
180  // Saving alt rewrites no post: alt is contextual, so only future insertions pick it up.
181  await upsertMediaRecord(env, { key, alt: String(form.get("alt") ?? "") });
182  return { message: `Alt text saved for ${key}. Existing posts are unchanged.` };
183}
184
185/** The row count the rebuild confirmation shows. */
186export async function mediaRowTotal(env: Env) {
187  const before = await mediaCounts(env);
188  return before.reduce((sum, row) => sum + Number(row.n), 0);
189}
190
191/** Runs the rebuild the route has confirmed and reports what the index holds after it. */
192export async function rebuildMedia(env: Env): Promise<Message> {
193  const report = await rebuildMediaIndex(env);
194  const after = await mediaCounts(env);
195  const total = after.reduce((sum, row) => sum + Number(row.n), 0);
196  const breakdown = after
197    .map((row) => `${row.n} ${row.storage}/${row.kind}`)
198    .sort()
199    .join(", ");
200  const roles = await mediaRoleCounts(env);
201  const roleBreakdown = roles
202    .map((row) => `${row.n} ${row.role}`)
203    .sort()
204    .join(", ");
205
206  const parts = [
207    `Rebuilt from ${report.scannedObjects} R2 object(s) and ${report.scannedFiles} static ` +
208      `file(s). The index now holds ${total} row(s): ${breakdown}`,
209    `By role: ${roleBreakdown}`,
210  ];
211  if (report.removed > 0) {
212    parts.push(`${report.removed} row(s) removed for sources that no longer exist`);
213  }
214  if (report.failures.length > 0) {
215    parts.push(
216      `${report.failures.length} could not be derived: ${report.failures.slice(0, 3).join("; ")}` +
217        (report.failures.length > 3 ? ` and ${report.failures.length - 3} more` : ""),
218    );
219  }
220  parts.push("Alt text, captions and focal points were preserved");
221  return { message: `${parts.join(". ")}.` };
222}
223
224/** Every place one key is used, on a fresh read: the resolver scan and the pipeline's recorded refs. */
225export async function mediaUsage(env: Env, key: string) {
226  const [resolution, refs] = await Promise.all([
227    resolveCitations(env, [key]),
228    mediaRefsFor(env, [key]),
229  ]);
230  return {
231    complete: resolution.complete,
232    failed: resolution.failed,
233    citations: resolution.citations.get(key) ?? [],
234    refs: refs.get(key) ?? [],
235  };
236}
237
238/**
239 * Whether one key may be deleted, as a verdict rather than prose, so the admin action and Carrel's
240 * media adapter refuse on the same checks. `clear` still has to win the atomic claim.
241 */
242export type MediaDeleteVerdict =
243  | { kind: "static" }
244  | { kind: "unmanaged" }
245  | { kind: "scan-failed"; failed: string[] }
246  | { kind: "cited"; citations: MediaCitation[]; refs: MediaRef[] }
247  | { kind: "clear" };
248
249export async function mediaDeleteVerdict(env: Env, key: string): Promise<MediaDeleteVerdict> {
250  // Refused in the action, not by hiding a button: a deleted row would return on the next rebuild.
251  if (storageOf(key) === "static") return { kind: "static" };
252  if (!isManagedKey(key)) return { kind: "unmanaged" };
253
254  // Server side on a fresh read: a post may have cited the object since the page rendered.
255  const usage = await mediaUsage(env, key);
256
257  // Fail closed: a failed scan is not "nothing cites it".
258  if (!usage.complete) return { kind: "scan-failed", failed: usage.failed };
259
260  // The refcount: content-addressed keys let posts share a blob, so any citation blocks the delete.
261  if (usage.refs.length > 0 || usage.citations.length > 0) {
262    return { kind: "cited", citations: usage.citations, refs: usage.refs };
263  }
264  return { kind: "clear" };
265}
266
267/** Deletes one object the route has confirmed, refusing a static key or anything cited. */
268export async function deleteMedia(env: Env, key: string): Promise<Message> {
269  const verdict = await mediaDeleteVerdict(env, key);
270
271  if (verdict.kind === "static") {
272    return {
273      message:
274        `Delete refused: ${key} is a static asset, served from the repo rather than R2. ` +
275        `Remove it with a commit that deletes the file, then rebuild the index.`,
276      refused: true,
277    };
278  }
279
280  if (verdict.kind === "unmanaged") return { message: "Not a managed media key.", refused: true };
281
282  if (verdict.kind === "scan-failed") {
283    return {
284      message: `Delete refused: the reference scan failed (${verdict.failed.join(", ")}), so it cannot be confirmed that nothing cites this object.`,
285      refused: true,
286    };
287  }
288
289  if (verdict.kind === "cited") {
290    const rows = verdict.refs;
291    const sources = new Set(rows.map((row) => `${row.sourceType}:${row.sourceId}`));
292    const refNote =
293      rows.length > 0
294        ? ` The pipeline recorded ${rows.length} reference(s) across ${sources.size} item(s).`
295        : "";
296    return {
297      message: `Delete refused. ${describeCitations(verdict.citations)}${refNote}`,
298      refused: true,
299    };
300  }
301
302  /* One statement claims the row only if nothing cites it now. Row first: an orphan object backfills. */
303  if (!(await claimMediaKeyForDelete(env, key))) {
304    return {
305      message: `Delete refused: ${key} was cited or removed while this delete was being checked. Reload and try again.`,
306      refused: true,
307    };
308  }
309
310  await deleteMediaObject(env, key);
311  return { message: `Deleted ${key} and its row. Nothing cited it.` };
312}
313
314function describeCitations(citations: MediaCitation[]) {
315  const byItem = new Map<string, MediaCitation[]>();
316  for (const citation of citations) {
317    const list = byItem.get(citation.id);
318    if (list) list.push(citation);
319    else byItem.set(citation.id, [citation]);
320  }
321  const parts = [...byItem.entries()].map(([id, list]) => {
322    const forms = [...new Set(list.map((c) => c.form))].join(", ");
323    return `${list[0]?.title ?? ""} (${id}: ${forms}, ${list.map((c) => c.detail).join("; ")})`;
324  });
325  return `Still cited by ${parts.length} post${parts.length === 1 ? "" : "s"}: ${parts.join(" and ")}.`;
326}