Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

11.1 KB
Raw Blame
// Server-only module: reads `process.env.GITHUB_TOKEN` and is imported only by
// the `/api/stargazers` route handler. Never import this from a client component.
import { formatStars } from "@/lib/github";

// Re-export so the /stars consumer can format counts without a second import.
export { formatStars };

/** A single stargazer keyframe — mirrors the registry `github-stars` component. */
export type Stargazer = {
  login: string;
  avatarUrl: string;
  /** ISO timestamp, e.g. "2021-03-04T11:22:33Z". */
  starredAt: string;
};

export type StargazersResult = {
  stargazers: Stargazer[];
  totalStars: number;
  /** True when the repo exceeds GitHub's ~400-page (~40k-star) listing ceiling. */
  truncated: boolean;
};

export type StargazersErrorCode =
  | "invalid_repo"
  | "not_found"
  | "rate_limited"
  | "fetch_failed";

/** Typed error so the route handler can map cleanly to a status + JSON code. */
export class StargazersError extends Error {
  readonly code: StargazersErrorCode;
  readonly status: number;
  constructor(code: StargazersErrorCode, message: string, status: number) {
    super(message);
    this.name = "StargazersError";
    this.code = code;
    this.status = status;
  }
}

/**
 * We only need ~60 keyframes spread across the repo's whole star history, so we
 * fetch a small, evenly-spaced SAMPLE of pages instead of every page — a handful
 * of requests regardless of repo size (this used to page through up to 5000
 * stargazers). GitHub won't list stargazers past ~page 400 (~40k stars); beyond
 * that the newest are unreachable → `truncated: true`.
 */
const SAMPLE_PAGES = 8;
const GITHUB_MAX_LISTABLE_PAGES = 400;
const PER_PAGE = 100;
// High enough to fetch every sampled page in a single parallel round.
const CONCURRENCY = 8;
/**
 * Keyframe cap — how many avatars the clip animates. Fewer avatars = far less
 * image loading + decoding in BOTH the Player preview and the MP4 render, which
 * is the dominant cost here. Kept ≤ the component's own downsample cap.
 */
const KEYFRAME_CAP = 40;
/**
 * GitHub avatars honor an `s=<px>` size query. Requesting ~120px (retina-safe for
 * the ~60px on-screen size) downloads ~5KB instead of the default ~50-100KB+
 * image — the single biggest win for preview load time and render speed.
 */
const AVATAR_SIZE = 120;
const API_BASE = "https://api.github.com";

// `parseRepoInput` lives in a client-safe module so the `/stars` client tool can
// validate input without importing this server-only file. Re-exported here so
// the route handler + tests keep their existing `@/lib/github-stargazers` import.
export { parseRepoInput } from "@/lib/parse-repo";

function buildHeaders(accept: string, withToken = true): HeadersInit {
  const headers: Record<string, string> = {
    Accept: accept,
    "X-GitHub-Api-Version": "2022-11-28",
  };
  const token = process.env.GITHUB_TOKEN;
  if (withToken && token) headers.Authorization = `Bearer ${token}`;
  return headers;
}

/**
 * Fetch a GitHub endpoint, transparently retrying WITHOUT the token when an
 * authenticated request is rejected on data that is publicly readable.
 *
 * Stargazers are always public, yet some tokens can't list them: a fine-grained
 * PAT scoped to another owner returns 403, and a classic PAT tied to an account
 * with restricted user-list visibility returns 404 on `/stargazers` (and
 * `/subscribers`). Unauthenticated requests succeed in every one of these cases,
 * so on 401/403/404 we re-issue the request without `Authorization`. The token
 * still raises the rate limit on every request GitHub does accept (e.g. the repo
 * endpoint that backs the landing-page star count).
 */
