Модуль Apache mod_filter

Краткое описание

Этот модуль позволяет настраивать выходные фильтры содержимого с учетом контекста. Например, 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}.

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

Примеры

Серверные включения (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 только в том случае, если в заголовке Accept-Encoding НЕТ значения "gzip". Этот фильтр работает с 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