Skip to content

Never cache the interactive API docs (/ and /docs.json) - #10

Closed
Robbie1977 wants to merge 1 commit into
mainfrom
docs-page-uncached
Closed

Never cache the interactive API docs (/ and /docs.json)#10
Robbie1977 wants to merge 1 commit into
mainfrom
docs-page-uncached

Conversation

@Robbie1977

Copy link
Copy Markdown
Contributor

What changed

vfbquery ≥ 1.22.42 (VirtualFlyBrain/VFBquery#96) serves interactive API documentation at its root and a machine-readable catalogue at /docs.json, both generated in-memory from the running package version. Behind this cache they would be stored under CACHE_STALE_TIME, so after every vfbquery upgrade the docs would keep naming — and documenting — the previous release for up to a month.

A $request_uri map marks the two paths and feeds proxy_cache_bypass + proxy_no_cache, so they are always fetched fresh while every other path keeps the existing cache behaviour. Both responses are tiny and computed in-memory upstream, so the bypass costs nothing.

Why

Without it, the docs page at https://v3-cached.virtualflybrain.org/ would go stale on the first upgrade after it appears.

How to test

Rendered the template through the entrypoint's own envsubst set and ran nginx -t (clean), then ran the config in front of a live vfbquery: / and /docs.json answer X-Cache-Status: BYPASS on every request, /get_term_info still goes MISS then HIT. test/ip-maps-test.sh passes; test/cache-sync-test.sh fails identically on the base branch in this environment (rsync/find variance), untouched by this change.

Follow-ups left

None in this repo — the page appears once the vfbquery release is deployed as the upstream.

vfbquery >= 1.22.42 serves interactive API documentation at its root
and a machine-readable catalogue at /docs.json, both generated
in-memory from the *running* package version. Cached under
CACHE_STALE_TIME they would keep naming — and documenting — a release
that is no longer deployed, for up to a month after every upgrade.

A request-uri map marks the two paths and feeds proxy_cache_bypass and
proxy_no_cache, so every other path keeps the existing cache behaviour.
Verified against a live vfbquery upstream: / and /docs.json answer
BYPASS on every request while /get_term_info still goes MISS then HIT,
and the rendered config passes nginx -t.
@Robbie1977 Robbie1977 closed this Aug 30, 2026
@Robbie1977
Robbie1977 deleted the docs-page-uncached branch August 30, 2026 00:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant