diff --git a/docs/common/caching.md b/docs/common/caching.md index 82da94b..40d70e3 100644 --- a/docs/common/caching.md +++ b/docs/common/caching.md @@ -13,7 +13,7 @@ Every proxied request on a remote is classified as **denied**, **immutable** or | `mutable_patterns` | Regexes forcing a path mutable. | | `immutable_ttl` | Seconds an immutable path stays fresh. `0` = forever. | | `mutable_ttl` | Seconds a mutable path stays fresh. `0` also means never expires, and the API stores `0` when the field is omitted. | -| `check_mutable` | Once a mutable path expires, revalidate with a conditional `HEAD` (`If-None-Match`) before refetching. | +| `check_mutable` | Stores the upstream ETag and tries a conditional `HEAD` (`If-None-Match`) when a mutable path is fetched. The ETag expires with the `mutable_ttl` freshness key, so an expired mutable path is refetched in full, not revalidated. | | `stale_on_error` | On an upstream network error, serve the stored copy instead of failing. | | `quarantine_enabled` / `quarantine_days` | Stored on the remote but not enforced by the proxy yet. | | `mirrorlist` / `mirror_strategy` | rpm/deb/alpine only. Upstream pool is `[base_url] + mirrorlist`; `round_robin` (default) rotates the starting mirror, `least_conn` starts at the one with the fewest in-flight requests. Network errors and 5xx fail over to the next mirror; other statuses return as-is. | @@ -38,7 +38,7 @@ So `blocklist` beats the allowlist, and `immutable_patterns` beats - Regexes are Go `regexp`, matched **unanchored** (`MatchString`). Add `^` or `$` yourself when you need them. - They match the path after `/api/v1/remote//`, without a leading slash, e.g. `9/BaseOS/x86_64/os/repodata/repomd.xml`. - The query string is not part of the path. It is dropped and not forwarded upstream. -- An invalid regex is silently skipped. +- `create` and `update` reject an invalid regex in `patterns`, `blocklist`, `mutable_patterns`, `immutable_patterns` or `ban_tags` with a 400. Only invalid regexes already stored before that check are skipped at match time. ## Lifecycles @@ -46,7 +46,7 @@ So `blocklist` beats the allowlist, and `immutable_patterns` beats |---|---|---| | Stored as | content-addressed blob (sha256), streamed | per-path index object, buffered and rewritten by the provider | | Fresh for | `immutable_ttl` (`0` = forever) | `mutable_ttl` | -| After expiry | refetched from upstream | with `check_mutable` and a stored ETag, upstream `304` re-arms the TTL and serves the cached copy; otherwise refetched | +| After expiry | refetched from upstream | refetched from upstream (the ETag expires with the TTL, so `check_mutable` does not revalidate it) | | Upstream down | `stale_on_error` serves the stored copy and re-arms the TTL; an open circuit breaker always serves stale if a copy exists, else 503 | same | Concurrent misses on one path share a fetch lock. Waiters poll the store for