Add --force-refresh flag to overwrite owl_cache canonical slots

[Robbie1977]

The existing pre-warm pass walks every (query_type, entity_id) tuple for the OWLERY + V3 endpoints and runs a GET against owl_cache (v3-cached.virtualflybrain.org for V3, owl.virtualflybrain.org for the legacy OWLERY queries). That's enough on first deploy when the cache is cold, but it does nothing for a refresh: the very first request after the wamup is served from the existing cache slot.

After a VFBquery release the deployed response shape may differ (new columns, fixed wire format, etc.). We need a way to force-fetch every entry from upstream and overwrite the canonical owl_cache slot, in the background, so end-users hitting v3-cached after the release get either a stale (previous-version) entry or a fresh (post-warmup) entry -- never a cold miss.

owl_cache's companion change adds:

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

with the pre-existing proxy_cache_bypass $force_refresh and no proxy_no_cache -- so a request with X-Force-Refresh: true bypasses the cache for the fetch AND the upstream response then overwrites the canonical slot.

This change adds the matching CLI flag. With --force-refresh, every request sent through this tool gets X-Force-Refresh: true. Without the flag, behaviour is unchanged (cold-cache pre-warm).

Mechanical changes:

• run_query and run_query_type now accept an optional headers kwarg threaded through to requests.get.
• --force-refresh argparse flag (default off).
• request_headers = {'X-Force-Refresh': 'true'} built once in main and passed to every executor submit.

Rollout order:

1. owl_cache header-based-force-refresh branch -> merge -> redeploy.
2. This owlery-cache-reload PR -> merge -> redeploy.
3. Jenkins job: python main.py --force-refresh after each tagged VFBquery push.

[Copilot]

Pull request overview

Adds an opt-in CLI switch to force an owl_cache refresh during the pre-warm pass by attaching a request header that instructs the cache to bypass and overwrite the canonical slot. This supports post–VFBquery-release rollouts where response shapes change and stale cached entries must be replaced without causing cold misses for end users.

Changes:

• Thread an optional headers kwarg through run_query_type → run_query → requests.Session().get(...).
• Add --force-refresh argparse flag to enable sending X-Force-Refresh: true on every request.
• Build request headers once in main() and pass them to all submitted query jobs.

---

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