Директивы Caddyfile

Директивы — это функциональные ключевые слова, которые появляются внутри блоков сайта. Иногда они могут открывать собственные блоки, которые могут содержать поддирективы, но директивы нельзя использовать внутри других директив, если не указано иное. Например, вы не можете использовать basic_auth внутри блока file_server, потому что file_server не знает, как выполнять аутентификацию. Однако вы можете использовать некоторые директивы внутри специальных блоков директив, таких как handle и route, потому что они специально разработаны для группировки директив обработчика HTTP.

• Синтаксис
• Порядок директив
• Алгоритм сортировки

Следующие директивы поставляются с Caddy по умолчанию и могут использоваться в Caddyfile HTTP:

Синтаксис

Синтаксис каждой директивы будет выглядеть примерно так:

directive [<matcher>] <args...> {
	subdirective [<args...>]
}

<carets> указывают токены, которые должны быть заменены фактическими значениями.

[brackets] указывают необязательные параметры.

Многоточие ... указывает продолжение, т. е. один или несколько параметров или строк.

Поддирективы обычно необязательны, если не указано иное, даже если они не появляются в [brackets].

Матчи

Большинство (но не все) директив принимают маркеры матчинга, которые позволяют фильтровать запросы. Маркеры матчинга обычно необязательны. Директивы поддерживают матчи, если вы видите это в синтаксисе директивы:

[<matcher>]

Поскольку маркеры матчинга работают одинаково, различные варианты маркера матчинга не будут описаны на каждой странице, чтобы сократить дублирование. Вместо этого обратитесь к документации по матчинг для получения подробного объяснения синтаксиса.

Порядок директив

Многие директивы управляют цепочкой обработчиков HTTP. Порядок оценки этих директив имеет значение, поэтому в Caddy жестко закодирован порядок по умолчанию.

Вы можете переопределить/настроить этот порядок, используя глобальный параметр order или директиву route.

tracing
map
vars
fs
root
log_append
log_skip
log_name
header
copy_response_headers # only in reverse_proxy's handle_response block
request_body
redir# incoming request manipulation
method
rewrite
uri
try_files# middleware handlers; some wrap responses
basic_auth
forward_auth
request_header
encode
push
intercept
templates# special routing & dispatching directives
invoke
handle
handle_path
route# handlers that typically respond to requests
abort
error
copy_response # only in reverse_proxy's handle_response block
respond
metrics
reverse_proxy
php_fastcgi
file_server
acme_server

Алгоритм сортировки

Для простоты использования адаптер Caddyfile сортирует директивы по следующим правилам:

• Директивы с разными именами сортируются в соответствии с их положением в порядке по умолчанию. Порядок по умолчанию можно переопределить с помощью глобального параметра order. Директивы из плагинов не имеют порядка, поэтому глобальный параметр order или директива route должны быть использованы для его задания.

• Директивы с одинаковыми именами сортируются по их матчигам.

  • Наивысший приоритет имеет директива с одним маркером матчинга пути.

    Маркеры матчинга пути сортируются по специфичности, от наиболее специфичных к наименее специфичным.

    В целом, это выполняется путем сортировки по длине маркера матчинга пути. Существует одно исключение, когда если путь заканчивается на *, а пути двух маркеров совпадают, то маркер без * считается более специфичным и сортируется выше.

    Например:

    • /foobar более специфичен, чем /foo
    • /foo более специфичен, чем /foo*
    • /foo/* более специфичен, чем /foo*

  • Директива с любым другим маркером сортируется далее в порядке ее появления в Caddyfile.

    Это включает маркеры матчинга пути с несколькими значениями и именованные маркеры матчинга.

  • Директива без маркера (т. е. совпадающая со всеми запросами) сортируется последней.

• Директива vars меняет порядок сортировки по матчинг, так как она предполагает установку значений, которые могут перезаписывать друг друга, поэтому наиболее специфичный матчинг должен оцениваться последним.

• Содержание директивы route игнорирует все вышеперечисленные правила и сохраняет порядок директив в их появлении в файле.