diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..41db0ec
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,20 @@
+cache/
+cache2/
+cache16a/
+cache16c/
+cache21/
+servroot/
+perfcache/
+bgcache/
+concurrent/
+throttle/
+t/servroot/
+t/cache/
+t/cache2/
+t/cache16a/
+t/cache16c/
+t/cache21/
+t/perfcache/
+t/bgcache/
+t/concurrent/
+t/throttle/
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 426a572..3a5ebdf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -183,6 +183,8 @@ jobs:
         sudo apt-get update && sudo apt-get install -y cppcheck
         cppcheck --enable=all --inconclusive --std=c89 \
           --suppress=missingIncludeSystem \
+          --suppress=toomanyconfigs \
+          --suppress=checkersReport \
           --error-exitcode=1 \
           ngx_cache_purge_module.c
 
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e458ed5
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.worktrees/
diff --git a/README.md b/README.md
index fe7af8b..9ca3448 100644
--- a/README.md
+++ b/README.md
@@ -45,9 +45,12 @@ matches the purge request.
 | nginx  | status     |
 |--------|------------|
 | 1.20.x | ✓ tested   |
+| 1.22.x | ✓ tested   |
+| 1.24.x | ✓ tested   |
 | 1.26.x | ✓ tested   |
 | 1.28.x | ✓ tested   |
-| 1.29.x | ✓ tested   |
+| latest stable | ✓ tested |
+| latest mainline | ✓ tested |
 
 Older releases back to 1.7.9 compile but are not covered by CI.
 
@@ -270,6 +273,312 @@ match will not align with the stored key.
 
 ## Sample configurations
 
+## Refresh (conditional cache validation)
+
+Instead of blindly purging matched cache entries, `refresh` sends conditional
+`HEAD` subrequests upstream using `If-None-Match` / `If-Modified-Since`
+headers extracted from each cached file. Entries that return `200` are
+purged; entries that return `304` are kept.
+
+Refresh currently supports `proxy_cache` only. Attempting refresh on
+`fastcgi`, `scgi`, or `uwsgi` caches returns `400 Bad Request`.
+
+### Refresh directives
+
+`proxy_cache_refresh`
+
+```
+Syntax:  proxy_cache_refresh <method> [refresh_all] [from all|<ip> [.. <ip>]]
+Default: none
+Context: http, server, location
+```
+
+Enables refresh mode with a dedicated directive. The first argument is the
+HTTP method used to trigger refresh requests, for example `REFRESH`. Optional
+`refresh_all` enables full-zone refresh.
+
+The legacy `refresh` parameter on `proxy_cache_purge` is removed; use
+`proxy_cache_refresh` instead.
+
+`proxy_cache_refresh` and `proxy_cache_purge` cannot be configured together in
+the same `location`. If you need both actions, expose separate endpoints such as
+`/purge/...` and `/refresh/...`.
+
+`cache_purge_refresh_timeout`
+
+```
+Syntax:  cache_purge_refresh_timeout <time>
+Default: 600s
+Context: http, server, location
+```
+
+Maximum wall-clock time for a refresh operation. After the timeout, no new
+subrequests are dispatched and remaining entries are counted as errors.
+
+`cache_purge_refresh_concurrency`
+
+```
+Syntax:  cache_purge_refresh_concurrency <number>
+Default: 1
+Context: http, server, location
+```
+
+Maximum number of concurrent validator subrequests during refresh.
+### Important Rules
+
+- One `location` can configure only one entry directive: `proxy_cache_purge` or `proxy_cache_refresh`.
+- For exact and partial requests, both entry directives accept both `PURGE` and `REFRESH`.
+- For exact and partial requests, the actual action is decided by the HTTP method, not by the directive name.
+- Successful purge and refresh responses include `X-Cache-Action: purge` or `X-Cache-Action: refresh`.
+- Full-zone requests are not freely interchangeable: `PURGE` needs `purge_all`, and `REFRESH` needs `refresh_all`.
+- A full-zone capability mismatch returns `400 Bad Request`.
+- `purge_all` belongs to `proxy_cache_purge`; `refresh_all` belongs to `proxy_cache_refresh`.
+- `proxy_cache_refresh ... purge_all ...` is invalid configuration and is rejected at config load time.
+- Refresh is `proxy_cache` only. It is not available for `fastcgi_cache`, `scgi_cache`, or `uwsgi_cache`.
+- Batch/refresh invalidation now destroys each item's temporary cache-open pool immediately after that item finishes invalidation, so cache-file cleanup is not deferred until the very end of a large request.
+- This avoids worker file descriptor buildup during large refresh / batch invalidate runs while preserving concurrent refresh safety.
+- Any proxy location that participates in the refresh request path must include both:
+
+      proxy_cache_bypass  $cache_purge_refresh_bypass;
+      proxy_no_cache      $cache_purge_refresh_bypass;
+
+- Refresh can only reconstruct the upstream request path safely when the evaluated cache key makes the request-path tail unambiguous. The safest shapes are keys where the whole key is already the request path (for example `$uri$is_args$args` or `$request_uri`), keys whose tail still clearly preserves the URI/request-URI portion (for example `$host$request_uri`, `$scheme$host$request_uri`, or `$host$uri$is_args$args`), or exact literal-path keys such as `proxy_cache_key /dir01/file1.txt;`. This also applies to separate-location partial refresh: safe prefixed tails still work as long as the final key tail remains the request target. If refresh cannot determine that tail reliably, it now rejects the request with `400 Bad Request` instead of guessing and risking a wrong purge.
+- Partial refresh requests with query args (for example `REFRESH /refresh/path*?v=1`) are also rejected with `400 Bad Request`. Once `*` appears before `?args`, the evaluated request target no longer maps cleanly to a safe scan prefix.
+
+### Method Routing Model
+
+For exact and partial requests, runtime routing is method-driven:
+
+| Configured entry directive | Request method | Actual action |
+| --- | --- | --- |
+| `proxy_cache_purge` | `PURGE` | purge |
+| `proxy_cache_purge` | `REFRESH` | refresh |
+| `proxy_cache_refresh` | `REFRESH` | refresh |
+| `proxy_cache_refresh` | `PURGE` | purge |
+
+This table applies only to exact and partial requests. Full-zone requests use the
+capability rules in the next section.
+
+### Capability Matrix
+
+For full-zone requests, the request method and the configured full capability must match:
+
+| Full-zone request | Required configured capability | Failure result |
+| --- | --- | --- |
+| `PURGE /.../*` | `purge_all` on `proxy_cache_purge` | `400 Bad Request` |
+| `REFRESH /.../*` | `refresh_all` on `proxy_cache_refresh` | `400 Bad Request` |
+
+Configuration-time rules are also strict:
+
+- `proxy_cache_purge ... purge_all ...` is valid.
+- `proxy_cache_refresh ... refresh_all ...` is valid.
+- `proxy_cache_refresh ... purge_all ...` is invalid.
+- `proxy_cache_purge` and `proxy_cache_refresh` in the same `location` are invalid.
+
+Refresh subrequests are sent as true `HEAD` requests with conditional headers
+(`If-None-Match` / `If-Modified-Since`). The module clears nginx's internal
+`cache_convert_head` override during the cache-bypass check so upstream sees
+`HEAD` rather than a converted `GET`, which keeps 200/304 validation responses
+bodyless and minimizes bandwidth.
+
+Refresh uses nginx background subrequests (`NGX_HTTP_SUBREQUEST_BACKGROUND`)
+to avoid `r->main->count` overflow. This lets a single refresh request safely
+validate 100,000+ cached entries without tripping nginx's 64535 subrequest
+limit.
+
+Refresh locations must include:
+
+```nginx
+proxy_cache_bypass $cache_purge_refresh_bypass;
+proxy_no_cache     $cache_purge_refresh_bypass;
+```
+
+The module automatically sets `$cache_purge_refresh_bypass` for refresh
+subrequests so validation reaches upstream instead of being satisfied by the
+local cache.
+
+Refresh only works when the evaluated cache key keeps the request-target tail
+unambiguous. Safe shapes include keys that are already the request path (for
+example `$uri$is_args$args` or `$request_uri`), keys whose tail still clearly
+preserves the URI / request-URI portion (for example `$host$request_uri`,
+`$scheme$host$request_uri`, or `$host$uri$is_args$args`), and exact literal-path
+keys such as `proxy_cache_key /dir01/file1.txt;`.
+
+Recommended separate-endpoint layout:
+
+```nginx
+http {
+    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;
+
+    server {
+        location / {
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_cache        tmpcache;
+            proxy_cache_key    "$scheme$host$request_uri";
+            proxy_cache_bypass $cache_purge_refresh_bypass;
+            proxy_no_cache     $cache_purge_refresh_bypass;
+        }
+
+        location ~ /purge(/.*) {
+            allow              127.0.0.1;
+            deny               all;
+            proxy_cache_purge  tmpcache $scheme$host$1$is_args$args;
+        }
+
+        location ~ /refresh(/.*) {
+            allow                             127.0.0.1;
+            deny                              all;
+            proxy_pass                        http://127.0.0.1:8000;
+            proxy_cache_bypass                $cache_purge_refresh_bypass;
+            proxy_no_cache                    $cache_purge_refresh_bypass;
+            proxy_cache_refresh               tmpcache $scheme$host$1$is_args$args;
+            cache_purge_refresh_timeout       600s;
+            cache_purge_refresh_concurrency   32;
+        }
+    }
+}
+```
+
+Gradual migration layout: keep one entry directive and migrate clients by
+switching HTTP method first. Exact and partial requests already route by
+method.
+
+```nginx
+http {
+    proxy_cache_path  /tmp/cache  keys_zone=tmpcache:10m;
+
+    server {
+        location / {
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_cache        tmpcache;
+            proxy_cache_key    "$host$request_uri";
+            proxy_cache_bypass $cache_purge_refresh_bypass;
+            proxy_no_cache     $cache_purge_refresh_bypass;
+            proxy_cache_purge  PURGE from 127.0.0.1;
+        }
+    }
+}
+```
+
+In that layout:
+
+- `PURGE /path/file` performs purge.
+- `REFRESH /path/file` performs refresh.
+- Full-zone `REFRESH` still needs a dedicated `proxy_cache_refresh ... refresh_all ...` location.
+
+This migration trick does not remove refresh prerequisites. If a request is
+routed to refresh, the proxy path participating in that refresh flow still
+needs the refresh bypass rules, and the evaluated cache key still needs to keep
+the request-target tail safely identifiable.
+
+### Common Misconfigurations
+
+- Do not put both entry directives in one `location`:
+
+      location /control/ {
+          proxy_cache_purge   PURGE from 127.0.0.1;
+          proxy_cache_refresh REFRESH from 127.0.0.1;
+      }
+
+- Do not expect full-zone `PURGE` to work on a `refresh_all` location, or full-zone `REFRESH` to work on a `purge_all` location. Those fail with `400 Bad Request`.
+
+- Do not write `proxy_cache_refresh REFRESH purge_all from 127.0.0.1;`. Use `refresh_all`, not `purge_all`.
+
+- Do not omit refresh bypass rules from proxy locations used by refresh:
+
+      proxy_cache_bypass $cache_purge_refresh_bypass;
+      proxy_no_cache     $cache_purge_refresh_bypass;
+
+- Do not use a cache key where the URI appears only in the middle, or where the request target is followed by extra suffix data, such as `$arg_x$uri$host`, `$uri|suffix`, `$request_uri$host`, or `$host$request_uri$arg_v`. The real question is not "does this key contain a URI somewhere?" but "can refresh still identify the request-path tail from the final key shape?" If the answer is no, refresh now rejects the request with `400 Bad Request` instead of attempting to invalidate cache entries from a guessed URI.
+- Do not send partial refresh requests with query args, such as `REFRESH /refresh/path*?v=1`. Current refresh matching only supports wildcard partial scans when the `*` remains the final path marker.
+
+- Do not try refresh on `fastcgi`, `scgi`, or `uwsgi` caches.
+
+- If you add a custom `X-Cache-Status` header based on `$upstream_cache_status`, use `always` so it appears on error responses too:
+
+      add_header X-Cache-Status $upstream_cache_status always;
+
+### Response Format
+
+Refresh success responses return `200 OK`. The exact body format depends on
+`cache_purge_response_type`, but refresh currently supports only JSON or text
+output. If `cache_purge_response_type` is `json`, refresh returns JSON like
+`{"status":"refresh",...,"total_bytes":12345,"kept_bytes":6789,"purged_bytes":5556,"status_counts":{"200":190,"301":1,"304":15375},"status_bytes":{"200":1048576,"301":512,"304":2097152}}`;
+all other values fall back to text. In the default text format, the body looks
+like:
+
+    Refresh: total=<N> kept=<K> purged=<P> errors=<E> total_bytes=<B> kept_bytes=<KB> purged_bytes=<PB> statuses={200:<N>,304:<N>,...} status_bytes={200:<BYTES>,304:<BYTES>,...}
+
+Where:
+- `total`: number of matched cache entries scanned
+- `kept`: entries whose final action was to retain the cache entry (for example upstream `304`, `301`, `403`, `500`, or a race-kept result)
+- `purged`: entries whose final action was to invalidate the cache entry (currently upstream `200`, `404`, or `410` when invalidate succeeds)
+- `errors`: true refresh failures only (for example subrequest creation failure, timeout, transport failure, or internal invalidate/helper failure)
+- `total_bytes`: total cached file size of all matched entries, based on the scan-stage `fs_size` snapshot
+- `kept_bytes`: scan-stage cached file size total for entries whose final action was keep
+- `purged_bytes`: scan-stage cached file size total for entries whose final action was purge/invalidate
+- `statuses={...}`: dynamic upstream HTTP status counts for this refresh request; only observed HTTP statuses are listed
+- `status_bytes={...}`: dynamic upstream HTTP status bytes for this refresh request; each value is the scan-stage cached file size total for entries that produced that upstream status
+
+The `*_bytes` fields are intentionally based on the cache entry size observed
+during refresh scanning (`fs_size`). Under concurrent races they are best-effort
+accounting, not a guaranteed post-action view of the final on-disk state.
+
+Successful purge and refresh responses also include:
+
+    X-Cache-Action: purge
+
+or:
+
+    X-Cache-Action: refresh
+
+### How it works
+
+Refresh subrequests use conditional validator headers (`If-None-Match` /
+`If-Modified-Since`) so unchanged objects can be kept with `304 Not Modified`
+responses. Internally nginx may still convert the upstream request method to
+`GET`, but refresh forces header-only handling and does not read the response
+body. The bandwidth savings therefore come from validator-based `304` responses
+and from avoiding response-body reads on the refresh path.
+
+Subrequests use nginx's background subrequest mechanism (`NGX_HTTP_SUBREQUEST_BACKGROUND`)
+to avoid `r->main->count` overflow. This allows refresh to handle 100,000+ cached
+entries in a single request without hitting nginx's 64535 subrequest limit.
+
+```bash
+# Refresh a single file
+curl -X REFRESH http://localhost/refresh/path/to/file.txt
+```
+
+Current upstream status policy during refresh is intentionally conservative:
+
+- `304 Not Modified`: keep the cache entry
+- `200 OK`: treat as changed and run the normal invalidate path
+- `404 Not Found` / `410 Gone`: purge the cache entry because the upstream object is gone
+- other HTTP statuses (for example `301`, `302`, `403`, `429`, `500`): keep the cache entry and record the code in `statuses={...}`
+- subrequest creation failure, timeout, transport failure, premature upstream close, or internal invalidate/helper failure: increment `errors`
+
+The invalidate path used by refresh and scanned wildcard/tree purge intentionally
+trusts stable identity fields (`exists`, `uniq`, `body_start`) but no longer
+uses shm-node `fs_size` as a hard replacement signal. In real nginx cache state,
+`node->uniq` / `node->body_start` may legitimately remain `0`, and `node->fs_size`
+may drift from the currently opened file's block count, without meaning that a
+different cache object replaced the scanned one.
+
+At the end of each refresh request, the module also emits one `error_log notice`
+summary line like:
+
+    cache refresh summary uri="/path/*" total=<N> kept=<K> purged=<P> errors=<E> timed_out=<0|1> total_bytes=<B> kept_bytes=<KB> purged_bytes=<PB> statuses={200:190,301:1,304:15375} status_bytes={200:1048576,301:512,304:2097152}
+
+Per-entry decisions remain debug-level logs.
+
+# Refresh a wildcard prefix
+curl -X REFRESH http://localhost/refresh/images/*
+
+# Refresh the whole cache zone (requires refresh_all)
+curl -X REFRESH http://localhost/refresh/*
+```
+
 ### Basic — inline purge method
 
 ```nginx
@@ -466,7 +775,41 @@ Enable `cache_purge_vary_aware on`.
 
 ## Testing
 
