CDN cache
Every public HTTP project goes through the CDN included with Zenifra. The CDN keeps copies of static files close to the visitor, so those files arrive faster and the instance stays free to answer everything else. Your application decides how long each file stays cached, through the Cache-Control header.
What is cached
| Response | Cached by the CDN? |
|---|---|
| Static file (list below) with status 200 | Yes, for the time set by the application or the default |
HTML, APIs and any path without an extension (/, /products, /api/orders) | No. It always reaches the application, even with Cache-Control: public |
| Status 404 | No. A file that does not exist yet during a deploy does not get stuck |
Response with Cache-Control: no-store or private | No |
Response that sends Set-Cookie | No |
POST, PUT, PATCH and DELETE requests | No |
Extensions treated as static files: 7z, avi, avif, apk, bin, bmp, bz2, class, css, csv, doc, docx, dmg, ejs, eot, eps, exe, flac, gif, gz, ico, iso, jar, jpg, jpeg, 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, zst.
The full URL, including the query string, identifies the copy. /app.js?v=1 and /app.js?v=2 are cached separately.
Warning: the CDN does not tell users apart. A request with
Authorizationor a session cookie receives the same cached copy of a static file. Do not serve private content on paths with these extensions; if you must, respond withCache-Control: privateorno-store.
Default time
When a static file has no Cache-Control, the CDN keeps it for 2 hours. In that case Zenifra does not send Cache-Control to the browser, which follows its own default behavior.
How to change the cache time
Send the Cache-Control header from the application (in the framework, middleware or web server). The CDN follows the application's value:
| Header sent by the application | At the CDN | In the browser |
|---|---|---|
Cache-Control: public, max-age=31536000, immutable | 1 year | 1 year |
Cache-Control: public, max-age=60 | 60 seconds | 60 seconds |
Cache-Control: public, max-age=3600, s-maxage=60 | 60 seconds (s-maxage applies to the CDN) | 1 hour |
Cache-Control: public, max-age=3600 + CDN-Cache-Control: max-age=60 | 60 seconds (CDN-Cache-Control does not reach the browser) | 1 hour |
Cache-Control: public, max-age=60, stale-while-revalidate=300 | 60 seconds; after that, serves the old copy right away and fetches the new one in the background | 60 seconds |
Cache-Control: no-cache or max-age=0 | Stored, but checks the application on every request | Revalidates on every use |
Cache-Control: no-store or private | Not stored | no-store: not stored; private: only the browser stores it |
Express example:
// Files with a hash in the name: long cache
app.use('/assets', express.static('dist/assets', { maxAge: '1y', immutable: true }))
// File that changes without a new name: 5 minutes at the CDN and in the browser
app.get('/widget.js', (req, res) => {
res.set('Cache-Control', 'public, max-age=300')
res.sendFile('widget.js', { root: 'public' })
})Nginx example:
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
}Latency difference
A cached response leaves the CDN location closest to the visitor. Without cache, the request has to reach the application, and the time grows with distance. Time to first byte measured for the same project in November 2026:
| Visitor in | Cached | Not cached |
|---|---|---|
| São Paulo | ~26 ms | ~51 ms |
| Porto Alegre | ~34 ms | ~68 ms |
| Fortaleza | ~8 ms | ~74 ms |
| Miami (USA) | ~40 ms | ~510 ms |
| Frankfurt (Germany) | ~48 ms | ~900 ms |
That is why a long cache is worth it for static files with versioned names.
Ship a new version and invalidate the cache
A new deploy, a restart or an image change does not clear the CDN cache. Until the cache time ends, visitors may receive the previous version of a file that kept the same name. There is no console or API action to clear the cache today. Use one of these approaches:
- Hashed file names (recommended): tools such as Vite, Next.js, webpack and Angular generate names like
app.3f9a2c.json every build. Each version gets a new URL and can use a long cache (max-age=31536000, immutable). The HTML, which is never cached by the CDN, always points to the new names. - Version in the URL: change
/app.js?v=1to/app.js?v=2. The CDN treats it as another file. - Short time: for files that change without a new name, use a short
max-ageorno-cache. The new version shows up within that time at most.
How to check
The Age header shows how many seconds the copy has been cached (it only appears when the response came from the cache):
curl -sI https://your-project.clients.zenifra.com/assets/app.js | grep -i -E "^(age|cache-control):"FAQ
Can I cache HTML or API responses at the CDN?
No. Paths without a static file extension always reach the application. To speed up pages and APIs, cache inside the application, for example with the managed Valkey Cache.
I changed a file and visitors still see the old one. What do I do?
Change the file URL (hashed name or ?v=) and publish the HTML that points to it. The old copy leaves the CDN when its cache time ends.
Does the CDN cache change what my application receives?
It only reduces how many static file requests reach the instance. The real visitor IP and the headers of the requests that do arrive stay the same.
Last updated on
Real visitor IP
Learn how to read the real IP of whoever accesses your application on Zenifra with the X-Real-IP header, with examples in Node.js, Python, PHP, and Go.
Custom domains
Point your own domain to a Zenifra app: CNAME for subdomains, a single A record on the apex domain, TXT validation, Cloudflare DNS only and automatic HTTPS.