Why

The universal reader is functionally correct but too slow in normal production use. On 2026-08-25, warmed repository routes measured about 0.3-0.5 seconds, while the two-minute application cache expired often enough that ordinary reads repeatedly paid 1.1-1.7 seconds of GitHub latency. A cold failure may wait for the full eight-second upstream timeout.

GitHub's unauthenticated REST allowance is also shared by Cloudflare egress. The reader must improve cache reuse without reusing any credential that could access private repositories.

What

In scope:

• Cache successful public GitHub subrequests through Cloudflare fetch, which is compatible with tiered caching.
• Keep the local Cache API as a fast transformed-data cache and safe stale copy, but extend its fresh lifetime.
• Use the smaller default GitHub media type for repository lists; reserve rendered HTML for issue bodies and comments.
• Fetch the issue and its comments concurrently.
• Shorten cold-failure time while retaining bounded retries and honest errors.
• Measure production before and after from the same client.

Out of scope:

• Private repositories, OAuth, privileged GitHub tokens, or D1 ingestion of arbitrary repository content.
• Client-side trust of unsanitized GitHub HTML.
• A new Cloudflare storage resource.

Design

flowchart LR
  R[Reader request] --> L{Local transformed cache}
  L -->|fresh| H[Render HTML]
  L -->|miss| F{Tiered fetch cache}
  F -->|hit| N[Normalize and sanitize]
  F -->|miss| G[GitHub public REST]
  G --> N
  N --> L
  L -->|transient failure| S[Last safe copy]

Cloudflare documents the Cache API as data-center-local and not compatible with tiered caching. The runtime fetch cache is therefore the shared upstream layer; the existing Cache API remains the local transformed representation and stale safety layer.

Specs

Requirement: Fast repeat reads

The universal reader SHALL avoid a GitHub network request for public data already cached within the configured freshness window.

Scenario: Repository was recently read

• WHEN another reader opens the same repository within the freshness window
• THEN IssuePages serves transformed cached data without waiting for GitHub

Requirement: Smaller repository reads

Repository lists SHALL request only the GitHub representation needed for summaries.

Scenario: Reader opens a repository index

• WHEN IssuePages fetches the issue list
• THEN it does not request rendered body HTML that the listing never displays

Requirement: Concurrent article hydration

Issue metadata and first-page comments SHALL be fetched concurrently on a cold article read.

Scenario: Issue has comments

• WHEN neither resource is cached
• THEN total upstream latency approaches the slower request rather than the sum of both requests

Requirement: Preserve trust boundaries

The optimization SHALL remain unauthenticated, read-only, noindex, bounded, sanitized, and separate from D1.

Scenario: GitHub is unavailable

• WHEN no safe cached representation exists
• THEN the reader fails within the shortened timeout and renders the existing retry experience

Tasks

• 1. Capture production baseline timings and identify local Cache API scope as the primary architecture gap.
• 2. Add tiered public GitHub fetch caching, longer transformed-data freshness, and shorter upstream timeout.
• 3. Reduce repository-list media/payload and parallelize issue/comment hydration.
• 4. Add cache policy, media type, concurrency, timeout, security, and stale-fallback regression coverage.
• 5. Run formatting, lint, typecheck, tests, build, and startup profiling.
• 6. Commit, push, obtain green current-SHA CI, deploy exact SHA, and compare production timings.