app/lib/roster/save.server.ts

Functions

Imports

It imports app/lib/cache-purge.server.ts, app/lib/carrel/errors.server.ts, app/lib/content/load-pipeline.server.ts, app/lib/editor/converge.mjs, app/lib/editor/github.server.ts, app/lib/editor/publish-policy.mjs, app/lib/editor/write-path.server.ts, app/lib/roster/compile.mjs. Imported by app/lib/carrel/roster-handler.server.ts, app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts.

Source

1// The one roster save, called by the site-api adapter for Carrel (app/lib/carrel/roster-handler.server.ts), and
2// the read the operator's get_roster tool answers. The roster is edited through Carrel and nothing else:
3// there is no save tool and no admin editor. A save compiles the file the way CI does (compile.mjs), refuses
4// it with every message if it fails, commits it to the repository (unless it is byte-identical,
5// commitUnlessUnchanged), then writes its D1 row and purges the pages that embed the roster, so the roster
6// changes on the next request with no build or deploy. The commit is never reverted when the D1 write
7// fails: the error says the commit landed and how to repair the row.
8
9import { ContentInvalid } from "~/lib/carrel/errors.server";
10import { purgeRoster, type PurgeOutcome } from "~/lib/cache-purge.server";
11import { loadPipeline } from "~/lib/content/load-pipeline.server";
12import { convergeWithRetry } from "~/lib/editor/converge.mjs";
13import { blobGuard, commitFiles, publicFileEntry, readFile } from "~/lib/editor/github.server";
14import { decideFileWrite, type Actor } from "~/lib/editor/publish-policy.mjs";
15import { commitUnlessUnchanged, UNCHANGED_NOTE } from "~/lib/editor/write-path.server";
16
17import { compileCohort, rosterPath, type Cohort, type RosterHost } from "./compile.mjs";
18
19type RosterEnv = Env & { GITHUB_TOKEN?: string };
20
21/** A cohort's file key is its four-digit year, which is also what keeps an id from naming any other path. */
22export const COHORT_SLUG = /^\d{4}$/;
23
24/** A file the validator refused: carries every message, so the caller can fix its own edit. */
25class RosterInvalid extends ContentInvalid {
26  constructor(slug: string, errors: string[]) {
27    super(`The ${slug} cohort was not saved: it fails ${errors.length} check(s). Nothing was committed.`, errors);
28    this.name = "RosterInvalid";
29  }
30}
31
32/** The repository's photographs, asked of GitHub: they are static assets, so existence is all there is to read. */
33function githubHost(env: RosterEnv): RosterHost {
34  return { photo: async (src) => (await publicFileEntry(env, src)) !== null };
35}
36
37/** The one compile door: the save, get_roster and sync_roster all read a file through it. */
38export async function compile(env: RosterEnv, slug: string, raw: string) {
39  const { findWideDashes } = await loadPipeline();
40  return compileCohort({ slug, raw, host: githubHost(env), pipeline: { findWideDashes } });
41}
42
43type Compiled = Extract<Awaited<ReturnType<typeof compile>>, { ok: true }>;
44
45/** The slug of an id, or a refusal: nothing but a year names a cohort file. */
46function registered(slug: string) {
47  if (!COHORT_SLUG.test(slug)) {
48    throw new RosterInvalid(slug, [`"${slug}" is not a cohort file key; a cohort's file is named for its year, such as 2025`]);
49  }
50  return { slug, file: rosterPath(slug) };
51}
52
53/** The cohort the committed file holds, judged by the same validator, for get_roster. */
54export async function readRoster(env: RosterEnv, slug: string) {
55  const { file } = registered(slug);
56  const existing = await readFile(env, file);
57  if (!existing) return null;
58  const compiled = await compile(env, slug, existing.content);
59  return { slug, path: file, cohort: compiled.ok ? compiled.cohort : null, errors: compiled.ok ? [] : compiled.errors };
60}
61
62/** The D1 row, in one statement: a cohort is one row, so it moves whole. */
63export async function writeRosterRow(env: RosterEnv, compiled: Compiled) {
64  const cohort: Cohort = compiled.cohort;
65  await env.DB.prepare(
66    `INSERT INTO roster (slug, year, record, source_path, source_blob_sha, synced_at)
67     VALUES (?1, ?2, ?3, ?4, ?5, unixepoch())
68     ON CONFLICT(slug) DO UPDATE SET year = excluded.year, record = excluded.record,
69       source_path = excluded.source_path, source_blob_sha = excluded.source_blob_sha,
70       synced_at = excluded.synced_at`,
71  )
72    .bind(String(cohort.year), cohort.year, compiled.record, compiled.sourcePath, compiled.sourceBlobSha)
73    .run();
74}
75
76/** The row of a cohort whose file is gone: the one removal sync_roster makes. */
77export async function deleteRosterRow(env: RosterEnv, row: { slug: string }) {
78  await env.DB.prepare(`DELETE FROM roster WHERE slug = ?1`).bind(row.slug).run();
79}
80
81/** True when D1's row for the cohort was compiled from exactly this file (the git blob sha matches). */
82async function rowIsCurrent(env: RosterEnv, slug: string, blobSha: string) {
83  const row = await env.DB.prepare("SELECT source_blob_sha FROM roster WHERE slug = ?1")
84    .bind(slug)
85    .first<{ source_blob_sha: string | null }>();
86  return row?.source_blob_sha === blobSha;
87}
88
89export type SavedCohort = {
90  slug: string;
91  commitSha: string;
92  /** The git blob sha of the committed file: Carrel's version of the item. */
93  sourceBlobSha: string;
94  unchanged: boolean;
95  created: boolean;
96  purged: PurgeOutcome;
97  note?: string;
98};
99
100/** validate -> policy -> commitUnlessUnchanged -> blob verify -> D1 write (convergeWithRetry) -> purge by tag. */
101export async function saveRoster(
102  env: RosterEnv,
103  options: { slug: string; raw: string; expectedHeadSha?: string | null;
104    /** The blob sha of this file as Carrel loaded it; undefined means no check. */
105    expectedBlobSha?: string | null; isNew: boolean; actor: Actor },
106): Promise<SavedCohort> {
107  const { raw, actor } = options;
108  const { slug, file } = registered(options.slug);
109  const existing = await readFile(env, file);
110  if (options.isNew && existing) throw new RosterInvalid(slug, [`the ${slug} cohort already has a file (${file}); pass isNew false to edit it`]);
111  if (!options.isNew && !existing) throw new RosterInvalid(slug, [`the ${slug} cohort has no file yet; pass isNew to create it`]);
112
113  const compiled = await compile(env, slug, raw);
114  if (!compiled.ok) throw new RosterInvalid(slug, compiled.errors);
115  // A cohort has no draft state: it is public when it is saved, so the policy reads it as published.
116  decideFileWrite({ actor, noun: "roster cohort", incomingDraft: false, priorRaw: existing?.content ?? null, isDraft: () => false });
117
118  const tag = actor.kind === "operator" ? ` [operator:${actor.id}]` : actor.kind === "carrel" ? ` [carrel:${actor.changeId}]` : "";
119  // After the gate, so a file that fails validation is still refused even when it is unchanged.
120  const written = await commitUnlessUnchanged(env, {
121    existing,
122    raw,
123    rowIsCurrent: () => rowIsCurrent(env, slug, compiled.sourceBlobSha),
124    commit: () =>
125      commitFiles(env, {
126        expectedHeadSha: options.expectedHeadSha,
127        expectedBlobs: blobGuard(file, options.expectedBlobSha),
128        message: `${options.isNew ? "Add" : "Update"} roster: ${slug} cohort${tag}`,
129        changes: [{ path: file, content: raw }],
130      }),
131  });
132  if (written.action === "noop") {
133    return { slug, commitSha: written.commitSha, sourceBlobSha: compiled.sourceBlobSha, unchanged: true, created: false, purged: null, note: UNCHANGED_NOTE };
134  }
135  const { commitSha } = written;
136  const blobSha = written.blobShas[file];
137  if (blobSha && blobSha !== compiled.sourceBlobSha) {
138    throw new Error(
139      `The ${slug} cohort WAS committed as ${commitSha}, but the committed bytes (${blobSha}) are not ` +
140        `the bytes compiled (${compiled.sourceBlobSha}), so its row was not updated. Run the content sync to ` +
141        `rebuild the row from the repository.`,
142    );
143  }
144
145  let purged: PurgeOutcome = false;
146  await convergeWithRetry({
147    write: async () => {
148      await writeRosterRow(env, compiled);
149      purged = await purgeRoster(`save roster ${slug}`);
150    },
151    // Nothing kept in KV for a cohort: the thrown error names the commit and the repair (the content sync),
152    // and the next ship's sync converges the row from the repository anyway.
153    recordDivergence: async () => undefined,
154    slug,
155    commitSha,
156  });
157
158  return { slug, commitSha, sourceBlobSha: compiled.sourceBlobSha, unchanged: written.action === "repair", created: options.isNew, purged };
159}