app/lib/carrel/site-adapter.server.ts

Functions

Imports

It imports app/db/index.ts, app/db/schema.ts, app/lib/carrel/content-kinds.server.ts, app/lib/carrel/cv-handler.server.ts, app/lib/carrel/dictionary-handler.server.ts, app/lib/carrel/document-handler.server.ts, app/lib/carrel/errors.server.ts, app/lib/carrel/front-matter-lines.ts, app/lib/carrel/media-adapter.server.ts, app/lib/carrel/page-handler.server.ts, app/lib/carrel/phage-handler.server.ts, app/lib/carrel/procedure-handler.server.ts, app/lib/carrel/publication-handler.server.ts, app/lib/carrel/registry-handler.server.ts, app/lib/carrel/roster-handler.server.ts, app/lib/content/slug.mjs, app/lib/context.ts, app/lib/editor/frontmatter.ts, app/lib/editor/github.server.ts, app/lib/editor/post-rows.server.ts, app/lib/editor/publish-policy.mjs, app/lib/editor/publish.server.ts, app/lib/seo.ts. Imported by app/lib/carrel/site-api.server.ts.

Source

1// The dustinedwards.info side of Carrel's site API (the site-api package): the package owns the
2// route, the key, the rate limit and every body's shape; this adapter maps its content and preview
3// calls onto the site's own save, render and history code. Nothing here writes around savePost.
4// Media (v0.2.0) is its own module, over the site's media code.
5
6import { NotFoundError, RefusedError, VersionConflictError, type SiteAdapter } from "@dustinedwards/site-api";
7import type { ContentStatus, ContentSummary, WriteResult } from "@dustinedwards/site-api";
8import { getTableColumns } from "drizzle-orm";
9import { RouterContextProvider } from "react-router";
10
11import { listAllPostsForAdmin, previewBlogPost, type PostRow } from "~/db";
12import { posts } from "~/db/schema";
13import { carrelMediaAdapter } from "~/lib/carrel/media-adapter.server";
14import { postPath } from "~/lib/content/slug.mjs";
15import { cloudflareContext, nonceContext, postPreviewContext } from "~/lib/context";
16import { contentRegistry, type ContentKindHandler } from "~/lib/carrel/content-kinds.server";
17import { publicationHandler } from "~/lib/carrel/publication-handler.server";
18import { asSiteApiError } from "~/lib/carrel/errors.server";
19import { withPublication } from "~/lib/carrel/front-matter-lines";
20import { documentHandler } from "~/lib/carrel/document-handler.server";
21import { dictionaryHandler } from "~/lib/carrel/dictionary-handler.server";
22import { pageHandler } from "~/lib/carrel/page-handler.server";
23import { cvHandler } from "~/lib/carrel/cv-handler.server";
24import { procedureHandler } from "~/lib/carrel/procedure-handler.server";
25import { phageHandler } from "~/lib/carrel/phage-handler.server";
26import { registryHandlers } from "~/lib/carrel/registry-handler.server";
27import { rosterHandler } from "~/lib/carrel/roster-handler.server";
28import { fileRevisions, fileRevisionSource, readFile } from "~/lib/editor/github.server";
29import { parsePost } from "~/lib/editor/frontmatter";
30import {
31  deletePost,
32  renderRecord,
33  savePost,
34} from "~/lib/editor/publish.server";
35import { postColumnValues, type PostRecord } from "~/lib/editor/post-rows.server";
36import { readState } from "~/lib/editor/publish-policy.mjs";
37import { SITE, SITE_ORIGIN } from "~/lib/seo";
38
39export { withPublication };
40
41type CarrelEnv = Env & { GITHUB_TOKEN?: string };
42
43type RenderDocument = (request: Request, context: RouterContextProvider) => Promise<Response>;
44
45/**
46 * A revision's version is a commit sha. A post's own version is different: the git blob sha of its file at
47 * head, so only a change to that post moves it, and saving another post no longer makes this one look changed.
48 */
49
50/** A preview of a post not yet in D1 needs an id no stored row has, for its neighbours' tie-break. */
51const PREVIEW_ROW_ID = Number.MAX_SAFE_INTEGER;
52
53/** The slug a preview renders at when Carrel sends no id: a new post that has none yet. */
54const UNSAVED_PREVIEW_SLUG = "carrel-preview";
55
56/** Draft, scheduled or published, from the file itself, which is the only authority on status. */
57function statusOf(raw: string, now = Date.now()): ContentStatus {
58  if (readState(raw).draft) return "draft";
59  const at = parsePost(raw).publishAt.trim();
60  return at && Date.parse(at) > now ? "scheduled" : "published";
61}
62
63/** The effective publication time, as the pipeline computes it: publish_at, else the date. */
64function effectivePublishAt(raw: string): number {
65  const fields = parsePost(raw);
66  return Date.parse(fields.publishAt.trim() || `${fields.date}T00:00:00.000Z`);
67}
68
69/**
70 * The drizzle row getBlogPost would read once this record were synced: the synced columns decoded
71 * through the schema's own column mappers, and the columns the sync does not write kept from the
72 * stored row. A column neither supplies is an error, so a new column cannot quietly go missing here.
73 */
74async function previewRow(env: CarrelEnv, record: PostRecord): Promise<PostRow> {
75  const stored = await env.DB.prepare(
76    `SELECT id, excerpt, og_image, created_at, updated_at FROM posts WHERE slug = ?1`,
77  )
78    .bind(record.slug)
79    .first<{
80      id: number;
81      excerpt: string | null;
82      og_image: string | null;
83      created_at: number;
84      updated_at: number;
85    }>();
86  const now = Math.floor(Date.now() / 1000);
87
88  const raw: Record<string, unknown> = {
89    id: stored?.id ?? PREVIEW_ROW_ID,
90    kind: "post",
91    excerpt: stored?.excerpt ?? null,
92    og_image: stored?.og_image ?? null,
93    created_at: stored?.created_at ?? now,
94    ...postColumnValues(record),
95  };
96  // postColumnValues' `updated_at` is NULL when the post has no frontmatter `updated`: the stored one stands.
97  raw.updated_at ??= stored?.updated_at ?? now;
98
99  const row: Record<string, unknown> = {};
100  for (const [key, column] of Object.entries(getTableColumns(posts))) {
101    if (!(column.name in raw)) {
102      throw new Error(`the Carrel preview has no value for posts.${column.name}; add it to postColumnValues`);
103    }
104    const value = raw[column.name];
105    row[key] = value === null || value === undefined ? null : column.mapFromDriverValue(value as never);
106  }
107  return row as PostRow;
108}
109
110/** What the blog loader reads for a preview: getBlogPost's shape, for a record not yet in D1. */
111export async function previewPost(env: CarrelEnv, record: PostRecord) {
112  return previewBlogPost(env, await previewRow(env, record), record.tags);
113}
114
115export function carrelSiteAdapter(options: {
116  env: CarrelEnv;
117  ctx: ExecutionContext;
118  /** The origin the preview's page request is made against: the request's own. */
119  origin: string;
120  renderDocument: RenderDocument | null;
121}): SiteAdapter {
122  const { env, ctx, origin, renderDocument } = options;
123
124  /** One write through savePost as the Carrel actor, answered in the package's terms. */
125  async function write(
126    id: string,
127    changeId: string,
128    raw: string,
129    expectedVersion: string | null,
130  ): Promise<WriteResult> {
131    try {
132      const saved = await savePost(env, {
133        slug: id,
134        raw,
135        // A create (null) is guarded by isNew; every other write by the post's own blob sha.
136        expectedBlobSha: expectedVersion ?? undefined,
137        isNew: expectedVersion === null,
138        actor: { kind: "carrel", changeId },
139      });
140      // The record was rendered from the stamped file that was committed, so this is that file's blob sha.
141      return { id, version: saved.record.sourceBlobSha, status: statusOf(raw), changeId };
142    } catch (error) {
143      return asSiteApiError(env, error, postPath(id));
144    }
145  }
146
147  /** The stored file for a write that names a version; a version for a missing id is a conflict. */
148  async function existing(id: string): Promise<string> {
149    const file = await readFile(env, postPath(id));
150    if (!file) throw new VersionConflictError(null);
151    return file.content;
152  }
153
154  const postHandler: ContentKindHandler = {
155    kind: "post",
156
157    async list(query) {
158      const now = Date.now();
159      const needle = query.q?.toLowerCase();
160      const summaries: ContentSummary[] = (await listAllPostsForAdmin(env)).map((row) => {
161        const at = row.publishAt ? row.publishAt.getTime() : null;
162        const status: ContentStatus =
163          row.status === "draft" ? "draft" : at !== null && at > now ? "scheduled" : "published";
164        return {
165          id: row.slug,
166          kind: "post",
167          title: row.title,
168          status,
169          // D1 cannot tell a withdrawn post from one never published, so a draft has no public path.
170          path: status === "draft" ? null : `/writing/${row.slug}`,
171          publishAt: status === "scheduled" && at !== null ? new Date(at).toISOString() : null,
172          publishedAt: status === "published" && at !== null ? new Date(at).toISOString() : null,
173          updatedAt: row.updatedAt ? row.updatedAt.toISOString() : null,
174        };
175      });
176      return summaries
177        .filter((s) => !query.status || s.status === query.status)
178        .filter((s) => !needle || s.title.toLowerCase().includes(needle) || s.id.includes(needle));
179    },
180
181    async get(id) {
182      const file = await readFile(env, postPath(id));
183      if (!file) return null;
184      const updated = await env.DB.prepare(`SELECT updated_at FROM posts WHERE slug = ?1`)
185        .bind(id)
186        .first<{ updated_at: number }>();
187      const fields = parsePost(file.content);
188      const { firstPublished } = readState(file.content);
189      const status = statusOf(file.content);
190      return {
191        id,
192        kind: "post",
193        title: fields.title || id,
194        status,
195        path: firstPublished ? `/writing/${id}` : null,
196        publishAt: status === "scheduled" ? new Date(Date.parse(fields.publishAt)).toISOString() : null,
197        publishedAt: firstPublished ? `${firstPublished}T00:00:00.000Z` : null,
198        updatedAt: updated ? new Date(updated.updated_at * 1000).toISOString() : null,
199        format: "markdown",
200        source: file.content,
201        version: file.sha,
202      };
203    },
204
205    // Keeps the stored status, as the contract's reference adapter does: a save to a live post
206    // edits it live, and a new post starts as a draft.
207    async saveDraft(id, input) {
208      const file = await readFile(env, postPath(id));
209      if (input.expectedVersion === null && file) throw new VersionConflictError(file.sha);
210      if (input.expectedVersion !== null && !file) throw new VersionConflictError(null);
211      const raw = file
212        ? withPublication(input.source, {
213            draft: readState(file.content).draft,
214            publishAt: parsePost(file.content).publishAt.trim() || null,
215          })
216        : withPublication(input.source, { draft: true });
217      return write(id, input.changeId, raw, input.expectedVersion);
218    },
219
220    async publish(id, input) {
221      // Read even when source is sent: a version for an id that does not exist is a conflict.
222      const stored = await existing(id);
223      const source = input.source ?? stored;
224      // A post whose time is still ahead would publish invisible, so publishing now means now.
225      const due = effectivePublishAt(source) > Date.now() ? new Date().toISOString() : undefined;
226      return write(id, input.changeId, withPublication(source, { draft: false, publishAt: due }), input.expectedVersion);
227    },
228
229    async schedule(id, input) {
230      const at = Date.parse(input.publishAt);
231      if (!(at > Date.now())) {
232        throw new RefusedError("publishAt is not in the future; publish it now instead.");
233      }
234      const stored = await existing(id);
235      const source = input.source ?? stored;
236      return write(
237        id,
238        input.changeId,
239        withPublication(source, { draft: false, publishAt: new Date(at).toISOString() }),
240        input.expectedVersion,
241      );
242    },
243
244    async unpublish(id, input) {
245      const source = await existing(id);
246      return write(id, input.changeId, withPublication(source, { draft: true }), input.expectedVersion);
247    },
248
249    revisions(id) {
250      return fileRevisions(env, postPath(id));
251    },
252
253    revisionSource(id, version) {
254      return fileRevisionSource(env, postPath(id), version);
255    },
256
257    // The post's own delete, the one the admin uses: the file's commit, the D1 rows, the cache purge and the
258    // Ask index as one unit. The version is checked here for a clean answer and again inside the commit, at
259    // the head it is built on. A check that cannot run (GitHub unreadable) throws, so nothing is deleted.
260    async delete(id, input) {
261      const file = await readFile(env, postPath(id));
262      if (!file) throw new NotFoundError(`No post "${id}" exists.`);
263      if (file.sha !== input.expectedVersion) throw new VersionConflictError(file.sha);
264      try {
265        await deletePost(env, {
266          slug: id,
267          expectedBlobSha: input.expectedVersion,
268          actor: { kind: "carrel", changeId: input.changeId },
269        });
270      } catch (error) {
271        return asSiteApiError(env, error, postPath(id));
272      }
273    },
274
275    // The page the save would publish: the same record renderAndWrite builds, rendered through the
276    // blog route and the root layout in-process, so nothing is written and nothing is cached.
277    async preview(previewSlug, input) {
278      if (!renderDocument) throw new Error("the document handler is not on this request's context");
279      const slug = previewSlug ?? UNSAVED_PREVIEW_SLUG;
280      let record: PostRecord;
281      try {
282        record = await renderRecord(env, slug, input.source);
283      } catch (error) {
284        return asSiteApiError(env, error, postPath(slug));
285      }
286      const post = await previewPost(env, record);
287
288      // Every context the Renderer sets for a public path: the nonce is undefined there, as a
289      // public page carries none (workers/csp.mjs).
290      const context = new RouterContextProvider();
291      context.set(cloudflareContext, { env, ctx });
292      context.set(nonceContext, undefined);
293      context.set(postPreviewContext, post);
294      const response = await renderDocument(
295        new Request(`${origin}/writing/${slug}`, { headers: { accept: "text/html" } }),
296        context,
297      );
298      if (!response.ok) {
299        throw new RefusedError(`The page did not render: the blog route answered ${response.status}.`);
300      }
301      return response.text();
302    },
303  };
304
305  const registry = contentRegistry([
306    postHandler,
307    publicationHandler(env),
308    pageHandler(env),
309    documentHandler(env),
310    cvHandler(env, ctx),
311    dictionaryHandler(env),
312    rosterHandler(env),
313    phageHandler(env),
314    procedureHandler(env),
315    // One per registry kind (app/kb/registry/kinds.mjs); none until a kind is defined.
316    ...registryHandlers(env),
317  ]);
318
319  return {
320    site: { id: "dustinedwards-info", name: SITE.name, origin: SITE_ORIGIN },
321    content: registry.adapter,
322    preview: { render: registry.render },
323    media: carrelMediaAdapter(env),
324  };
325}