-The test suite uses [Test::Nginx](https://github.com/openresty/test-nginx).
+The project keeps two complementary testing entry points:
+
+- `t/Makefile` for Docker-based Test::Nginx runs
+- `scripts/run_regression.sh` from the repo root for the broader regression backstop
+
+Current compatibility matrix policy is:
+
+- latest stable
+- latest mainline
+- every legacy stable line from `1.20.x` up to the current stable line
+
+Current concrete regression versions are:
+
+- `1.20.2`
+- `1.22.1`
+- `1.24.0`
+- `1.26.3`
+- `1.28.3`
+- latest stable
+- latest mainline
+
+Before running the matrix, re-check the nginx download page and refresh the
+concrete latest stable / latest mainline / legacy stable versions if upstream
+has moved.
+
+Docker-based test targets from `t/`:
+
+```bash
+make test
+make test-all
+make test-version VERSION=1.28.3
+make test-compat
+```
+
+Legacy direct `prove` usage is still available when dependencies are installed:
 
 ```bash
 prove -r t/
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..612d0c8
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,276 @@
+# ngx_cache_purge / refresh 部署说明
+
+这份文档面向部署者，重点说明当前实现里 `purge` / `refresh` 的入口规则、动作路由、能力边界、推荐配置和常见误配。
+
+## 核心规则
+
+- 同一个 `location` 只能配置一个入口指令：`proxy_cache_purge` 或 `proxy_cache_refresh`。
+- 对于精确匹配和通配前缀匹配（exact / partial），`proxy_cache_purge` 与 `proxy_cache_refresh` 都同时接受 `PURGE` 和 `REFRESH`。
+- exact / partial 最终执行的是 `purge` 还是 `refresh`，由实际 HTTP method 决定，不由 directive 名称决定。
+- 成功响应会返回 `X-Cache-Action: purge` 或 `X-Cache-Action: refresh`，用于标识本次实际动作。
+- full-zone 请求不能自由互串：`PURGE` 需要 `purge_all`，`REFRESH` 需要 `refresh_all`。
+- full-zone 能力不匹配时返回 `400 Bad Request`。
+- 配置期规则同样严格：`purge_all` 只能用于 `proxy_cache_purge`，`refresh_all` 只能用于 `proxy_cache_refresh`。
+- `proxy_cache_refresh ... purge_all ...` 是非法配置，nginx 在加载配置时就会拒绝。
+- refresh 只支持 `proxy_cache`，不支持 `fastcgi_cache`、`scgi_cache`、`uwsgi_cache`。
+- 参与 refresh 请求链路的 proxy 配置必须包含：
+
+      proxy_cache_bypass  $cache_purge_refresh_bypass;
+      proxy_no_cache      $cache_purge_refresh_bypass;
+
+- refresh 能否正确工作，关键在于它能不能从“实际展开后的 cache key”里明确找出请求路径那一段。最稳妥的写法，是让 key 本身就是请求路径（例如 `$uri$is_args$args`、`$request_uri`），或者至少让 key 的最后一段仍然清楚地保留完整的 URI / request URI（例如 `$host$request_uri`、`$scheme$host$request_uri`、`$host$uri$is_args$args`），或者干脆就是精确字面路径（例如 `proxy_cache_key /dir01/file1.txt;`）。这条规则对 separate-location partial refresh 也一样成立：只要最终 key 的尾部仍然是可识别的请求目标，就可以安全工作。如果 refresh 不能可靠判断这一段，它现在会直接返回 `400 Bad Request`，而不是继续猜测并误删缓存。
+- partial refresh 如果再带 query 参数（例如 `REFRESH /refresh/path*?v=1`），当前实现也会直接返回 `400 Bad Request`。因为这时 `*` 会落在 `?args` 前面，最终请求目标已经不能再安全映射回扫描前缀。
+- 现在 batch / refresh invalidate 在单个对象处理完成后会立即销毁该对象的临时 cache-open pool，不再把这批 pool 一直拖到整个大请求结束再统一释放。
+- 这样可以避免大规模 refresh / batch invalidate 时 worker 文件描述符长时间堆积，同时不破坏并发 refresh 的稳定性。
+
+## 动作路由说明
+
+对 exact / partial 请求，动作路由遵循下面这张表：
+
+| 配置的入口指令 | 请求 method | 实际动作 |
+| --- | --- | --- |
+| `proxy_cache_purge` | `PURGE` | purge |
+| `proxy_cache_purge` | `REFRESH` | refresh |
+| `proxy_cache_refresh` | `REFRESH` | refresh |
+| `proxy_cache_refresh` | `PURGE` | purge |
+
+要点只有一条：
+
+> 对 exact / partial，请把 directive 名称理解成“入口类型”，不要把它误解成“最终动作已经固定”。真正决定动作的是 HTTP method。
+
+但 full-zone 不适用这张自由互串表。full-zone 需要同时满足 method 与 capability 的匹配关系：
+
+| full-zone 请求 | location 必须具备的能力 | 不匹配时结果 |
+| --- | --- | --- |
+| `PURGE /.../*` | `proxy_cache_purge ... purge_all ...` | `400 Bad Request` |
+| `REFRESH /.../*` | `proxy_cache_refresh ... refresh_all ...` | `400 Bad Request` |
+
+## 推荐配置
+
+### 模板一：生产推荐，`/purge` 与 `/refresh` 分离
+
+这是最稳妥的部署方式。运维、权限、监控、限流和回滚都更直观。
+
+```nginx
+http {
+    proxy_cache_path  /var/cache/nginx  keys_zone=app_cache:100m;
+
+    server {
+        location / {
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_cache        app_cache;
+            proxy_cache_key    "$scheme$host$request_uri";
+            proxy_cache_bypass $cache_purge_refresh_bypass;
+            proxy_no_cache     $cache_purge_refresh_bypass;
+        }
+
+        location ~ /purge(/.*) {
+            allow              127.0.0.1;
+            deny               all;
+            proxy_cache_purge  app_cache $scheme$host$1$is_args$args;
+        }
+
+        location ~ /refresh(/.*) {
+            allow              127.0.0.1;
+            deny               all;
+
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_cache_bypass $cache_purge_refresh_bypass;
+            proxy_no_cache     $cache_purge_refresh_bypass;
+
+            proxy_cache_refresh            app_cache $scheme$host$1$is_args$args;
+            cache_purge_refresh_timeout     600s;
+            cache_purge_refresh_concurrency 32;
+        }
+    }
+}
+```
+
+适用场景：
+
+- 新部署。
+- 希望把 purge 和 refresh 分开做权限控制。
+- 希望接口命名与实际运维动作一一对应。
+
+### 模板二：渐进迁移，单入口先切 method
+
+如果你已有 `proxy_cache_purge` 入口，不想马上新增 `/refresh` endpoint，可以先让客户端切换 method。该方案只适合 exact / partial 的过渡期。
+
+```nginx
+http {
+    proxy_cache_path  /var/cache/nginx  keys_zone=app_cache:100m;
+
+    server {
+        location / {
+            proxy_pass         http://127.0.0.1:8000;
+            proxy_cache        app_cache;
+            proxy_cache_key    "$host$request_uri";
+            proxy_cache_bypass $cache_purge_refresh_bypass;
+            proxy_no_cache     $cache_purge_refresh_bypass;
+            proxy_cache_purge  PURGE from 127.0.0.1;
+        }
+    }
+}
+```
+
+在这套配置里：
+
+- `PURGE /path/file` -> purge
+- `REFRESH /path/file` -> refresh
+- `PURGE /dir/*` -> partial purge
+- `REFRESH /dir/*` -> partial refresh
+
+注意：单入口 method 兼容不等于 full-zone 也能兼容。`REFRESH /*` 仍然需要一个显式配置了 `proxy_cache_refresh ... refresh_all ...` 的 location。
+
+还要特别注意：单入口渐进迁移只解决“入口不想立刻拆分”的问题，不会自动豁免 refresh 的基础前提。如果请求最终按 `REFRESH` 路由执行，那么参与 refresh 请求链路的 proxy 配置仍然必须满足 bypass/no_cache 约束，cache key 也仍然必须让 refresh 能可靠识别出 URI / request URI 这一段。
+
+`cache_purge_refresh_timeout` 也只是 refresh 的总体软截止时间：超时后会停止继续派发新的校验子请求，但已经在途的子请求会自然收尾，而不是被粗暴中断。
+
+## 能力边界
+
+### `purge_all` 与 `refresh_all` 的边界
+
+- `purge_all` 表示 full-zone purge 能力。
+- `refresh_all` 表示 full-zone refresh 能力。
+- 二者不能靠切换 method 互相替代。
+- 运行时 capability mismatch 返回 `400 Bad Request`。
+
+### refresh 的实现边界
+
+- refresh 只支持 `proxy_cache`。
+- refresh 会向 upstream 发带条件头（`If-None-Match` / `If-Modified-Since`）的校验子请求，并读取缓存文件里的 `ETag` / `Last-Modified`。
+- nginx 内部仍可能把上游方法转成 `GET`，但 refresh 路径会强制只处理响应头、不读取响应体；真正的带宽收益主要来自 `304 Not Modified` 和不读 body。
+- upstream 返回 `304` 时保留缓存；返回 `200` 时走正常 invalidate 路径；返回 `404` / `410` 时直接 purge；其它 HTTP 状态默认保留缓存，并额外记入状态码统计；只有内部/传输失败才计入 `errors`。
+
+### cache key 边界
+
+可工作的典型 key：
+
+- `$uri`
+- `$uri$is_args$args`
+- `$host$uri$is_args$args`
+- `$host$request_uri`
+- `$scheme$host$request_uri`
+- 精确字面路径，例如 `proxy_cache_key /dir01/file1.txt;`
+
+不可靠的典型 key：
+
+- `$uri$host`
+- `$request_uri$cookie_user`
+- `$request_uri$host`
+- `$host$request_uri$arg_v`
+- `$arg_x$uri$host`
+- partial refresh 请求里再拼 `?args`，例如 `REFRESH /refresh/path*?v=1`
+
+判断标准不是“key 里有没有出现 URI”，而是“refresh 能不能从最终 key 里明确识别出请求路径的最后一段”。像 `$arg_x$uri$host`、`$uri|suffix` 这种写法虽然也包含 URI，但 URI 只出现在中间，或者尾部又拼了别的维度，refresh 就无法安全反推出上游请求。遇到这种情况，当前实现会直接拒绝 refresh（`400 Bad Request`），而不是冒险继续执行。
+
+## 常见错误配置
+
+### 错误一：同一个 `location` 里同时放两个入口指令
+
+```nginx
+location /control/ {
+    proxy_cache_purge   PURGE from 127.0.0.1;
+    proxy_cache_refresh REFRESH from 127.0.0.1;
+}
+```
+
+为什么错：同一个 `location` 只能有一个入口指令。这个组合会在配置期被拒绝。
+
+### 错误二：把 `purge_all` 写到 `proxy_cache_refresh` 上
+
+```nginx
+location /refresh-all/ {
+    proxy_cache_refresh REFRESH purge_all from 127.0.0.1;
+}
+```
+
+为什么错：`purge_all` 属于 `proxy_cache_purge`，这里必须写 `refresh_all`。
+
+### 错误三：把 full-zone `PURGE` 发到只有 `refresh_all` 的入口
+
+```nginx
+location /refresh-all/ {
+    allow               127.0.0.1;
+    deny                all;
+    proxy_pass          http://127.0.0.1:8000;
+    proxy_cache_bypass  $cache_purge_refresh_bypass;
+    proxy_no_cache      $cache_purge_refresh_bypass;
+    proxy_cache_refresh REFRESH refresh_all from 127.0.0.1;
+}
+```
+
+如果这里是 `REFRESH ... refresh_all ...` 能力，那么客户端发 full-zone `PURGE` 仍会因为 capability mismatch 返回 `400 Bad Request`。
+
+### 错误四：refresh 链路缺少 bypass / no_cache
+
+```nginx
+location / {
+    proxy_pass      http://127.0.0.1:8000;
+    proxy_cache     app_cache;
+    proxy_cache_key "$host$request_uri";
+}
+```
+
+为什么错：如果 refresh 子请求最终走到这样的 proxy location，而没有：
+
+```nginx
+proxy_cache_bypass $cache_purge_refresh_bypass;
+proxy_no_cache     $cache_purge_refresh_bypass;
+```
+
+那么 refresh 可能误读本地缓存，或者把校验请求重新写回缓存。
+
+### 错误五：把 refresh 用到非 proxy cache
+
+```nginx
+location /fcgi-refresh/ {
+    fastcgi_cache_purge REFRESH from 127.0.0.1;
+}
+```
+
+为什么错：当前 refresh 不支持 `fastcgi` / `scgi` / `uwsgi`。
+
+### 错误六：cache key 的末尾不是 URI / request URI
+
+```nginx
+location / {
+    proxy_pass         http://127.0.0.1:8000;
+    proxy_cache        app_cache;
+    proxy_cache_key    "$arg_x$uri$host";
+    proxy_cache_purge  PURGE from 127.0.0.1;
+}
+```
+
+为什么错：refresh 需要从缓存 key 的最后一段反推出上游请求路径。只要 URI / request URI 不在 key 的末尾，这个反推过程就不可靠。
+
+## 生产部署建议
+
+- 新部署优先使用“双入口”模型：`/purge/...` 和 `/refresh/...` 分离。
+- 只有在迁移期才建议使用“单入口 + method 切换”。
+- refresh endpoint 建议做单独的访问控制、限流、审计和监控。
+- 对大规模 refresh，结合业务体量调 `cache_purge_refresh_concurrency` 和 `cache_purge_refresh_timeout`。
+- 生产前先核对 `proxy_cache_key` 是否以 URI / request URI 结尾；这是功能正确性的前提，不只是文档建议。
+- 检查 refresh 子请求实际会经过哪些 proxy location，确保这些 location 都正确配置了 `proxy_cache_bypass` 与 `proxy_no_cache`。
+- 把 `X-Cache-Action` 纳入日志或审计字段，这样能快速确认一次请求最终执行的是 purge 还是 refresh。
+
+## 兼容与测试
+
+- 当前兼容矩阵遵循这条规则：覆盖 latest stable、latest mainline，以及从 `1.20.x` 到当前 stable 之间的所有 legacy stable lines。
+- 当前具体回归版本为：`1.20.2`、`1.22.1`、`1.24.0`、`1.26.3`、`1.28.3`、latest stable、latest mainline。
+- 每次跑矩阵前，都要先检查 nginx 官方下载页；如果 latest stable、latest mainline 或任一 legacy stable line 已更新，就先刷新具体版本号再测试。
+- 在 `t/` 目录下优先使用 Docker 化入口：`make test`、`make test-all`、`make test-version VERSION=<x.y.z>`、`make test-compat`。
+- repo 级集成回归回退命令仍然是仓库根目录下的 `./scripts/run_regression.sh`。
+
+## 响应与排错提示
+
+- refresh 成功时返回 `200 OK`；refresh 目前只支持 JSON 或 text 两种正文格式：当 `cache_purge_response_type=json` 时返回 JSON，例如 `{"status":"refresh",...,"total_bytes":12345,"kept_bytes":6789,"purged_bytes":5556,"status_counts":{"200":190,"301":1,"304":15375},"status_bytes":{"200":1048576,"301":512,"304":2097152}}`；其余取值都会回退到 text。默认 text 模式下，正文类似 `Refresh: total=<N> kept=<K> purged=<P> errors=<E> total_bytes=<B> kept_bytes=<KB> purged_bytes=<PB> statuses={200:<N>,304:<N>,...} status_bytes={200:<BYTES>,304:<BYTES>,...}`。
+- 其中统计口径是：`kept` 表示本次 refresh 的最终动作是保留缓存（例如上游返回 `304`、`301`、`403`、`500`，或者竞态下保留缓存）；`purged` 表示最终动作是清理缓存（当前主要对应上游返回 `200`、`404`、`410` 且 invalidate 成功）；`errors` 只表示真正需要排查的失败，例如子请求创建失败、超时、传输失败、内部 invalidate/helper 失败。
+- `total_bytes` 表示本次匹配到的缓存条目总大小；`kept_bytes` / `purged_bytes` 分别表示最终保留 / 清理的缓存条目大小总和。
+- `statuses={...}` 表示本次 refresh 实际观察到的 upstream HTTP 状态码统计；`status_bytes={...}` 表示这些状态码对应条目的缓存大小总和。两者都只显示本次请求里真正出现过的状态码，不做穷举。
+- `*_bytes` 的统计基于 refresh 扫描阶段看到的缓存文件大小（`fs_size`）。如果 refresh 过程中发生并发 race，这些字节数属于近似值，不保证和最终磁盘状态完全一致。
+- purge / refresh 成功时都带 `X-Cache-Action` 响应头。
+- full-zone 能力错配时返回 `400 Bad Request`，优先检查是不是把 `PURGE` 发到了 `refresh_all` location，或者把 `REFRESH` 发到了 `purge_all` location。
+- refresh 当前对上游状态码的策略是保守的：`304` 保留，`200` 走正常 invalidate 路径，`404` / `410` 直接 purge，其它 HTTP 状态默认保留并写入 `statuses={...}`；只有内部/传输失败才计入 `errors`。
+- 每次 refresh 结束时，模块还会在 `error_log notice` 写一条汇总日志，例如 `cache refresh summary uri="/path/*" total=<N> kept=<K> purged=<P> errors=<E> timed_out=<0|1> total_bytes=<B> kept_bytes=<KB> purged_bytes=<PB> statuses={200:190,301:1,304:15375} status_bytes={200:1048576,301:512,304:2097152}`；逐条条目的明细仍然只在 debug 日志中可见。
+- 如果 refresh 结果异常，优先检查三件事：是否是 `proxy_cache`、refresh 链路上是否配置 bypass/no_cache、cache key 是否以 URI/request URI 结尾。
diff --git a/config b/config
index 350b17d..6c113e0 100644
--- a/config
+++ b/config
@@ -37,7 +37,7 @@ fi
 # Module identity and sources
 # ------------------------------------------------------------------
 ngx_addon_name=ngx_http_cache_purge_module
-CACHE_PURGE_SRCS="$ngx_addon_dir/ngx_cache_purge_module.c"
+CACHE_PURGE_SRCS="$ngx_addon_dir/ngx_cache_purge_module.c $ngx_addon_dir/ngx_http_cache_refresh.c"
 
 # ------------------------------------------------------------------
 # Register the module with nginx's build system.
diff --git a/ngx_cache_purge_module.c b/ngx_cache_purge_module.c
index 5a31506..567df7a 100644
--- a/ngx_cache_purge_module.c
+++ b/ngx_cache_purge_module.c
@@ -31,16 +31,12 @@
 #include <ngx_core.h>
 #include <ngx_http.h>
 
+#include "ngx_http_cache_refresh.h"
 
 #ifndef nginx_version
 # error This module cannot be built against an unknown nginx version.
 #endif
 
-#define NGX_CACHE_PURGE_RESPONSE_TYPE_HTML  1
-#define NGX_CACHE_PURGE_RESPONSE_TYPE_XML   2
-#define NGX_CACHE_PURGE_RESPONSE_TYPE_JSON  3
-#define NGX_CACHE_PURGE_RESPONSE_TYPE_TEXT  4
-
 #define NGX_CACHE_PURGE_QUEUE_SIZE_DEFAULT   1024
 #define NGX_CACHE_PURGE_BATCH_SIZE_DEFAULT   10
 /*
@@ -53,7 +49,6 @@
  * suffix ("10ms", "1s", ...) to get the intended unit.
  */
 #define NGX_CACHE_PURGE_THROTTLE_MS_DEFAULT  10  /* milliseconds */
-#define NGX_CACHE_PURGE_KEY_MAX_LEN          512
 #define NGX_CACHE_PURGE_QUEUE_TIMEOUT        60000   /* ms */
 /*
  * Byte offset from the start of a cache file to the first character of the
@@ -91,6 +86,8 @@ static const char ngx_http_cache_purge_content_type_json[] = "application/json";
 static const char ngx_http_cache_purge_content_type_html[] = "text/html";
 static const char ngx_http_cache_purge_content_type_xml[]  = "text/xml";
 static const char ngx_http_cache_purge_content_type_text[] = "text/plain";
+static ngx_str_t ngx_http_cache_purge_method_purge = ngx_string("PURGE");
+static ngx_str_t ngx_http_cache_purge_method_refresh = ngx_string("REFRESH");
 
 static const size_t ngx_http_cache_purge_content_type_json_size =
     sizeof(ngx_http_cache_purge_content_type_json);
@@ -104,8 +101,8 @@ static const size_t ngx_http_cache_purge_content_type_text_size =
 static const char ngx_http_cache_purge_body_templ_json[] =
     "{\"Key\": \"%s\", \"Status\": \"%s\"}";
 static const char ngx_http_cache_purge_body_templ_html[] =
-    "<html><head><title>Cache Purge</title></head>"
-    "<body bgcolor=\"white\"><center><h1>Cache Purge</h1>"
+    "<html><head><title>Cache purge</title></head>"
+    "<body bgcolor=\"white\"><center><h1>Cache purge</h1>"
     "<p>Key: %s</p><p>Status: %s</p></center></body></html>";
 static const char ngx_http_cache_purge_body_templ_xml[] =
     "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
@@ -127,113 +124,6 @@ static const size_t ngx_http_cache_purge_body_templ_text_size =
 
 /* -- forward declarations ----------------------------------------------- */
 
-typedef struct ngx_http_cache_purge_queue_item_s ngx_http_cache_purge_queue_item_t;
-typedef struct ngx_http_cache_purge_queue_s      ngx_http_cache_purge_queue_t;
-typedef struct ngx_http_cache_purge_main_conf_s  ngx_http_cache_purge_main_conf_t;
-
-
-/* -- data structures ---------------------------------------------------- */
-
-struct ngx_http_cache_purge_queue_item_s {
-    ngx_str_t                          cache_path;
-    ngx_str_t                          key_partial;
-    ngx_uint_t                         hash;
-    ngx_flag_t                         purge_all;
-    ngx_uint_t                         in_progress; /* reserved for ABI stability */
-    ngx_msec_t                         enqueued_at;
-    ngx_http_cache_purge_queue_item_t *next;
-};
-
-struct ngx_http_cache_purge_queue_s {
-    ngx_http_cache_purge_queue_item_t *head;
-    ngx_http_cache_purge_queue_item_t *tail;
-    /*
-     * size is always read and written while queue->mutex is held.
-     * ngx_atomic_t was used historically but implies lock-free semantics that
-     * do not exist here.  ngx_uint_t is the correct plain unsigned type.
-     */
-    ngx_uint_t                         size;
-    ngx_shmtx_sh_t                     sh;
-    ngx_shmtx_t                        mutex;
-    ngx_slab_pool_t                   *shpool;
-    ngx_uint_t                         max_size;
-    ngx_uint_t                         batch_size;
-    ngx_msec_t                         throttle_ms;
-};
-
-struct ngx_http_cache_purge_main_conf_s {
-    ngx_http_cache_purge_queue_t      *queue;
-    ngx_shm_zone_t                    *shm_zone;
-    ngx_uint_t                         queue_size;
-    ngx_uint_t                         batch_size;
-    ngx_msec_t                         throttle_ms;
-    ngx_flag_t                         background_purge;
-    ngx_flag_t                         legacy_status_codes;
-    /*
-     * vary_aware: when on, an exact-key purge walks the cache directory after
-     * deleting the primary file and removes any remaining files that carry the
-     * same KEY: string (i.e. Vary / gzip_vary variants at different paths).
-     * Disabled by default because it adds a full cache walk per purge request.
-     */
-    ngx_flag_t                         vary_aware;
-};
-
-typedef struct {
-    ngx_flag_t    enable;
-    ngx_str_t     method;
-    ngx_flag_t    purge_all;
-    ngx_array_t  *access;    /* ngx_in_cidr_t  */
-    ngx_array_t  *access6;   /* ngx_in6_cidr_t */
-} ngx_http_cache_purge_conf_t;
-
-typedef struct {
-# if (NGX_HTTP_FASTCGI)
-    ngx_http_cache_purge_conf_t  fastcgi;
-# endif
-# if (NGX_HTTP_PROXY)
-    ngx_http_cache_purge_conf_t  proxy;
-# endif
-# if (NGX_HTTP_SCGI)
-    ngx_http_cache_purge_conf_t  scgi;
-# endif
-# if (NGX_HTTP_UWSGI)
-    ngx_http_cache_purge_conf_t  uwsgi;
-# endif
-
-    ngx_http_cache_purge_conf_t *conf;
-    ngx_http_handler_pt          handler;
-    ngx_http_handler_pt          original_handler;
-    ngx_uint_t                   response_type;
-
-# if (NGX_HTTP_PROXY)
-    /*
-     * Separate-location syntax stores the cache zone and purge key here
-     * instead of in plcf->upstream, which avoids triggering nginx's internal
-     * proxy_cache merge path and the resulting duplicate location "/" error
-     * introduced in nginx >= 1.27.x.
-     */
-    ngx_shm_zone_t              *proxy_separate_zone;   /* static zone name  */
-    ngx_http_complex_value_t    *proxy_separate_value;  /* dynamic zone expr */
-    ngx_http_complex_value_t     proxy_separate_key;    /* purge key template*/
-# endif
-} ngx_http_cache_purge_loc_conf_t;
-
-typedef struct {
-    u_char                 *key_partial;
-    ngx_uint_t              key_len;
-    u_char                  key_buffer[NGX_CACHE_PURGE_KEY_MAX_LEN];
-    ngx_uint_t              files_deleted;
-    ngx_uint_t              files_checked;
-    /*
-     * cache is set by ngx_http_cache_purge_delete_variants() so that
-     * delete_exact_file can update shm metadata (sh->size, node->exists,
-     * node->fs_size) for each variant it deletes.  NULL in all other walk
-     * contexts where metadata updates are not needed.
-     */
-    ngx_http_file_cache_t  *cache;
-} ngx_http_cache_purge_walk_ctx_t;
-
-
 /* -- function prototypes ------------------------------------------------ */
 
 static void *ngx_http_cache_purge_create_main_conf(ngx_conf_t *cf);
@@ -261,6 +151,8 @@ ngx_int_t  ngx_http_fastcgi_cache_purge_handler(ngx_http_request_t *r);
 # if (NGX_HTTP_PROXY)
 char      *ngx_http_proxy_cache_purge_conf(ngx_conf_t *cf,
                ngx_command_t *cmd, void *conf);
+char      *ngx_http_proxy_cache_refresh_conf(ngx_conf_t *cf,
+               ngx_command_t *cmd, void *conf);
 ngx_int_t  ngx_http_proxy_cache_purge_handler(ngx_http_request_t *r);
 # endif
 
@@ -284,6 +176,8 @@ char *ngx_http_cache_purge_legacy_status_conf(ngx_conf_t *cf,
     ngx_command_t *cmd, void *conf);
 char *ngx_http_cache_purge_vary_aware_conf(ngx_conf_t *cf,
     ngx_command_t *cmd, void *conf);
+char *ngx_http_cache_refresh_conf(ngx_conf_t *cf,
+    ngx_http_cache_purge_conf_t *cpcf);
 static ngx_int_t ngx_http_purge_file_cache_noop(ngx_tree_ctx_t *ctx,
     ngx_str_t *path);
 static ngx_int_t ngx_http_purge_file_cache_delete_file(ngx_tree_ctx_t *ctx,
@@ -305,6 +199,10 @@ static ngx_int_t ngx_http_purge_file_cache_delete_partial_file(
  */
 static ngx_int_t ngx_http_purge_file_cache_delete_exact_file(
     ngx_tree_ctx_t *ctx, ngx_str_t *path);
+static ngx_int_t ngx_http_cache_purge_invalidate_file(ngx_tree_ctx_t *ctx,
+    ngx_str_t *path);
+static ngx_int_t ngx_http_cache_purge_invalidate_partial_file(
+    ngx_tree_ctx_t *ctx, ngx_str_t *path);
 static void ngx_http_cache_purge_invalidate_node(ngx_http_file_cache_t *cache,
     ngx_str_t *path);
 
@@ -316,6 +214,18 @@ ngx_int_t  ngx_http_cache_purge_access(ngx_array_t *a, ngx_array_t *a6,
                struct sockaddr *s);
 ngx_int_t  ngx_http_cache_purge_send_response(ngx_http_request_t *r,
                ngx_str_t *status);
+static ngx_uint_t ngx_http_cache_purge_method_equals(ngx_str_t *a,
+    ngx_str_t *b);
+static ngx_uint_t ngx_http_cache_purge_request_has_method(
+    ngx_http_request_t *r, ngx_str_t *method);
+static ngx_uint_t ngx_http_cache_purge_allows_runtime_dispatch(
+    ngx_http_cache_purge_loc_conf_t *cplcf);
+static ngx_uint_t ngx_http_cache_purge_is_runtime_refresh(
+    ngx_http_request_t *r, ngx_http_cache_purge_loc_conf_t *cplcf);
+ngx_int_t ngx_http_cache_purge_add_action_header(
+    ngx_http_request_t *r, ngx_uint_t refresh);
+static ngx_int_t ngx_http_cache_purge_send_capability_error(
+    ngx_http_request_t *r, ngx_uint_t refresh);
 # if (nginx_version >= 1007009)
 ngx_int_t  ngx_http_cache_purge_cache_get(ngx_http_request_t *r,
                ngx_http_upstream_t *u, ngx_http_file_cache_t **cache);
@@ -332,10 +242,36 @@ ngx_uint_t ngx_http_cache_purge_partial(ngx_http_request_t *r,
 ngx_int_t  ngx_http_cache_purge_is_partial(ngx_http_request_t *r);
 char      *ngx_http_cache_purge_conf(ngx_conf_t *cf,
                ngx_http_cache_purge_conf_t *cpcf);
+static void ngx_http_cache_purge_merge_conf(ngx_http_cache_purge_conf_t *conf,
+    ngx_http_cache_purge_conf_t *prev);
 void      *ngx_http_cache_purge_create_loc_conf(ngx_conf_t *cf);
 char      *ngx_http_cache_purge_merge_loc_conf(ngx_conf_t *cf,
                void *parent, void *child);
 
+static ngx_int_t ngx_http_cache_purge_read_item(ngx_pool_t *pool,
+    ngx_log_t *log, ngx_str_t *path,
+    ngx_http_cache_purge_invalidate_item_t *item);
+void ngx_http_cache_purge_drain_temp_pools(ngx_queue_t *queue);
+static ngx_int_t ngx_http_cache_purge_invalidate_opened_cache(ngx_log_t *log,
+    ngx_http_file_cache_t *cache, ngx_http_cache_t *c,
+    ngx_pool_t *pool, ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result);
+static ngx_int_t ngx_http_cache_purge_open_temp_cache(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool, ngx_str_t *cache_key,
+    ngx_http_cache_t *c);
+static ngx_int_t ngx_http_cache_purge_item_matches_cache(
+    ngx_http_cache_purge_invalidate_item_t *expected,
+    ngx_http_cache_t *c);
+static ngx_int_t ngx_http_cache_purge_cache_matches_node(
+    ngx_http_cache_t *c);
+ngx_int_t ngx_http_cache_purge_invalidate_item(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool,
+    ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result);
+ngx_int_t ngx_http_cache_purge_refresh(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache);
+ngx_int_t ngx_http_cache_purge_add_variable(ngx_conf_t *cf);
+
 
 /* -- module commands ---------------------------------------------------- */
 
@@ -353,6 +289,10 @@ static ngx_command_t  ngx_http_cache_purge_module_commands[] = {
       NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_1MORE,
       ngx_http_proxy_cache_purge_conf,
       NGX_HTTP_LOC_CONF_OFFSET, 0, NULL },
+    { ngx_string("proxy_cache_refresh"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_1MORE,
+      ngx_http_proxy_cache_refresh_conf,
+      NGX_HTTP_LOC_CONF_OFFSET, 0, NULL },
 # endif
 
 # if (NGX_HTTP_SCGI)
@@ -416,6 +356,20 @@ static ngx_command_t  ngx_http_cache_purge_module_commands[] = {
       NGX_HTTP_MAIN_CONF_OFFSET,
       offsetof(ngx_http_cache_purge_main_conf_t, vary_aware), NULL },
 
+    { ngx_string("cache_purge_refresh_concurrency"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
+      ngx_conf_set_num_slot,
+      NGX_HTTP_LOC_CONF_OFFSET,
+      offsetof(ngx_http_cache_purge_loc_conf_t, refresh_concurrency),
+      NULL },
+
+    { ngx_string("cache_purge_refresh_timeout"),
+      NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
+      ngx_conf_set_msec_slot,
+      NGX_HTTP_LOC_CONF_OFFSET,
+      offsetof(ngx_http_cache_purge_loc_conf_t, refresh_timeout),
+      NULL },
+
     ngx_null_command
 };
 
@@ -423,7 +377,7 @@ static ngx_command_t  ngx_http_cache_purge_module_commands[] = {
 /* -- module context & descriptor ---------------------------------------- */
 
 static ngx_http_module_t  ngx_http_cache_purge_module_ctx = {
-    NULL,                                   /* preconfiguration  */
+    ngx_http_cache_purge_add_variable,      /* preconfiguration  */
     NULL,                                   /* postconfiguration */
     ngx_http_cache_purge_create_main_conf,  /* create main conf  */
     ngx_http_cache_purge_init_main_conf,    /* init main conf    */
@@ -1551,7 +1505,17 @@ ngx_http_fastcgi_cache_purge_conf(ngx_conf_t *cf, ngx_command_t *cmd,
     }
 
     if (cf->args->nelts != 3) {
-        return ngx_http_cache_purge_conf(cf, &cplcf->fastcgi);
+        if (ngx_http_cache_purge_conf(cf, &cplcf->fastcgi) != NGX_CONF_OK) {
+            return NGX_CONF_ERROR;
+        }
+
+        if (cplcf->fastcgi.refresh) {
+            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                               "\"refresh\" is supported only with \"proxy_cache_purge\"");
+            return NGX_CONF_ERROR;
+        }
+
+        return NGX_CONF_OK;
     }
 
     if (cf->cmd_type & (NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF)) {
@@ -1861,7 +1825,7 @@ ngx_http_proxy_cache_purge_conf(ngx_conf_t *cf, ngx_command_t *cmd,
     cplcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_cache_purge_module);
 
     if (cplcf->proxy.enable != NGX_CONF_UNSET) {
-        return "is duplicate";
+        return "\"proxy_cache_purge\" cannot be used together with \"proxy_cache_refresh\" in the same location";
     }
 
     if (cf->args->nelts != 3) {
@@ -1964,12 +1928,103 @@ ngx_http_proxy_cache_purge_conf(ngx_conf_t *cf, ngx_command_t *cmd,
     return NGX_CONF_OK;
 }
 
+char *
+ngx_http_proxy_cache_refresh_conf(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) {
+    ngx_http_compile_complex_value_t   ccv;
+    ngx_http_cache_purge_loc_conf_t   *cplcf;
+    ngx_http_core_loc_conf_t          *clcf;
+    ngx_http_proxy_loc_conf_t         *plcf;
+    ngx_str_t                         *value;
+#  if (nginx_version >= 1007009)
+    ngx_http_complex_value_t           cv;
+#  endif /* nginx_version >= 1007009 */
+
+    cplcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_cache_purge_module);
+
+    if (cplcf->proxy.enable != NGX_CONF_UNSET) {
+        return "\"proxy_cache_refresh\" cannot be used together with \"proxy_cache_purge\" in the same location";
+    }
+
+    if (cf->args->nelts != 3) {
+        return ngx_http_cache_refresh_conf(cf, &cplcf->proxy);
+    }
+
+    if (cf->cmd_type & (NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF)) {
+        return "(separate location syntax) is not allowed here";
+    }
+
+    plcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_proxy_module);
+
+#  if (nginx_version >= 1007009)
+
+    plcf->upstream.cache = 1;
+
+    value = cf->args->elts;
+
+    ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));
+    ccv.cf = cf;
+    ccv.value = &value[1];
+    ccv.complex_value = &cv;
+
+    if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
+        return NGX_CONF_ERROR;
+    }
+
+    if (cv.lengths != NULL) {
+        plcf->upstream.cache_value = ngx_palloc(cf->pool,
+                                                sizeof(ngx_http_complex_value_t));
+        if (plcf->upstream.cache_value == NULL) {
+            return NGX_CONF_ERROR;
+        }
+
+        *plcf->upstream.cache_value = cv;
+
+    } else {
+        plcf->upstream.cache_zone = ngx_shared_memory_add(cf, &value[1], 0,
+                                    &ngx_http_proxy_module);
+        if (plcf->upstream.cache_zone == NULL) {
+            return NGX_CONF_ERROR;
+        }
+    }
+
+#  else
+
+    value = cf->args->elts;
+
+    plcf->upstream.cache = ngx_shared_memory_add(cf, &value[1], 0,
+                           &ngx_http_proxy_module);
+    if (plcf->upstream.cache == NULL) {
+        return NGX_CONF_ERROR;
+    }
+
+#  endif /* nginx_version >= 1007009 */
+
+    ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));
+    ccv.cf = cf;
+    ccv.value = &value[2];
+    ccv.complex_value = &plcf->cache_key;
+
+    if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
+        return NGX_CONF_ERROR;
+    }
+
+    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
+
+    cplcf->proxy.enable = 0;
+    cplcf->proxy.refresh = 1;
+    cplcf->conf = &cplcf->proxy;
+    clcf->handler = ngx_http_proxy_cache_purge_handler;
+
+    return NGX_CONF_OK;
+}
+
 ngx_int_t
 ngx_http_proxy_cache_purge_handler(ngx_http_request_t *r)
 {
     ngx_http_file_cache_t            *cache;
     ngx_http_proxy_loc_conf_t        *plcf;
     ngx_http_cache_purge_loc_conf_t  *cplcf;
+    ngx_uint_t                        refresh;
     ngx_http_cache_purge_main_conf_t *cmcf;
     ngx_str_t                         status;
     ngx_str_t                        *key;
@@ -1986,6 +2041,7 @@ ngx_http_proxy_cache_purge_handler(ngx_http_request_t *r)
     ngx_str_set(&status, "purged");
 
     cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+    refresh = ngx_http_cache_purge_is_runtime_refresh(r, cplcf);
 
     /*
      * Separate-location syntax (proxy_cache_purge zone key): the cache zone
@@ -2046,6 +2102,19 @@ ngx_http_proxy_cache_purge_handler(ngx_http_request_t *r)
         }
 
         plcf = ngx_http_get_module_loc_conf(r, ngx_http_proxy_module);
+
+        /*
+         * Runtime refresh on a purge entry still needs a real proxy_cache
+         * definition in the current location so cache_zone/cache_key can be
+         * evaluated safely.  A plain /purge endpoint with only proxy_pass and
+         * proxy_cache_purge cannot be auto-upgraded into refresh.
+         */
+        if (refresh && !plcf->upstream.cache) {
+            ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
+                          "runtime refresh rejected: current location has no proxy_cache configuration");
+            return NGX_HTTP_BAD_REQUEST;
+        }
+
         r->upstream->conf = &plcf->upstream;
 
 #  if (nginx_version >= 1007009)
