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

Functions

Imports

It imports app/db/cv.ts, app/lib/carrel/content-kinds.server.ts, app/lib/carrel/errors.server.ts, app/lib/cv/entries.mjs, app/lib/cv/parse.mjs, app/lib/cv/save.server.ts, app/lib/cv/view.mjs, app/lib/editor/github.server.ts. Imported by app/lib/carrel/site-adapter.server.ts.

Source

1// The "cv" kind of Carrel's content group (docs/CV.md): the files in content/cv/. The id is `cv.<slug>`, the slug
2// being the file's name (`cv.grants` for content/cv/grants.md, `cv.profile` for the edition and the person).
3// Every write is saveCvFile, the one CV save, so a file saved through Carrel is validated by the code CI runs,
4// committed, written to D1 and live on the next request with no deploy. A file cannot be created here: the set
5// of files is structure and lives in CV_FILES, so an id no file names is refused. The CV has no draft state, so
6// it cannot be unpublished.
7
8import { RefusedError, VersionConflictError } from "@dustinedwards/site-api";
9import type { ContentSummary, WriteResult } from "@dustinedwards/site-api";
10
11import { listCvRows } from "~/db/cv";
12import type { ContentKindHandler } from "~/lib/carrel/content-kinds.server";
13import { asSiteApiError } from "~/lib/carrel/errors.server";
14import { CV_PAGE } from "~/lib/cv/entries.mjs";
15import { CV_DIR, CV_FILES, cvFileFor, cvSourcePath } from "~/lib/cv/parse.mjs";
16import { saveCvFile } from "~/lib/cv/save.server";
17import { TYPES } from "~/lib/cv/view.mjs";
18import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
19
20type CvEnv = Env & { GITHUB_TOKEN?: string };
21
22/** A revision's version is a commit sha; an item's own version is the blob sha of its file. */
23
24/** The name a list shows for a file: the section's plural as the CV prints it. */
25function titleOf(slug: string) {
26  const type = cvFileFor(slug)?.type;
27  const plural = TYPES.find(([id]) => id === type)?.[2];
28  return `${CV_PAGE.title}: ${type === "profile" ? "Profile" : (plural ?? slug)}`;
29}
30
31export function cvHandler(env: CvEnv, ctx: Pick<ExecutionContext, "waitUntil">): ContentKindHandler {
32  /** The file of a registered slug, or null: an id no file names owns nothing. */
33  function registered(slug: string) {
34    return cvFileFor(slug) ? cvSourcePath(slug) : null;
35  }
36
37  /** The same, for a write: a missing registration is a refusal that says why. */
38  function target(slug: string) {
39    const found = registered(slug);
40    if (!found) {
41      throw new RefusedError(
42        `"${slug}" names no CV file. A save cannot create one: the set of files is CV_FILES ` +
43          `(app/lib/cv/parse.mjs). The files are ${CV_FILES.map((f) => f.slug).join(", ")}, in ${CV_DIR}/.`,
44      );
45    }
46    return found;
47  }
48
49  /** One write through saveCvFile as the Carrel actor, answered in the package's terms. */
50  async function write(slug: string, changeId: string, raw: string, expectedVersion: string | null): Promise<WriteResult> {
51    target(slug);
52    try {
53      const saved = await saveCvFile(env, {
54        slug,
55        raw,
56        expectedBlobSha: expectedVersion ?? undefined,
57        actor: { kind: "carrel", changeId },
58        // The PDF follows the save after the response: Browser Run is seconds, a save should not wait for it.
59        background: (work) => ctx.waitUntil(work),
60      });
61      return { id: slug, version: saved.sourceBlobSha, status: "published", changeId };
62    } catch (error) {
63      // A CvInvalid carries every message the validator gave; asSiteApiError passes them on.
64      return asSiteApiError(env, error, target(slug));
65    }
66  }
67
68  /** The stored file for a write that names a version; a version for a missing file is a conflict. */
69  async function existing(slug: string): Promise<string> {
70    const file = await readFile(env, target(slug));
71    if (!file) throw new VersionConflictError(null);
72    return file.content;
73  }
74
75  return {
76    kind: "cv",
77
78    async list(query) {
79      const needle = query.q?.toLowerCase();
80      const summaries: ContentSummary[] = (await listCvRows(env)).map((row) => ({
81        id: row.slug,
82        kind: "cv",
83        title: titleOf(row.slug),
84        status: "published",
85        path: CV_PAGE.path,
86        publishAt: null,
87        publishedAt: null,
88        updatedAt: row.syncedAt.toISOString(),
89      }));
90      return summaries
91        .filter((s) => !query.status || s.status === query.status)
92        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
93    },
94
95    async get(slug) {
96      const found = registered(slug);
97      if (!found) return null;
98      const file = await readFile(env, found);
99      if (!file) return null;
100      const row = await env.DB.prepare(`SELECT synced_at FROM cv WHERE slug = ?1`).bind(slug).first<{ synced_at: number }>();
101      return {
102        id: slug,
103        kind: "cv",
104        title: titleOf(slug),
105        status: "published",
106        path: CV_PAGE.path,
107        publishAt: null,
108        publishedAt: null,
109        updatedAt: row ? new Date(row.synced_at * 1000).toISOString() : null,
110        format: "markdown",
111        source: file.content,
112        version: file.sha,
113      };
114    },
115
116    // A file always exists, so a save that names no version is a conflict, as a page's is.
117    async saveDraft(slug, input) {
118      const found = target(slug);
119      const file = await readFile(env, found);
120      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
121      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
122      if (!file) throw new RefusedError(`The file ${found} is missing from the repository, so it cannot be saved.`);
123      return write(slug, input.changeId, input.source, input.expectedVersion);
124    },
125
126    async publish(slug, input) {
127      const stored = await existing(slug);
128      return write(slug, input.changeId, input.source ?? stored, input.expectedVersion);
129    },
130
131    async unpublish() {
132      throw new RefusedError("The CV has no draft state, so it cannot be unpublished. Edit the file, or remove an entry.");
133    },
134
135    revisions(slug) {
136      return fileRevisions(env, registered(slug) ?? null);
137    },
138
139    revisionSource(slug, version) {
140      return fileRevisionSource(env, registered(slug) ?? null, version);
141    },
142  };
143}