Caddy Module: http.handlers.cache

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

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

{
    cache
}

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

Global Option Syntax

Here are all the available options for the global options

{
    log {
        level debug
    }
    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
    }
}

:4443
respond "Hello World!"

Cache directive Syntax

Here are all the available options for the directive options

@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
    }
}

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
        }
    }
}

badger-configuration.com {
    cache {
        badger {
            configuration {
                # Required value
                ValueDir <string>

                # Optional
                SyncWrites <bool>
                NumVersionsToKeep <int>
                ReadOnly <bool>
                Compression <int>
                InMemory <bool>
                MetricsEnabled <bool>
                MemTableSize <int>
                BaseTableSize <int>
                BaseLevelSize <int>
                LevelSizeMultiplier <int>
                TableSizeMultiplier <int>
                MaxLevels <int>
                VLogPercentile <float>
                ValueThreshold <int>
                NumMemtables <int>
                BlockSize <int>
                BloomFalsePositive <float>
                BlockCacheSize <int>
                IndexCacheSize <int>
                NumLevelZeroTables <int>
                NumLevelZeroTablesStall <int>
                ValueLogFileSize <int>
                ValueLogMaxEntries <int>
                NumCompactors <int>
                CompactL0OnClose <bool>
                LmaxCompaction <bool>
                ZSTDCompressionLevel <int>
                VerifyValueChecksum <bool>
                EncryptionKey <string>
                EncryptionKeyRotationDuration <Duration>
                BypassLockGuard <bool>
                ChecksumVerificationMode <int>
                DetectConflicts <bool>
                NamespaceOffset <int>
            }
        }
    }
}

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 rueidis client options to define your config as key value.

redis-configuration.com {
    cache {
        redis {
            configuration {
                Network my-network
                Addr 127.0.0.1:6379
                Username user
                Password password
                DB 1
                MaxRetries 1
                MinRetryBackoff 5s
                MaxRetryBackoff 5s
                DialTimeout 5s
                ReadTimeout 5s
                WriteTimeout 5s
                PoolFIFO true
                PoolSize 99999
                PoolTimeout 10s
                MinIdleConns 100
                MaxIdleConns 100
                ConnMaxIdleTime 5s
                ConnMaxLifetime 5s
            }
        }
    }
}

What does these directives mean?

Other resources

You can find an example for the Caddyfile or the JSON file.
See the Souin configuration for the full configuration, and its associated Caddyfile