Apache Module mod_filter

Summary

Этот модуль позволяет выполнять интеллектуальную, контекстно-зависимую настройку фильтров содержимого вывода. Например, можно настроить Apache на обработку различных типов содержимого с помощью различных фильтров, даже если тип содержимого неизвестен заранее (например, при использовании прокси).

mod_filter работает, вводя косвенность в цепочку фильтров. Вместо вставки фильтров в цепочку, мы вставляем механизм фильтрации, который в свою очередь условно перенаправляет запрос к поставщику фильтра. Любой фильтр содержимого может использоваться в качестве поставщика для mod_filter; изменения в существующих модулях фильтров не требуются (хотя их можно упростить).

Интеллектуальная фильтрация

В традиционной модели фильтрации фильтры вставляются безусловно с помощью AddOutputFilter и аналогичных команд. Каждый фильтр затем должен определить, нужно ли его запускать, и для администраторов сервера доступно мало гибкости для динамической конфигурации цепочки.

mod_filter в отличие от этого даёт администраторам сервера большую гибкость в конфигурации цепочки фильтров. На самом деле, фильтры могут быть вставлены на основе сложных булевых выражений. Это обобщает ограниченную гибкость, предлагаемую AddOutputFilterByType.

Объявления фильтров, поставщики и цепочки

Рисунок 1: Традиционная модель фильтрации

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

Рисунок 2: Модель mod_filter

mod_filter работает, вводя косвенность в цепочку фильтров. Вместо вставки фильтров в цепочку, мы вставляем механизм фильтрации, который в свою очередь условно перенаправляет запрос к поставщику фильтра. Любой фильтр содержимого может использоваться в качестве поставщика для mod_filter; изменения в существующих модулях фильтров не требуются (хотя их можно упростить). Может быть несколько поставщиков для одного фильтра, но для каждого запроса будет выполняться не более одного поставщика.

Цепочка фильтров состоит из любого количества экземпляров механизма фильтрации, каждый из которых может иметь любое количество поставщиков. Частным случаем является один поставщик с безусловным перенаправлением: это эквивалентно прямой вставке фильтра-поставщика в цепочку.

Настройка цепочки

Для настройки цепочки фильтров с помощью mod_filter есть три этапа. Подробности директив см. ниже.

Объявить фильтры

Директива FilterDeclare объявляет фильтр, присваивая ему имя и тип фильтра. Требуется только если фильтр не имеет типа по умолчанию AP_FTYPE_RESOURCE.

Зарегистрировать поставщиков

Директива FilterProvider регистрирует поставщика для фильтра. Фильтр может быть объявлен с помощью FilterDeclare; в противном случае FilterProvider неявно объявит его с типом по умолчанию AP_FTYPE_RESOURCE. Поставщик должен быть зарегистрирован с помощью ap_register_output_filter каким-либо модулем. Последний аргумент FilterProvider — это выражение: поставщик будет выбран для выполнения запроса только в том случае, если выражение приведёт к значению true. Выражение может оценивать заголовки HTTP-запроса или ответа, переменные среды или обработчик, используемый этим запросом. В отличие от предыдущих версий, mod_filter теперь поддерживает сложные выражения, включающие несколько критериев с логикой И/ИЛИ (&& / ||) и скобками. Подробности синтаксиса выражений описаны в документации ap_expr.

Настроить цепочку

Вышеперечисленные директивы создают компоненты интеллектуальной цепочки фильтров, но не настраивают её для запуска. Директива FilterChain создаёт цепочку фильтров из объявленных интеллектуальных фильтров, предоставляя гибкость для вставки фильтров в начало или конец цепочки, удаления фильтра или очистки цепочки.

Фильтрация и код состояния ответа

mod_filter обычно выполняет фильтры только для ответов со статусом HTTP 200 (OK). Если вы хотите отфильтровать документы с другими кодами состояния ответа, можно установить переменную среды filter-errordocs, и она будет работать со всеми ответами независимо от статуса. Для дальнейшего уточнения можно использовать условия выражений с FilterProvider.

Обновление конфигурации Apache HTTP Server 2.2

Директива FilterProvider изменилась с httpd 2.2: аргументы match и dispatch заменены единственным, но более универсальным аргументом expression. В общем случае вы можете преобразовать пару match/dispatch в два операнда выражения, используя что-то вроде:

"dispatch = 'match'"

Заголовки запроса, заголовки ответа и переменные среды теперь интерпретируются в соответствии с синтаксисом %{req:foo}, %{resp:foo} и %{env:foo} соответственно. Также поддерживаются переменные %{HANDLER} и %{CONTENT_TYPE}.

Обратите внимание, что match больше не поддерживает совпадение по подстрокам. Их можно заменить совпадениями по регулярным выражениям.

Примеры

Включения на стороне сервера (SSI)

Простой пример замены AddOutputFilterByType

FilterDeclare SSI
FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
FilterChain SSI

Включения на стороне сервера (SSI)

То же самое, что и выше, но перенаправление по обработчику (классическое поведение SSI; файлы .shtml обрабатываются).

FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
FilterChain SSI

Эмуляция mod_gzip с помощью mod_deflate

Вставить фильтр INFLATE только в том случае, если "gzip" НЕ содержится в заголовке Accept-Encoding. Этот фильтр запускается с типом ftype CONTENT_SET.

FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
FilterChain gzip

Изменение размера изображения

Предположим, мы хотим уменьшить размер всех веб-изображений и имеем фильтры для GIF, JPEG и PNG.

FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"

FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider repack gif_pack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
<Location "/image-filter">
    FilterChain unpack downsample repack
</Location>

Обработка протокола

Исторически каждый фильтр отвечает за то, чтобы любые изменения, которые он вносит, корректно отражались в заголовках HTTP-ответа и чтобы он не запускался, если это приведёт к незаконному изменению. Это возлагает на авторов фильтров задачу повторной реализации некоторых общих функций в каждом фильтре:

• Многие фильтры изменяют содержимое, делая недействительными существующие теги содержимого, контрольные суммы, хеши и длины.
• Фильтры, которые требуют полного, непрерывного ответа на входе, должны гарантировать, что они не получат фрагменты байтов от бэкэнда.
• Фильтры, которые преобразуют вывод в фильтре, должны гарантировать, что они не нарушают заголовок Cache-Control: no-transform от бэкэнда.
• Фильтры могут сделать ответы некэшируемыми.

mod_filter призван предложить общую обработку этих деталей реализации фильтров, уменьшая сложность, необходимую модулям фильтров содержимого. Эта функция находится в стадии разработки; FilterProtocol реализует некоторые из этих функций для обеспечения обратной совместимости с модулями Apache 2.0. Для httpd 2.1 и более поздних версий, API ap_register_output_filter_protocol и ap_filter_protocol позволяют модулям фильтров объявлять своё поведение.

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

На момент написания этой функции в значительной степени не тестировалось, так как модули, которые обычно используются, предназначены для работы с версией 2.0. Модули, использующие эту функцию, должны тщательно её протестировать.

AddOutputFilterByType filter[;filter...] media-type [media-type] ...

AddOutputFilterByType DEFLATE text/html text/plain

<Location "/cgi-bin/">
    Options Includes
    AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>

FilterChain [+=-@!]filter-name ...

FilterDeclare filter-name [type]

FilterProtocol filter-name [provider-name] proto-flags

FilterProvider filter-name provider-name expression

FilterTrace filter-name level