Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
C

cache-handler

> 编程语言
Open source

Distributed HTTP caching module for Caddy

391 stars0 likes0 views
WebsiteGitHub

About

Distributed HTTP caching module for Caddy

Caddy Module: http.handlers.cache

This is a distributed HTTP cache module for Caddy based on Souin cache.

[!WARNING] Since v1.7.0 Souin (the development repository that cache-handler is based on) implements only one storage. If you need a specific storage you have to take it from the storages repository and add it either in your code, during the build otherwise.
(e.g. with otter using caddy) You have to build your caddy module with the desired storage xcaddy build --with github.com/caddyserver/cache-handler --with github.com/darkweak/storages/otter/caddy and configure otter in your Caddyfile/JSON configuration file.
See the documentation about the storages.

Features

  • RFC 7234 compliant HTTP Cache.
  • Sets the Cache-Status HTTP Response Header
  • REST API to purge the cache and list stored resources.
  • ESI tags processing (using the go-esi package).
  • Builtin support for distributed cache.

Minimal Configuration

Using the minimal configuration the responses will be cached for 120s

caddy
{
    cache
}

example.com {
    cache
    reverse_proxy your-app:8080
}

Global Option Syntax

Here are all the available options for the global options

…

Cache directive Syntax

Here are all the available options for the directive options

…

Provider Syntax

Badger

The badger provider must have either the path or the configuration directive.

badger-path.com {
    cache {
        badger {
            path /tmp/badger/first-match
        }
    }
}
…

Etcd

The etcd provider must have the configuration directive.

etcd-configuration.com {
    cache {
        etcd {
            configuration {
                Endpoints etcd1:2379 etcd2:2379 etcd3:2379
                AutoSyncInterval 1s
                DialTimeout 1s
                DialKeepAliveTime 1s
                DialKeepAliveTimeout 1s
                MaxCallSendMsgSize 10000000
                MaxCallRecvMsgSize 10000000
                Username john
                Password doe
                RejectOldCluster false
                PermitWithoutStream false
            }
        }
    }
}

NutsDB

The nutsdb provider must have either the path or the configuration directive.

nuts-path.com {
    cache {
        nuts {
            path /tmp/nuts-path
        }
    }
}
nuts-configuration.com {
    cache {
        nuts {
            configuration {
                Dir /tmp/nuts-configuration
                EntryIdxMode 1
                RWMode 0
                SegmentSize 1024
                NodeNum 42
                SyncEnable true
                StartFileLoadingMode 1
            }
        }
    }
}

Olric

The olric provider must have either the url directive to work as client mode.

olric-url.com {
    cache {
        olric {
            url olric:3320
        }
    }
}

The olric provider must have either the path or the configuration directive to work as embedded mode.

olric-path.com {
    cache {
        olric {
            path /path/to/olricd.yml
        }
    }
}
olric-configuration.com {
    cache {
        nuts {
            configuration {
                Dir /tmp/nuts-configuration
                EntryIdxMode 1
                RWMode 0
                SegmentSize 1024
                NodeNum 42
                SyncEnable true
                StartFileLoadingMode 1
            }
        }
    }
}

Redis

The redis provider must have either the URL or the configuration directive.

redis-url.com {
    cache {
        redis {
            url 127.0.0.1:6379
        }
    }
}
…

You can also use the configuration. Refer to the Souin docs or rueidis client options to define your config as key value.

What does these directives mean?

Key Description Value example
allowed_http_verbs The HTTP verbs allowed to be cached GET POST PATCH

(default: GET HEAD) | | allowed_additional_status_codes | The additional HTTP status codes allowed to be cached | 202 400 | | api | The cache-handler API cache management | | | api.basepath | BasePath for all APIs to avoid conflicts | /your-non-conflict-route

(default: /souin-api) | | api.prometheus | Enable the Prometheus metrics | | | api.souin.basepath | Souin API basepath | /another-souin-api-route

(default: /souin) | | badger | Configure the Badger cache storage | | | badger.path | Configure Badger with a file | /anywhere/badger_configuration.json | | badger.configuration | Configure Badger directly in the Caddyfile or your JSON caddy configuration | See the Badger configuration for the options | | cache_name | Override the cache name to use in the Cache-Status response header | Another Caddy Cache-Handler Souin | | cache_keys | Define the key generation rules for each URI matching the key regexp | | | cache_keys.{your regexp} | Regexp that the URI should match to override the key generation | .+\.css | | cache_keys.{your regexp} | Regexp that the URI should match to override the key generation | .+\.css | | cache_keys.{your regexp}.disable_body | Disable the body part in the key matching the regexp (GraphQL context) | true

(default: false) | | cache_keys.{your regexp}.disable_host | Disable the host part in the key matching the regexp | true

(default: false) | | cache_keys.{your regexp}.disable_method | Disable the method part in the key matching the regexp | true

(default: false) | | cache_keys.{your regexp}.disable_query | Disable the query string part in the key matching the regexp | true

(default: false) | | cache_keys.{your regexp}.headers | Add headers to the key matching the regexp | Authorization Content-Type X-Additional-Header | | cache_keys.{your regexp}.hide | Prevent the key from being exposed in the Cache-Status HTTP response header | true

(default: false) | | cdn | The CDN management, if you use any cdn to proxy your requests Souin will handle that | | | cdn.provider | The provider placed before Souin | akamai

fastly

souin | | cdn.api_key | The api key used to access to the provider | XXXX | | cdn.dynamic | Enable the dynamic keys returned by your backend application | (default: true) | | cdn.email | The api key used to access to the provider if required, depending the provider

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Go

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言