async function githubFetch(
  url: string,
  accept: string,
  signal?: AbortSignal,
): Promise<Response> {
  const res = await fetch(url, {
    headers: buildHeaders(accept),
    signal,
    next: { revalidate: 3600 },
  });
  if (
    process.env.GITHUB_TOKEN &&
    (res.status === 401 || res.status === 403 || res.status === 404)
  ) {
    return fetch(url, {
      headers: buildHeaders(accept, false),
      signal,
      next: { revalidate: 3600 },
    });
  }
  return res;
}

/** Map a non-OK GitHub response to a typed error (rate limit vs. not found). */
function errorForResponse(res: Response, context: string): StargazersError {
  if (res.status === 404) {
    return new StargazersError("not_found", "Repository not found.", 404);
  }
  const remaining = res.headers.get("x-ratelimit-remaining");
  if (res.status === 429 || (res.status === 403 && remaining === "0")) {
    return new StargazersError(
      "rate_limited",
      "GitHub API rate limit exceeded. Add a GITHUB_TOKEN to raise the limit.",
      429,
    );
  }
  return new StargazersError(
    "fetch_failed",
    `GitHub request failed (${context}): ${res.status} ${res.statusText}`,
    502,
  );
}

/** Pull the `rel="last"` page number out of a GitHub Link header, if any. */
function parseLastPage(link: string | null): number | null {
  if (!link) return null;
  for (const part of link.split(",")) {
    const match = part.match(/[?&]page=(\d+)[^>]*>\s*;\s*rel="last"/);
    if (match) return Number(match[1]);
  }
  return null;
}

type RawStargazer = {
  starred_at?: string;
  user?: { login?: string; avatar_url?: string } | null;
};

/** Append GitHub's `s=` size query for a much smaller avatar download. */
function withAvatarSize(url: string): string {
  return url.includes("?")
    ? `${url}&s=${AVATAR_SIZE}`
    : `${url}?s=${AVATAR_SIZE}`;
}

function mapEntry(raw: RawStargazer): Stargazer | null {
  const user = raw?.user;
  if (!user?.login || !user.avatar_url || !raw.starred_at) return null;
  return {
    login: user.login,
    avatarUrl: withAvatarSize(user.avatar_url),
    starredAt: raw.starred_at,
  };
}

/**
 * Evenly sample down to `max` keyframes, always keeping the first and last
 * entry. Replicated from the component's `downsampleStargazers` so the data
 * layer stays free of the `"use client"` registry module.
 */
function downsample(stargazers: Stargazer[], max = KEYFRAME_CAP): Stargazer[] {
  const len = stargazers.length;
  if (len <= max) return stargazers;
  if (max <= 1) return len ? [stargazers[0]] : [];
  const out: Stargazer[] = [];
  for (let i = 0; i < max; i++) {
    out.push(stargazers[Math.round((i * (len - 1)) / (max - 1))]);
  }
  return out;
}

/**
 * Evenly spaced page numbers across `[1..last]`, inclusive of the first (oldest
 * stargazers) and last (newest) page, de-duplicated. For small repos
 * (`last <= count`) this is simply every page.
 */
function samplePageNumbers(last: number, count: number): number[] {
  if (last <= count) {
    return Array.from({ length: last }, (_, i) => i + 1);
  }
  const pages = new Set<number>();
  for (let i = 0; i < count; i++) {
    pages.add(1 + Math.round((i * (last - 1)) / (count - 1)));
  }
  return [...pages].sort((a, b) => a - b);
}

/** Run `fn` over `items` with a bounded number of in-flight requests. */
async function mapWithConcurrency<T, R>(
  items: T[],
  limit: number,
  fn: (item: T) => Promise<R>,
): Promise<R[]> {
  const results = new Array<R>(items.length);
  let cursor = 0;
  const workers = Array.from(
    { length: Math.min(limit, items.length) },
    async () => {
      while (cursor < items.length) {
        const index = cursor++;
        results[index] = await fn(items[index]);
      }
    },
  );
  await Promise.all(workers);
  return results;
}

