How RenderCache works

RenderCache sits between crawler requests and a fixed origin. A normal visitor receives the original application. A matching crawler request can receive an eligible saved response from disk. User agents are configurable routing claims; they are not authenticated bot identities.

Start with the sitemap

The service discovers pages from your sitemap and schedules missing or expired snapshots through a bounded queue. Chrome loads each page on the configured origin, waits for a readiness selector or a settling delay, and captures the rendered document. The snapshot preserves structured data while removing executable scripts and inline event handlers. Chrome is an external process; the Go executable does not contain a browser.

Only public, unauthenticated content belongs in the shared cache. Render jobs do not inherit visitor cookies or authorization. Private, no-store, cookie-setting, 401 and 403 outcomes withdraw an old shared copy; ordinary render failures keep a usable older snapshot and retry with backoff. The browser’s allowed HTTP destinations are constrained, but host isolation and Chrome’s sandbox remain part of deployment.

HIT, STALE and MISS

A fresh saved response returns X-RenderCache: HIT. An expired copy returns STALE while refresh work is deduplicated in the background. A cold MISS proxies the origin and requests background rendering; it does not make that crawler wait for Chrome. That fallback can still be an empty JavaScript shell, which is why checking warm coverage matters.

Snapshots also preserve redirects and 404/410 removal responses. Eligible HTML GET and HEAD requests support validators, including 304 replies. Cookies, authorization, APIs, assets, ranges and unsuitable request methods bypass shared snapshots and preserve origin behavior. The protected purge API requests a refresh without first deleting a good copy.

Know what left the server

Rotating JSON receipts record a bounded crawler claim, path without query strings, method, status, cache outcome, snapshot age, body bytes accepted by the response writer, and duration. Cached availability and full snapshot HTML delivery are separate fields. A HEAD request can hit the cache and still deliver no HTML body. A partial write cannot be reported as a full snapshot.

These are server-side receipts. They do not prove that a remote client read the response, that its user agent was genuine, or that a search engine or AI service indexed or cited the page. Paths can still contain sensitive information; protect access to the logs.

Keep operations small and explicit

One process owns the local data directory. Serialized snapshot bytes and file counts have quotas; an over-quota refresh preserves the existing record. There is no automatic eviction. The offline prune command removes recognized old records when you choose to reclaim space. Browser concurrency, public requests, connections and output sizes are bounded; use OS or container limits for browser memory, processes and temporary files.

Run the alpha or read the deployment guidance.