feat: implement stale fallback for GitHub content fetching and enhance error handling

Author: LadyBluenotes

src/utils/cache.server.ts

@@ -12,10 +12,70 @@ const docCache =
     max: 300,
     // ttl: 1,
     ttl: process.env.NODE_ENV === 'production' ? 1 : 1000000,
+    deleteOnStale: false,
   }))
 
 const pendingDocCache = new Map<string, Promise<unknown>>()
 
+export function getCached<T>(key: string): T | undefined {
+  if (!docCache.has(key)) {
+    return undefined
+  }
+
+  return docCache.get(key) as T
+}
+
+export function getStaleCached<T>(key: string): T | undefined {
+  return docCache.get(key, { allowStale: true }) as T | undefined
+}
+
+export async function fetchCachedWithStaleFallback<T>(opts: {
+  fn: () => Promise<T>
+  key: string
+  ttl: number
+  shouldFallbackToStale: (error: unknown) => boolean
+  onStaleFallback?: (error: unknown) => void
+}): Promise<T> {
+  const cached = getCached<T>(opts.key)
+
+  if (cached !== undefined) {
+    return cached
+  }
+
+  const pending = pendingDocCache.get(opts.key)
+
+  if (pending) {
+    return pending as Promise<T>
+  }
+
+  const resultPromise = opts
+    .fn()
+    .then((result) => {
+      docCache.set(opts.key, result, {
+        ttl: opts.ttl,
+      })
+
+      return result
+    })
+    .catch((error) => {
+      const stale = getStaleCached<T>(opts.key)
+
+      if (stale !== undefined && opts.shouldFallbackToStale(error)) {
+        opts.onStaleFallback?.(error)
+        return stale
+      }
+
+      throw error
+    })
+    .finally(() => {
+      pendingDocCache.delete(opts.key)
+    })
+
+  pendingDocCache.set(opts.key, resultPromise)
+
+  return resultPromise
+}
+
 export async function fetchCached<T>(opts: {
   fn: () => Promise<T>
   key: string

src/utils/config.ts

@@ -1,5 +1,8 @@
 import * as v from 'valibot'
-import { fetchRepoFile } from './documents.server'
+import {
+  fetchRepoFile,
+  isRecoverableGitHubContentError,
+} from './documents.server'
 import { createServerFn } from '@tanstack/react-start'
 import { setResponseHeaders } from '@tanstack/react-start/server'
 
@@ -48,6 +51,10 @@ const configSchema = v.object({
 
 export type ConfigSchema = v.InferOutput<typeof configSchema>
 
+const EMPTY_CONFIG: ConfigSchema = {
+  sections: [],
+}
+
 /**
   Fetch the config file for the project and validate it.
   */
@@ -56,7 +63,23 @@ export const getTanstackDocsConfig = createServerFn({ method: 'GET' })
     v.object({ repo: v.string(), branch: v.string(), docsRoot: v.string() }),
   )
   .handler(async ({ data: { repo, branch, docsRoot } }) => {
-    const config = await fetchRepoFile(repo, branch, `${docsRoot}/config.json`)
+    let config: string | null
+
+    try {
+      config = await fetchRepoFile(repo, branch, `${docsRoot}/config.json`)
+    } catch (error) {
+      if (isRecoverableGitHubContentError(error)) {
+        console.warn('[getTanstackDocsConfig] Falling back to empty config:', {
+          repo,
+          branch,
+          docsRoot,
+          message: error instanceof Error ? error.message : String(error),
+        })
+        return EMPTY_CONFIG
+      }
+
+      throw error
+    }
 
     if (!config) {
       throw new Error(`Repo's ${docsRoot}/config.json was not found!`)

src/utils/docs.ts

@@ -2,13 +2,57 @@ import {
   extractFrontMatter,
   fetchApiContents,
   fetchRepoFile,
+  isRecoverableGitHubContentError,
 } from '~/utils/documents.server'
 import removeMarkdown from 'remove-markdown'
 import { notFound } from '@tanstack/react-router'
 import { createServerFn } from '@tanstack/react-start'
 import * as v from 'valibot'
 import { setResponseHeader } from '@tanstack/react-start/server'
 
+const DOCS_UNAVAILABLE_TITLE = 'Content temporarily unavailable'
+
+function buildUnavailableDoc(filePath: string) {
+  return {
+    title: DOCS_UNAVAILABLE_TITLE,
+    description:
+      'This page could not be refreshed from GitHub right now. Please try again shortly.',
+    filePath,
+    content: [
+      '# Content temporarily unavailable',
+      '',
+      'This page could not be refreshed from GitHub right now.',
+      'Please try again shortly.',
+    ].join('\n'),
+    frontmatter: {
+      title: DOCS_UNAVAILABLE_TITLE,
+      description:
+        'This page could not be refreshed from GitHub right now. Please try again shortly.',
+    },
+  }
+}
+
+function buildUnavailableFile(filePath: string) {
+  const lowerFilePath = filePath.toLowerCase()
+  const isMarkdown = lowerFilePath.endsWith('.md')
+
+  if (isMarkdown) {
+    return [
+      '# Content temporarily unavailable',
+      '',
+      'This file could not be refreshed from GitHub right now.',
+      'Please try again shortly.',
+    ].join('\n')
+  }
+
+  return [
+    '// Content temporarily unavailable',
+    `// ${filePath}`,
+    '// This file could not be refreshed from GitHub right now.',
+    '// Please try again shortly.',
+  ].join('\n')
+}
+
 export const loadDocs = async ({
   repo,
   branch,
@@ -42,7 +86,23 @@ export const fetchDocs = createServerFn({ method: 'GET' })
     v.object({ repo: v.string(), branch: v.string(), filePath: v.string() }),
   )
   .handler(async ({ data: { repo, branch, filePath } }) => {
-    const file = await fetchRepoFile(repo, branch, filePath)
+    let file: string | null
+
+    try {
+      file = await fetchRepoFile(repo, branch, filePath)
+    } catch (error) {
+      if (isRecoverableGitHubContentError(error)) {
+        console.warn('[fetchDocs] Falling back to unavailable placeholder:', {
+          repo,
+          branch,
+          filePath,
+          message: error instanceof Error ? error.message : String(error),
+        })
+        return buildUnavailableDoc(filePath)
+      }
+
+      throw error
+    }
 
     if (!file) {
       throw notFound()
@@ -73,7 +133,23 @@ export const fetchFile = createServerFn({ method: 'GET' })
     v.object({ repo: v.string(), branch: v.string(), filePath: v.string() }),
   )
   .handler(async ({ data: { repo, branch, filePath } }) => {
-    const file = await fetchRepoFile(repo, branch, filePath)
+    let file: string | null
+
+    try {
+      file = await fetchRepoFile(repo, branch, filePath)
+    } catch (error) {
+      if (isRecoverableGitHubContentError(error)) {
+        console.warn('[fetchFile] Falling back to unavailable placeholder:', {
+          repo,
+          branch,
+          filePath,
+          message: error instanceof Error ? error.message : String(error),
+        })
+        return buildUnavailableFile(filePath)
+      }
+
+      throw error
+    }
 
     if (!file) {
       throw notFound()