@@ -2068,6 +2137,20 @@ ngx_http_proxy_cache_purge_handler(ngx_http_request_t *r)
     cmcf  = ngx_http_get_module_main_conf(r, ngx_http_cache_purge_module);
     cplcf = ngx_http_get_module_loc_conf(r,  ngx_http_cache_purge_module);
 
+    if (cplcf->conf->purge_all
+        && ((cplcf->conf->refresh != 0) != (refresh != 0)))
+    {
+        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
+                      refresh
+                      ? "runtime refresh_all rejected: current location has only purge_all capability"
+                      : "runtime purge_all rejected: current location has only refresh_all capability");
+        return ngx_http_cache_purge_send_capability_error(r, refresh);
+    }
+
+    if (refresh) {
+        return ngx_http_cache_purge_refresh(r, cache);
+    }
+
     if (cmcf != NULL && cmcf->background_purge
         && (cplcf->conf->purge_all || ngx_http_cache_purge_is_partial(r)))
     {
@@ -2178,7 +2261,17 @@ ngx_http_scgi_cache_purge_conf(ngx_conf_t *cf, ngx_command_t *cmd,
     }
 
     if (cf->args->nelts != 3) {
-        return ngx_http_cache_purge_conf(cf, &cplcf->scgi);
+        if (ngx_http_cache_purge_conf(cf, &cplcf->scgi) != NGX_CONF_OK) {
+            return NGX_CONF_ERROR;
+        }
+
+        if (cplcf->scgi.refresh) {
+            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                               "\"refresh\" is supported only with \"proxy_cache_purge\"");
+            return NGX_CONF_ERROR;
+        }
+
+        return NGX_CONF_OK;
     }
 
     if (cf->cmd_type & (NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF)) {
@@ -2431,7 +2524,17 @@ ngx_http_uwsgi_cache_purge_conf(ngx_conf_t *cf, ngx_command_t *cmd,
     }
 
     if (cf->args->nelts != 3) {
-        return ngx_http_cache_purge_conf(cf, &cplcf->uwsgi);
+        if (ngx_http_cache_purge_conf(cf, &cplcf->uwsgi) != NGX_CONF_OK) {
+            return NGX_CONF_ERROR;
+        }
+
+        if (cplcf->uwsgi.refresh) {
+            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                               "\"refresh\" is supported only with \"proxy_cache_purge\"");
+            return NGX_CONF_ERROR;
+        }
+
+        return NGX_CONF_OK;
     }
 
     if (cf->cmd_type & (NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF)) {
@@ -2638,125 +2741,645 @@ ngx_http_cache_purge_response_type_conf(ngx_conf_t *cf, ngx_command_t *cmd,
 
 /* -- access control ----------------------------------------------------- */
 
-ngx_int_t
-ngx_http_cache_purge_access_handler(ngx_http_request_t *r)
+static ngx_int_t
+ngx_http_cache_purge_invalidate_file(ngx_tree_ctx_t *ctx, ngx_str_t *path)
 {
-    ngx_http_cache_purge_loc_conf_t *cplcf;
-
-    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
-
-    /*
-     * Belt-and-suspenders: the merge logic only installs this handler when
-     * conf->conf is set, so this should never be NULL in production.  Guard
-     * anyway to eliminate the crash class entirely.
-     */
-    if (cplcf->conf == NULL) {
-        return NGX_HTTP_NOT_FOUND;
+    ngx_http_cache_purge_batch_ctx_t         *data;
+    ngx_http_cache_purge_invalidate_item_t    item;
+    ngx_http_cache_purge_invalidate_result_e  result;
+    ngx_pool_t                               *pool;
+
+    data = ctx->data;
+    pool = ngx_create_pool(4096, ctx->log);
+    if (pool == NULL) {
+        return NGX_OK;
     }
 
-    if (r->method_name.len != cplcf->conf->method.len
-        || ngx_strncmp(r->method_name.data, cplcf->conf->method.data,
-                       r->method_name.len) != 0)
-    {
-        /*
-         * Not a purge request.  Forward to the original content handler
-         * if one exists (e.g. proxy_pass), otherwise return 404.
-         * original_handler is NULL when proxy_cache is used without
-         * proxy_pass (cache-only / purge-only location).
-         */
-        if (cplcf->original_handler != NULL) {
-            return cplcf->original_handler(r);
+    if (ngx_http_cache_purge_read_item(pool, ctx->log, path, &item) == NGX_OK) {
+        if (ngx_http_cache_purge_invalidate_item(data->request, data->cache,
+                                                 pool, &item, &result)
+            != NGX_OK)
+        {
+            ngx_log_error(NGX_LOG_CRIT, ctx->log, 0,
+                          "http file cache invalidate failed for \"%V\"",
+                          path);
+        } else if (result == NGX_HTTP_CACHE_PURGE_INVALIDATE_PURGED) {
+            data->files_deleted++;
         }
-        return NGX_HTTP_NOT_FOUND;
-    }
-
-    if ((cplcf->conf->access || cplcf->conf->access6)
-        && ngx_http_cache_purge_access(cplcf->conf->access,
-                                       cplcf->conf->access6,
-                                       r->connection->sockaddr) != NGX_OK)
-    {
-        ngx_log_error(NGX_LOG_WARN, r->connection->log, 0,
-                      "ngx_cache_purge: access denied for %V",
-                      &r->connection->addr_text);
-        return NGX_HTTP_FORBIDDEN;
     }
 
-    if (cplcf->handler == NULL) {
-        return NGX_HTTP_NOT_FOUND;
-    }
+    ngx_destroy_pool(pool);
 
-    return cplcf->handler(r);
+    return NGX_OK;
 }
 
-ngx_int_t
-ngx_http_cache_purge_access(ngx_array_t *access, ngx_array_t *access6,
-    struct sockaddr *s)
+
+static ngx_int_t
+ngx_http_cache_purge_invalidate_partial_file(ngx_tree_ctx_t *ctx,
+    ngx_str_t *path)
 {
-    in_addr_t        inaddr;
-    ngx_in_cidr_t   *a;
-    ngx_uint_t       i;
-# if (NGX_HAVE_INET6)
-    struct in6_addr *inaddr6;
-    ngx_in6_cidr_t  *a6;
-    u_char          *p;
-    ngx_uint_t       n;
-# endif
+    ngx_http_cache_purge_batch_ctx_t         *data;
+    ngx_http_cache_purge_invalidate_item_t    item;
+    ngx_http_cache_purge_invalidate_result_e  result;
+    ngx_pool_t                               *pool;
+
+    data = ctx->data;
+    pool = ngx_create_pool(4096, ctx->log);
+    if (pool == NULL) {
+        return NGX_OK;
+    }
 
-    switch (s->sa_family) {
-    case AF_INET:
-        if (access == NULL) {
-            return NGX_DECLINED;
+    if (ngx_http_cache_purge_read_item(pool, ctx->log, path, &item) == NGX_OK) {
+        if (data->partial_prefix.len == 0
+            || (item.cache_key.len >= data->partial_prefix.len
+                && ngx_strncmp(item.cache_key.data,
+                               data->partial_prefix.data,
+                               data->partial_prefix.len) == 0))
+        {
+            if (ngx_http_cache_purge_invalidate_item(data->request, data->cache,
+                                                     pool, &item, &result)
+                != NGX_OK)
+            {
+                ngx_log_error(NGX_LOG_CRIT, ctx->log, 0,
+                              "http partial cache invalidate failed for \"%V\"",
+                              path);
+            } else if (result == NGX_HTTP_CACHE_PURGE_INVALIDATE_PURGED) {
+                data->files_deleted++;
+            }
         }
+    }
 
-        inaddr = ((struct sockaddr_in *) s)->sin_addr.s_addr;
+    ngx_destroy_pool(pool);
 
-# if (NGX_HAVE_INET6)
-ipv4:
-# endif
-        a = access->elts;
-        for (i = 0; i < access->nelts; i++) {
-            if ((inaddr & a[i].mask) == a[i].addr) {
-                return NGX_OK;
-            }
-        }
-        return NGX_DECLINED;
+    return NGX_OK;
+}
 
-# if (NGX_HAVE_INET6)
-    case AF_INET6:
-        inaddr6 = &((struct sockaddr_in6 *) s)->sin6_addr;
-        p       = inaddr6->s6_addr;
 
-        if (access && IN6_IS_ADDR_V4MAPPED(inaddr6)) {
-            inaddr  = p[12] << 24;
-            inaddr += p[13] << 16;
-            inaddr += p[14] << 8;
-            inaddr += p[15];
-            inaddr  = htonl(inaddr);
-            goto ipv4;
-        }
+void
+ngx_http_cache_purge_drain_temp_pools(ngx_queue_t *queue)
+{
+    ngx_queue_t                              *q;
+    ngx_http_cache_purge_refresh_temp_pool_t *entry;
 
-        if (access6 == NULL) {
-            return NGX_DECLINED;
-        }
+    while (!ngx_queue_empty(queue)) {
+        q = ngx_queue_head(queue);
+        entry = (ngx_http_cache_purge_refresh_temp_pool_t *) ngx_queue_data(
+                    q, ngx_http_cache_purge_refresh_temp_pool_t, queue);
+        ngx_queue_remove(q);
 
-        a6 = access6->elts;
-        for (i = 0; i < access6->nelts; i++) {
-            for (n = 0; n < 16; n++) {
-                if ((p[n] & a6[i].mask.s6_addr[n]) != a6[i].addr.s6_addr[n]) {
-                    goto next;
-                }
-            }
-            return NGX_OK;
-next:
-            continue;
+        if (entry->pool != NULL) {
+            ngx_destroy_pool(entry->pool);
         }
-        return NGX_DECLINED;
-# endif
+    }
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_read_item(ngx_pool_t *pool, ngx_log_t *log,
+    ngx_str_t *path, ngx_http_cache_purge_invalidate_item_t *item)
+{
+    ngx_http_file_cache_header_t  header;
+    ngx_file_t                    file;
+    ngx_file_info_t               fi;
+    u_char                       *key_buf;
+    size_t                        key_len;
+    ssize_t                       n;
+
+    ngx_memzero(item, sizeof(ngx_http_cache_purge_invalidate_item_t));
+    ngx_memzero(&file, sizeof(ngx_file_t));
+
+    file.fd = ngx_open_file(path->data, NGX_FILE_RDONLY, NGX_FILE_OPEN,
+                            NGX_FILE_DEFAULT_ACCESS);
+    if (file.fd == NGX_INVALID_FILE) {
+        return NGX_ERROR;
+    }
+
+    file.name = *path;
+    file.log = log;
+
+    if (ngx_fd_info(file.fd, &fi) == NGX_FILE_ERROR) {
+        ngx_close_file(file.fd);
+        return NGX_ERROR;
+    }
+
+    item->fs_size = ngx_file_size(&fi);
+    item->uniq = ngx_file_uniq(&fi);
+
+    n = ngx_read_file(&file, (u_char *) &header, sizeof(header), 0);
+    if (n < (ssize_t) sizeof(header)) {
+        ngx_close_file(file.fd);
+        return NGX_ERROR;
+    }
+
+    if (header.header_start <= sizeof(header) + 6) {
+        ngx_close_file(file.fd);
+        return NGX_ERROR;
+    }
+
+    key_len = header.header_start - sizeof(header) - 6;
+    if (key_len == 0 || key_len > 8192) {
+        ngx_close_file(file.fd);
+        return NGX_ERROR;
+    }
+
+    key_buf = ngx_pnalloc(pool, key_len + 1);
+    if (key_buf == NULL) {
+        ngx_close_file(file.fd);
+        return NGX_ERROR;
+    }
+
+    n = ngx_read_file(&file, key_buf, key_len, sizeof(header) + 6);
+    ngx_close_file(file.fd);
+    if (n < 1) {
+        return NGX_ERROR;
+    }
+
+    key_buf[n] = '\0';
+    if (n > 0 && key_buf[n - 1] == LF) {
+        key_buf[n - 1] = '\0';
+        n--;
+    }
+
+    item->cache_key.data = key_buf;
+    item->cache_key.len = n;
+
+    item->cache_path.data = ngx_pnalloc(pool, path->len + 1);
+    if (item->cache_path.data == NULL) {
+        return NGX_ERROR;
+    }
+
+    ngx_memcpy(item->cache_path.data, path->data, path->len);
+    item->cache_path.data[path->len] = '\0';
+    item->cache_path.len = path->len;
+
+    item->last_modified = header.last_modified;
+    item->body_start = header.body_start;
+    if (header.etag_len > 0 && header.etag_len < NGX_HTTP_CACHE_ETAG_LEN) {
+        item->etag_len = header.etag_len;
+        ngx_memcpy(item->etag, header.etag, header.etag_len);
+    }
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_invalidate_opened_cache(ngx_log_t *log,
+    ngx_http_file_cache_t *cache, ngx_http_cache_t *c,
+    ngx_pool_t *pool, ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result)
+{
+    (void) pool;
+
+    ngx_shmtx_lock(&cache->shpool->mutex);
+
+    if (!c->node->exists) {
+        ngx_shmtx_unlock(&cache->shpool->mutex);
+        *result = NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_MISSING;
+        return NGX_OK;
+    }
+
+    if (item != NULL) {
+        if (!ngx_http_cache_purge_item_matches_cache(item, c)
+            || !ngx_http_cache_purge_cache_matches_node(c))
+        {
+            ngx_shmtx_unlock(&cache->shpool->mutex);
+            *result = NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_REPLACED;
+            return NGX_OK;
+        }
+    }
+
+#  if (nginx_version >= 1000001)
+    cache->sh->size -= c->node->fs_size;
+    c->node->fs_size = 0;
+#  else
+    cache->sh->size -= (c->node->length + cache->bsize - 1) / cache->bsize;
+    c->node->length = 0;
+#  endif
+
+    c->node->exists = 0;
+#  if (nginx_version >= 8001) \
+       || ((nginx_version < 8000) && (nginx_version >= 7060))
+    c->node->updating = 0;
+#  endif
+
+    ngx_shmtx_unlock(&cache->shpool->mutex);
+
+    if (ngx_delete_file(c->file.name.data) == NGX_FILE_ERROR) {
+        ngx_log_error(NGX_LOG_CRIT, log, ngx_errno,
+                      ngx_delete_file_n " \"%s\" failed", c->file.name.data);
+    }
+
+    *result = NGX_HTTP_CACHE_PURGE_INVALIDATE_PURGED;
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_open_temp_cache(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool, ngx_str_t *cache_key,
+    ngx_http_cache_t *c)
+{
+    ngx_http_request_t *tr;
+    ngx_str_t          *key;
+
+    ngx_memzero(c, sizeof(ngx_http_cache_t));
+
+    /*
+     * Allocate a shallow copy of the request on the temp pool so that
+     * any cleanup registered by ngx_http_file_cache_open (which holds
+     * a pointer to tr->cache) remains valid for the lifetime of the pool.
+     * A stack-allocated copy would become a dangling pointer after this
+     * function returns, risking use-after-free when the pool cleanup runs.
+     */
+    tr = ngx_palloc(pool, sizeof(ngx_http_request_t));
+    if (tr == NULL) {
+        return NGX_ERROR;
+    }
+    ngx_memcpy(tr, r, sizeof(ngx_http_request_t));
+
+    tr->pool = pool;
+    tr->cache = c;
+
+    if (ngx_array_init(&c->keys, pool, 1, sizeof(ngx_str_t)) != NGX_OK) {
+        return NGX_ERROR;
+    }
+
+    key = ngx_array_push(&c->keys);
+    if (key == NULL) {
+        return NGX_ERROR;
+    }
+
+    *key = *cache_key;
+    c->body_start = ngx_pagesize;
+    c->file_cache = cache;
+    c->file.log = r->connection->log;
+
+    ngx_http_file_cache_create_key(tr);
+
+    switch (ngx_http_file_cache_open(tr)) {
+    case NGX_OK:
+    case NGX_HTTP_CACHE_STALE:
+#  if (nginx_version >= 8001) \
+       || ((nginx_version < 8000) && (nginx_version >= 7060))
+    case NGX_HTTP_CACHE_UPDATING:
+#  endif
+        return NGX_OK;
+
+    case NGX_DECLINED:
+        return NGX_DECLINED;
+
+    default:
+        return NGX_ERROR;
+    }
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_item_matches_cache(
+    ngx_http_cache_purge_invalidate_item_t *expected,
+    ngx_http_cache_t *c)
+{
+    if (expected->etag_len > 0) {
+        if (expected->etag_len != c->etag.len
+            || c->etag.data == NULL
+            || ngx_memcmp(expected->etag, c->etag.data, expected->etag_len) != 0)
+        {
+            return 0;
+        }
+    }
+
+    if (expected->last_modified > 0) {
+        if (expected->last_modified != c->last_modified) {
+            return 0;
+        }
+    }
+
+    if (expected->uniq != 0) {
+        if (expected->uniq != c->uniq) {
+            return 0;
+        }
+    }
+
+    if (expected->body_start > 0) {
+        if (expected->body_start != c->body_start) {
+            return 0;
+        }
+    }
+
+    /*
+     * If no fields were available for comparison (all zero/empty in the
+     * scanned item), we cannot confirm a race.  Allow the invalidation
+     * rather than silently skipping it — a false positive purge is safer
+     * than a false negative that leaves stale content.
+     */
+    return 1;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_cache_matches_node(ngx_http_cache_t *c)
+{
+    if (!c->node->exists) {
+        return 0;
+    }
+
+    /*
+     * A live shm node may legitimately keep uniq/body_start at 0 even though
+     * the cache file on disk has already been populated and opened into "c".
+     * Treat 0 here as "unknown" rather than "replaced"; otherwise refresh
+     * and scanned purge paths keep stale entries due to false races.
+     */
+    if (c->uniq != 0 && c->node->uniq != 0 && c->node->uniq != c->uniq) {
+        return 0;
+    }
+
+    if (c->node->body_start != 0 && c->node->body_start != c->body_start) {
+        return 0;
+    }
+
+    return 1;
+}
+
+
+ngx_int_t
+ngx_http_cache_purge_invalidate_item(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool,
+    ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result)
+{
+    ngx_http_cache_t                     *c;
+    ngx_int_t                              rc;
+
+    *result = NGX_HTTP_CACHE_PURGE_INVALIDATE_ERROR;
+
+    /*
+     * Allocate c on the pool rather than the stack.
+     * ngx_http_file_cache_open registers a pool cleanup that references c,
+     * so c must survive until the pool is destroyed.
+     */
+    c = ngx_pcalloc(pool, sizeof(ngx_http_cache_t));
+    if (c == NULL) {
+        return NGX_ERROR;
+    }
+
+    rc = ngx_http_cache_purge_open_temp_cache(r, cache, pool, &item->cache_key, c);
+    if (rc == NGX_DECLINED) {
+        *result = NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_MISSING;
+        return NGX_OK;
+    }
+
+    if (rc != NGX_OK) {
+        return NGX_ERROR;
+    }
+
+    rc = ngx_http_cache_purge_invalidate_opened_cache(r->connection->log,
+                                                      cache, c, NULL, item,
+                                                      result);
+
+    /*
+     * Release the node reference acquired by open_temp_cache.
+     * ngx_http_file_cache_free decrements count under mutex and,
+     * if exists==0 && count==0, safely removes the node from the
+     * rbtree and frees the slab memory.  It also sets c->updated=1,
+     * so the pool cleanup (ngx_http_file_cache_cleanup) will be a
+     * no-op when the pool is eventually destroyed.
+     */
+    ngx_http_file_cache_free(c, NULL);
+
+    return rc;
+}
+
+ngx_int_t
+ngx_http_cache_purge_access_handler(ngx_http_request_t *r)
+{
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+
+    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+
+    /*
+     * Belt-and-suspenders: the merge logic only installs this handler when
+     * conf->conf is set, so this should never be NULL in production.  Guard
+     * anyway to eliminate the crash class entirely.
+     */
+    if (cplcf->conf == NULL) {
+        return NGX_HTTP_NOT_FOUND;
+    }
+
+    if (r->method_name.len != cplcf->conf->method.len
+        || ngx_strncmp(r->method_name.data, cplcf->conf->method.data,
+                       r->method_name.len) != 0)
+    {
+        /*
+         * Not a purge request.  Forward to the original content handler
+         * if one exists (e.g. proxy_pass), otherwise return 404.
+         * original_handler is NULL when proxy_cache is used without
+         * proxy_pass (cache-only / purge-only location).
+         */
+        if (!ngx_http_cache_purge_allows_runtime_dispatch(cplcf)
+            || (!ngx_http_cache_purge_request_has_method(r,
+                    &ngx_http_cache_purge_method_purge)
+                && !ngx_http_cache_purge_request_has_method(r,
+                    &ngx_http_cache_purge_method_refresh)))
+        {
+            if (cplcf->original_handler != NULL) {
+                return cplcf->original_handler(r);
+            }
+
+            return NGX_HTTP_NOT_FOUND;
+        }
+    }
+
+    if ((cplcf->conf->access || cplcf->conf->access6)
+        && ngx_http_cache_purge_access(cplcf->conf->access,
+                                       cplcf->conf->access6,
+                                       r->connection->sockaddr) != NGX_OK)
+    {
+        ngx_log_error(NGX_LOG_WARN, r->connection->log, 0,
+                      "ngx_cache_purge: access denied for %V",
+                      &r->connection->addr_text);
+        return NGX_HTTP_FORBIDDEN;
+    }
+
+    if (cplcf->handler == NULL) {
+        return NGX_HTTP_NOT_FOUND;
+    }
+
+    return cplcf->handler(r);
+}
+
+ngx_int_t
+ngx_http_cache_purge_access(ngx_array_t *access, ngx_array_t *access6,
+    struct sockaddr *s)
+{
+    in_addr_t        inaddr;
+    ngx_in_cidr_t   *a;
+    ngx_uint_t       i;
+# if (NGX_HAVE_INET6)
+    struct in6_addr *inaddr6;
+    ngx_in6_cidr_t  *a6;
+    u_char          *p;
+    ngx_uint_t       n;
+# endif
+
+    switch (s->sa_family) {
+    case AF_INET:
+        if (access == NULL) {
+            return NGX_DECLINED;
+        }
+
+        inaddr = ((struct sockaddr_in *) s)->sin_addr.s_addr;
+
+# if (NGX_HAVE_INET6)
+ipv4:
+# endif
+        a = access->elts;
+        for (i = 0; i < access->nelts; i++) {
+            if ((inaddr & a[i].mask) == a[i].addr) {
+                return NGX_OK;
+            }
+        }
+        return NGX_DECLINED;
+
+# if (NGX_HAVE_INET6)
+    case AF_INET6:
+        inaddr6 = &((struct sockaddr_in6 *) s)->sin6_addr;
+        p       = inaddr6->s6_addr;
+
+        if (access && IN6_IS_ADDR_V4MAPPED(inaddr6)) {
+            inaddr  = p[12] << 24;
+            inaddr += p[13] << 16;
+            inaddr += p[14] << 8;
+            inaddr += p[15];
+            inaddr  = htonl(inaddr);
+            goto ipv4;
+        }
+
+        if (access6 == NULL) {
+            return NGX_DECLINED;
+        }
+
+        a6 = access6->elts;
+        for (i = 0; i < access6->nelts; i++) {
+            for (n = 0; n < 16; n++) {
+                if ((p[n] & a6[i].mask.s6_addr[n]) != a6[i].addr.s6_addr[n]) {
+                    goto next;
+                }
+            }
+            return NGX_OK;
+next:
+            continue;
+        }
+        return NGX_DECLINED;
+# endif
     }
 
     return NGX_DECLINED;
 }
 
+static ngx_uint_t
+ngx_http_cache_purge_method_equals(ngx_str_t *a, ngx_str_t *b) {
+    return a->len == b->len
+           && ngx_strncmp(a->data, b->data, a->len) == 0;
+}
+
+static ngx_uint_t
+ngx_http_cache_purge_request_has_method(ngx_http_request_t *r, ngx_str_t *method) {
+    return ngx_http_cache_purge_method_equals(&r->method_name, method);
+}
+
+static ngx_uint_t
+ngx_http_cache_purge_allows_runtime_dispatch(ngx_http_cache_purge_loc_conf_t *cplcf) {
+    return cplcf->conf == &cplcf->proxy
+           && (cplcf->conf->method.len == 0
+               || ngx_http_cache_purge_method_equals(&cplcf->conf->method,
+                    &ngx_http_cache_purge_method_purge)
+               || ngx_http_cache_purge_method_equals(&cplcf->conf->method,
+                   &ngx_http_cache_purge_method_refresh));
+}
+
+static ngx_uint_t
+ngx_http_cache_purge_is_runtime_refresh(ngx_http_request_t *r,
+    ngx_http_cache_purge_loc_conf_t *cplcf)
+{
+    if (ngx_http_cache_purge_allows_runtime_dispatch(cplcf)) {
+        if (ngx_http_cache_purge_request_has_method(r,
+                &ngx_http_cache_purge_method_refresh)) {
+            return 1;
+        }
+
+        if (ngx_http_cache_purge_request_has_method(r,
+                &ngx_http_cache_purge_method_purge)) {
+            return 0;
+        }
+    }
+
+    return cplcf->conf->refresh;
+}
+
+ngx_int_t
+ngx_http_cache_purge_add_action_header(ngx_http_request_t *r,
+    ngx_uint_t refresh)
+{
+    ngx_table_elt_t  *h;
+
+    h = ngx_list_push(&r->headers_out.headers);
+    if (h == NULL) {
+        return NGX_ERROR;
+    }
+
+    h->hash = 1;
+    ngx_str_set(&h->key, "X-Cache-Action");
+    if (refresh) {
+        ngx_str_set(&h->value, "refresh");
+
+    } else {
+        ngx_str_set(&h->value, "purge");
+    }
+
+    return NGX_OK;
+}
+
+static ngx_int_t
+ngx_http_cache_purge_send_capability_error(ngx_http_request_t *r,
+    ngx_uint_t refresh)
+{
+    ngx_buf_t    *b;
+    ngx_chain_t   out;
+    ngx_int_t     rc;
+    size_t        len;
+    const char   *msg;
+
+    msg = refresh
+          ? "refresh_all is not enabled for this location\n"
+          : "purge_all is not enabled for this location\n";
+    len = ngx_strlen(msg);
+
+    r->headers_out.status = NGX_HTTP_BAD_REQUEST;
+    r->headers_out.content_type.len = ngx_http_cache_purge_content_type_text_size - 1;
+    r->headers_out.content_type.data = (u_char *) ngx_http_cache_purge_content_type_text;
+    r->headers_out.content_length_n = len;
+
+    rc = ngx_http_send_header(r);
+    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
+        return rc;
+    }
+
+    b = ngx_create_temp_buf(r->pool, len);
+    if (b == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    b->last = ngx_cpymem(b->pos, msg, len);
+    b->last_buf = 1;
+    b->last_in_chain = 1;
+
+    out.buf = b;
+    out.next = NULL;
+
+    return ngx_http_output_filter(r, &out);
+}
+
 
 /* -- response builder --------------------------------------------------- */
 
@@ -2850,6 +3473,15 @@ ngx_http_cache_purge_send_response(ngx_http_request_t *r, ngx_str_t *status)
                                       ? NGX_HTTP_ACCEPTED : NGX_HTTP_OK;
     r->headers_out.content_length_n = (off_t) body_len;
 
+    if (ngx_http_cache_purge_add_action_header(r, 0) != NGX_OK) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    if (r->method == NGX_HTTP_HEAD) {
+        rc = ngx_http_send_header(r);
+        return rc;
+    }
+
     b = ngx_create_temp_buf(r->pool, body_len);
     if (b == NULL) {
         return NGX_HTTP_INTERNAL_SERVER_ERROR;
@@ -3033,6 +3665,7 @@ ngx_http_file_cache_purge(ngx_http_request_t *r)
 {
     ngx_http_file_cache_t *cache;
     ngx_http_cache_t      *c;
+    ngx_http_cache_purge_invalidate_result_e  result;
 
     switch (ngx_http_file_cache_open(r)) {
     case NGX_OK:
@@ -3058,37 +3691,17 @@ ngx_http_file_cache_purge(ngx_http_request_t *r)
     c     = r->cache;
     cache = c->file_cache;
 
-    ngx_shmtx_lock(&cache->shpool->mutex);
-
-    if (!c->node->exists) {
-        ngx_shmtx_unlock(&cache->shpool->mutex);
-        return NGX_DECLINED;
+    if (ngx_http_cache_purge_invalidate_opened_cache(r->connection->log,
+                                                     cache, c, NULL, NULL,
+                                                     &result)
+        != NGX_OK)
+    {
+        return NGX_ERROR;
     }
 
-# if (nginx_version >= 1000001)
-    cache->sh->size -= c->node->fs_size;
-    c->node->fs_size  = 0;
-# else
-    cache->sh->size -= (c->node->length + cache->bsize - 1) / cache->bsize;
-    c->node->length   = 0;
-# endif
-
-    c->node->exists = 0;
-# if (nginx_version >= 8001) \
-     || ((nginx_version < 8000) && (nginx_version >= 7060))
-    c->node->updating = 0;
-# endif
-
-    ngx_shmtx_unlock(&cache->shpool->mutex);
-
-    if (ngx_delete_file(c->file.name.data) == NGX_FILE_ERROR) {
-        ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno,
-                      "ngx_cache_purge: could not delete \"%V\"", &c->file.name);
-    } else {
-        ngx_log_debug1(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
-                       "ngx_cache_purge: deleted \"%V\"", &c->file.name);
+    if (result == NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_MISSING) {
+        return NGX_DECLINED;
     }
-
     return NGX_OK;
 }
 
@@ -3098,13 +3711,23 @@ ngx_http_file_cache_purge(ngx_http_request_t *r)
 void
 ngx_http_cache_purge_all(ngx_http_request_t *r, ngx_http_file_cache_t *cache)
 {
-    ngx_http_cache_purge_walk_ctx_t  ctx;
-    ngx_tree_ctx_t                   tree;
+    ngx_http_cache_purge_batch_ctx_t  ctx;
+    ngx_tree_ctx_t                    tree;
 
-    ngx_memzero(&ctx,  sizeof(ngx_http_cache_purge_walk_ctx_t));
+    ngx_memzero(&ctx, sizeof(ngx_http_cache_purge_batch_ctx_t));
     ngx_memzero(&tree, sizeof(ngx_tree_ctx_t));
 
-    tree.file_handler      = ngx_http_purge_file_cache_delete_file;
+    ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                  "purge_all http in %s",
+                  cache->path->name.data);
+
+    ctx.request   = r;
+    ctx.cache     = cache;
+    ctx.match_all = 1;
+    ctx.files_deleted = 0;
+    ngx_queue_init(&ctx.temp_pools);
+
+    tree.file_handler      = ngx_http_cache_purge_invalidate_file;
     tree.pre_tree_handler  = ngx_http_purge_file_cache_noop;
     tree.post_tree_handler = ngx_http_purge_file_cache_noop;
     tree.spec_handler      = ngx_http_purge_file_cache_noop;
@@ -3112,20 +3735,22 @@ ngx_http_cache_purge_all(ngx_http_request_t *r, ngx_http_file_cache_t *cache)
     tree.log               = ngx_cycle->log;
 
     ngx_walk_tree(&tree, &cache->path->name);
-
-    ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
-                   "ngx_cache_purge: purge_all deleted %ui file(s) "
-                   "from zone \"%V\"", ctx.files_deleted, &cache->path->name);
+    ngx_http_cache_purge_drain_temp_pools(&ctx.temp_pools);
 }
 
 ngx_uint_t
 ngx_http_cache_purge_partial(ngx_http_request_t *r,
     ngx_http_file_cache_t *cache)
 {
-    ngx_http_cache_purge_walk_ctx_t  ctx;
-    ngx_tree_ctx_t                   tree;
-    ngx_str_t                       *key;
-    ngx_uint_t                       len;
+    ngx_http_cache_purge_batch_ctx_t  ctx;
+    ngx_tree_ctx_t                    tree;
+    ngx_str_t                        *key;
+    ngx_uint_t                        len;
+
+    ngx_memzero(&ctx, sizeof(ngx_http_cache_purge_batch_ctx_t));
+    ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                  "purge_partial http in %s",
+                  cache->path->name.data);
 
     key = r->cache->keys.elts;
     len = key[0].len;
@@ -3134,13 +3759,18 @@ ngx_http_cache_purge_partial(ngx_http_request_t *r,
         len--;
     }
 
-    ngx_memzero(&ctx,  sizeof(ngx_http_cache_purge_walk_ctx_t));
+    ngx_memzero(&ctx, sizeof(ngx_http_cache_purge_batch_ctx_t));
     ngx_memzero(&tree, sizeof(ngx_tree_ctx_t));
 
-    ctx.key_partial = key[0].data;
-    ctx.key_len     = len;
+    ctx.request = r;
+    ctx.cache   = cache;
+    ctx.partial_prefix.data = key[0].data;
+    ctx.partial_prefix.len  = len;
+    ctx.files_deleted = 0;
+    ngx_queue_init(&ctx.temp_pools);
+    ctx.match_all = (len == 0);
 
-    tree.file_handler      = ngx_http_purge_file_cache_delete_partial_file;
+    tree.file_handler      = ngx_http_cache_purge_invalidate_partial_file;
     tree.pre_tree_handler  = ngx_http_purge_file_cache_noop;
     tree.post_tree_handler = ngx_http_purge_file_cache_noop;
     tree.spec_handler      = ngx_http_purge_file_cache_noop;
@@ -3148,10 +3778,7 @@ ngx_http_cache_purge_partial(ngx_http_request_t *r,
     tree.log               = ngx_cycle->log;
 
     ngx_walk_tree(&tree, &cache->path->name);
-
-    ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
-                   "ngx_cache_purge: partial walk deleted %ui file(s) "
-                   "for key prefix \"%V\"", ctx.files_deleted, &key[0]);
+    ngx_http_cache_purge_drain_temp_pools(&ctx.temp_pools);
 
     return ctx.files_deleted;
 }
@@ -3159,9 +3786,17 @@ ngx_http_cache_purge_partial(ngx_http_request_t *r,
 ngx_int_t
 ngx_http_cache_purge_is_partial(ngx_http_request_t *r)
 {
-    ngx_http_cache_t *c   = r->cache;
-    ngx_str_t        *key = c->keys.elts;
+    ngx_http_cache_t *c;
+    ngx_str_t        *key;
+
+    if (r->uri.len > 0 && r->uri.data[r->uri.len - 1] == '*') {
+        return 1;
+    }
+
+    c = r->cache;
+    key = c->keys.elts;
 
+    /* Only check the first key */
     return c->keys.nelts > 0
         && key[0].len > 0
         && key[0].data[key[0].len - 1] == '*';
@@ -3205,6 +3840,22 @@ ngx_http_cache_purge_conf(ngx_conf_t *cf, ngx_http_cache_purge_conf_t *cpcf)
         from_position++;
     }
 
+    if (from_position < cf->args->nelts
+        && ngx_strcmp(value[from_position].data, "refresh") == 0)
+    {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "the \"refresh\" parameter was removed from \"proxy_cache_purge\"; use \"proxy_cache_refresh\" instead");
+        return NGX_CONF_ERROR;
+    }
+
+
+    if (from_position >= cf->args->nelts) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "missing \"from\" keyword after optional parameters");
+        return NGX_CONF_ERROR;
+    }
+
+    /* sanity check */
     if (ngx_strcmp(value[from_position].data, "from") != 0) {
         ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
             "invalid parameter \"%V\", expected \"from\" keyword",
@@ -3212,6 +3863,12 @@ ngx_http_cache_purge_conf(ngx_conf_t *cf, ngx_http_cache_purge_conf_t *cpcf)
         return NGX_CONF_ERROR;
     }
 
+    if (from_position + 1 >= cf->args->nelts) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "missing argument after \"from\" keyword");
+        return NGX_CONF_ERROR;
+    }
+
     if (ngx_strcmp(value[from_position + 1].data, "all") == 0) {
         cpcf->enable = 1;
         return NGX_CONF_OK;
@@ -3279,6 +3936,134 @@ ngx_http_cache_purge_conf(ngx_conf_t *cf, ngx_http_cache_purge_conf_t *cpcf)
     return NGX_CONF_OK;
 }
 
+char *
+ngx_http_cache_refresh_conf(ngx_conf_t *cf, ngx_http_cache_purge_conf_t *cpcf) {
+    ngx_cidr_t       cidr;
+    ngx_in_cidr_t   *access;
+# if (NGX_HAVE_INET6)
+    ngx_in6_cidr_t  *access6;
+# endif /* NGX_HAVE_INET6 */
+    ngx_str_t       *value;
+    ngx_int_t        rc;
+    ngx_uint_t       i;
+    ngx_uint_t       from_position;
+
+    value = cf->args->elts;
+    from_position = 2;
+
+    if (ngx_strcmp(value[1].data, "on") == 0
+        || ngx_strcmp(value[1].data, "off") == 0)
+    {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "\"proxy_cache_refresh\" requires an explicit HTTP method such as \"REFRESH\"");
+        return NGX_CONF_ERROR;
+    }
+
+    cpcf->method = value[1];
+    cpcf->refresh = 1;
+
+    if (cf->args->nelts < 4) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "missing \"from\" keyword after refresh method");
+        return NGX_CONF_ERROR;
+    }
+
+    if (ngx_strcmp(value[from_position].data, "purge_all") == 0) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "unknown parameter \"purge_all\"; use \"refresh_all\" with \"proxy_cache_refresh\"");
+        return NGX_CONF_ERROR;
+    }
+
+    if (ngx_strcmp(value[from_position].data, "refresh_all") == 0) {
+        cpcf->purge_all = 1;
+        from_position++;
+    }
+
+    if (from_position >= cf->args->nelts) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "missing \"from\" keyword after optional parameters");
+        return NGX_CONF_ERROR;
+    }
+
+    if (ngx_strcmp(value[from_position].data, "from") != 0) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "invalid parameter \"%V\", expected \"from\" keyword",
+                           &value[from_position]);
+        return NGX_CONF_ERROR;
+    }
+
+    if (from_position + 1 >= cf->args->nelts) {
+        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                           "missing argument after \"from\" keyword");
+        return NGX_CONF_ERROR;
+    }
+
+    if (ngx_strcmp(value[from_position + 1].data, "all") == 0) {
+        cpcf->enable = 1;
+        return NGX_CONF_OK;
+    }
+
+    for (i = (from_position + 1); i < cf->args->nelts; i++) {
+        rc = ngx_ptocidr(&value[i], &cidr);
+
+        if (rc == NGX_ERROR) {
+            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                               "invalid parameter \"%V\"", &value[i]);
+            return NGX_CONF_ERROR;
+        }
+
+        if (rc == NGX_DONE) {
+            ngx_conf_log_error(NGX_LOG_WARN, cf, 0,
+                               "low address bits of %V are meaningless",
+                               &value[i]);
+        }
+
+        switch (cidr.family) {
+        case AF_INET:
+            if (cpcf->access == NULL) {
+                cpcf->access = ngx_array_create(cf->pool,
+                                                cf->args->nelts - (from_position + 1),
+                                                sizeof(ngx_in_cidr_t));
+                if (cpcf->access == NULL) {
+                    return NGX_CONF_ERROR;
+                }
+            }
+
+            access = ngx_array_push(cpcf->access);
+            if (access == NULL) {
+                return NGX_CONF_ERROR;
+            }
+
+            access->mask = cidr.u.in.mask;
+            access->addr = cidr.u.in.addr;
+            break;
+
+# if (NGX_HAVE_INET6)
+        case AF_INET6:
+            if (cpcf->access6 == NULL) {
+                cpcf->access6 = ngx_array_create(cf->pool,
+                                                 cf->args->nelts - (from_position + 1),
+                                                 sizeof(ngx_in6_cidr_t));
+                if (cpcf->access6 == NULL) {
+                    return NGX_CONF_ERROR;
+                }
+            }
+
+            access6 = ngx_array_push(cpcf->access6);
+            if (access6 == NULL) {
+                return NGX_CONF_ERROR;
+            }
+
+            access6->mask = cidr.u.in6.mask;
+            access6->addr = cidr.u.in6.addr;
+            break;
+# endif /* NGX_HAVE_INET6 */
+        }
+    }
+
+    cpcf->enable = 1;
+    return NGX_CONF_OK;
+}
 
 /* -- location configuration --------------------------------------------- */
 
