Caddy Http Cache

This is a http cache plugin for caddy 2. The difference between this and cache-handler https://github.com/caddyserver/cache-handler is that this one is much easier to understand and configure. But it does not support a distrobuted ache, and it needs to be compiled with golang 1.20 and caddy version v2.6.4

In fact, I am not so familiar with the part of cdn cache’s mechanism so I reference the code from https://github.com/nicolasazrak/caddy-cache. which is the caddy v1’s cache module. Then, I migrate the codebase to be consist with the caddy2 architecture and develop more features based on that.

Currently, this doesn’t support distributed cache yet. It’s still in plan.

Features

Multi storage backends support

Now the following backends are supported.

• file
• inmemory
• redis

In the latter part, I will show the example Caddyfile to serve different type of proxy cache server.

Conditional rule to cache the upstream response

• uri path matcher
• http header matcher

Set default cache’s max age

A default age for matched responses that do not have an explicit expiration.

Purge cache

There are exposed endpoints to purge cache. I implement it with admin apis endpoints. The following will show you how to purge cache

first you can list the current caches

Given that you specify the port 7777 to serve caddy admin, you can get the list of cache by the api below.

GET http://example.com:7777/caches

purge the cache with http DELETE request

It supports the regular expression.

DELETE http://example.com:7777/caches/purge
Content-Type: application/json

{
  "method": "GET",
  "host": "localhost",
  "uri": ".*\\.txt"
}

Support cluster with consul

NOTE: still under development and only the memory backend supports.

I’ve provided a simple example to mimic a cluster environment.

PROJECT_PATH=/app docker-compose --project-directory=./ -f example/distributed_cache/docker-compose.yaml up

How to build

In development, go to the cmd folder and type the following commands.

go build -ldflags="-w -s" -o caddy

To build linux binary by this

GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o caddy

Or you can use the xcaddy to build the executable file. Ensure you’ve install it by go get -u github.com/caddyserver/xcaddy/cmd/xcaddy

xcaddy build v2.6.4 --with github.com/sillygod/cdp-cache

Xcaddy also provide a way to develop plugin locally.

xcaddy run --config cmd/Caddyfile

To remove unused dependencies

go mod tidy

How to run

You can directly run with the binary.

caddy run --config [caddy file] --adapter caddyfile

Or if you are preferred to use the docker

docker run -it -p80:80 -p443:443 -v [the path of caddyfile]:/app/Caddyfile docker.pkg.github.com/sillygod/cdp-cache/caddy:latest

Configuration

The following will list current support configs in the caddyfile.

status_header

The header to set cache status. default value: X-Cache-Status

match_path

Only the request’s path match the condition will be cached. Ex. / means all request need to be cached because all request’s path must start with /

match_methods

By default, only GET and POST methods are cached. If you would like to cache other methods as well you can configure here which methods should be cached, e.g.: GET HEAD POST.

To be able to distinguish different POST requests, it is advisable to include the body hash in the cache key, e.g.: {http.request.method} {http.request.host}{http.request.uri.path}?{http.request.uri.query} {http.request.contentlength} {http.request.bodyhash}

default_max_age

The cache’s expiration time.

stale_max_age

The duration that a cache entry is kept in the cache, even though it has already expired. The default duration is 0.

If this duration is > 0 and the upstream server answers with an HTTP status code >= 500 (server error) this plugin checks whether there is still an expired (stale) entry from a previous, successful call in the cache. In that case, this stale entry is used to answer instead of the 5xx response.

match_header

only the req’s header match the condtions ex.

match_header Content-Type image/jpg image/png “text/plain; charset=utf-8”

path

The position where to save the file. Only applied when the cache_type is file.

cache_key

The key of cache entry. The default value is {http.request.method} {http.request.host}{http.request.uri.path}?{http.request.uri.query}

cache_bucket_num

The bucket number of the mod of cache_key’s checksum. The default value is 256.

cache_type

Indicate to use which kind of cache’s storage backend. Currently, there are two choices. One is file and the other is in_memory

cache_max_memory_size

The max memory usage for in_memory backend.

distributed

Working in process. Currently, only support consul to establish the cluster of cache server node.

To see a example config, please refer this

service_name

specify your service to be registered in the consul agent.

addr

the address of the consul agent.

health_check

indicate the health_check endpoint which consul agent will use this endpoint to check the cache server is healthy

Example configs

You can go to the directory example. It shows you each type of cache’s configuration.

Benchmarks

Now, I just simply compares the performance between in-memory and disk.

Env

Caddy run with the config file under directory benchmark and tests were run on the mac book pro (1.4 GHz Intel Core i5, 16 GB 2133 MHz LPDDR3)

Test Result

The following benchmark is analysized by wrk -c 50 -d 30s --latency -t 4 http://localhost:9991/pg31674.txt without log open. Before running this, ensure you provision the tests data by bash benchmark/provision.sh

	req/s	latency (50% 90% 99%)
proxy + file cache	13853	3.29ms / 4.09ms / 5.26ms
proxy + in memory cache	20622	2.20ms / 3.03ms / 4.68ms

Todo list

• [ ] upgrade to the latest caddy
• [ ] https://github.com/mastercactapus/caddy2-proxyprotocol https://caddyserver.com/docs/caddyfile/options#listener-wrappers https://github.com/pires/go-proxyproto (add proxy protocol support)
• [ ] distributed cache (in progress)
• [ ] more optimization..