Edge Caching for Web Services – Render Docs
Render provides edge caching for static assets (documents, images, etc.) served by paid web services. With edge caching enabled, you can speed up response times and reduce load on your web service:
Edge caching is powered by the same global CDN as Render static sites.
Setup
Edge caching is not available for free web services.
In the Render Dashboard, open your web service's Settings page and scroll down to the Edge Caching section:
Under Cacheable file types, click the dropdown and select an option:
| Option | Description |
|---|---|
| None | Disables edge caching. All assets are served from your web service. This is the default option. |
| Common static files | Unless overridden by a Cache-Control header, Render caches assets with the following file types:7z``avi``avif``bin``bmp``bz2``class``css``csv``dmg``doc``docx``eot``ejs``eps``exe``flac``gif``gz``ico``iso``jar``jpeg``jpg``js``mid``midi``mkv``mp3``mp4``ogg``otf``pdf``pict``pls``png``ppt``pptx``ps``rar``svg``svgz``swf``tar``tif``tiff``ttf``webm``webp``woff``woff2``xls``xlsx``zip``zstOther file types are never cached, regardless of Cache-Control headers. |
| All files | Unless overridden by a Cache-Control header, all of your service's eligible responses are cached, regardless of file type. This might include dynamic content.If you use this option, make sure to set Cache-Control headers for dynamically generated content to prevent it from being cached. Otherwise, you might serve the wrong version of that content to clients. |
- After you select an option, a confirmation dialog appears. Review and Confirm the notices, then click Save changes.
You're all set! Render begins caching your web service's cache-eligible responses.
How edge caching works
Whenever a client sends an HTTP request to your cache-enabled web service, Render determines whether the request is eligible to serve from the edge cache. (For details, see Cache eligibility.)
If the request is cache-eligible, Render checks the edge cache for the corresponding resource.
- If the requested resource is in the cache (and the entry isn't stale), Render serves the cached version:
In this case, the request never reaches your web service. This speeds up the response and reduces load.
- Otherwise, Render fetches the resource from your web service and—if it's also cache-eligible—caches it for future requests:
Cache eligibility
When serving a request from your web service, Render uses the following logic to determine whether the response can be cached for future requests:
Yep!
Nope, some other
HTTP method.
Yep!
Nope.
Yep!
Header is
not present.
Header is present, but
it disallows caching.
Yep!
Nope.
Is the request method
either GET or HEAD? Does the asset have a
cacheable file type?**
Does the response include a Cache-Control header that allows caching? Is the HTTP status code
cacheable by default?**
❌
Response is not cache-eligible.
✅
Response is
cache-eligible!
* See details below. To summarize, all of the following must be true for a response to be cache-eligible:
- The originating request must use the
GETorHEADHTTP method. - The requested resource must have a cacheable file type based on your settings.
- The response must either include a
Cache-Controlheader that allows caching or have a default-cacheable status code. - Additionally, the response must not include a
Set-Cookieheader.
Cacheable file types
When you enable edge caching for your web service, you select one of the following options for Cacheable file types:
| Option | Description |
|---|---|
| Common static files | Unless overridden by a Cache-Control header, Render caches assets with the following file types:7z``avi``avif``bin``bmp``bz2``class``css``csv``dmg``doc``docx``eot``ejs``eps``exe``flac``gif``gz``ico``iso``jar``jpeg``jpg``js``mid``midi``mkv``mp3``mp4``ogg``otf``pdf``pict``pls``png``ppt``pptx``ps``rar``svg``svgz``swf``tar``tif``tiff``ttf``webm``webp``woff``woff2``xls``xlsx``zip``zstOther file types are never cached, regardless of Cache-Control headers. |
| All files | Unless overridden by a Cache-Control header, all of your service's eligible responses are cached, regardless of file type. This might include dynamic content.If you use this option, make sure to set Cache-Control headers for dynamically generated content to prevent it from being cached. Otherwise, you might serve the wrong version of that content to clients. |
Default-cacheable status codes
If your web service returns a cache-eligible response without a Cache-Control header, Render caches the response if it has one of the following status codes (and applies the corresponding default TTL):
| Status code | Default TTL |
|---|---|
| 200, 206, 301 | 120 minutes |
| 302, 303 | 20 minutes |
| 404, 410 | 3 minutes |
Invalidation and expiration
To help ensure that clients receive up-to-date content, Render invalidates edge cache entries in the following scenarios:
| Scenario | Description |
|---|---|
| New deploys | Each time you successfully deploy a new version of your web service, Render purges all of the service's edge cache entries. This way, the cache doesn't serve stale content from the service's previous version. Render waits until all of the previous version's instances have shut down before purging the cache (learn more about zero-downtime deploys). Failed deploys do not trigger a purge. Purging the cache might briefly increase your web service's request volume, but only slightly. See details. |
| TTL expiration | Each cache entry has a corresponding time-to-live (TTL). When an entry's TTL expires, the entry is considered stale. The next request for a stale entry is sent to your web service, which refreshes the entry. |
| Manual purge | You can trigger a cache purge for your web service from its Settings page in the Render Dashboard: As with a new deploy, this purges all of your web service's associated edge cache entries. Purging the cache might briefly increase your web service's request volume, but only slightly. See details. |
Load protection on cache purge
Whenever you purge your web service's edge cache (either manually or by triggering a new deploy), Render's CDN automatically protects your web service from receiving a sudden influx of requests.
If multiple clients request the same uncached resource, Render's CDN forwards only one of those requests along to your web service. The CDN caches your web service's response, then serves it to all waiting clients. This pattern is called request collapsing.
Your web service might experience a brief traffic increase after a cache purge, but thanks to request collapsing, the size of that increase is roughly equal to the number of unique resources being requested. This is usually a small fraction of your service's total request volume.
Setting Cache-Control headers
You can customize Render's edge caching behavior for a particular resource by including a Cache-Control (or CDN-Cache-Control) header in your web service's response:
httpCopy to clipboard
Cache-Control: public, max-age=7200
New to cache control headers?
Learn more about supported response directives.
| Customization | Description |
|---|---|
| Set a TTL (time-to-live) | Do both of the following in your response's Cache-Control header:- Include the public directive.- Set the max-age or s-maxage directive to a value greater than 0.httpCopy to clipboard http<br>Cache-Control: public, max-age=3600<br> |
| Disable caching | Do either of the following in your response's Cache-Control header:- Include the no-store directive to prevent storage in all caches.- Include private, max-age=0, no-transform to prevent storage in the edge cache while allowing browser storage with revalidation.httpCopy to clipboard http<br>Cache-Control: private, max-age=0, no-transform<br> |
| Set revalidation behavior | Include a combination of the must-revalidate, stale-while-revalidate, and stale-if-error directives.httpCopy to clipboard http<br>Cache-Control: stale-while-revalidate=60, stale-if-error=3600, public, max-age=1200<br> |
Precedence rules
Render applies the following precedence rules to cache control headers:
- The
CDN-Cache-Controlheader takes precedence over theCache-Controlheader if both are present. - The
s-maxagedirective takes precedence over themax-agedirective if both are present.
Inspecting cache behavior
Each response from a cache-enabled web service includes a CF-Cache-Status header:
httpCopy to clipboard
CF-Cache-Status: HIT
The value of this header indicates whether the response interacted with the edge cache and in what way. The most common values are:
| Value | Description |
|---|---|
HIT |
The response was served from the edge cache. |
MISS |
The response was not found in the edge cache. It was served from your web service and cached if eligible. |
DYNAMIC |
Some element of the incoming HTTP request was not cache-eligible, and the response was served from your web service. Most commonly indicates one of the following: - The request used an HTTP method other than GET or HEAD.- The requested resource did not have a cacheable file type based on your settings. |
EXPIRED |
The response was found in the edge cache, but its TTL had expired. It was served from your web service and the edge cache was updated with the new response. |
BYPASS |
The response was served directly from your web service and was not stored in the edge cache, usually for one of the following reasons: - The response included a Cache-Control header that disabled caching.- The response did not include a Cache-Control header, and it returned a status code that is not default-cacheable.- The response included a Set-Cookie header. |