Disclaimer

Usage

Build your caddy binary

We assume that you already installed the xcaddy binary on your device. If not, you can refer to the documentation here

  xcaddy build --with github.com/darkweak/souin/plugins/caddy

You should get a new caddy executable file in your current directory.

Run your HTTP cache

We need to tell caddy that it must use the HTTP cache with the cache global and handler directives. You can set your configuration globally and override it in each handlers.

  {
    debug
    cache {
        ttl 1h
    }
}

route {
    cache {
        ttl 30s
    }
    respond "Hello HTTP cache"
}

Configuration

Every configuration directives can be used either in the global or in the handler blocks.

Basic configuration

Usually we set the ttl, the stale and the default_cache_control directives in the global configuration.

  {
    ...
    cache {
        ttl 100s
        stale 3h
        default_cache_control public, s-maxage=100
    }
}

But we can go further by enabling the Souin API and enable the debug, prometheus, souin endpoints

  {
    ...
    cache {
        api {
            debug
            prometheus
            souin
        }
    }
}

route {
    cache
}

With this given configuration if you go on https://localhost/souin-api/souin we get the stored keys list.
If we go on https://localhost/souin-api/metrics we access to the prometheus web page.
If we go on https://localhost/souin-api/debug/ we access to the pprof web page.

Complex configuration

Storages

First you have to build Caddy with Souin and a storage using the following template.

  xcaddy build \
    --with github.com/darkweak/souin/plugins/caddy \
    --with github.com/darkweak/storages/{your_storage_name}/caddy

You can also use as many storages you want.

  xcaddy build \
    --with github.com/darkweak/souin/plugins/caddy \
    --with github.com/darkweak/storages/redis/caddy \
    --with github.com/darkweak/storages/nuts/caddy \
    --with github.com/darkweak/storages/otter/caddy

We can define multiple storages to use to store the response from the upstream server and specify the order. Here, we define 3 storages badger, nuts and redis and nuts will be accessed first, badger the second and redis the third only if the previous doesn’t return suitable data.

  {
    ...
    cache {
        badger {
            path /tmp/badger/default
        }
        nuts {
            path /tmp/nuts/default
        }
        redis {
            url 127.0.0.1:6379
        }

        storers nuts badger redis
    }
}

Indeed you can configure each storage with the path or url directive (depending the provider) but also with the configuration directive. That’s a simple key - value that are defined by the library used to implement each provider.

  route /nuts-path {
    cache {
        nuts {
            path /tmp/nuts/file
        }
    }
}

route /nuts-configuration {
    cache {
        nuts {
            configuration {
                Dir /tmp/nuts-configuration
                EntryIdxMode 1
                RWMode 0
                SegmentSize 1024
                NodeNum 42
                SyncEnable true
                StartFileLoadingMode 1
            }
        }
    }
    respond "Hello nuts"
}