async function fetchStargazerPage(
  owner: string,
  repo: string,
  page: number,
  signal?: AbortSignal,
): Promise<{ entries: RawStargazer[]; link: string | null }> {
  const url = `${API_BASE}/repos/${owner}/${repo}/stargazers?per_page=${PER_PAGE}&page=${page}`;
  let res: Response;
  try {
    res = await githubFetch(url, "application/vnd.github.star+json", signal);
  } catch (err) {
    if (err instanceof StargazersError) throw err;
    throw new StargazersError(
      "fetch_failed",
      `Network error fetching stargazers page ${page}.`,
      502,
    );
  }
  if (!res.ok) throw errorForResponse(res, `stargazers page ${page}`);
  const entries = (await res.json()) as RawStargazer[];
  return { entries, link: res.headers.get("link") };
}

/**
 * Fetch a repository's stargazers with `starred_at` timestamps, sorted oldest
 * → newest and downsampled to a small keyframe set for the animation.
 *
 * - Uses `Accept: application/vnd.github.star+json` (required for `starred_at`).
 * - Sends `Authorization: Bearer ${GITHUB_TOKEN}` only when the env var is set;
 *   works unauthenticated (60/hr) too.
 * - Reads the page count from the first response's Link header, then fetches a
 *   small evenly-spaced SAMPLE of pages (including the newest) in parallel — fast
 *   regardless of repo size. `truncated: true` only when GitHub can't list past
 *   its ~40k-star ceiling.
 * - Throws {@link StargazersError} for not-found / rate-limited / fetch failures.
 */
export async function fetchStargazers({
  owner,
  repo,
  signal,
}: {
  owner: string;
  repo: string;
  signal?: AbortSignal;
}): Promise<StargazersResult> {
  // 1. Repo endpoint → existence check (404) + authoritative star total.
  let repoRes: Response;
  try {
    repoRes = await githubFetch(
      `${API_BASE}/repos/${owner}/${repo}`,
      "application/vnd.github+json",
      signal,
    );
  } catch (err) {
    if (err instanceof StargazersError) throw err;
    throw new StargazersError(
      "fetch_failed",
      "Network error fetching repository.",
      502,
    );
  }
  if (!repoRes.ok) throw errorForResponse(repoRes, "repo");
  const repoData = (await repoRes.json()) as {
    stargazers_count?: number;
  };
  const totalStars =
    typeof repoData.stargazers_count === "number"
      ? repoData.stargazers_count
      : 0;

  // 2. Zero-star repo: nothing to paginate, render gracefully.
  if (totalStars === 0) {
    return { stargazers: [], totalStars: 0, truncated: false };
  }

  // 3. First page drives the page count via its Link header.
  const first = await fetchStargazerPage(owner, repo, 1, signal);
  const lastPage = parseLastPage(first.link) ?? 1;
  const listableLast = Math.min(lastPage, GITHUB_MAX_LISTABLE_PAGES);
  // "truncated" only when GitHub itself can't list the newest stargazers (repos
  // beyond its ~40k-star ceiling); a normal sample still spans first → last.
  const truncated = lastPage > GITHUB_MAX_LISTABLE_PAGES;

  const rawEntries: RawStargazer[] = [...first.entries];

  // 4. Fetch a small, evenly-spaced SAMPLE of the remaining pages in parallel —
  //    enough to span the whole history (including the genuine newest page)
  //    without paging through thousands of stargazers we'd only downsample away.
  const samplePages = samplePageNumbers(listableLast, SAMPLE_PAGES).filter(
    (p) => p !== 1,
  );
  if (samplePages.length) {
    const pageResults = await mapWithConcurrency(
      samplePages,
      CONCURRENCY,
      (page) => fetchStargazerPage(owner, repo, page, signal),
    );
    for (const result of pageResults) rawEntries.push(...result.entries);
  }

  // 5. Map → filter → sort ascending by starredAt → downsample.
  const mapped = rawEntries
    .map(mapEntry)
    .filter((s): s is Stargazer => s !== null)
    .sort((a, b) => a.starredAt.localeCompare(b.starredAt));

  const stargazers = downsample(mapped);

  return { stargazers, totalStars, truncated };
}