app/lib/carrel/phage-handler.server.ts

Functions

Imports

It imports app/db/phages.ts, app/lib/carrel/content-kinds.server.ts, app/lib/carrel/errors.server.ts, app/lib/editor/github.server.ts, app/lib/phages/compile.mjs, app/lib/phages/save.server.ts. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The phage kind of Carrel's /content group (docs/PHAGES.md): ids are `phage.<slug>` (the registry encodes
2// them), the slug being the phage's name in lower case (content/phages/acorn15.md). Every write is savePhage,
3// the one path a phage reaches the repository by, so a phage saved through Carrel is validated by the code CI
4// runs, committed, written to D1, drawn into /research/phages and live on the next request with no deploy.
5// There is no editor in the site's admin for this kind and no operator save tool. A phage has no draft state:
6// it is public when it is saved, so saving and publishing are the same write and unpublishing is refused.
7
8import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentSummary, WriteResult } from "@dustinedwards/site-api";
10
11import { listPhageRows } from "~/db/phages";
12import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
13import { asSiteApiError } from "~/lib/carrel/errors.server";
14import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
15import { PHAGES_PAGE_PATH, phagePath } from "~/lib/phages/compile.mjs";
16import { PHAGE_SLUG, savePhage } from "~/lib/phages/save.server";
17
18type PhageEnv = Env & { GITHUB_TOKEN?: string };
19
20/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
21
22export function phageHandler(env: PhageEnv): ContentKindHandler {
23  /** One write through savePhage as the Carrel actor, answered in the package's terms. */
24  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
25    try {
26      const saved = await savePhage(env, {
27        slug,
28        raw,
29        expectedBlobSha: expectedVersion ?? undefined,
30        isNew: expectedVersion === null,
31        actor: { kind: "carrel", changeId },
32      });
33      return { id: slug, version: saved.sourceBlobSha, status: "published", changeId };
34    } catch (error) {
35      // A PhageInvalid carries every message the validator gave; asSiteApiError passes them on.
36      return asSiteApiError(env, error, phagePath(slug));
37    }
38  }
39
40  /** A slug that is not a lower-case name owns no file, so a read of it is a missing id and never a path to read. */
41  const owns = (slug: string) => PHAGE_SLUG.test(slug);
42
43  return {
44    kind: "phage",
45
46    async list(query) {
47      const needle = query.q?.toLowerCase();
48      const summaries: ContentSummary[] = (await listPhageRows(env)).map((row) => ({
49        id: row.slug,
50        kind: "phage",
51        title: row.name,
52        status: "published",
53        // A phage has no page of its own: it is a row of the table, and a section, on the phages page.
54        path: `${PHAGES_PAGE_PATH}#${row.slug}`,
55        publishAt: null,
56        publishedAt: null,
57        updatedAt: row.syncedAt.toISOString(),
58      }));
59      return summaries
60        .filter((s) => !query.status || s.status === query.status)
61        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
62    },
63
64    async get(slug) {
65      if (!owns(slug)) return null;
66      const file = await readFile(env, phagePath(slug));
67      if (!file) return null;
68      const row = await env.DB.prepare(`SELECT name, synced_at FROM phages WHERE slug = ?1`).bind(slug).first<{ name: string; synced_at: number }>();
69      return {
70        id: slug,
71        kind: "phage",
72        title: row?.name ?? slug,
73        status: "published",
74        path: `${PHAGES_PAGE_PATH}#${slug}`,
75        publishAt: null,
76        publishedAt: null,
77        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
78        format: "markdown",
79        source: file.content,
80        version: file.sha,
81      };
82    },
83
84    // Creates a phage (no version) or edits one (its version), as every kind does; either way it is public.
85    async saveDraft(slug, input) {
86      if (!owns(slug)) throw new RefusedError(`"${slug}" is not a phage file key; a phage is named for its name in lower case, such as acorn15.`);
87      const file = await readFile(env, phagePath(slug));
88      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
89      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
90      return write(slug, input.changeId, input.source, input.expectedVersion);
91    },
92
93    async publish(slug, input) {
94      if (!owns(slug)) throw new RefusedError(`"${slug}" is not a phage file key; a phage is named for its name in lower case, such as acorn15.`);
95      // Read even when source is sent: a version for an id that does not exist is a conflict.
96      const file = await readFile(env, phagePath(slug));
97      if (!file) throw new VersionConflictError(null);
98      return write(slug, input.changeId, input.source ?? file.content, input.expectedVersion);
99    },
100
101    async unpublish() {
102      throw new RefusedError(
103        "A phage has no draft state, so it cannot be unpublished. To remove a phage, delete its file from " +
104          "content/phages/ in a commit; the next content sync removes its row and redraws the table.",
105      );
106    },
107
108    revisions(slug) {
109      return fileRevisions(env, owns(slug) ? phagePath(slug) : null);
110    },
111
112    revisionSource(slug, version) {
113      return fileRevisionSource(env, owns(slug) ? phagePath(slug) : null, version);
114    },
115  };
116}