caddyserver-cache-handler

Global options allow you to define default behaviors for the entire Caddy instance. Key configuration areas include:

• api: Configures the REST API for cache management (basepath, Prometheus metrics, and Souin-specific endpoints).
• cache_keys: Defines how cache keys are generated using regex patterns, allowing you to disable specific parts of the request (body, host, method, query) or include specific headers.
• cdn: Configures CDN integration (e.g., Fastly) with settings for API keys, service IDs, and invalidation strategies.
• distributed storage: Supports providers like etcd and olric for distributed caching.
• ttl & stale: Sets the default Time-To-Live and stale period.
• mode: Sets the operational mode (e.g., bypass).

{
    cache {
        allowed_http_verbs GET POST PATCH
        api {
            basepath /some-basepath
            prometheus
            souin {
                basepath /souin-changed-endpoint-path
            }
        }
        badger {
            path the_path_to_a_file.json
        }
        cache_keys {
            .*\.css {
                disable_body
                disable_host
                disable_method
                disable_query
                headers X-Token Authorization
                hide
            }
        }
        cache_name Another
        cdn {
            api_key XXXX
            dynamic
            email darkweak@protonmail.com
            hostname domain.com
            network your_network
            provider fastly
            strategy soft
            service_id 123456_id
            zone_id anywhere_zone
        }
        etcd {
            configuration {
                # Your etcd configuration here
            }
        }
        key {
            disable_body
            disable_host
            disable_method
            headers Content-Type Authorization
        }
        log_level debug
        mode bypass
        nuts {
            path /path/to/the/storage
        }
        olric {
            url url_to_your_cluster:3320
            path the_path_to_a_file.yaml
            configuration {
                # Your olric configuration here
            }
        }
        regex {
            exclude /test2.*
        }
        stale 200s
        ttl 1000s
        default_cache_control no-store
    }
}

The cache directive can be used within site blocks or matchers to apply specific caching logic to certain requests. This allows for granular control, such as using different cache_name values or different cache_keys patterns for specific URL paths or hostnames.

@match path /path

handle @match {
    cache {
        cache_name ChangeName
        cache_keys {
            (host1|host2).*\.css {
                disable_body
                disable_host
                disable_method
                disable_query
                headers X-Token Authorization
            }
        }
        cdn {
            api_key XXXX
            dynamic
            email darkweak@protonmail.com
            hostname domain.com
            network your_network
            provider fastly
            strategy soft
            service_id 123456_id
            zone_id anywhere_zone
        }
        key {
            disable_body
            disable_host
            disable_method
            disable_query
            headers Content-Type Authorization
        }
        log_level debug
        regex {
            exclude /test2.*
        }
        stale 200s
        ttl 1000s
        default_cache_control no-store
    }
}

The Configuration struct is the top-level container for the cache handler's settings. It holds the DefaultCache settings and allows for overrides based on specific URLs or cache key rules.

Key fields:

• DefaultCache: The fallback cache settings.
• API: Configuration for enabling API endpoints (e.g., Prometheus, Souin, or Debug endpoints).
• CacheKeys: Rules for overriding cache key generation.
• URLs: A map of specific URL patterns to their own configurationtypes.URL overrides.
• SurrogateKeys: A map of surrogate key configurations for cache invalidation.
• LogLevel: The logging level for the handler.

type Configuration struct {
	DefaultCache      DefaultCache 
	API               configurationtypes.API 
	CacheKeys         configurationtypes.CacheKeys `json:"cache_keys"` 
	URLs              map[string]configurationtypes.URL 
	LogLevel          string 
	SurrogateKeys     map[string]configurationtypes.SurrogateKeys 
	SurrogateKeyDisabled bool 
	logger            core.Logger 
}

The SouinCaddyMiddleware (module ID http.handlers.cache) is a Caddy middleware that implements an RFC-7234 compliant HTTP cache system. It supports distributed storage (via Redis, Etcd, Olric, etc.), tag-based cache purging (surrogates), and customizable key generation.

Key Configuration Options

When configuring the middleware via JSON, you can use the following fields within the SouinCaddyMiddleware struct:

Supported Storage Providers

You can configure various storage backends by providing their specific configuration objects:

• badger: Badger storage.
• etcd: Etcd distributed storage.
• nats: Nats storage.
• nuts: Nuts storage.
• otter: Otter storage.
• redis: Redis distributed storage.
• olric: Olric distributed storage.
• simplefs: SimpleFS storage.

{
  "http": {
    "handlers": {
      "cache": {
        "log_level": "info",
        "allowed_http_verbs": ["GET"],
        "ttl": "5m",
        "redis": {
          "url": "redis://localhost:6379"
        },
        "storers": ["redis"]
      }
    }
  }
}