Заголовок

Управляет полями заголовков HTTP-ответа. Можно устанавливать, добавлять и удалять значения заголовков, а также выполнять замены с помощью регулярных выражений.

По умолчанию операции с заголовками выполняются немедленно, если только какие-либо из заголовков не удаляются (префикс -) или не устанавливается значение по умолчанию (префикс ?). В этих случаях операции с заголовками автоматически откладываются до момента записи на клиент.

Для управления заголовками HTTP-запроса можно использовать директиву request_header.

Синтаксис

header [<matcher>] [[+|-|?|>]<field> [<value>|<find>][<replace>]] {	# Add
	+<field> <value>	# Set
	<field> <value>	# Set with defer
	><field> <value>	# Delete
	-<field>	# Replace
	<field> <find> <replace>	# Replace with defer
	><field> <find> <replace>	# Default
	?<field> <value>
	[defer]
}

• <field> — имя поля заголовка.

  Без префикса поле устанавливается (перезаписывается).

  Префикс + добавляет поле, вместо перезаписи, если поле уже существует; поля заголовков могут появляться более чем один раз в запросе.

  Префикс - удаляет поле. Поле может использовать префиксы или суффиксы * для удаления всех соответствующих полей.

  Префикс ? устанавливает значение по умолчанию для поля. Поле записывается только если оно еще не существует.

  Префикс > устанавливает поле и включает defer — сокращение.

• <value> — значение поля заголовка при добавлении или установке поля.

• <find> — подстрока или регулярное выражение для поиска.

• <replace> — значение замены; необходимо при поиске и замене. Используйте $1 или $2 и так далее, чтобы сослаться на группы захвата из шаблона поиска. Если значение замены — "", то соответствующий текст удаляется из значения. Для подробностей обратитесь к документации Go по regexp.

• defer принудительно отложит операции с заголовками до момента записи ответа клиенту. Это автоматически включено, если удаляются какие-либо поля заголовков с -, при установке значения по умолчанию с ? или при использовании префикса >.

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

При использовании префикса ? для установки значения заголовка по умолчанию, он автоматически отделяется в свой собственный header обработчик, если он находился в блоке header с несколькими операциями над заголовками. Внутри использование ? настраивает совпадение ответа, которое применяется ко всему обработчику директивы, который применяет только операции с заголовками (например, defer), но только если поле ещё не установлено.

Примеры

Установить пользовательское поле заголовка для всех запросов:

header Custom-Header "My value"

Удалить поле заголовка "Hidden":

header -Hidden

Заменить http:// на https:// в любом заголовке Location:

header Location http:// https://

Установить заголовки безопасности и конфиденциальности для всех страниц: (ВНИМАНИЕ: используйте только если понимаете последствия!)

header {	# disable FLoC tracking
	Permissions-Policy interest-cohort=()	# enable HSTS
	Strict-Transport-Security max-age=31536000;	# disable clients from sniffing the media type
	X-Content-Type-Options nosniff	# clickjacking protection
	X-Frame-Options DENY
}

Несколько взаимно исключающих директивы заголовков:

route {
	header           Cache-Control max-age=3600
	header /static/* Cache-Control max-age=31536000
}

Установить значение кэширования по умолчанию, если оно не задано поставщиком:

header ?Cache-Control "max-age=3600"
reverse_proxy upstream:443

Для переопределения срока действия кэша, установленного прокси-поставщиком для путей, начинающихся с /no-cache; необходимо включить defer, чтобы убедиться, что заголовок устанавливается после записи прокси своих заголовков:

header /no-cache* >Cache-Control nocache
reverse_proxy upstream:443

Для отложенного обновления заголовка Set-Cookie, чтобы добавить SameSite=None; используется захват regexp для получения существующего значения, а $1 вставляет его в начало с добавленным параметром:

header >Set-Cookie (.*) "$1; SameSite=None;"