app/lib/editor/converge.mjs

Functions

Imports

It imports app/lib/error-message.mjs. Imported by app/kb/procedures/save.server.ts, app/kb/registry/save.server.ts, app/lib/cv/save.server.ts, app/lib/dictionary/save.server.ts, app/lib/editor/publish.server.ts, app/lib/llms/save.server.ts, app/lib/operator/api.server.ts, app/lib/pages/save.server.ts, app/lib/phages/save.server.ts, app/lib/publications/save.server.ts, app/lib/roster/save.server.ts.

Source

1import { errorMessage } from "../error-message.mjs";
2
3/**
4 * A name string, not a class: the thrower is .mjs and the catcher is .ts, and instanceof across
5 * two build graphs breaks when a bundler duplicates the module.
6 */
7export const DIVERGENCE_ERROR_NAME = "D1DivergenceError";
8
9/**
10 * @param {{ slug: string, commitSha: string, attempts: number, cause?: unknown }} facts
11 * @returns {string}
12 */
13function divergenceMessage({ slug, commitSha, attempts, cause }) {
14  const reason = cause instanceof Error ? cause.message : String(cause ?? "unknown");
15  return (
16    `The post "${slug}" WAS committed as ${commitSha}, and the database index ` +
17    `could not be updated after ${attempts} attempt(s): ${reason}. ` +
18    `Your writing is safe in git and is not lost. The site will serve the ` +
19    `previous version of this post until the index catches up. ` +
20    `Do NOT save again; the commit already landed and a second save changes nothing. ` +
21    `Repair: run the content sync (npm run sync:content -- --remote), or press ` +
22    `Sync Ask corpus on /admin/posts, either of which rebuilds this row from the repo.`
23  );
24}
25
26/**
27 * Never reverts the commit on failure: the repo is the source and D1 is derived.
28 * One retry only: a second failure is not transient, and the repair is a rebuild from the repo.
29 * The recorder must not write to D1, the store that just failed; the caller passes KV.
30 *
31 * @param {{
32 *   write: () => Promise<unknown>,
33 *   recordDivergence: (facts: { slug: string, commitSha: string, error: string }) => Promise<unknown>,
34 *   slug: string,
35 *   commitSha: string,
36 *   attempts?: number,
37 * }} options
38 * @returns {Promise<{ ok: true, attempts: number, retried: boolean }>}
39 */
40export async function convergeWithRetry({
41  write,
42  recordDivergence,
43  slug,
44  commitSha,
45  attempts = 2,
46}) {
47  /** @type {unknown} */
48  let last;
49
50  for (let attempt = 1; attempt <= attempts; attempt += 1) {
51    try {
52      await write();
53      return { ok: true, attempts: attempt, retried: attempt > 1 };
54    } catch (error) {
55      last = error;
56    }
57  }
58
59  const message = divergenceMessage({ slug, commitSha, attempts, cause: last });
60
61  try {
62    await recordDivergence({
63      slug,
64      commitSha,
65      error: last instanceof Error ? last.message : String(last ?? "unknown"),
66    });
67  } catch (recordError) {
68    // Logged, never rethrown: the divergence error must still reach the operator.
69    console.error(JSON.stringify({ alert: "divergence-record-failed", detail: errorMessage(recordError) }));
70  }
71
72  const error = new Error(message);
73  error.name = DIVERGENCE_ERROR_NAME;
74  error.cause = last;
75  return Promise.reject(error);
76}