fix(updater): bypass cache for encoded file fallbacks

[riderx]

Summary (AI generated)

• Bypass the file endpoint cache when a request has same-app decoded/raw percent-encoded route fallback candidates.
• Keep normal file download URLs on the existing cache path.
• Add unit coverage proving cache bypass only applies to safe same-app encoded fallback paths.

Motivation (AI generated)

PR #2247 fixes the manifest/path mismatch, but an already cached bad response for an encoded file URL could still be returned before the worker checks R2. This follow-up makes affected encoded fallback requests ignore the file cache and read directly from the safe decoded/raw R2 candidates.

Business Impact (AI generated)

Customers do not need to re-upload, publish a native release, or wait for new CLI adoption for the already fixed uploads to begin working after deploy. Normal file URLs keep the existing cache behavior, so cache and performance impact is limited to special-character fallback requests that need this protection.

Test Plan (AI generated)

• bunx vitest run tests/manifest-path-encoding.unit.test.ts tests/upload-path-encoding.unit.test.ts
• bun lint:backend
• bun typecheck
• git diff --check origin/main...HEAD

Generated with AI

Summary by CodeRabbit

Release Notes

• New Features

  • Attachment cache now conditionally bypasses caching for certain files, enabling more flexible content delivery based on file identifiers.

• Tests

  • Added test coverage for cache bypass behavior across different file path scenarios.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 636315e1-f344-4c90-8b4d-d5c11de1c586

📥 Commits

Reviewing files that changed from the base of the PR and between 9918530 and 5705e51.

📒 Files selected for processing (3)

• supabase/functions/_backend/files/files.ts
• supabase/functions/_backend/files/util.ts
• tests/upload-path-encoding.unit.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds a cache-bypass decision mechanism for attachment reads. When an attachment has multiple candidate read keys, the handler skips both cache lookups and cache writes, optionally logging the bypass decision. Otherwise, the handler serves cached responses and persists newly fetched responses to cache, with a best-effort background restore to R2 if the object is missing.

Changes

Attachment cache bypass mechanism

Layer / File(s)	Summary
Cache bypass utility and validation supabase/functions/_backend/files/util.ts, tests/upload-path-encoding.unit.test.ts	New shouldBypassAttachmentCache(decodedKey, rawRouteKey) helper returns whether safe candidate read keys exceed one, indicating cache should be bypassed. Tests validate bypass behavior for same-app and cross-app decoded/raw percent-encoded fallback scenarios.
Handler cache bypass integration supabase/functions/_backend/files/files.ts	Handler imports the bypass utility and applies it to conditionally skip cache reads (cache.match) and cache writes (cache.put) in the attachment read flow. When bypass is enabled, the handler logs the event and always fetches from upstream; when disabled, prior caching behavior is retained.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Cap-go/capgo#2247: Both PRs modify the attachment read flow in supabase/functions/_backend/files by handling decoded vs raw percent-encoded candidate key selection (this PR adds cache-bypass gating; related PR centralizes candidate-key selection).
• Cap-go/capgo#2057: Both PRs guard attachment read behavior with conditional logic based on request attributes (added guarded/signed read logic; this PR adds cache-bypass handling).

Poem

🐰 A clever cache now knows when to skip,
Multiple keys? Then let data whip!
Bypass the store, fetch fresh and fleet,
When fallbacks abound, the upstream's sweet. ✨

🚥 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
Title check	✅ Passed	The title clearly and concisely describes the main change: implementing cache bypass for encoded file fallbacks, which is the primary focus of this changeset.
Description check	✅ Passed	The description includes a summary explaining the change, motivation, business impact, and a detailed test plan, fulfilling the template requirements. However, it lacks the standard checklist section from the template.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/bypass-cache-encoded-file-fallbacks

---

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 43 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing codex/bypass-cache-encoded-file-fallbacks (5705e51) with main (9918530)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud