perf: serve stale sponsors when github is unavailable

Author: LadyBluenotes

src/server/github.ts

@@ -1,6 +1,116 @@
 import { graphql } from '@octokit/graphql'
 import { env } from '~/utils/env'
 
+export type GitHubApiErrorKind =
+  | 'rate_limited'
+  | 'forbidden'
+  | 'unauthorized'
+  | 'upstream'
+  | 'unknown'
+
+export class GitHubApiError extends Error {
+  kind: GitHubApiErrorKind
+  status?: number
+  resetAt?: Date
+
+  constructor(opts: {
+    message: string
+    kind: GitHubApiErrorKind
+    status?: number
+    resetAt?: Date
+  }) {
+    super(opts.message)
+    this.name = 'GitHubApiError'
+    this.kind = opts.kind
+    this.status = opts.status
+    this.resetAt = opts.resetAt
+  }
+}
+
+function getHeader(
+  headers: Record<string, string> | undefined,
+  key: string,
+): string | undefined {
+  if (!headers) return undefined
+
+  const loweredKey = key.toLowerCase()
+  const entry = Object.entries(headers).find(
+    ([headerKey]) => headerKey.toLowerCase() === loweredKey,
+  )
+
+  return entry?.[1]
+}
+
+function parseRateLimitReset(headers: Record<string, string> | undefined) {
+  const resetHeader = getHeader(headers, 'x-ratelimit-reset')
+
+  if (!resetHeader) return undefined
+
+  const epochSeconds = Number.parseInt(resetHeader, 10)
+  if (Number.isNaN(epochSeconds)) return undefined
+
+  return new Date(epochSeconds * 1000)
+}
+
+export function normalizeGitHubApiError(error: unknown, context: string) {
+  const status =
+    typeof error === 'object' && error && 'status' in error
+      ? Number(error.status)
+      : undefined
+  const responseHeaders =
+    typeof error === 'object' && error && 'response' in error
+      ? (error.response as { headers?: Record<string, string> }).headers
+      : undefined
+  const message =
+    error instanceof Error ? error.message : `${context} failed`
+
+  if (status === 401) {
+    return new GitHubApiError({
+      kind: 'unauthorized',
+      status,
+      message: `${context} was unauthorized`,
+    })
+  }
+
+  if (status === 403 && getHeader(responseHeaders, 'x-ratelimit-remaining') === '0') {
+    const resetAt = parseRateLimitReset(responseHeaders)
+    return new GitHubApiError({
+      kind: 'rate_limited',
+      status,
+      resetAt,
+      message: resetAt
+        ? `${context} hit the GitHub rate limit until ${resetAt.toISOString()}`
+        : `${context} hit the GitHub rate limit`,
+    })
+  }
+
+  if (status === 403) {
+    return new GitHubApiError({
+      kind: 'forbidden',
+      status,
+      message: `${context} was forbidden`,
+    })
+  }
+
+  if (typeof status === 'number' && status >= 500) {
+    return new GitHubApiError({
+      kind: 'upstream',
+      status,
+      message: `${context} failed with GitHub ${status}`,
+    })
+  }
+
+  return new GitHubApiError({
+    kind: 'unknown',
+    status,
+    message,
+  })
+}
+
+export function isRecoverableGitHubApiError(error: unknown) {
+  return error instanceof GitHubApiError
+}
+
 export const graphqlWithAuth = graphql.defaults({
   headers: {
     authorization: `token ${env.GITHUB_AUTH_TOKEN}`,

src/server/sponsors.ts

@@ -1,5 +1,9 @@
-import { fetchCached } from '~/utils/cache.server'
-import { graphqlWithAuth } from '~/server/github'
+import { fetchCachedWithStaleFallback } from '~/utils/cache.server'
+import {
+  graphqlWithAuth,
+  isRecoverableGitHubApiError,
+  normalizeGitHubApiError,
+} from '~/server/github'
 import { createServerFn } from '@tanstack/react-start'
 import { setResponseHeaders } from '@tanstack/react-start/server'
 import sponsorMetaData from '~/utils/gh-sponsor-meta.json'
@@ -24,15 +28,35 @@ export type Sponsor = {
   createdAt: string
 }
 
+const SPONSOR_CACHE_TTL_MS = process.env.NODE_ENV === 'development' ? 1 : 5 * 60 * 1000
+
 export const getSponsorsForSponsorPack = createServerFn({
   method: 'GET',
 }).handler(async () => {
-  const sponsors = await fetchCached({
-    key: 'sponsors',
-    // ttl: process.env.NODE_ENV === 'development' ? 1 : 60 * 60 * 1000,
-    ttl: 60 * 1000,
-    fn: getSponsors,
-  })
+  let sponsors: Sponsor[]
+
+  try {
+    sponsors = await fetchCachedWithStaleFallback({
+      key: 'sponsors',
+      ttl: SPONSOR_CACHE_TTL_MS,
+      fn: getSponsors,
+      shouldFallbackToStale: isRecoverableGitHubApiError,
+      onStaleFallback: (error) => {
+        console.warn('[getSponsorsForSponsorPack] Serving stale sponsors after GitHub failure:', {
+          message: error instanceof Error ? error.message : String(error),
+        })
+      },
+    })
+  } catch (error) {
+    if (isRecoverableGitHubApiError(error)) {
+      console.warn('[getSponsorsForSponsorPack] Falling back to metadata-only sponsors:', {
+        message: error.message,
+      })
+      sponsors = await getSponsorsFromMetadataOnly()
+    } else {
+      throw error
+    }
+  }
 
   // In recent @tanstack/react-start versions, getEvent is no longer exported.
   // Headers can be set unconditionally here; framework will merge appropriately.
@@ -58,14 +82,12 @@ export const getSponsorsForSponsorPack = createServerFn({
     }))
 })
 
-export async function getSponsors() {
-  const [sponsors, sponsorsMeta] = await Promise.all([
-    getGithubSponsors(),
-    getSponsorsMeta(),
-  ])
-
+function mergeSponsorsWithMetadata(
+  sponsors: Sponsor[],
+  sponsorsMeta: SponsorMeta[],
+) {
   sponsorsMeta.forEach((sponsorMeta: SponsorMeta) => {
-    const matchingSponsor = sponsors.find((d) => d.login == sponsorMeta.login)
+    const matchingSponsor = sponsors.find((d) => d.login === sponsorMeta.login)
 
     if (matchingSponsor) {
       Object.assign(matchingSponsor, {
@@ -95,6 +117,19 @@ export async function getSponsors() {
   return sponsors
 }
 
+export async function getSponsors() {
+  const [sponsors, sponsorsMeta] = await Promise.all([
+    getGithubSponsors(),
+    getSponsorsMeta(),
+  ])
+
+  return mergeSponsorsWithMetadata(sponsors, sponsorsMeta)
+}
+
+async function getSponsorsFromMetadataOnly() {
+  return mergeSponsorsWithMetadata([], await getSponsorsMeta())
+}
+
 async function getGithubSponsors() {
   let sponsors: Sponsor[] = []
   try {
@@ -205,35 +240,8 @@ async function getGithubSponsors() {
     await fetchPage()
 
     return sponsors
-  } catch (err) {
-    const error = err as { status?: number }
-    if (error.status === 401) {
-      console.error('Missing github credentials, returning mock data.')
-      return [
-        'tannerlinsley',
-        'tkdodo',
-        'crutchcorn',
-        'kevinvandy',
-        'jherr',
-        'seancassiere',
-        'schiller-manuel',
-      ].flatMap((d) =>
-        new Array(20).fill(d).map((_, i2) => ({
-          login: d,
-          name: d,
-          amount: (20 - i2) / 20 + Math.random(),
-          createdAt: new Date().toISOString(),
-          private: false,
-          linkUrl: `https://github.com/${d}`,
-          imageUrl: `https://github.com/${d}.png`,
-        })),
-      )
-    }
-    if (error.status === 403) {
-      console.error('GitHub rate limit exceeded, returning empty sponsors.')
-      return []
-    }
-    throw err
+  } catch (error) {
+    throw normalizeGitHubApiError(error, 'Fetching GitHub sponsors')
   }
 }