From d70848f06a82f85bed8eba485908fd1ad4550329 Mon Sep 17 00:00:00 2001 From: Rouven Hurling Date: Sat, 25 Jul 2026 18:09:04 +0200 Subject: [PATCH] docs: document disable_surrogate_key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The option has been parsed since the souin v1.7.7 bump but is absent from the README, so it is effectively undiscoverable — in #118 and #127 it only surfaced through maintainer comments. It matters most on high-cardinality workloads, where maintaining the surrogate index dominates the cost of a cache store, so document both what it does and when reaching for it is worthwhile. --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index dc68022..a066bbf 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,7 @@ Here are all the available options for the global options stale 200s ttl 1000s default_cache_control no-store + disable_surrogate_key } } @@ -106,6 +107,25 @@ Here are all the available options for the global options respond "Hello World!" ``` +### `disable_surrogate_key` + +Disables the surrogate-key storage entirely. + +Souin maintains a surrogate-key index (the `SURROGATE_` entries in your storage) +so that groups of responses can be invalidated together. If you never invalidate +by surrogate key — no `Surrogate-Key`, `Cache-Groups`, `Edge-Cache-Tag` or +`Cache-Tags` response headers, and no purge-by-key API — that index is pure +overhead and can be turned off. + +It is worth turning off on high-cardinality workloads. Maintaining the index +means a read-modify-write of an index entry on every cache store, so the cost of +storing a response grows with the number of responses already indexed. See +[#114](https://github.com/caddyserver/cache-handler/issues/114), +[#118](https://github.com/caddyserver/cache-handler/issues/118) and +[#127](https://github.com/caddyserver/cache-handler/issues/127). + +Caching itself is unaffected — only the surrogate bookkeeping is skipped. + ## Cache directive Syntax Here are all the available options for the directive options