Avoid caching temporary docs fallbacks

[tannerlinsley]

Evidence

PR #1167 raised the latest docs edge policy from 60 seconds to one hour plus 24 hours of stale-while-revalidate. Its review identified that readRepoFileOrFallback returns a 200 “Content temporarily unavailable” placeholder for recoverable GitHub failures, and both fetchDocs and fetchFile applied the normal cache policy without knowing the response was a fallback.

That can retain an outage placeholder at the edge for up to 25 hours after GitHub recovers.

Change

Track whether repository content came from the recoverable fallback. Normal documents keep their existing cache policy; fallback HTML and raw-file responses now send Cache-Control: no-store and Cloudflare-CDN-Cache-Control: no-store.

Follow-up to #1167.

Impact

A transient GitHub failure can still render the existing graceful placeholder, but the next request retries instead of receiving a cached outage page.

Validation

• pnpm test
• TypeScript and type-aware lint clean
• 338 tests total: 337 passed, 1 environment-gated docs smoke test skipped
• Commit hook reran formatting and the full test gate successfully
• git diff --check

Risk

Low. Successful docs responses retain the cache durations introduced by #1167. Only recoverable fallback responses change caching behavior.

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of temporary documentation-service failures.
  • Prevented unavailable fallback content from being cached, so later requests can retry successfully.
  • Preserved existing caching behavior when documentation is retrieved successfully.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 06e8e305-0951-4221-a104-2af5f726a08f

📥 Commits

Reviewing files that changed from the base of the PR and between b48f153 and e8b7ba4.

📒 Files selected for processing (1)

• src/utils/docs.functions.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Repository file reads now return content with fallback status. fetchDocs and fetchFile disable caching for fallback responses and retain existing cache durations for successful responses.

Changes

Fallback-aware caching

Layer / File(s)	Summary
Fallback status and cache policy src/utils/docs.functions.ts	readRepoFileOrFallback returns the file and an isFallback flag. fetchDocs uses no-store for fallback content and one-hour caching for normal content. fetchFile uses no-store for fallback content and five-minute caching for normal content.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to e8b7b

Fallback documentation responses are no longer cached, while successful responses retain their existing cache behavior; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• TanStack/tanstack.com#1167: Both changes modify fetchDocs caching behavior in src/utils/docs.functions.ts.

Suggested reviewers: ladybluenotes, tombeckenham

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing temporary documentation fallback responses from being cached.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/prevent-docs-fallback-cache

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	e8b7ba4	Commit Preview URL Branch Preview URL	Aug 19 2026, 02:09 PM