Apache 模組 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 現在支援涉及多個條件的複雜表示式，且包含 AND / OR 邏輯 (&& / ||) 和括號。表示式語法的詳細資訊會在 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 配對轉換成表示式的兩邊

請求標頭、回應標頭和環境變數現在會根據語法 %{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_deflate 模擬 mod_gzip

僅在「Accept-Encoding」標頭中沒有「gzip」時，才插入 INFLATE 過濾器。此過濾器會和 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 和更新版本，ap_register_output_filter_protocol 和 ap_filter_protocol API 能讓過濾模組宣告自己的行為。

同時，mod_filter 不應干擾想要處理所有通訊協定面向的濾器。預設情況（例如，沒有任何 FilterProtocol 指令時），mod_filter 會讓標頭保持不變。

在撰寫本文件時，此功能在很大程度上尚未經過測試，因為一般使用的模組都是設計為可與 2.0 協作。使用此功能的模組應先仔細測試。