Imported from wpelevator/ngx_cache_pilot (
AGENTS.md). Install upstream withnpx skills add wpelevator/ngx_cache_pilot. Copyright stays with the author.
Agent instructions
Coding style
- Follow the Nginx core development guide https://nginx.org/en/docs/dev/development_guide.html
- Follow established pattern of CI steps -- ensure all steps can be run locally and are composed of existing tools. Update or introduce tools that can be used for composing the CI steps.
Verifying changes
- Follow the Development section in README.md: use the included containers for development, testing, packaging, and manual validation work.
- For source builds, tests, formatting, benchmarks, and manual nginx validation, run
makeinside thedevcontainer. Prefer one of these patterns:docker compose run --rm dev make <target>for one-off commands.make shellfirst, then runmake <target>from inside the container for multi-step interactive work.
- For Debian packaging work, use the
packagingcontainer:docker compose run --rm packaging make debian-package-smokedocker compose run --rm packaging make debian-source-package ...
- In GitHub Codespaces, the
.devcontaineris already the development environment, so run the usualmaketargets directly instead of nestingdocker compose. - CI validates source builds and benchmarks against nginx
1.26.3,1.28.3, and1.29.8. Keep workflow matrices and published dev-image versions in sync when changing supported nginx versions; note that the local Makefile default may differ. - CI formatting runs
docker compose run --rm dev make formatand then checks for source diffs. After formatting locally, inspect the diff before closing the task. - For performance-sensitive purge or index changes, run
docker compose run --rm dev make bench-quickwhen practical. - For non-trivial C refactors, check editor diagnostics first, then run containerized tests. Static diagnostics are useful for fast feedback, but they do not reliably catch nginx-version-specific or preprocessor-heavy regressions in this repo.
Current ngx_cache_pilot assumptions
ngx_cache_pilotcurrently has a single shared-memory index backend. Do not reintroduce backend selectors or store ops indirection unless a real second backend is being added.- Indexed tag purges no longer bootstrap the index on demand inside the request path. If the target cache zone is not registered for indexing or its index is not ready, the purge declines.
- Protocol-specific purge integration is table-driven in
src/ngx_cache_pilot_module.c. Prefer extending the shared protocol descriptor/helpers instead of copying per-protocol handler or attach logic. - Request-level purge metrics are intentionally centralized through shared helpers in
src/ngx_cache_pilot_module.c. Keep newpurges_*and key-index counters routed through those helpers instead of scatteringNGX_CACHE_PILOT_METRICS_INC()calls.
Build notes
- On dynamic builds using
--add-dynamic-module, a missingngx_modulessymbol at runtime points to a packaging or build-flow problem outside the normal nginxauto/modulepath. - The dynamic
.sostill depends on nginx protocol modules such as fastcgi, proxy, scgi, and uwsgi; packaged deployments may require those modules to be statically linked into nginx or loaded before this module.
Purge semantics
fastcgi_cache_purge,proxy_cache_purge,scgi_cache_purge, anduwsgi_cache_purgeaccept one or more complex-value conditions followed by optionalsoftandpurge_allflags.- Purge is enabled when at least one configured condition evaluates to a value that is non-empty, not
"0", and not"off". Request-method and client-IP restrictions should be expressed with normal nginx mechanisms such asmap,allow, anddeny. cache_pilot_purge_mode_headervaluessoft,true, or1only switch soft versus hard purge mode after a purge request has already matched; they do not enable purge conditionally.purge_alluses the configuredsoftflag and does not honorcache_pilot_purge_mode_header.
Documentation
- After any change that affects user-visible behaviour, known limitations, configuration options, or the public API, review
README.mdand update it to reflect the current state before closing the task. Pay particular attention to the Known issues section, which documents known limitations — keep each entry accurate and up to date. - Before completing work, review
CHANGELOG.mdand add every notable user-visible change, fix, packaging change, or release-tooling change toUNRELEASED. During release preparation, move those entries into a dated version section and keep the topdebian/changelogversion and notes aligned with the Git tag and GitHub release because packaging tools derive the source package version from that file.
