feat(code.gs): optional spreadsheet-backed response cache with TTL

[euvel]

Summary

Adds an optional spreadsheet-backed response caching layer to Code.gs that reduces UrlFetchApp quota consumption by serving repeat public GET requests from a Google Sheet.

All five review suggestions from the discussion thread are addressed:

• TTL-aware caching — _parseMaxAge() reads Cache-Control: max-age, respects no-cache/no-store/private, stores an Expires_At column, and skips expired entries on lookup. Falls back to 24 hours when no Cache-Control header is present.
• 35 KB body-size gate — CACHE_MAX_BODY_BYTES = 35000 prevents hitting the 50,000-character Sheets cell limit. Oversized responses are returned to the user but skipped for storage.
• Header rewriting on cache hit — Date, Age, and Cache-Control are recalculated to reflect time-since-cache. Original Cache-Control is preserved in X-Original-Cache-Control. Diagnostic headers X-Cache: HIT from relay-spreadsheet and X-Cached-At are added.
• Circular buffer (O(1) writes) — A hidden RelayMeta sheet tracks a write cursor that wraps at CACHE_MAX_ROWS. Replaces appendRow / deleteRows, eliminating reindexing overhead.
• Vary-aware compound cache keys — Accept-Encoding and Accept-Language are hashed alongside the URL using case-insensitive matching and whitespace normalization. Covers ~95% of real-world Vary usage without inspecting the response.

Design Discussion

See this issue thread for full discussion and reviewer feedback.

Configuration

Opt-in via a single constant at the top of Code.gs:

const CACHE_SPREADSHEET_ID = "YOUR_SPREADSHEET_ID_HERE";

Leave as-is to disable caching entirely — zero overhead, no behavioral change for existing deployments.

How to Test

1. Create a new Google Sheet and copy its ID from the URL
2. Set CACHE_SPREADSHEET_ID to that ID in Code.gs
3. Deploy as a new Web App (Deploy -> New deployment)
4. Use the proxy to browse a few sites
5. Open the spreadsheet — the RelayCache sheet will populate with cached responses
6. Run getCacheStats() from the Apps Script editor to view stats

Breaking Changes

None. The cache is off by default.

[therealaleph]

Merged + included in v1.8.3 (just tagged). Builds clean, all 160 tests pass on main. Thanks for shipping this — exactly the kind of contribution that scales the project beyond what one maintainer can ship alone.

v1.8.3 release page: https://github.com/therealaleph/MasterHttpRelayVPN-RUST/releases/tag/v1.8.3

Telegram channel announcement: https://t.me/mhrv_rs (will fire once release CI completes)

Will tag you on the v1.9.0 xmux design issue when drafted (~1-2 weeks).

---

_{[reply via Anthropic Claude | reviewed by @therealaleph]}