Project configuration

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

ResponseCached by the CDN?
Static file (list below) with status 200Yes, 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 404No. A file that does not exist yet during a deploy does not get stuck
Response with Cache-Control: no-store or privateNo
Response that sends Set-CookieNo
POST, PUT, PATCH and DELETE requestsNo

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 Authorization or 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 with Cache-Control: private or no-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 applicationAt the CDNIn the browser
Cache-Control: public, max-age=31536000, immutable1 year1 year
Cache-Control: public, max-age=6060 seconds60 seconds
Cache-Control: public, max-age=3600, s-maxage=6060 seconds (s-maxage applies to the CDN)1 hour
Cache-Control: public, max-age=3600 + CDN-Cache-Control: max-age=6060 seconds (CDN-Cache-Control does not reach the browser)1 hour
Cache-Control: public, max-age=60, stale-while-revalidate=30060 seconds; after that, serves the old copy right away and fetches the new one in the background60 seconds
Cache-Control: no-cache or max-age=0Stored, but checks the application on every requestRevalidates on every use
Cache-Control: no-store or privateNot storedno-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 inCachedNot 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.js on 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=1 to /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-age or no-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

On this page