Lesson 1

Caddy sorts your routes before it runs them

A Caddyfile is not what Caddy runs. The adapter reads it and emits a JSON configuration, and along the way it reorders the handle blocks. At request time Caddy walks the sorted list and takes the first route that matches. Knowing that order is knowing the answer.

The file you write is not the config that runs

caddy adapt prints the generated JSON, so nothing has to be guessed. Take a Caddyfile with five blocks written in no particular order:

handle /a*      { ... }
handle /abcdef* { ... }
handle /abc*    { ... }
handle /x/y/z*  { ... }
handle /x*      { ... }
handle          { ... }

The route order in the JSON that caddy adapt produces:

0  path /abcdef*
1  path /x/y/z*
2  path /abc*
3  path /a*
4  path /x*
5  (no matcher)

The order is nothing like the file. /abcdef* was written second and is evaluated first; /a* was written first and drops to fourth.

The sorting rule, from 24 measurements

The rule below is not copied from documentation. It is what fits 24 Caddyfiles put through caddy adapt, most of them written as pairs in opposite orders so that the effect of sorting can be separated from the effect of the order you typed.

Four pairs isolate one clause of the rule each. Each pair was run twice, with the two blocks swapped:

A non-path matcher stops the reordering

This is the second hard-to-guess part. A route carrying a different matcher — path_regexp, for instance — stays exactly where it is, and the reordering cannot cross it:

handle /a* { ... }

@re path_regexp \.gif$
handle @re { ... }

handle /abcdef* { ... }

If sorting were global, /abcdef* (specificity 7) would have to jump above /a* (specificity 2). What caddy adapt prints is:

0  path /a*
1  path_regexp \.gif$
2  path /abcdef*
3  (no matcher)

Unchanged. The description that fits every measurement: split the list into contiguous runs of routes carrying only a path matcher, sort inside each run, and leave everything else in place, ending the run there. A handle block with no pattern behaves the same way — it matches every request and is evaluated exactly where you wrote it, so putting one in the middle of a file kills everything below it.

handle /img/*             @gif path_regexp \.gif$
@gif path_regexp \.gif$   handle /img/*
handle @gif               handle @gif

curl /img/a.gif           curl /img/a.gif
→ "prefix /img/*"         → "regexp .gif$"

Two blocks with the same matcher merge silently

Write two handle /ab* blocks in the same site block. caddy adapt does not emit two routes; it emits one, with the two handlers chained inside it:

"routes": [ { "group": "group2",
    "match": [ { "path": ["/ab*"] } ],
    "handle": [ { "handler": "subroute", … "body": "P" },
                { "handler": "subroute", … "body": "Q" } ] } ]

curl /ab/x returns P: the block written first wins and the second becomes dead code. Caddy starts normally and says nothing. The merge does not require the blocks to be adjacent either — writing /ab*, /zz*, /ab* gives the same result.

nginx handles the same situation the other way round. With location /ab/ written twice, nginx -t says:

nginx: [emerg] duplicate location "/ab/" in /etc/nginx/conf.d/default.conf:4
nginx: configuration file /etc/nginx/nginx.conf test failed

Against nginx

Run the swap-two-lines experiment on nginx 1.27.5 with location /img/ and location ~ \.gif$, in both orders: both times /img/a.gif lands in the regex block. nginx does not care about the written order between a prefix block and a regex block, because it runs five fixed steps and the regex step always precedes the fall-back-to-prefix step.

The lab

Edit the Caddyfile and the path as you like. The algorithm running in your browser is a reimplementation of the rule above, checked against 24 caddy adapt results and 14 curl results from a real Caddy — all of them agree. The left column is the line number in the file, so you can see which route moved where and which blocks were merged.

Check yourself