Velocity response cache and HTTP cache #

This page is for IT teams in public bodies whose sites see traffic peaks: an election night, a storm warning, a deadline for applications. It answers which caches answer before Exponential renders a page, what they never store, how fresh the pages they serve are, and how to check and clear them. The references are Velocity response cache, The role-aware HTTP cache and the hosting pages Velocity response cache and Caching layers.

Contents #

1. Two caches in front of the application
2. What is never cached
3. Freshness and urgent corrections
4. Checking them
5. Clearing them in the right order
6. Checklist

Two caches in front of the application #

The response cache "keeps rendered anonymous pages and answers repeat requests inside the server process, before a worker is chosen: no fork, no PHP, no database" (Velocity response cache). The HTTP cache keeps whole pages per permission context, so that users with the same roles share one copy (The role-aware HTTP cache).

For availability this matters: while the cache answers, a page can still be served when PHP workers are busy, and the database is spared the load of a surge. It does not keep a site up when the database or the server is down for pages nobody requested recently.

What is never cached #

From the response cache's documentation:

• signed-in visitors are never served from it; a page carrying a form token is sent private;
• a request with the session cookie or is_logged_in, or an Authorization header;
• a response that sets a cookie or says no-store or private;
• anything but GET, and statuses other than 200 (a 404 only when NotFoundSeconds is above 0).

The response cache needs engine 0.0.4.26 or later: older versions could serve a signed-in visitor's pages to everybody. Keep the engine current.

Freshness and urgent corrections #

DefaultTtl=30 seconds is how long an anonymous page is kept when it brings no lifetime of its own; StaleWhileRevalidate=60 seconds is how long an expired page may still be served while one request renders the new one. For a public body, decide whether that delay is acceptable for urgent corrections (a wrong phone number, a changed deadline). It usually is; if not, clear the cache right after publishing the correction (below), or lower the values in settings/override/velocity.ini.append.php and restart Velocity.

Checking them #

./console exp:cache status --allow-root-user
php bin/php/cache.php velocity status --allow-root-user
php bin/php/cache.php httpcache status --allow-root-user
curl -sI https://www.example.gov/ | grep -i -E 'x-cache|x-exp-cache|age'

exp:cache status prints one line per layer. The status commands end in PASS with a line about entries and size (Operating a site).

Clearing them in the right order #

Clear the caches in front of PHP after PHP-FPM or Velocity runs the new code; otherwise a page rendered by the old code in between is stored again. After a code or settings change, exp:velocity deploy does every step in the right order. After a template change or an urgent content correction:

php bin/php/ezcache.php --clear-tag=content --allow-root-user
./console exp:velocity cache clear --apply --allow-root-user
php bin/php/cache.php httpcache clear --allow-root-user

With several web servers, clear the response cache and HTTP cache on every node; they are local (Several web servers behind a load balancer). Maintenance mode pauses Velocity's response caches while it is on (Maintenance mode).

Checklist #

• To do: The engine version supports the response cache safely (0.0.4.26 or later).
• To do: The freshness values are accepted by the communications team, or changed.
• To do: The HTTP cache decision (on or off) is recorded.
• To do: Runbooks clear caches after the reload, on every node.
• To do: exp:cache status is part of the weekly checks.

Related pages #

• Availability index of this folder
• Cache warming after changes
• Static cache
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.