Update directive sorting order description for clarity

[christaikobo]

Document here https://caddyserver.com/docs/caddyfile/directives#directive-order says:

Same-named directives are sorted according to their matchers.

The highest priority is a directive with a single path matcher.

A directive with any other matcher is sorted next, in the order it appears in the Caddyfile. This includes path matchers with multiple values, and named matchers.

Based on the description, one would logically assume that, when sorting same named directive, like handle under the same site block, like:

example.com {
    @UA header User-Agent *something*
    handle @UA {
        reverse_proxy 127.0.0.1:8080
    }
    handle /path1 {
        reverse_proxy 127.0.0.1:8081
    }
    handle /path2 {
        reverse_proxy 127.0.0.1:8082
    }
}

path1 and path2 would have highest priority, after all they have a single path matcher. @UA as a named matcher would be sorted next, based on the order it appeared in the caddyfile.

However in reality, the @UA matcher is the first one to be handled, which contradicts what is being said in the documents.

On the forum a dev told me that (https://caddy.community/t/confusion-about-directive-order/30985):

If they’re different, the matcher defined first stays before the other. https://github.com/caddyserver/caddy/blob/master/caddyconfig%2Fhttpcaddyfile%2Fdirectives.go#L496-L500

Maybe, the document could use some touch up for clarity regarding the sorting order?

[mholt]

That does look incongruent, indeed. We should definitely update the docs. Before we do, do you think the current behavior makes sense?

[christaikobo]

For my use case, the current behavior makes a lot of sense.

I think in general, when I am using a named matcher, it's usually something special that I am trying to do and I want it to be prioritized over generic single path matchers. On the other hand, if I really want a certain single path matcher to have higher priority, I can always put it in a named matcher.

Let's take this as an example:

example.com {
    @UA header User-Agent *something*
    handle @UA {
        reverse_proxy 127.0.0.1:8080
    }
    handle /path1 {
        reverse_proxy 127.0.0.1:8081
    }
    handle /path2 {
        reverse_proxy 127.0.0.1:8082
    }
}

In this example, my intention is to catch all requests with certain user agent first, and if I really want /path2 to be prioritized, I think I can simply do this:

example.com {
    @path2 path /path2
    handle @path2 {
        reverse_proxy 127.0.0.1:8082
    }
    @UA header User-Agent *something*
    handle @UA {
        reverse_proxy 127.0.0.1:8080
    }
    handle /path1 {
        reverse_proxy 127.0.0.1:8081
    }
}

The current behavior is IMO better than the alternative, which is the single path matcher having priority. In that case, if I really want a named matcher to have priority, I would need to wrap everything else in another handle block which adds a layer of indentation as well:

example.com {
    @UA header User-Agent *something*
    handle @UA {
        reverse_proxy 127.0.0.1:8080
    }
    handle {
        handle /path1 {
            reverse_proxy 127.0.0.1:8081
        }
        handle /path2 {
            reverse_proxy 127.0.0.1:8082
        }
    }

This is not preferred.

So to warp it up, I think the current logic is very sensible. The document needs to be updated to correctly reflect the logic. The current explanation for same name directive has 3 sub paragraphs, the order of the first 2 should be inverted, and I feel like the wording can use a little touch up for better clarification. For example, "sorted next" is a bit ambiguous, if I am sorting 3 apples and 3 oranges purely based on their size, I sort apples first and oranges second, that doesn't necessarily mean that the order is 3 apples then 3 oranges, it's just I started sorting orange after I finished sorting apples, one of the orange could still be largest therefore take the NO.1 place in the order. I think "order" "position" or "priority" are better ways to describe them. (Though as a non native speaker, it's only my 2 cents)