@@ -3293,6 +4078,7 @@ ngx_http_cache_purge_merge_conf(ngx_http_cache_purge_conf_t *conf,
             conf->purge_all = prev->purge_all;
             conf->access    = prev->access;
             conf->access6   = prev->access6;
+            conf->refresh = prev->refresh;
         } else {
             conf->enable = 0;
         }
@@ -3332,6 +4118,8 @@ ngx_http_cache_purge_create_loc_conf(ngx_conf_t *cf)
 # endif
 
     conf->response_type = NGX_CONF_UNSET_UINT;
+    conf->refresh_concurrency = NGX_CONF_UNSET_UINT;
+    conf->refresh_timeout = NGX_CONF_UNSET_MSEC;
     conf->conf     = NGX_CONF_UNSET_PTR;
 
     return conf;
@@ -3373,6 +4161,7 @@ ngx_http_cache_purge_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
 # endif
 # if (NGX_HTTP_PROXY)
     ngx_flag_t  was_set_proxy;
+    ngx_http_proxy_loc_conf_t       *plcf;
 # endif
 # if (NGX_HTTP_SCGI)
     ngx_flag_t  was_set_scgi;
@@ -3399,6 +4188,11 @@ ngx_http_cache_purge_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
     ngx_conf_merge_uint_value(conf->response_type, prev->response_type,
                               NGX_CACHE_PURGE_RESPONSE_TYPE_HTML);
 
