nginx: honour X-Force-Refresh header for per-request cache bypass

[Robbie1977]

The previous $force_refresh map keyed off $request_uri with a single ${FORCE_CACHE_REFRESH_ON_REQUEST} default -- meaning every URI mapped to the same env-var value. No per-request control. Useful only as a global toggle (currently false).

After v1.14.x VFBquery releases we need a way to overwrite canonical cache slots for the (query_type, entity_id) matrix in the background so end-users never pay the cold-miss latency. Combined with proxy_cache_use_stale updating + proxy_cache_background_update (already on), this gives stale-while-revalidate semantics plus an explicit warmup hook.

Wire shape:

map $http_x_force_refresh $force_refresh {
default ${FORCE_CACHE_REFRESH_ON_REQUEST};
"~*^(true|1|yes)$" 1;
}

proxy_cache_bypass $force_refresh; is unchanged downstream and critically proxy_no_cache is NOT set, so the upstream response from a force-refreshed request overwrites the canonical cache entry -- subsequent normal users get the fresh body. Header-not-query-param is deliberate: the cache key includes the URI so a ?force_refresh=true query param would land the fresh response in a different cache slot than the slot normal users read from. Header has zero effect on the key.

Companion: owlery-cache-reload --force-refresh (separate PR) sets this header on every request during the post-release warmup pass.

Operational note: owl_cache should sit behind the VFB firewall and v3-cached.virtualflybrain.org is only reachable from the internet via the Informatics LBs. If external exposure for X-Force-Refresh ever becomes a worry, gate the header inside the existing $is_whitelisted_ip machinery in this file. Not done here -- the overhead of an extra map for a clearly-internal-only tool is more mechanism than the threat warrants today.

[Copilot]

Pull request overview

This PR updates the NGINX cache-bypass mechanism to support a per-request cache refresh trigger via the X-Force-Refresh header, enabling controlled cache warmups that overwrite the canonical cache entry without changing the cache key.

Changes:

• Replace the $force_refresh map input from $request_uri to $http_x_force_refresh to allow header-driven bypass.
• Add detailed inline documentation explaining why the header approach preserves canonical cache slots while enabling explicit warmups.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.