Loading…
Yujin’s Notebook
Back to articles
System Design

Cache invalidation is a publishing decision

A small publishing system is a useful place to understand the difference between authoritative data, derived views, and eventual consistency.

On this page

A cached page is a view of an article at a particular point in time. Editing the source file changes the article, but it does not automatically change every view of it.

Start with one source of truth

For this site, Markdown files own the content. HTML pages, RSS entries, and search documents are derived representations. Each representation can be rebuilt.

async function saveAndPublish(input: ArticleInput) {
  const article = await saveMarkdown(input);
  invalidatePublicPages(article.slug);
  return article;
}

The search worker reconciles the source files separately. That separation lets an author save a post even when the search service is temporarily unavailable.

Model the failure cases

Successful writes are only half of the design. Ask what a reader sees when one service is unavailable.

  • A failed file write must leave the previous version intact.
  • A failed search update must be retried.
  • An article changed back to draft must disappear from public results.
  • A conflict between two editors must be visible to the author.

Check visibility at the boundary

Search results can briefly reflect an older index. Before returning them to a browser, check that their source articles are still public. A stale index must never grant access to a draft.

Prefer recoverable operations

A full index rebuild is useful because it repairs both missing and obsolete documents. It should be safe to run after deployment and after restoring a backup.

pnpm content:validate
pnpm search:index

Measure the result

Performance is an observed property. Test the production build, a representative article, and the actual deployment environment. Keep third-party comments out of the initial rendering path so reading can begin immediately.

Site navigation