From 8304cc95a5b05e055dc03bc3c8335f358da62430 Mon Sep 17 00:00:00 2001 From: Kaspars Dambis Date: Sun, 31 May 2026 18:50:55 +0300 Subject: [PATCH 1/2] sync instructions --- AGENTS.md | 18 +++++++++++++----- README.md | 2 +- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 26a1175..02f5723 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,10 +6,17 @@ ## Verifying changes -- Follow the Development section in [README.md](README.md): use the included development container for development, testing, and manual validation work. -- When a task requires `make`, run it inside the `dev` container instead.Prefer one of these patterns: +- Follow the Development section in [README.md](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 `make` inside the `dev` container. Prefer one of these patterns: - `docker compose run --rm dev make ` for one-off commands. - `make shell` first, then run `make ` from inside the container for multi-step interactive work. +- For Debian packaging work, use the `packaging` container: + - `docker compose run --rm packaging make debian-package-smoke` + - `docker compose run --rm packaging make debian-source-package ...` +- In GitHub Codespaces, the `.devcontainer` is already the development environment, so run the usual `make` targets directly instead of nesting `docker compose`. +- CI validates source builds and benchmarks against nginx `1.26.3`, `1.28.3`, and `1.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 format` and 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-quick` when 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 @@ -26,9 +33,10 @@ ## Purge semantics -- Same-location `xxx_cache_purge` syntax stores a literal method token in `ngx_http_cache_pilot_conf_t.method`; it is not compiled as a complex value, so variables like `$foo` are not evaluated there. -- `ngx_http_cache_pilot_access_handler()` only activates purge when the request method exactly matches the configured token and the client address passes the optional `from` CIDR list; otherwise request handling falls through to the original upstream handler. -- `cache_purge_mode_header` values `soft`, `true`, or `1` only switch soft versus hard purge mode after a purge request has already matched; they do not enable purge conditionally. +- `fastcgi_cache_purge`, `proxy_cache_purge`, `scgi_cache_purge`, and `uwsgi_cache_purge` accept one or more complex-value conditions followed by optional `soft` and `purge_all` flags. +- 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 as `map`, `allow`, and `deny`. +- `cache_pilot_purge_mode_header` values `soft`, `true`, or `1` only switch soft versus hard purge mode after a purge request has already matched; they do not enable purge conditionally. +- `purge_all` uses the configured `soft` flag and does not honor `cache_pilot_purge_mode_header`. ## README hygiene diff --git a/README.md b/README.md index 2a37de3..00e0fe0 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ _This module is not distributed with the NGINX source. See [Installation Instruc ## Status -This is a fork of the [`ngx_cache_purge` module](https://github.com/nginx-modules/ngx_cache_purge) to add support for soft purgaging and cache tags (also known as surrogate keys). +This is a fork of the [`ngx_cache_purge` module](https://github.com/nginx-modules/ngx_cache_purge) to add support for soft purging and cache tags (also known as surrogate keys). Tagged upstream releases are the packaging input. Distribution packages should ship this module as a version-matched dynamic nginx module, not as a standalone binary intended to work across arbitrary nginx builds. From 653890c566f62f174de4b66c6cc3edcc74569608 Mon Sep 17 00:00:00 2001 From: Kaspars Dambis Date: Sun, 31 May 2026 18:55:12 +0300 Subject: [PATCH 2/2] Also docker image status --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 00e0fe0..b99c9b1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # ngx_cache_pilot -[![CI](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/ci.yml) [![Bench](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/bench.yml/badge.svg)](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/bench.yml) +[![CI](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/ci.yml) +[![Bench](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/bench.yml/badge.svg)](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/bench.yml) +[![Publish Docker Images](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/publish-docker-images.yml/badge.svg)](https://github.com/wpelevator/ngx_cache_pilot/actions/workflows/publish-docker-images.yml) `ngx_cache_pilot` is an `nginx` module that adds cache purge support for [`fastcgi_cache`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html), [`proxy_cache`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html), [`scgi_cache`](https://nginx.org/en/docs/http/ngx_http_scgi_module.html), and [`uwsgi_cache`](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) caches. A purge operation removes or expires cached content that matches the cache key, wildcard key, or configured cache tags for the request.