app/lib/podcast/podcast.server.ts

Functions

Imports

It imports app/lib/context.ts, app/lib/error-message.mjs, app/lib/podcast/feed.mjs, app/lib/site-origin.mjs. Imported by app/routes/home.tsx.

Source

1import type { RouterContextProvider } from "react-router";
2
3import { getEnv, getExecutionContext } from "~/lib/context";
4import { PODCAST_FEED_URL, parsePodcastFeed, type PodcastEpisode } from "~/lib/podcast/feed.mjs";
5import { errorMessage } from "~/lib/error-message.mjs";
6import { SITE_USER_AGENT } from "~/lib/site-origin.mjs";
7
8// The page never waits on the podcast host: loaders read KV only and refresh in `waitUntil` (this Worker
9// has no cron). A failed refresh keeps the episodes and stamps `checkedAt`, so a down host is asked once
10// per interval, not on every render.
11
12const CACHE_KEY = "podcast:germomics:v1";
13const REFRESH_AFTER_MS = 3 * 60 * 60 * 1000;
14const FETCH_TIMEOUT_MS = 8000;
15
16/**
17 * `lastError` says why the last refresh failed; absent after one that landed. With no episodes ever
18 * read, a failed refresh still answers (episodes empty, `fetchedAt` null, `lastError` set), so a
19 * reader can tell "the read failed" from "not read yet", which is the only thing null means.
20 */
21type CachedFeed = {
22  episodes: PodcastEpisode[];
23  fetchedAt: string | null;
24  checkedAt: string;
25  lastError?: string;
26};
27
28// A failed refresh never takes the page down, but it is logged under one alert key and kept on the
29// cached feed as `lastError`, so a host that has been down for a week is not read as a quiet podcast.
30function logFailure(stage: string, detail: unknown) {
31  console.error(
32    JSON.stringify({
33      alert: "podcast-refresh-failed",
34      stage,
35      detail: errorMessage(detail),
36    }),
37  );
38}
39
40async function readCache(kv: KVNamespace): Promise<CachedFeed | null> {
41  try {
42    return await kv.get<CachedFeed>(CACHE_KEY, "json");
43  } catch (error) {
44    // A KV hiccup must never take the page down.
45    logFailure("kv-read", error);
46    return null;
47  }
48}
49
50async function fetchEpisodes(): Promise<{ episodes: PodcastEpisode[] } | { error: string }> {
51  try {
52    const res = await fetch(PODCAST_FEED_URL, {
53      headers: { "user-agent": SITE_USER_AGENT, accept: "application/rss+xml, application/xml" },
54      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
55    });
56    if (!res.ok) return { error: `the feed answered HTTP ${res.status}` };
57    const episodes = parsePodcastFeed(await res.text());
58    return episodes.length > 0 ? { episodes } : { error: "the feed parsed to no episodes" };
59  } catch (error) {
60    return { error: errorMessage(error) };
61  }
62}
63
64async function refresh(kv: KVNamespace, cached: CachedFeed | null): Promise<CachedFeed> {
65  const now = new Date().toISOString();
66  const fetched = await fetchEpisodes();
67  let next: CachedFeed;
68  if ("episodes" in fetched) {
69    next = { episodes: fetched.episodes, fetchedAt: now, checkedAt: now };
70  } else {
71    logFailure("fetch", fetched.error);
72    // Not stored when nothing was ever read: a cached empty feed would hold off the retry for the
73    // whole refresh interval, where today every render retries a cold cache.
74    if (!cached) return { episodes: [], fetchedAt: null, checkedAt: now, lastError: fetched.error };
75    next = { ...cached, checkedAt: now, lastError: fetched.error };
76  }
77  try {
78    await kv.put(CACHE_KEY, JSON.stringify(next));
79  } catch (error) {
80    // The next render tries again.
81    logFailure("kv-write", error);
82  }
83  return next;
84}
85
86const isStale = (cached: CachedFeed) =>
87  Date.now() - Date.parse(cached.checkedAt) > REFRESH_AFTER_MS;
88
89// A public render never blocks on the podcast host: a stale or cold cache answers with what it has
90// and the refresh runs in `waitUntil`.
91async function readPodcastFeed(
92  context: Readonly<RouterContextProvider>,
93): Promise<CachedFeed | null> {
94  const env = getEnv(context);
95  const ctx = getExecutionContext(context);
96  const kv = env.APP_KV;
97  const cached = await readCache(kv);
98  if (cached && !isStale(cached)) return cached;
99  ctx.waitUntil(refresh(kv, cached));
100  return cached;
101}
102
103// Always the latest episode in the feed: there is no stored choice to fall back from.
104export async function homePodcastEpisode(
105  context: Readonly<RouterContextProvider>,
106): Promise<PodcastEpisode | null> {
107  const feed = await readPodcastFeed(context);
108  return feed?.episodes[0] ?? null;
109}