+    ngx_conf_merge_uint_value(conf->refresh_concurrency,
+                              prev->refresh_concurrency, 32);
+    ngx_conf_merge_msec_value(conf->refresh_timeout,
+                              prev->refresh_timeout, 600000);
+
 # if (NGX_HTTP_FASTCGI)
     ngx_http_cache_purge_merge_conf(&conf->fastcgi, &prev->fastcgi);
 
@@ -3416,6 +4210,18 @@ ngx_http_cache_purge_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
 # if (NGX_HTTP_PROXY)
     ngx_http_cache_purge_merge_conf(&conf->proxy, &prev->proxy);
 
+    if (conf->proxy.enable && conf->proxy.refresh) {
+        plcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_proxy_module);
+
+        if (!(plcf->upstream.upstream || plcf->proxy_lengths)
+            && !(conf->proxy_separate_zone || conf->proxy_separate_value))
+        {
+            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
+                               "\"proxy_cache_refresh\" is supported only with \"proxy_cache\"");
+            return NGX_CONF_ERROR;
+        }
+    }
+
     if (conf->proxy.enable) {
         conf->conf             = &conf->proxy;
         conf->handler          = ngx_http_proxy_cache_purge_handler;
diff --git a/ngx_http_cache_refresh.c b/ngx_http_cache_refresh.c
new file mode 100644
index 0000000..09a62e4
--- /dev/null
+++ b/ngx_http_cache_refresh.c
@@ -0,0 +1,1899 @@
+#include <ngx_config.h>
+#include <nginx.h>
+#include <ngx_core.h>
+#include <ngx_http.h>
+
+#include "ngx_http_cache_refresh.h"
+
+ngx_int_t ngx_http_cache_purge_add_action_header(
+    ngx_http_request_t *r, ngx_uint_t refresh);
+void ngx_http_cache_purge_drain_temp_pools(ngx_queue_t *queue);
+ngx_int_t ngx_http_cache_purge_invalidate_item(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool,
+    ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result);
+ngx_int_t ngx_http_cache_purge_is_partial(ngx_http_request_t *r);
+static ngx_int_t ngx_http_cache_purge_send_cache_key_error(
+    ngx_http_request_t *r);
+static ngx_flag_t ngx_http_cache_purge_refresh_infer_key_prefix_len(
+    ngx_str_t *key, ngx_str_t *targets, ngx_uint_t ntargets,
+    ngx_uint_t *prefix_len);
+static ngx_int_t ngx_http_cache_purge_refresh_collect_target_tails(
+    ngx_http_request_t *r, ngx_str_t *targets, ngx_uint_t max_targets,
+    ngx_uint_t *ntargets, ngx_flag_t partial);
+
+static ngx_str_t ngx_http_cache_purge_refresh_bypass_name =
+    ngx_string("cache_purge_refresh_bypass");
+
+static ngx_str_t ngx_http_head_method_name = ngx_string("HEAD");
+
+static ngx_int_t ngx_http_cache_purge_refresh_bypass_variable(
+    ngx_http_request_t *r, ngx_http_variable_value_t *v, uintptr_t data);
+static ngx_int_t ngx_http_cache_purge_refresh_record_status(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_uint_t status, off_t bytes);
+static size_t ngx_http_cache_purge_refresh_status_counts_text_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_counts_text(
+    u_char *p, ngx_array_t *status_counts);
+static size_t ngx_http_cache_purge_refresh_status_bytes_text_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_bytes_text(
+    u_char *p, ngx_array_t *status_counts);
+static size_t ngx_http_cache_purge_refresh_status_counts_json_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_counts_json(
+    u_char *p, ngx_array_t *status_counts);
+static size_t ngx_http_cache_purge_refresh_status_bytes_json_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_bytes_json(
+    u_char *p, ngx_array_t *status_counts);
+static size_t ngx_http_cache_purge_refresh_status_counts_log_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_counts_log(
+    u_char *p, ngx_array_t *status_counts);
+static size_t ngx_http_cache_purge_refresh_status_bytes_log_len(
+    ngx_array_t *status_counts);
+static u_char *ngx_http_cache_purge_refresh_write_status_bytes_log(
+    u_char *p, ngx_array_t *status_counts);
+static ngx_int_t ngx_http_cache_purge_refresh_collect_open_file(
+    ngx_http_request_t *r, ngx_http_cache_purge_refresh_ctx_t *ctx);
+static ngx_int_t ngx_http_cache_purge_refresh_collect_path(
+    ngx_http_cache_purge_refresh_ctx_t *rctx, ngx_str_t *path,
+    ngx_uint_t exact_match);
+static void ngx_http_cache_purge_refresh_start(ngx_http_request_t *r);
+static ngx_int_t ngx_http_cache_purge_refresh_fire_subrequest(
+    ngx_http_request_t *r, ngx_http_cache_purge_refresh_ctx_t *ctx);
+static ngx_int_t ngx_http_cache_purge_refresh_done(ngx_http_request_t *r,
+    void *data, ngx_int_t rc);
+static ngx_int_t ngx_http_cache_purge_refresh_enqueue_retired_chunk_pool(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_pool_t *pool);
+static void ngx_http_cache_purge_refresh_drain_retired_chunk_pools(
+    ngx_http_cache_purge_refresh_ctx_t *ctx);
+static ngx_int_t ngx_http_cache_purge_refresh_send_response(
+    ngx_http_request_t *r);
+static void ngx_http_cache_purge_refresh_timeout_handler(ngx_event_t *ev);
+static void ngx_http_cache_purge_refresh_mark_timeout(
+    ngx_http_cache_purge_refresh_ctx_t *ctx);
+static void ngx_http_cache_purge_refresh_pool_cleanup(void *data);
+static void ngx_http_cache_purge_refresh_finalize(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx);
+static ngx_int_t ngx_http_cache_purge_refresh_scan_next_chunk(
+    ngx_http_request_t *r, ngx_http_cache_purge_refresh_ctx_t *ctx);
+static ngx_int_t ngx_http_cache_purge_refresh_enqueue_dir(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_str_t *path);
+static ngx_int_t ngx_http_cache_purge_refresh_load_dir(
+    ngx_http_request_t *r, ngx_http_cache_purge_refresh_ctx_t *ctx,
+    ngx_str_t *path);
+static void ngx_http_cache_purge_refresh_do_invalidate(
+    ngx_http_request_t *r, ngx_http_cache_purge_refresh_ctx_t *ctx,
+    ngx_http_cache_purge_refresh_file_t *file, ngx_uint_t status);
+
+static ngx_int_t
+ngx_http_cache_purge_send_cache_key_error(ngx_http_request_t *r)
+{
+    ngx_buf_t    *b;
+    ngx_chain_t   out;
+    ngx_int_t     rc;
+    size_t        len;
+    const char   *msg;
+
+    msg = "refresh requires proxy_cache_key to end with uri or request_uri, or evaluate to uri/request_uri itself\n";
+    len = ngx_strlen(msg);
+
+    r->headers_out.status = NGX_HTTP_BAD_REQUEST;
+    r->headers_out.content_type.len = sizeof("text/plain") - 1;
+    r->headers_out.content_type.data = (u_char *) "text/plain";
+    r->headers_out.content_length_n = len;
+
+    rc = ngx_http_send_header(r);
+    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
+        return rc;
+    }
+
+    b = ngx_create_temp_buf(r->pool, len);
+    if (b == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    b->last = ngx_cpymem(b->pos, msg, len);
+    b->last_buf = 1;
+    b->last_in_chain = 1;
+
+    out.buf = b;
+    out.next = NULL;
+
+    return ngx_http_output_filter(r, &out);
+}
+
+
+static ngx_flag_t
+ngx_http_cache_purge_refresh_infer_key_prefix_len(ngx_str_t *key,
+        ngx_str_t *targets, ngx_uint_t ntargets, ngx_uint_t *prefix_len)
+{
+    ngx_uint_t  i;
+    size_t      j;
+    ngx_str_t   tail;
+    u_char      ch;
+
+    for (i = 0; i < ntargets; i++) {
+        if (targets[i].len > 0 && key->len >= targets[i].len
+            && ngx_strncmp(key->data + key->len - targets[i].len,
+                           targets[i].data, targets[i].len) == 0)
+        {
+            *prefix_len = key->len - targets[i].len;
+            return 1;
+        }
+    }
+
+    if (key->len > 0 && key->data[0] == '/') {
+        for (j = 0; j < key->len; j++) {
+            ch = key->data[j];
+
+            if (ch < 0x21 || ch == '|' || ch == '?' || ch == '#') {
+                return 0;
+            }
+        }
+
+        *prefix_len = 0;
+        return 1;
+    }
+
+    for (j = 1; j < key->len; j++) {
+        if (key->data[j] != '/') {
+            continue;
+        }
+
+        tail.len = key->len - j;
+        tail.data = key->data + j;
+
+        if (tail.len == 0) {
+            continue;
+        }
+
+        if (tail.data[0] != '/') {
+            continue;
+        }
+
+        for (i = 0; i < j; i++) {
+            ch = key->data[i];
+
+            if (ch < 0x21 || ch == '|' || ch == '/' || ch == '?' || ch == '#') {
+                break;
+            }
+        }
+
+        if (i != j) {
+            continue;
+        }
+
+        for (i = 0; i < ntargets; i++) {
+            if (targets[i].len == tail.len
+                && ngx_strncmp(tail.data, targets[i].data, tail.len) == 0)
+            {
+                *prefix_len = j;
+                return 1;
+            }
+        }
+    }
+
+    return 0;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_collect_target_tails(ngx_http_request_t *r,
+        ngx_str_t *targets, ngx_uint_t max_targets, ngx_uint_t *ntargets,
+        ngx_flag_t partial)
+{
+    ngx_str_t    tail, capture, capture_source;
+    ngx_uint_t   i, ncaptures;
+    intptr_t     start, end;
+    u_char      *p, *data;
+
+    *ntargets = 0;
+
+    tail = r->unparsed_uri;
+
+    if (partial && tail.len > 0 && tail.data[tail.len - 1] == '*') {
+        tail.len--;
+    }
+
+    if (tail.len > 0 && *ntargets < max_targets) {
+        targets[(*ntargets)++] = tail;
+    }
+
+    tail = r->uri;
+
+    if (partial && tail.len > 0 && tail.data[tail.len - 1] == '*') {
+        tail.len--;
+    }
+
+    if (tail.len > 0 && *ntargets < max_targets
+            && (*ntargets == 0 || targets[0].len != tail.len
+                || ngx_strncmp(targets[0].data, tail.data, tail.len) != 0))
+    {
+        targets[(*ntargets)++] = tail;
+    }
+
+    if (r->captures == NULL || r->captures_data == NULL || r->ncaptures < 2) {
+        return NGX_OK;
+    }
+
+    capture_source = r->unparsed_uri;
+    if (r->captures_data == r->uri.data) {
+        capture_source = r->uri;
+
+    } else if (r->captures_data != r->unparsed_uri.data) {
+        return NGX_OK;
+    }
+
+    data = capture_source.data;
+    ncaptures = r->ncaptures / 2;
+
+    for (i = 0; i < ncaptures && *ntargets < max_targets; i++) {
+        start = r->captures[i * 2];
+        end = r->captures[i * 2 + 1];
+
+        if (start < 0 || end < start
+            || (size_t) end > capture_source.len)
+        {
+            continue;
+        }
+
+        capture.data = &data[start];
+        capture.len = (size_t) (end - start);
+
+        if (capture.len == 0 || capture.data[0] != '/') {
+            continue;
+        }
+
+        if (partial && capture.len > 0
+            && capture.data[capture.len - 1] == '*')
+        {
+            capture.len--;
+        }
+
+        if (r->args.len == 0) {
+            targets[(*ntargets)++] = capture;
+            continue;
+        }
+
+        p = ngx_pnalloc(r->pool, capture.len + 1 + r->args.len);
+        if (p == NULL) {
+            return NGX_ERROR;
+        }
+
+        ngx_memcpy(p, capture.data, capture.len);
+        p[capture.len] = '?';
+        ngx_memcpy(p + capture.len + 1, r->args.data, r->args.len);
+
+        tail.data = p;
+        tail.len = capture.len + 1 + r->args.len;
+        targets[(*ntargets)++] = tail;
+    }
+
+    return NGX_OK;
+}
+
+/* Restore HEAD requests for refresh subrequests and expose bypass variable. */
+static ngx_int_t
+ngx_http_cache_purge_refresh_bypass_variable(ngx_http_request_t *r,
+    ngx_http_variable_value_t *v, uintptr_t data)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+
+    if (r->parent != NULL) {
+        ctx = ngx_http_get_module_ctx(r->parent, ngx_http_cache_purge_module);
+        if (ctx != NULL) {
+            v->len = 1;
+            v->valid = 1;
+            v->no_cacheable = 1;
+            v->not_found = 0;
+            v->data = (u_char *) "1";
+
+            if (r->upstream != NULL && r->method == NGX_HTTP_HEAD) {
+                r->upstream->method.len = 0;
+                r->upstream->method.data = NULL;
+            }
+
+            return NGX_OK;
+        }
+    }
+
+    v->not_found = 1;
+    return NGX_OK;
+}
+
+
+ngx_int_t
+ngx_http_cache_purge_add_variable(ngx_conf_t *cf)
+{
+    ngx_http_variable_t *var;
+
+    var = ngx_http_add_variable(cf, &ngx_http_cache_purge_refresh_bypass_name,
+                                NGX_HTTP_VAR_NOCACHEABLE);
+    if (var == NULL) {
+        return NGX_ERROR;
+    }
+
+    var->get_handler = ngx_http_cache_purge_refresh_bypass_variable;
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_collect_open_file(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    switch (ngx_http_file_cache_open(r)) {
+    case NGX_OK:
+    case NGX_HTTP_CACHE_STALE:
+#if (nginx_version >= 8001) || ((nginx_version < 8000) && (nginx_version >= 7060))
+    case NGX_HTTP_CACHE_UPDATING:
+#endif
+        return ngx_http_cache_purge_refresh_collect_path(ctx,
+                                                         &r->cache->file.name,
+                                                         1);
+
+    case NGX_DECLINED:
+        return NGX_OK;
+
+#if (NGX_HAVE_FILE_AIO)
+    case NGX_AGAIN:
+#endif
+    default:
+        return NGX_ERROR;
+    }
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_collect_path(
+    ngx_http_cache_purge_refresh_ctx_t *rctx, ngx_str_t *path,
+    ngx_uint_t exact_match)
+{
+    ngx_http_cache_purge_refresh_file_t *file;
+    ngx_http_file_cache_header_t header;
+    ngx_file_t f;
+    ngx_file_info_t fi;
+    ngx_str_t path_copy, uri, args, etag, cache_key;
+    ngx_http_cache_purge_invalidate_item_t item;
+    u_char *key_buf;
+    u_char *path_data;
+    u_char *uri_data;
+    u_char *args_data;
+    u_char *etag_data;
+    u_char *cache_key_data;
+    ssize_t n;
+    size_t key_read_len;
+    u_char *p, *q;
+    ngx_pool_t *pool;
+
+    ngx_memzero(&path_copy, sizeof(ngx_str_t));
+    ngx_memzero(&uri, sizeof(ngx_str_t));
+    ngx_memzero(&args, sizeof(ngx_str_t));
+    ngx_memzero(&etag, sizeof(ngx_str_t));
+    ngx_memzero(&cache_key, sizeof(ngx_str_t));
+    ngx_memzero(&item, sizeof(ngx_http_cache_purge_invalidate_item_t));
+
+    pool = rctx->chunk_pool != NULL ? rctx->chunk_pool : rctx->request->pool;
+
+    if (rctx->timeout_enabled && !rctx->timed_out
+        && ngx_current_msec >= rctx->deadline)
+    {
+        ngx_http_cache_purge_refresh_mark_timeout(rctx);
+        return NGX_ABORT;
+    }
+
+    ngx_memzero(&f, sizeof(ngx_file_t));
+    f.fd = ngx_open_file(path->data, NGX_FILE_RDONLY, NGX_FILE_OPEN,
+                         NGX_FILE_DEFAULT_ACCESS);
+    if (f.fd == NGX_INVALID_FILE) {
+        return NGX_OK;
+    }
+    f.name.data = path->data;
+    f.name.len = path->len;
+    f.log = ngx_cycle->log;
+
+    if (ngx_fd_info(f.fd, &fi) == NGX_FILE_ERROR) {
+        ngx_close_file(f.fd);
+        return NGX_OK;
+    }
+
+    n = ngx_read_file(&f, (u_char *) &header, sizeof(header), 0);
+    if (n < (ssize_t) sizeof(header)) {
+        ngx_close_file(f.fd);
+        return NGX_OK;
+    }
+
+    if (header.header_start <= sizeof(header) + 6) {
+        ngx_close_file(f.fd);
+        return NGX_OK;
+    }
+
+    key_read_len = header.header_start - sizeof(header) - 6;
+    if (key_read_len == 0 || key_read_len > 8192) {
+        ngx_close_file(f.fd);
+        return NGX_OK;
+    }
+
+    key_buf = ngx_alloc(key_read_len + 1, ngx_cycle->log);
+    if (key_buf == NULL) {
+        ngx_close_file(f.fd);
+        return NGX_ERROR;
+    }
+
+    n = ngx_read_file(&f, key_buf, key_read_len, sizeof(header) + 6);
+    ngx_close_file(f.fd);
+
+    if (n < 1) {
+        ngx_free(key_buf);
+        return NGX_OK;
+    }
+
+    key_buf[n] = '\0';
+    if (n > 0 && key_buf[n - 1] == LF) {
+        key_buf[n - 1] = '\0';
+        n--;
+    }
+
+    if (exact_match) {
+        if ((size_t) n != rctx->key_partial.len
+            || ngx_strncmp(key_buf, rctx->key_partial.data,
+                           rctx->key_partial.len) != 0)
+        {
+            ngx_free(key_buf);
+            return NGX_OK;
+        }
+
+    } else if (!rctx->purge_all && rctx->key_partial.len > 0) {
+        if ((size_t) n < rctx->key_partial.len) {
+            ngx_free(key_buf);
+            return NGX_OK;
+        }
+        if (ngx_strncmp(key_buf, rctx->key_partial.data,
+                        rctx->key_partial.len) != 0)
+        {
+            ngx_free(key_buf);
+            return NGX_OK;
+        }
+    }
+
+    if ((size_t) n < rctx->key_prefix_len) {
+        ngx_free(key_buf);
+        return NGX_OK;
+    }
+
+    path_data = ngx_pnalloc(pool, path->len + 1);
+    if (path_data == NULL) {
+        ngx_free(key_buf);
+        return NGX_ERROR;
+    }
+    ngx_memcpy(path_data, path->data, path->len);
+    path_data[path->len] = '\0';
+    path_copy.len = path->len;
+    path_copy.data = path_data;
+    item.cache_path = path_copy;
+
+    p = key_buf + rctx->key_prefix_len;
+    q = (u_char *) ngx_strchr(p, '?');
+    if (q != NULL) {
+        uri.len = q - p;
+        uri_data = ngx_pnalloc(pool, uri.len + 1);
+        if (uri_data == NULL) {
+            ngx_free(key_buf);
+            return NGX_ERROR;
+        }
+        ngx_memcpy(uri_data, p, uri.len);
+        uri_data[uri.len] = '\0';
+        uri.data = uri_data;
+
+        q++;
+        if ((size_t) n < rctx->key_prefix_len + uri.len + 1) {
+            ngx_free(key_buf);
+            return NGX_OK;
+        }
+        args.len = n - rctx->key_prefix_len - uri.len - 1;
+        args_data = ngx_pnalloc(pool, args.len + 1);
+        if (args_data == NULL) {
+            ngx_free(key_buf);
+            return NGX_ERROR;
+        }
+        ngx_memcpy(args_data, q, args.len);
+        args_data[args.len] = '\0';
+        args.data = args_data;
+    } else {
+        uri.len = n - rctx->key_prefix_len;
+        uri_data = ngx_pnalloc(pool, uri.len + 1);
+        if (uri_data == NULL) {
+            ngx_free(key_buf);
+            return NGX_ERROR;
+        }
+        ngx_memcpy(uri_data, p, uri.len);
+        uri_data[uri.len] = '\0';
+        uri.data = uri_data;
+    }
+
+    if (header.etag_len > 0 && header.etag_len < NGX_HTTP_CACHE_ETAG_LEN) {
+        etag_data = ngx_pnalloc(pool, header.etag_len + 1);
+        if (etag_data == NULL) {
+            ngx_free(key_buf);
+            return NGX_ERROR;
+        }
+        ngx_memcpy(etag_data, header.etag, header.etag_len);
+        etag_data[header.etag_len] = '\0';
+        etag.len = header.etag_len;
+        etag.data = etag_data;
+    }
+
+    item.etag_len = etag.len;
+    if (etag.len > 0) {
+        ngx_memcpy(item.etag, etag.data, etag.len);
+    }
+
+    item.uniq = ngx_file_uniq(&fi);
+    item.last_modified = header.last_modified;
+    item.body_start = header.body_start;
+    item.fs_size = ngx_file_size(&fi);
+
+    cache_key_data = ngx_pnalloc(pool, n + 1);
+    if (cache_key_data == NULL) {
+        ngx_free(key_buf);
+        return NGX_ERROR;
+    }
+    ngx_memcpy(cache_key_data, key_buf, n);
+    cache_key_data[n] = '\0';
+    cache_key.len = n;
+    cache_key.data = cache_key_data;
+    item.cache_key = cache_key;
+
+    ngx_free(key_buf);
+
+    file = ngx_array_push(rctx->files);
+    if (file == NULL) {
+        return NGX_ERROR;
+    }
+
+    file->path = path_copy;
+    file->uri = uri;
+    file->args = args;
+    file->etag = etag;
+    file->last_modified = header.last_modified;
+    file->item = item;
+
+    rctx->queued++;
+    rctx->total++;
+    rctx->total_bytes += item.fs_size;
+
+    ngx_log_debug3(NGX_LOG_DEBUG_HTTP, ngx_cycle->log, 0,
+                   "refresh collect: uri=\"%V\" etag=\"%V\" path=\"%V\"",
+                   &file->uri, &file->etag, &file->path);
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_record_status(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_uint_t status, off_t bytes)
+{
+    ngx_uint_t i;
+    ngx_http_cache_purge_refresh_status_count_t *entry;
+
+    if (ctx->status_counts == NULL) {
+        return NGX_ERROR;
+    }
+
+    entry = ctx->status_counts->elts;
+    for (i = 0; i < ctx->status_counts->nelts; i++) {
+        if (entry[i].status == status) {
+            entry[i].count++;
+            entry[i].bytes += bytes;
+            return NGX_OK;
+        }
+    }
+
+    entry = ngx_array_push(ctx->status_counts);
+    if (entry == NULL) {
+        return NGX_ERROR;
+    }
+
+    entry->status = status;
+    entry->count = 1;
+    entry->bytes = bytes;
+
+    return NGX_OK;
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_counts_text_len(ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    size_t len;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return 0;
+    }
+
+    len = sizeof(" statuses={}") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        len += 2 * NGX_INT_T_LEN;
+        if (i != 0) {
+            len++;
+        }
+    }
+
+    return len;
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_counts_text(u_char *p,
+    ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    ngx_http_cache_purge_refresh_status_count_t *entry;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return p;
+    }
+
+    entry = status_counts->elts;
+    *p++ = ' ';
+    ngx_memcpy(p, "statuses={", sizeof("statuses={") - 1);
+    p += sizeof("statuses={") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        if (i != 0) {
+            *p++ = ',';
+        }
+
+        p = ngx_sprintf(p, "%ui:%ui", entry[i].status, entry[i].count);
+    }
+
+    *p++ = '}';
+
+    return p;
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_bytes_text_len(ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    size_t len;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return 0;
+    }
+
+    len = sizeof(" status_bytes={}") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        len += NGX_INT_T_LEN + NGX_OFF_T_LEN + 1;
+        if (i != 0) {
+            len++;
+        }
+    }
+
+    return len;
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_bytes_text(u_char *p,
+    ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    ngx_http_cache_purge_refresh_status_count_t *entry;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return p;
+    }
+
+    entry = status_counts->elts;
+    *p++ = ' ';
+    ngx_memcpy(p, "status_bytes={", sizeof("status_bytes={") - 1);
+    p += sizeof("status_bytes={") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        if (i != 0) {
+            *p++ = ',';
+        }
+
+        p = ngx_sprintf(p, "%ui:%O", entry[i].status, entry[i].bytes);
+    }
+
+    *p++ = '}';
+
+    return p;
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_counts_json_len(ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    size_t len;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return sizeof(",\"status_counts\":{}") - 1;
+    }
+
+    len = sizeof(",\"status_counts\":{}") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        len += 2 * NGX_INT_T_LEN + 4;
+        if (i != 0) {
+            len++;
+        }
+    }
+
+    return len;
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_bytes_json_len(ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    size_t len;
+
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return sizeof(",\"status_bytes\":{}") - 1;
+    }
+
+    len = sizeof(",\"status_bytes\":{}") - 1;
+
+    for (i = 0; i < status_counts->nelts; i++) {
+        len += NGX_INT_T_LEN + NGX_OFF_T_LEN + 4;
+        if (i != 0) {
+            len++;
+        }
+    }
+
+    return len;
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_bytes_json(u_char *p,
+    ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    ngx_http_cache_purge_refresh_status_count_t *entry;
+
+    ngx_memcpy(p, ",\"status_bytes\":{", sizeof(",\"status_bytes\":{") - 1);
+    p += sizeof(",\"status_bytes\":{") - 1;
+
+    if (status_counts != NULL && status_counts->nelts != 0) {
+        entry = status_counts->elts;
+        for (i = 0; i < status_counts->nelts; i++) {
+            if (i != 0) {
+                *p++ = ',';
+            }
+
+            p = ngx_sprintf(p, "\"%ui\":%O", entry[i].status,
+                            entry[i].bytes);
+        }
+    }
+
+    *p++ = '}';
+
+    return p;
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_counts_json(u_char *p,
+    ngx_array_t *status_counts)
+{
+    ngx_uint_t i;
+    ngx_http_cache_purge_refresh_status_count_t *entry;
+
+    ngx_memcpy(p, ",\"status_counts\":{", sizeof(",\"status_counts\":{") - 1);
+    p += sizeof(",\"status_counts\":{") - 1;
+
+    if (status_counts != NULL && status_counts->nelts != 0) {
+        entry = status_counts->elts;
+        for (i = 0; i < status_counts->nelts; i++) {
+            if (i != 0) {
+                *p++ = ',';
+            }
+
+            p = ngx_sprintf(p, "\"%ui\":%ui", entry[i].status,
+                            entry[i].count);
+        }
+    }
+
+    *p++ = '}';
+
+    return p;
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_counts_log_len(ngx_array_t *status_counts)
+{
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return 0;
+    }
+
+    return ngx_http_cache_purge_refresh_status_counts_text_len(status_counts);
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_counts_log(u_char *p,
+    ngx_array_t *status_counts)
+{
+    return ngx_http_cache_purge_refresh_write_status_counts_text(p,
+            status_counts);
+}
+
+
+static size_t
+ngx_http_cache_purge_refresh_status_bytes_log_len(ngx_array_t *status_counts)
+{
+    if (status_counts == NULL || status_counts->nelts == 0) {
+        return 0;
+    }
+
+    return ngx_http_cache_purge_refresh_status_bytes_text_len(status_counts);
+}
+
+
+static u_char *
+ngx_http_cache_purge_refresh_write_status_bytes_log(u_char *p,
+    ngx_array_t *status_counts)
+{
+    return ngx_http_cache_purge_refresh_write_status_bytes_text(p,
+            status_counts);
+}
+
+
+static void
+ngx_http_cache_purge_refresh_do_invalidate(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx,
+    ngx_http_cache_purge_refresh_file_t *file, ngx_uint_t status)
+{
+    ngx_pool_t *pool;
+    ngx_http_cache_purge_invalidate_result_e invalidate_result;
+
+    pool = ngx_create_pool(4096, r->connection->log);
+    if (pool == NULL) {
+        ctx->errors++;
+        return;
+    }
+
+    if (ngx_http_cache_purge_invalidate_item(ctx->request, ctx->cache,
+            pool, &file->item, &invalidate_result) != NGX_OK)
+    {
+        ctx->errors++;
+        ngx_log_error(NGX_LOG_CRIT, r->connection->log, 0,
+                      "refresh invalidate failed (%ui) for \"%V\"",
+                      status, &file->uri);
+    } else {
+        if (invalidate_result == NGX_HTTP_CACHE_PURGE_INVALIDATE_PURGED) {
+            ctx->purged++;
+            ctx->purged_bytes += file->item.fs_size;
+            ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                           "refresh: %ui purged \"%V\"", status,
+                           &file->uri);
+        } else if (invalidate_result
+                   == NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_MISSING
+                   || invalidate_result
+                   == NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_REPLACED)
+        {
+            ctx->refreshed++;
+            ctx->kept_bytes += file->item.fs_size;
+            ngx_log_debug3(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                           "refresh: %ui race-kept (%ui) \"%V\"",
+                           status, invalidate_result, &file->uri);
+        } else {
+            ctx->errors++;
+        }
+    }
+
+    ngx_destroy_pool(pool);
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_done(ngx_http_request_t *r, void *data,
+    ngx_int_t rc)
+{
+    ngx_http_cache_purge_refresh_post_data_t *pd;
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+    ngx_http_cache_purge_refresh_file_t *file;
+    ngx_uint_t status;
+
+    pd = data;
+    ctx = pd->ctx;
+
+    if (pd->handled) {
+        return NGX_OK;
+    }
+
+    pd->handled = 1;
+
+    if (ctx->finalized) {
+        return NGX_OK;
+    }
+
+    file = pd->file;
+
+    if (!pd->validation_ready) {
+        ctx->errors++;
+        if (ctx->active > 0) {
+            ctx->active--;
+        }
+
+        return NGX_OK;
+    }
+
+    if (rc != NGX_OK) {
+        ctx->errors++;
+        if (ctx->active > 0) {
+            ctx->active--;
+        }
+
+        return NGX_OK;
+    }
+
+    status = 0;
+    if (r->upstream != NULL) {
+        status = r->upstream->headers_in.status_n;
+    } else if (r->headers_out.status) {
+        status = r->headers_out.status;
+    }
+
+    if (status != 0
+        && ngx_http_cache_purge_refresh_record_status(ctx, status,
+                                                       file->item.fs_size)
+        != NGX_OK)
+    {
+        ctx->errors++;
+        if (ctx->active > 0) {
+            ctx->active--;
+        }
+
+        return NGX_OK;
+    }
+
+    if (status == NGX_HTTP_NOT_MODIFIED) {
+        ctx->refreshed++;
+        ctx->kept_bytes += file->item.fs_size;
+        ngx_log_debug1(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                       "refresh: 304 kept \"%V\"", &file->uri);
+    } else if (status == NGX_HTTP_OK) {
+        ngx_http_cache_purge_refresh_do_invalidate(r, ctx, file, status);
+    } else if (status == NGX_HTTP_NOT_FOUND || status == 410) {
+        ngx_http_cache_purge_refresh_do_invalidate(r, ctx, file, status);
+    } else if (status == 0) {
+        ctx->errors++;
+        ngx_log_debug1(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                       "refresh: no response, error \"%V\"", &file->uri);
+    } else {
+        ctx->refreshed++;
+        ctx->kept_bytes += file->item.fs_size;
+        ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                       "refresh: %ui kept \"%V\"", status, &file->uri);
+    }
+
+    if (ctx->active > 0) {
+        ctx->active--;
+    }
+
+    if (ctx->timed_out) {
+        if (ctx->current < ctx->queued) {
+            ctx->errors += ctx->queued - ctx->current;
+            ctx->current = ctx->queued;
+        }
+    }
+
+    ngx_http_post_request(ctx->request, NULL);
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_fire_subrequest(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+    ngx_http_cache_purge_refresh_file_t *file;
+    ngx_http_cache_purge_refresh_post_data_t *pd;
+    ngx_http_request_t *sr;
+    ngx_http_post_subrequest_t *ps;
+    ngx_int_t rc;
+    ngx_table_elt_t *h;
+    u_char *time_buf;
+
+    if (ctx->current >= ctx->queued) {
+        return NGX_OK;
+    }
+
+    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+
+    if (cplcf->refresh_timeout != 0 && ngx_current_msec >= ctx->deadline) {
+        ngx_http_cache_purge_refresh_mark_timeout(ctx);
+        return NGX_ABORT;
+    }
+
+    file = (ngx_http_cache_purge_refresh_file_t *) ctx->files->elts
+           + ctx->current;
+
+    ps = ngx_palloc(r->pool, sizeof(ngx_http_post_subrequest_t));
+    if (ps == NULL) {
+        return NGX_ERROR;
+    }
+
+    pd = ngx_palloc(r->pool, sizeof(ngx_http_cache_purge_refresh_post_data_t));
+    if (pd == NULL) {
+        return NGX_ERROR;
+    }
+    pd->ctx = ctx;
+    pd->file = file;
+    pd->validation_ready = 0;
+    pd->handled = 0;
+
+    ps->handler = ngx_http_cache_purge_refresh_done;
+    ps->data = pd;
+
+    rc = ngx_http_subrequest(r, &file->uri,
+                             file->args.len > 0 ? &file->args : NULL,
+                             &sr, ps,
+                             NGX_HTTP_SUBREQUEST_BACKGROUND);
+    if (rc != NGX_OK) {
+        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
+                      "refresh fire subrequest failed rc=%i uri=\"%V\"",
+                      rc, &file->uri);
+        ctx->errors++;
+        return rc;
+    }
+
+    ctx->current++;
+    ctx->active++;
+    ctx->dispatched++;
+
+    sr->method = NGX_HTTP_HEAD;
+    sr->method_name = ngx_http_head_method_name;
+    sr->header_only = 1;
+
+    if (ngx_list_init(&sr->headers_in.headers, r->pool, 8,
+                      sizeof(ngx_table_elt_t)) != NGX_OK)
+    {
+        pd->handled = 1;
+        ctx->errors++;
+        if (ctx->active > 0) { ctx->active--; }
+        if (ngx_http_post_request(ctx->request, NULL) != NGX_OK) {
+            return NGX_ERROR;
+        }
+        return NGX_OK;
+    }
+
+    if (r->headers_in.host != NULL) {
+        h = ngx_list_push(&sr->headers_in.headers);
+        if (h == NULL) {
+            pd->handled = 1;
+            ctx->errors++;
+            if (ctx->active > 0) { ctx->active--; }
+            if (ngx_http_post_request(ctx->request, NULL) != NGX_OK) {
+                return NGX_ERROR;
+            }
+            return NGX_OK;
+        }
+        *h = *r->headers_in.host;
+        sr->headers_in.host = h;
+    }
+
+    sr->headers_in.if_none_match = NULL;
+    sr->headers_in.if_modified_since = NULL;
+
+    if (file->etag.len > 0) {
+        h = ngx_list_push(&sr->headers_in.headers);
+        if (h == NULL) {
+            pd->handled = 1;
+            ctx->errors++;
+            if (ctx->active > 0) { ctx->active--; }
+            if (ngx_http_post_request(ctx->request, NULL) != NGX_OK) {
+                return NGX_ERROR;
+            }
+            return NGX_OK;
+        }
+        h->hash = 1;
+        ngx_str_set(&h->key, "If-None-Match");
+        h->value = file->etag;
+        h->lowcase_key = (u_char *) "if-none-match";
+        sr->headers_in.if_none_match = h;
+    }
+
+    if (file->last_modified > 0) {
+        h = ngx_list_push(&sr->headers_in.headers);
+        if (h == NULL) {
+            pd->handled = 1;
+            ctx->errors++;
+            if (ctx->active > 0) { ctx->active--; }
+            if (ngx_http_post_request(ctx->request, NULL) != NGX_OK) {
+                return NGX_ERROR;
+            }
+            return NGX_OK;
+        }
+        time_buf = ngx_pnalloc(r->pool,
+                               sizeof("Mon, 28 Sep 1970 06:00:00 GMT"));
+        if (time_buf == NULL) {
+            pd->handled = 1;
+            ctx->errors++;
+            if (ctx->active > 0) { ctx->active--; }
+            if (ngx_http_post_request(ctx->request, NULL) != NGX_OK) {
+                return NGX_ERROR;
+            }
+            return NGX_OK;
+        }
+        h->hash = 1;
+        ngx_str_set(&h->key, "If-Modified-Since");
+        h->value.data = time_buf;
+        ngx_http_time(time_buf, file->last_modified);
+        h->value.len = sizeof("Mon, 28 Sep 1970 06:00:00 GMT") - 1;
+        h->lowcase_key = (u_char *) "if-modified-since";
+        sr->headers_in.if_modified_since = h;
+    }
+
+    pd->validation_ready = 1;
+
+    ngx_log_debug3(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                   "refresh: fired subrequest for \"%V\" (%ui/%ui)",
+                   &file->uri, ctx->current, ctx->queued);
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_send_response(ngx_http_request_t *r)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+    ngx_buf_t *b;
+    ngx_chain_t out;
+    ngx_int_t rc;
+    size_t len;
+    u_char *p;
+
+    ctx = ngx_http_get_module_ctx(r, ngx_http_cache_purge_module);
+    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+
+    if (cplcf->response_type == NGX_CACHE_PURGE_RESPONSE_TYPE_JSON) {
+        len = sizeof("{\"status\":\"refresh\",\"total\":,\"kept\":,\"purged\":,\"errors\":,\"total_bytes\":,\"kept_bytes\":,\"purged_bytes\":}")
+              + 4 * NGX_INT_T_LEN + 3 * NGX_OFF_T_LEN
+              + ngx_http_cache_purge_refresh_status_counts_json_len(ctx->status_counts)
+              + ngx_http_cache_purge_refresh_status_bytes_json_len(ctx->status_counts);
+
+        r->headers_out.content_type.len = sizeof("application/json") - 1;
+        r->headers_out.content_type.data = (u_char *) "application/json";
+    } else {
+        len = sizeof("Refresh: total= kept= purged= errors= total_bytes= kept_bytes= purged_bytes=\n")
+              + 4 * NGX_INT_T_LEN + 3 * NGX_OFF_T_LEN
+              + ngx_http_cache_purge_refresh_status_counts_text_len(ctx->status_counts)
+              + ngx_http_cache_purge_refresh_status_bytes_text_len(ctx->status_counts);
+
+        r->headers_out.content_type.len = sizeof("text/plain") - 1;
+        r->headers_out.content_type.data = (u_char *) "text/plain";
+    }
+
+    b = ngx_create_temp_buf(r->pool, len);
+    if (b == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    if (cplcf->response_type == NGX_CACHE_PURGE_RESPONSE_TYPE_JSON) {
+        p = ngx_sprintf(b->pos,
+                        "{\"status\":\"refresh\",\"total\":%ui,\"kept\":%ui,"
+                        "\"purged\":%ui,\"errors\":%ui,"
+                        "\"total_bytes\":%O,\"kept_bytes\":%O,\"purged_bytes\":%O",
+                        ctx->total, ctx->refreshed, ctx->purged, ctx->errors,
+                        ctx->total_bytes, ctx->kept_bytes, ctx->purged_bytes);
+        p = ngx_http_cache_purge_refresh_write_status_counts_json(p,
+                ctx->status_counts);
+        p = ngx_http_cache_purge_refresh_write_status_bytes_json(p,
+                ctx->status_counts);
+        *p++ = '}';
+    } else {
+        p = ngx_sprintf(b->pos,
+                        "Refresh: total=%ui kept=%ui purged=%ui errors=%ui total_bytes=%O kept_bytes=%O purged_bytes=%O",
+                        ctx->total, ctx->refreshed, ctx->purged, ctx->errors,
+                        ctx->total_bytes, ctx->kept_bytes, ctx->purged_bytes);
+        p = ngx_http_cache_purge_refresh_write_status_counts_text(p,
+                ctx->status_counts);
+        p = ngx_http_cache_purge_refresh_write_status_bytes_text(p,
+                ctx->status_counts);
+        *p++ = '\n';
+    }
+
+    b->last = p;
+    b->last_buf = 1;
+    b->last_in_chain = 1;
+
+    r->headers_out.status = NGX_HTTP_OK;
+    r->headers_out.content_length_n = p - b->pos;
+
+    if (ngx_http_cache_purge_add_action_header(r, 1) != NGX_OK) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    rc = ngx_http_send_header(r);
+    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
+        return rc;
+    }
+
+    out.buf = b;
+    out.next = NULL;
+
+    return ngx_http_output_filter(r, &out);
+}
+
+
+static void
+ngx_http_cache_purge_refresh_mark_timeout(ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+    ngx_uint_t skipped;
+
+    if (ctx->timed_out) {
+        return;
+    }
+
+    ctx->timed_out = 1;
+    cplcf = ngx_http_get_module_loc_conf(ctx->request,
+                                         ngx_http_cache_purge_module);
+
+    if (ctx->dispatched < ctx->total) {
+        skipped = ctx->total - ctx->dispatched;
+        ctx->errors += skipped;
+        ctx->current = ctx->queued;
+        ctx->dispatched = ctx->total;
+    } else {
+        skipped = 0;
+    }
+
+    ngx_log_error(NGX_LOG_ERR, ctx->request->connection->log, 0,
+                  "cache purge refresh timed out after %M ms, skipped %ui pending entries",
+                  cplcf->refresh_timeout, skipped);
+}
+
+
+static void
+ngx_http_cache_purge_refresh_pool_cleanup(void *data)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+
+    ctx = data;
+
+    if (ctx == NULL) {
+        return;
+    }
+
+    ctx->finalized = 1;
+
+    if (ctx->timeout_ev.timer_set) {
+        ngx_del_timer(&ctx->timeout_ev);
+    }
+
+    if (ctx->scan_pool != NULL) {
+        ngx_destroy_pool(ctx->scan_pool);
+        ctx->scan_pool = NULL;
+    }
+
+    ngx_http_cache_purge_drain_temp_pools(&ctx->temp_pools);
+    ngx_http_cache_purge_refresh_drain_retired_chunk_pools(ctx);
+
+    if (ctx->chunk_pool != NULL) {
+        ngx_destroy_pool(ctx->chunk_pool);
+        ctx->chunk_pool = NULL;
+    }
+
+    if (ctx->retired_chunk_pool != NULL) {
+        ngx_destroy_pool(ctx->retired_chunk_pool);
+        ctx->retired_chunk_pool = NULL;
+    }
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_enqueue_retired_chunk_pool(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_pool_t *pool)
+{
+    ngx_http_cache_purge_refresh_temp_pool_t *entry;
+
+    entry = ngx_palloc(ctx->request->pool,
+                       sizeof(ngx_http_cache_purge_refresh_temp_pool_t));
+    if (entry == NULL) {
+        return NGX_ERROR;
+    }
+
+    entry->pool = pool;
+    ngx_queue_insert_tail(&ctx->retired_chunk_pools, &entry->queue);
+
+    return NGX_OK;
+}
+
+
+static void
+ngx_http_cache_purge_refresh_drain_retired_chunk_pools(
+    ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    ngx_queue_t *q;
+    ngx_http_cache_purge_refresh_temp_pool_t *entry;
+
+    while (!ngx_queue_empty(&ctx->retired_chunk_pools)) {
+        q = ngx_queue_head(&ctx->retired_chunk_pools);
+        ngx_queue_remove(q);
+
+        entry = ngx_queue_data(q,
+                               ngx_http_cache_purge_refresh_temp_pool_t,
+                               queue);
+
+        if (entry->pool != NULL) {
+            ngx_destroy_pool(entry->pool);
+        }
+    }
+}
+
+
+static void
+ngx_http_cache_purge_refresh_finalize(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    ngx_int_t rc;
+    size_t len;
+    u_char *msg;
+    u_char *p;
+
+    if (ctx->finalized) {
+        return;
+    }
+
+    ctx->finalized = 1;
+
+    if (ctx->timeout_ev.timer_set) {
+        ngx_del_timer(&ctx->timeout_ev);
+    }
+
+    len = sizeof("cache refresh summary uri=\"\" total= kept= purged= errors= timed_out= total_bytes= kept_bytes= purged_bytes=")
+          + r->uri.len + 5 * NGX_INT_T_LEN + 3 * NGX_OFF_T_LEN
+          + ngx_http_cache_purge_refresh_status_counts_log_len(ctx->status_counts)
+          + ngx_http_cache_purge_refresh_status_bytes_log_len(ctx->status_counts);
+
+    msg = ngx_pnalloc(r->pool, len + 1);
+    if (msg == NULL) {
+        ngx_log_error(NGX_LOG_NOTICE, r->connection->log, 0,
+                      "cache refresh summary uri=\"%V\" total=%ui kept=%ui purged=%ui errors=%ui timed_out=%ui total_bytes=%O kept_bytes=%O purged_bytes=%O",
+                      &r->uri, ctx->total, ctx->refreshed, ctx->purged,
+                      ctx->errors, ctx->timed_out ? 1 : 0,
+                      ctx->total_bytes, ctx->kept_bytes, ctx->purged_bytes);
+    } else {
+        p = ngx_sprintf(msg,
+                        "cache refresh summary uri=\"%V\" total=%ui kept=%ui purged=%ui errors=%ui timed_out=%ui total_bytes=%O kept_bytes=%O purged_bytes=%O",
+                        &r->uri, ctx->total, ctx->refreshed, ctx->purged,
+                        ctx->errors, ctx->timed_out ? 1 : 0,
+                        ctx->total_bytes, ctx->kept_bytes, ctx->purged_bytes);
+        p = ngx_http_cache_purge_refresh_write_status_counts_log(p,
+                ctx->status_counts);
+        p = ngx_http_cache_purge_refresh_write_status_bytes_log(p,
+                ctx->status_counts);
+        *p = '\0';
+
+        ngx_log_error(NGX_LOG_NOTICE, r->connection->log, 0,
+                      "%s", msg);
+    }
+
+    rc = ngx_http_cache_purge_refresh_send_response(r);
+    ngx_http_finalize_request(r, rc);
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_enqueue_dir(
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_str_t *path)
+{
+    ngx_http_cache_purge_refresh_dir_t *dir;
+    u_char *p;
+
+    dir = ngx_palloc(ctx->request->pool,
+                     sizeof(ngx_http_cache_purge_refresh_dir_t));
+    if (dir == NULL) {
+        return NGX_ERROR;
+    }
+
+    p = ngx_pnalloc(ctx->request->pool, path->len + 1);
+    if (p == NULL) {
+        return NGX_ERROR;
+    }
+
+    ngx_memcpy(p, path->data, path->len);
+    p[path->len] = '\0';
+
+    dir->path.len = path->len;
+    dir->path.data = p;
+
+    ngx_queue_insert_tail(&ctx->pending_dirs, &dir->queue);
+
+    return NGX_OK;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_load_dir(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx, ngx_str_t *path)
+{
+    ngx_dir_t dir;
+    ngx_http_cache_purge_refresh_scan_entry_t *entry;
+    ngx_str_t child;
+    u_char *name;
+    u_char *p;
+    size_t len;
+    ngx_int_t rc;
+
+    if (ctx->scan_pool != NULL) {
+        ngx_destroy_pool(ctx->scan_pool);
+        ctx->scan_pool = NULL;
+    }
+
+    ctx->scan_pool = ngx_create_pool(4096, r->connection->log);
+    if (ctx->scan_pool == NULL) {
+        return NGX_ERROR;
+    }
+
+    ctx->scan_entries = ngx_array_create(ctx->scan_pool, 64,
+                                         sizeof(ngx_http_cache_purge_refresh_scan_entry_t));
+    if (ctx->scan_entries == NULL) {
+        return NGX_ERROR;
+    }
+
+    ctx->scan_index = 0;
+
+    if (ngx_open_dir(path, &dir) == NGX_ERROR) {
+        ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno,
+                      ngx_open_dir_n " \"%V\" failed", path);
+        return NGX_ERROR;
+    }
+
+    rc = NGX_OK;
+
+    for ( ;; ) {
+        ngx_set_errno(0);
+
+        if (ngx_read_dir(&dir) == NGX_ERROR) {
+            if (ngx_errno != NGX_ENOMOREFILES) {
+                ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno,
+                              ngx_read_dir_n " \"%V\" failed", path);
+                rc = NGX_ERROR;
+            }
+
+            break;
+        }
+
+        len = ngx_de_namelen(&dir);
+        name = ngx_de_name(&dir);
+
+        if (len == 1 && name[0] == '.') {
+            continue;
+        }
+
+        if (len == 2 && name[0] == '.' && name[1] == '.') {
+            continue;
+        }
+
+        if (path->len == ctx->cache->path->name.len
+            && ngx_strncmp(path->data, ctx->cache->path->name.data,
+                           path->len) == 0
+            && ngx_de_is_dir(&dir))
+        {
+            if (len == sizeof("proxy_temp") - 1
+                && ngx_strncmp(name, (u_char *) "proxy_temp", len) == 0)
+            {
+                continue;
+            }
+        }
+
+        child.len = path->len + 1 + len;
+        child.data = ngx_pnalloc(ctx->scan_pool, child.len + 1);
+        if (child.data == NULL) {
+            rc = NGX_ERROR;
+            break;
+        }
+
+        p = ngx_cpymem(child.data, path->data, path->len);
+        *p++ = '/';
+        ngx_memcpy(p, name, len);
+        p[len] = '\0';
+
+        if (!dir.valid_info && ngx_de_info(child.data, &dir) == NGX_FILE_ERROR) {
+            ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno,
+                          ngx_de_info_n " \"%V\" failed", &child);
+            continue;
+        }
+
+        if (!ngx_de_is_file(&dir) && !ngx_de_is_dir(&dir)) {
+            continue;
+        }
+
+        entry = ngx_array_push(ctx->scan_entries);
+        if (entry == NULL) {
+            rc = NGX_ERROR;
+            break;
+        }
+
+        entry->path = child;
+        entry->is_dir = ngx_de_is_dir(&dir);
+    }
+
+    if (ngx_close_dir(&dir) == NGX_ERROR) {
+        ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno,
+                      ngx_close_dir_n " \"%V\" failed", path);
+        if (rc == NGX_OK) {
+            rc = NGX_ERROR;
+        }
+    }
+
+    return rc;
+}
+
+
+static ngx_int_t
+ngx_http_cache_purge_refresh_scan_next_chunk(ngx_http_request_t *r,
+    ngx_http_cache_purge_refresh_ctx_t *ctx)
+{
+    ngx_http_cache_purge_refresh_dir_t *dir;
+    ngx_http_cache_purge_refresh_scan_entry_t *entry;
+    ngx_int_t rc;
+
+    if (ctx->scan_done) {
+        return NGX_OK;
+    }
+
+    if (ctx->retired_chunk_pool != NULL) {
+        if (ngx_http_cache_purge_refresh_enqueue_retired_chunk_pool(
+                ctx, ctx->retired_chunk_pool) != NGX_OK)
+        {
+            ngx_destroy_pool(ctx->retired_chunk_pool);
+        }
+        ctx->retired_chunk_pool = NULL;
+    }
+
+    if (ctx->chunk_pool != NULL) {
+        ctx->retired_chunk_pool = ctx->chunk_pool;
+        ctx->chunk_pool = NULL;
+    }
+
+    ctx->chunk_pool = ngx_create_pool(4096, r->connection->log);
+    if (ctx->chunk_pool == NULL) {
+        return NGX_ERROR;
+    }
+
+    ctx->files = ngx_array_create(ctx->chunk_pool, ctx->chunk_limit,
+                                  sizeof(ngx_http_cache_purge_refresh_file_t));
+    if (ctx->files == NULL) {
+        return NGX_ERROR;
+    }
+
+    ctx->current = 0;
+    ctx->queued = 0;
+
+    if (ctx->exact) {
+        ctx->scan_done = 1;
+        return ngx_http_cache_purge_refresh_collect_open_file(r, ctx);
+    }
+
+    if (!ctx->scan_initialized) {
+        ngx_queue_init(&ctx->pending_dirs);
+        if (ngx_http_cache_purge_refresh_enqueue_dir(ctx,
+                                                     &ctx->cache->path->name)
+            != NGX_OK)
+        {
+            return NGX_ERROR;
+        }
+
+        ctx->scan_initialized = 1;
+    }
+
+    for ( ;; ) {
+        if (ctx->timeout_enabled && !ctx->timed_out
+            && ngx_current_msec >= ctx->deadline)
+        {
+            ngx_http_cache_purge_refresh_mark_timeout(ctx);
+            ctx->scan_done = 1;
+            return NGX_OK;
+        }
+
+        if (ctx->queued >= ctx->chunk_limit) {
+            return NGX_OK;
+        }
+
+        if (ctx->scan_entries != NULL
+            && ctx->scan_index < ctx->scan_entries->nelts)
+        {
+            entry = ((ngx_http_cache_purge_refresh_scan_entry_t *)
+                     ctx->scan_entries->elts) + ctx->scan_index++;
+
+            if (entry->is_dir) {
+                if (ngx_http_cache_purge_refresh_enqueue_dir(ctx, &entry->path)
+                    != NGX_OK)
+                {
+                    return NGX_ERROR;
+                }
+
+                continue;
+            }
+
+            rc = ngx_http_cache_purge_refresh_collect_path(ctx, &entry->path, 0);
+            if (rc != NGX_OK) {
+                if (rc == NGX_ABORT && ctx->timed_out) {
+                    ctx->scan_done = 1;
+                    return NGX_OK;
+                }
+
+                return rc;
+            }
+
+            continue;
+        }
+
+        if (ctx->scan_pool != NULL) {
+            ngx_destroy_pool(ctx->scan_pool);
+            ctx->scan_pool = NULL;
+        }
+
+        ctx->scan_entries = NULL;
+        ctx->scan_index = 0;
+
+        if (ngx_queue_empty(&ctx->pending_dirs)) {
+            ctx->scan_done = 1;
+            return NGX_OK;
+        }
+
+        dir = (ngx_http_cache_purge_refresh_dir_t *) ngx_queue_data(
+                  ngx_queue_head(&ctx->pending_dirs),
+                  ngx_http_cache_purge_refresh_dir_t, queue);
+        ngx_queue_remove(&dir->queue);
+
+        rc = ngx_http_cache_purge_refresh_load_dir(r, ctx, &dir->path);
+        if (rc != NGX_OK) {
+            return rc;
+        }
+    }
+}
+
+
+static void
+ngx_http_cache_purge_refresh_timeout_handler(ngx_event_t *ev)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+
+    ctx = ev->data;
+
+    if (ctx == NULL || ctx->finalized) {
+        return;
+    }
+
+    ngx_http_cache_purge_refresh_mark_timeout(ctx);
+
+    if (ctx->active == 0) {
+        ngx_http_cache_purge_refresh_finalize(ctx->request, ctx);
+    }
+}
+
+
+static void
+ngx_http_cache_purge_refresh_start(ngx_http_request_t *r)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+    ngx_int_t rc;
+    ngx_uint_t i, concurrency;
+
+    ctx = ngx_http_get_module_ctx(r, ngx_http_cache_purge_module);
+
+    if (ctx == NULL) {
+        ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR);
+        return;
+    }
+
+    if (ctx->queued == 0 && ctx->scan_done && ctx->total == 0) {
+        ngx_http_cache_purge_refresh_finalize(r, ctx);
+        return;
+    }
+
+    if (ctx->current >= ctx->queued && ctx->active == 0 && ctx->scan_done) {
+        ngx_http_cache_purge_refresh_finalize(r, ctx);
+        return;
+    }
+
+    if (ctx->timed_out) {
+        if (ctx->active == 0) {
+            ngx_http_cache_purge_refresh_finalize(r, ctx);
+        }
+        return;
+    }
+
+    if (ctx->active == 0 && ctx->current >= ctx->queued && !ctx->scan_done) {
+        ctx->current = 0;
+        ctx->queued = 0;
+    }
+
+    if (ctx->queued == 0) {
+        if (!ctx->scan_done) {
+            rc = ngx_http_cache_purge_refresh_scan_next_chunk(r, ctx);
+            if (rc != NGX_OK) {
+                ctx->errors++;
+                ngx_http_cache_purge_refresh_finalize(r, ctx);
+                return;
+            }
+        }
+
+        if (ctx->timed_out) {
+            ctx->current = ctx->queued;
+
+            if (ctx->active == 0) {
+                ngx_http_cache_purge_refresh_finalize(r, ctx);
+            }
+            return;
+        }
+
+        if (ctx->queued == 0) {
+            if (ctx->scan_done) {
+                ngx_http_cache_purge_refresh_finalize(r, ctx);
+            }
+            return;
+        }
+    }
+
+    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+    concurrency = cplcf->refresh_concurrency;
+    if (concurrency == 0) {
+        concurrency = 1;
+    }
+    if (concurrency > ctx->queued) {
+        concurrency = ctx->queued;
+    }
+
+    for (i = ctx->active; i < concurrency; i++) {
+        rc = ngx_http_cache_purge_refresh_fire_subrequest(r, ctx);
+        if (rc == NGX_OK) {
+            continue;
+        }
+
+        if (rc == NGX_ABORT && ctx->timed_out) {
+            break;
+        }
+
+        ctx->errors += ctx->queued - ctx->current;
+        ngx_http_cache_purge_refresh_finalize(r, ctx);
+        return;
+    }
+}
+
+
+ngx_int_t
+ngx_http_cache_purge_refresh(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache)
+{
+    ngx_http_cache_purge_refresh_ctx_t *ctx;
+    ngx_http_cache_purge_loc_conf_t *cplcf;
+    ngx_pool_cleanup_t *cln;
+    ngx_str_t *keys;
+    ngx_str_t targets[4];
+    ngx_str_t key;
+    ngx_uint_t ntargets;
+
+    ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
+                  "cache purge refresh in %s", cache->path->name.data);
+
+    ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_cache_purge_refresh_ctx_t));
+    if (ctx == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    ngx_queue_init(&ctx->temp_pools);
+    ngx_queue_init(&ctx->retired_chunk_pools);
+
+    ctx->request = r;
+    ctx->cache = cache;
+    ctx->status_counts = ngx_array_create(r->pool, 4,
+                                          sizeof(ngx_http_cache_purge_refresh_status_count_t));
+    if (ctx->status_counts == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    cln = ngx_pool_cleanup_add(r->pool, 0);
+    if (cln == NULL) {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+    cln->handler = ngx_http_cache_purge_refresh_pool_cleanup;
+    cln->data = ctx;
+
+    cplcf = ngx_http_get_module_loc_conf(r, ngx_http_cache_purge_module);
+    ctx->purge_all = cplcf->conf->purge_all;
+    ctx->exact = !ctx->purge_all && !ngx_http_cache_purge_is_partial(r);
+    ctx->timeout_enabled = (cplcf->refresh_timeout != 0);
+    ctx->deadline = ngx_current_msec + cplcf->refresh_timeout;
+    ctx->chunk_limit = cplcf->refresh_concurrency * 4;
+
+    if (!ctx->exact && r->args.len > 0) {
+        return ngx_http_cache_purge_send_cache_key_error(r);
+    }
+
+    if (ctx->chunk_limit == 0) {
+        ctx->chunk_limit = 4;
+    }
+    if (ctx->chunk_limit < 32) {
+        ctx->chunk_limit = 32;
+    }
+
+    ngx_memzero(&ctx->timeout_ev, sizeof(ngx_event_t));
+    ctx->timeout_ev.handler = ngx_http_cache_purge_refresh_timeout_handler;
+    ctx->timeout_ev.data = ctx;
+    ctx->timeout_ev.log = r->connection->log;
+
+    if (ctx->timeout_enabled) {
+        ngx_add_timer(&ctx->timeout_ev, cplcf->refresh_timeout);
+    }
+
+    keys = r->cache->keys.elts;
+    key = keys[0];
+    if (!ctx->exact && key.len > 0 && key.data[key.len - 1] == '*') {
+        key.len--;
+    }
+
+    ctx->key_partial.len = key.len;
+    ctx->key_partial.data = key.data;
+
+    if (ngx_http_cache_purge_refresh_collect_target_tails(r, targets,
+            sizeof(targets) / sizeof(targets[0]), &ntargets, !ctx->exact)
+        != NGX_OK)
+    {
+        return NGX_HTTP_INTERNAL_SERVER_ERROR;
+    }
+
+    if (!ngx_http_cache_purge_refresh_infer_key_prefix_len(&key, targets,
+            ntargets, &ctx->key_prefix_len))
+    {
+        return ngx_http_cache_purge_send_cache_key_error(r);
+    }
+
+    ngx_http_set_ctx(r, ctx, ngx_http_cache_purge_module);
+    r->write_event_handler = ngx_http_cache_purge_refresh_start;
+
+#if (nginx_version >= 8011)
+    r->main->count++;
+#endif
+
+    ngx_http_cache_purge_refresh_start(r);
+
+    return NGX_DONE;
+}
diff --git a/ngx_http_cache_refresh.h b/ngx_http_cache_refresh.h
new file mode 100644
index 0000000..77e9121
--- /dev/null
+++ b/ngx_http_cache_refresh.h
@@ -0,0 +1,228 @@
+#ifndef _NGX_HTTP_CACHE_REFRESH_H_INCLUDED_
+#define _NGX_HTTP_CACHE_REFRESH_H_INCLUDED_
+
+#include <ngx_config.h>
+#include <nginx.h>
+#include <ngx_core.h>
+#include <ngx_http.h>
+
+#define NGX_CACHE_PURGE_RESPONSE_TYPE_HTML  1
+#define NGX_CACHE_PURGE_RESPONSE_TYPE_XML   2
+#define NGX_CACHE_PURGE_RESPONSE_TYPE_JSON  3
+#define NGX_CACHE_PURGE_RESPONSE_TYPE_TEXT  4
+
+#define NGX_CACHE_PURGE_KEY_MAX_LEN          512
+
+typedef struct ngx_http_cache_purge_queue_item_s ngx_http_cache_purge_queue_item_t;
+typedef struct ngx_http_cache_purge_queue_s ngx_http_cache_purge_queue_t;
+typedef struct ngx_http_cache_purge_main_conf_s ngx_http_cache_purge_main_conf_t;
+
+struct ngx_http_cache_purge_queue_item_s {
+    ngx_str_t                          cache_path;
+    ngx_str_t                          key_partial;
+    ngx_uint_t                         hash;
+    ngx_flag_t                         purge_all;
+    ngx_uint_t                         in_progress;
+    ngx_msec_t                         enqueued_at;
+    ngx_http_cache_purge_queue_item_t *next;
+};
+
+struct ngx_http_cache_purge_queue_s {
+    ngx_http_cache_purge_queue_item_t *head;
+    ngx_http_cache_purge_queue_item_t *tail;
+    /*
+     * size is always read and written while queue->mutex is held.
+     * ngx_atomic_t was used historically but implies lock-free semantics that
+     * do not exist here.  ngx_uint_t is the correct plain unsigned type.
+     */
+    ngx_uint_t                         size;
+    ngx_shmtx_sh_t                     sh;
+    ngx_shmtx_t                        mutex;
+    ngx_slab_pool_t                   *shpool;
+    ngx_uint_t                         max_size;
+    ngx_uint_t                         batch_size;
+    ngx_msec_t                         throttle_ms;
+};
+
+struct ngx_http_cache_purge_main_conf_s {
+    ngx_http_cache_purge_queue_t      *queue;
+    ngx_shm_zone_t                    *shm_zone;
+    ngx_uint_t                         queue_size;
+    ngx_uint_t                         batch_size;
+    ngx_msec_t                         throttle_ms;
+    ngx_flag_t                         background_purge;
+    ngx_flag_t                         legacy_status_codes;
+    ngx_flag_t                         vary_aware;
+};
+
+typedef struct {
+    ngx_flag_t                    enable;
+    ngx_str_t                     method;
+    ngx_flag_t                    purge_all;
+    ngx_flag_t                    refresh;
+    ngx_array_t                  *access;
+    ngx_array_t                  *access6;
+} ngx_http_cache_purge_conf_t;
+
+typedef struct {
+# if (NGX_HTTP_FASTCGI)
+    ngx_http_cache_purge_conf_t  fastcgi;
+# endif
+# if (NGX_HTTP_PROXY)
+    ngx_http_cache_purge_conf_t  proxy;
+# endif
+# if (NGX_HTTP_SCGI)
+    ngx_http_cache_purge_conf_t  scgi;
+# endif
+# if (NGX_HTTP_UWSGI)
+    ngx_http_cache_purge_conf_t  uwsgi;
+# endif
+
+    ngx_http_cache_purge_conf_t *conf;
+    ngx_http_handler_pt          handler;
+    ngx_http_handler_pt          original_handler;
+    ngx_uint_t                   response_type;
+
+# if (NGX_HTTP_PROXY)
+    ngx_shm_zone_t              *proxy_separate_zone;
+    ngx_http_complex_value_t    *proxy_separate_value;
+    ngx_http_complex_value_t     proxy_separate_key;
+# endif
+    ngx_uint_t                   refresh_concurrency;
+    ngx_msec_t                   refresh_timeout;
+} ngx_http_cache_purge_loc_conf_t;
+
+typedef struct {
+    u_char     *key_partial;
+    ngx_uint_t  key_len;
+    u_char      key_buffer[512];
+    ngx_uint_t  files_deleted;
+    ngx_uint_t  files_checked;
+    /*
+     * cache is set by ngx_http_cache_purge_delete_variants() so that
+     * delete_exact_file can update shm metadata (sh->size, node->exists,
+     * node->fs_size) for each variant it deletes.  NULL in all other walk
+     * contexts where metadata updates are not needed.
+     */
+    ngx_http_file_cache_t  *cache;
+} ngx_http_cache_purge_walk_ctx_t;
+
+typedef enum {
+    NGX_HTTP_CACHE_PURGE_INVALIDATE_PURGED = 0,
+    NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_MISSING,
+    NGX_HTTP_CACHE_PURGE_INVALIDATE_RACED_REPLACED,
+    NGX_HTTP_CACHE_PURGE_INVALIDATE_ERROR
+} ngx_http_cache_purge_invalidate_result_e;
+
+typedef struct {
+    ngx_str_t        cache_key;
+    ngx_str_t        cache_path;
+    ngx_file_uniq_t  uniq;
+    time_t           last_modified;
+    u_short          body_start;
+    u_char           etag_len;
+    u_char           etag[NGX_HTTP_CACHE_ETAG_LEN];
+    off_t            fs_size;
+} ngx_http_cache_purge_invalidate_item_t;
+
+typedef struct {
+    ngx_str_t          cache_key;
+    ngx_str_t          cache_path;
+    ngx_http_request_t *request;
+    ngx_http_file_cache_t *cache;
+    ngx_str_t          partial_prefix;
+    ngx_flag_t         match_all;
+    ngx_uint_t         files_deleted;
+    ngx_queue_t        temp_pools;
+} ngx_http_cache_purge_batch_ctx_t;
+
+typedef struct {
+    ngx_str_t                         uri;
+    ngx_str_t                         args;
+    ngx_str_t                         etag;
+    time_t                            last_modified;
+    ngx_str_t                         path;
+    ngx_http_cache_purge_invalidate_item_t item;
+} ngx_http_cache_purge_refresh_file_t;
+
+typedef struct {
+    ngx_str_t     path;
+    ngx_flag_t    is_dir;
+} ngx_http_cache_purge_refresh_scan_entry_t;
+
+typedef struct {
+    ngx_queue_t   queue;
+    ngx_pool_t   *pool;
+} ngx_http_cache_purge_refresh_temp_pool_t;
+
+typedef struct {
+    ngx_queue_t   queue;
+    ngx_str_t     path;
+} ngx_http_cache_purge_refresh_dir_t;
+
+typedef struct {
+    ngx_uint_t    status;
+    ngx_uint_t    count;
+    off_t         bytes;
+} ngx_http_cache_purge_refresh_status_count_t;
+
+typedef struct {
+    ngx_http_request_t              *request;
+    ngx_http_file_cache_t           *cache;
+    ngx_str_t                        key_partial;
+    ngx_uint_t                       key_prefix_len;
+    ngx_flag_t                       purge_all;
+    ngx_flag_t                       exact;
+    ngx_flag_t                       timed_out;
+    ngx_flag_t                       timeout_enabled;
+    ngx_flag_t                       finalized;
+    ngx_msec_t                       deadline;
+    ngx_event_t                      timeout_ev;
+    ngx_pool_t                      *chunk_pool;
+    ngx_pool_t                      *retired_chunk_pool;
+    ngx_queue_t                      retired_chunk_pools;
+    ngx_pool_t                      *scan_pool;
+    ngx_array_t                     *files;
+    ngx_array_t                     *scan_entries;
+    ngx_uint_t                       current;
+    ngx_uint_t                       queued;
+    ngx_uint_t                       active;
+    ngx_uint_t                       dispatched;
+    ngx_uint_t                       chunk_limit;
+    ngx_uint_t                       scan_index;
+    ngx_flag_t                       scan_done;
+    ngx_flag_t                       scan_initialized;
+    ngx_queue_t                      temp_pools;
+    ngx_queue_t                      pending_dirs;
+    ngx_array_t                     *status_counts;
+    ngx_uint_t                       total;
+    ngx_uint_t                       refreshed;
+    ngx_uint_t                       purged;
+    ngx_uint_t                       errors;
+    off_t                            total_bytes;
+    off_t                            kept_bytes;
+    off_t                            purged_bytes;
+} ngx_http_cache_purge_refresh_ctx_t;
+
+typedef struct {
+    ngx_http_cache_purge_refresh_ctx_t  *ctx;
+    ngx_http_cache_purge_refresh_file_t *file;
+    ngx_flag_t                           validation_ready;
+    ngx_flag_t                           handled;
+} ngx_http_cache_purge_refresh_post_data_t;
+
+ngx_int_t ngx_http_cache_purge_add_variable(ngx_conf_t *cf);
+ngx_int_t ngx_http_cache_purge_refresh(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache);
+ngx_int_t ngx_http_cache_purge_add_action_header(ngx_http_request_t *r,
+    ngx_uint_t refresh);
+void ngx_http_cache_purge_drain_temp_pools(ngx_queue_t *queue);
+ngx_int_t ngx_http_cache_purge_invalidate_item(ngx_http_request_t *r,
+    ngx_http_file_cache_t *cache, ngx_pool_t *pool,
+    ngx_http_cache_purge_invalidate_item_t *item,
+    ngx_http_cache_purge_invalidate_result_e *result);
+ngx_int_t ngx_http_cache_purge_is_partial(ngx_http_request_t *r);
+
+extern ngx_module_t ngx_http_cache_purge_module;
+
+#endif /* _NGX_HTTP_CACHE_REFRESH_H_INCLUDED_ */
diff --git a/t/Makefile b/t/Makefile
index 2ed216c..fd5501a 100644
--- a/t/Makefile
+++ b/t/Makefile
@@ -2,7 +2,7 @@
 # Build context for Docker is always the repo root (one level up).
 .PHONY: help build test test-all test-compat test-version clean shell
 
-NGINX_VERSION ?= 1.28.2
+NGINX_VERSION ?= 1.31.1
 COMPOSE       := docker-compose -f docker-compose.test.yml
 IMAGE         := ngx-cache-purge-test:$(NGINX_VERSION)
 
@@ -25,12 +25,13 @@ help:
 	@echo ""
 	@echo "$(YELLOW)Variables:$(NC)"
 	@echo "  NGINX_VERSION  nginx version to build/test  (default: $(NGINX_VERSION))"
+	@echo "                 Re-check nginx.org before matrix runs to refresh latest stable/mainline/legacy versions"
 	@echo ""
 	@echo "$(YELLOW)Examples:$(NC)"
 	@echo "  make build"
 	@echo "  make test"
 	@echo "  make test-all"
-	@echo "  NGINX_VERSION=1.29.6 make build test-all"
+	@echo "  NGINX_VERSION=1.31.1 make build test-all"
 	@echo "  make test-compat"
 	@echo "  make test-version VERSION=1.26.3"
 
@@ -58,7 +59,8 @@ test-all: build
 
 test-compat:
 	@echo "$(GREEN)Compatibility test across supported nginx versions...$(NC)"
-	@for v in 1.20.2 1.26.3 1.28.2 1.29.6; do \
+	@echo "$(YELLOW)Check https://nginx.org/en/download.html before running to confirm latest stable/mainline/legacy versions.$(NC)"
+	@for v in 1.20.2 1.22.1 1.24.0 1.26.3 1.28.3 1.30.2 1.31.1; do \
 	    echo "$(YELLOW)--- nginx $$v ---$(NC)"; \
 	    $(MAKE) --no-print-directory NGINX_VERSION=$$v build test-all || exit 1; \
 	done
diff --git a/t/background_queue.t b/t/background_queue.t
index 173d02f..c930099 100644
--- a/t/background_queue.t
+++ b/t/background_queue.t
@@ -98,6 +98,25 @@ PURGE /cache/anything
 --- error_code: 202
 --- response_body_like: queued
 
+=== TEST 4a: queued HTML response uses neutral heading
+--- http_config eval: $::HttpConfig
+--- config
+    cache_purge_response_type html;
+    location /cache {
+        proxy_pass http://backend/origin;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_purge PURGE from 127.0.0.1;
+    }
+    location /origin {
+        return 200 "ok";
+    }
+--- request
+PURGE /cache/queued-html*
+--- error_code: 202
+--- response_body_like eval
+qr{<title>Cache purge</title>.*<h1>Cache purge</h1>.*Status: queued}si
+
 === TEST 5: background queue off — sync purge returns 412 on miss
 --- http_config
     proxy_cache_path $TEST_NGINX_SERVROOT/cache levels=1:2
diff --git a/t/basic.t b/t/basic.t
index d60b9aa..4a1a2cb 100644
--- a/t/basic.t
+++ b/t/basic.t
@@ -2,7 +2,7 @@
 use Test::Nginx::Socket 'no_plan';
 use Cwd qw(cwd);
 
-my $pwd  = cwd();
+our $pwd = cwd();
 my $port = server_port();
 
 # HttpConfig: cache zone + upstream pointing at the test server itself.
@@ -304,7 +304,408 @@ PURGE /cache/anything
 --- error_code eval
 [200, 200]
 
-=== TEST 15: vary_aware purge succeeds after real cache warm
+=== TEST 15: refresh keeps cached object on 304
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache {
+        proxy_pass http://backend/origin304;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin304 {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-refresh-304"';
+            return 304;
+        }
+        add_header ETag '"etag-refresh-304"';
+        return 200 "refresh-304-body";
+    }
+--- request eval
+["GET /cache/refresh304", "REFRESH /cache/refresh304", "GET /cache/refresh304"]
+--- response_body eval
+[
+    "refresh-304-body",
+    qr/Refresh: total=1 kept=1 purged=0 errors=0 .*statuses=\{304:1\}/,
+    "refresh-304-body"
+]
+--- error_code eval
+[200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m
+]
+
+=== TEST 16: refresh purges cached object on 200 change
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache {
+        proxy_pass http://backend/origin200;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin200 {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-refresh-200-v2"';
+            return 200;
+        }
+        add_header ETag '"etag-refresh-200-v1"';
+        return 200 "refresh-200-body";
+    }
+--- request eval
+["GET /cache/refresh200", "REFRESH /cache/refresh200", "GET /cache/refresh200"]
+--- response_body eval
+[
+    "refresh-200-body",
+    qr/Refresh: total=1 kept=0 purged=1 errors=0 .*statuses=\{200:1\}/,
+    "refresh-200-body"
+]
+--- error_code eval
+[200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m
+]
+
+=== TEST 17: refresh purges cached object on 404
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache {
+        proxy_pass http://backend/origin404;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin404 {
+        if ($request_method = HEAD) {
+            return 404;
+        }
+        return 200 "refresh-404-body";
+    }
+--- request eval
+["GET /cache/refresh404", "REFRESH /cache/refresh404", "GET /cache/refresh404"]
+--- response_body eval
+[
+    "refresh-404-body",
+    qr/Refresh: total=1 kept=0 purged=1 errors=0 .*statuses=\{404:1\}/,
+    "refresh-404-body"
+]
+--- error_code eval
+[200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m
+]
+
+=== TEST 18: refresh purges cached object on 410
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache {
+        proxy_pass http://backend/origin410;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin410 {
+        if ($request_method = HEAD) {
+            return 410;
+        }
+        return 200 "refresh-410-body";
+    }
+--- request eval
+["GET /cache/refresh410", "REFRESH /cache/refresh410", "GET /cache/refresh410"]
+--- response_body eval
+[
+    "refresh-410-body",
+    qr/Refresh: total=1 kept=0 purged=1 errors=0 .*statuses=\{410:1\}/,
+    "refresh-410-body"
+]
+--- error_code eval
+[200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m
+]
+
+=== TEST 19: runtime refresh rejects purge_all-only location
+--- http_config eval: $::HttpConfig
+--- config
+    location /cacheall {
+        proxy_pass http://backend/origin;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE purge_all from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+    }
+    location /origin {
+        return 200 "ok";
+    }
+--- request
+REFRESH /cacheall
+--- error_code: 400
+--- response_body_like: refresh_all is not enabled for this location
+
+=== TEST 20: partial refresh purges only changed matches
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache/partial/ {
+        proxy_pass http://backend/origin-partial/;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /cache/other/ {
+        proxy_pass http://backend/origin-other/;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin-partial/a.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-partial-a-v2"';
+            return 200;
+        }
+        add_header ETag '"etag-partial-a-v1"';
+        return 200 "partial-a-body";
+    }
+    location /origin-partial/b.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-partial-b-v1"';
+            return 304;
+        }
+        add_header ETag '"etag-partial-b-v1"';
+        return 200 "partial-b-body";
+    }
+    location /origin-other/c.txt {
+        add_header ETag '"etag-other-c-v1"';
+        return 200 "other-c-body";
+    }
+--- request eval
+[
+    "GET /cache/partial/a.txt",
+    "GET /cache/partial/b.txt",
+    "GET /cache/other/c.txt",
+    "REFRESH /cache/partial/*",
+    "GET /cache/partial/a.txt",
+    "GET /cache/partial/b.txt",
+    "GET /cache/other/c.txt"
+]
+--- response_body eval
+[
+    "partial-a-body",
+    "partial-b-body",
+    "other-c-body",
+    qr/Refresh: total=2 kept=1 purged=1 errors=0 .*statuses=\{200:1,304:1\}|Refresh: total=2 kept=1 purged=1 errors=0 .*statuses=\{304:1,200:1\}/,
+    "partial-a-body",
+    "partial-b-body",
+    "other-c-body"
+]
+--- error_code eval
+[200, 200, 200, 200, 200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    undef,
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m
+]
+
+=== TEST 21: refresh_all refreshes changed entries across the whole cache
+--- http_config eval: $::HttpConfig . "proxy_cache_path $::pwd/cache21 levels=1:2 keys_zone=cache21_zone:10m max_size=1g inactive=60m;"
+--- config
+    location /cache/refreshall/ {
+        proxy_pass http://backend/origin-refreshall/;
+        proxy_cache cache21_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /refreshall {
+        proxy_pass http://backend/;
+        proxy_cache cache21_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_refresh REFRESH refresh_all from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+    }
+    location /origin-refreshall/keep1.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-keep1-v1"';
+            return 304;
+        }
+        add_header ETag '"etag-keep1-v1"';
+        return 200 "refreshall-keep1";
+    }
+    location /origin-refreshall/keep2.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-keep2-v1"';
+            return 304;
+        }
+        add_header ETag '"etag-keep2-v1"';
+        return 200 "refreshall-keep2";
+    }
+    location /origin-refreshall/keep3.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-keep3-v1"';
+            return 304;
+        }
+        add_header ETag '"etag-keep3-v1"';
+        return 200 "refreshall-keep3";
+    }
+    location /origin-refreshall/keep4.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-keep4-v1"';
+            return 304;
+        }
+        add_header ETag '"etag-keep4-v1"';
+        return 200 "refreshall-keep4";
+    }
+    location /origin-refreshall/change1.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-change1-v2"';
+            return 200;
+        }
+        add_header ETag '"etag-change1-v1"';
+        return 200 "refreshall-change1";
+    }
+    location /origin-refreshall/change2.txt {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-change2-v2"';
+            return 200;
+        }
+        add_header ETag '"etag-change2-v1"';
+        return 200 "refreshall-change2";
+    }
+--- request eval
+[
+    "GET /cache/refreshall/keep1.txt",
+    "GET /cache/refreshall/keep2.txt",
+    "GET /cache/refreshall/keep3.txt",
+    "GET /cache/refreshall/keep4.txt",
+    "GET /cache/refreshall/change1.txt",
+    "GET /cache/refreshall/change2.txt",
+    "REFRESH /refreshall",
+    "GET /cache/refreshall/keep1.txt",
+    "GET /cache/refreshall/change1.txt",
+    "GET /cache/refreshall/change2.txt"
+]
+--- response_body eval
+[
+    "refreshall-keep1",
+    "refreshall-keep2",
+    "refreshall-keep3",
+    "refreshall-keep4",
+    "refreshall-change1",
+    "refreshall-change2",
+    qr/Refresh: total=6 kept=4 purged=2 errors=0 .*statuses=\{200:2,304:4\}|Refresh: total=6 kept=4 purged=2 errors=0 .*statuses=\{304:4,200:2\}/,
+    "refreshall-keep1",
+    "refreshall-change1",
+    "refreshall-change2"
+]
+--- error_code eval
+[200, 200, 200, 200, 200, 200, 200, 200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    undef,
+    undef,
+    undef,
+    undef,
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m,
+    qr/X-Cache-Status: MISS\r?$/m
+]
+
+=== TEST 22: partial refresh covers directory sort variants under query-aware key
+--- http_config eval: $::HttpConfig
+--- config
+    location /cache/dirvar/ {
+        proxy_pass http://backend/origin-dirvar/;
+        proxy_cache cache_zone;
+        proxy_cache_key "$uri$is_args$args";
+        proxy_cache_valid 200 1m;
+        proxy_cache_purge PURGE from 127.0.0.1;
+        proxy_cache_bypass $cache_purge_refresh_bypass;
+        proxy_no_cache $cache_purge_refresh_bypass;
+        add_header X-Cache-Status $upstream_cache_status always;
+    }
+    location /origin-dirvar/ {
+        if ($request_method = HEAD) {
+            add_header ETag '"etag-dir-v1"';
+            return 304;
+        }
+        return 200 "dirvar-body";
+    }
+--- request eval
+[
+    "GET /cache/dirvar/",
+    "GET /cache/dirvar/?C=M&O=A",
+    "REFRESH /cache/dirvar/*",
+    "GET /cache/dirvar/",
+    "GET /cache/dirvar/?C=M&O=A"
+]
+--- response_body eval
+[
+    "dirvar-body",
+    "dirvar-body",
+    qr/Refresh: total=2 kept=2 purged=0 errors=0 .*statuses=\{304:2\}/,
+    "dirvar-body",
+    "dirvar-body"
+]
+--- error_code eval
+[200, 200, 200, 200, 200]
+--- raw_response_headers_like eval
+[
+    undef,
+    undef,
+    qr/X-Cache-Action: refresh\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m,
+    qr/X-Cache-Status: HIT\r?$/m
+]
+
+=== TEST 23: vary_aware purge succeeds after real cache warm
 # cache_purge_vary_aware is a main-context directive (NGX_HTTP_MAIN_CONF).
 # It makes the module walk the cache shard directory after deleting the
 # primary entry, removing any variant files sharing the same KEY: line.