How to Configure Request and Response Header Manipulation Filters in INFINI Gateway

INFINI Gateway provides request_header_filter and response_header_filter plugins that allow you to permit or block traffic based on HTTP header values using include and exclude rules, with configurable actions for denying requests or redirecting flows.

INFINI Gateway supports fine-grained traffic control through header-based filtering. The request_header_filter and response_header_filter plugins enable you to inspect and manipulate traffic based on HTTP headers before requests reach upstream services or after responses are received, as implemented in the infinilabs/gateway repository.

Understanding the Header Filter Schema

Both filters share an identical configuration structure defined in the source code. You define rules using the following parameters:

• exclude — Array of <header>: <value> maps. Traffic matching any pair is denied or redirected.
• include — Array of <header>: <value> maps. Traffic must match at least one pair to proceed.
• action — Either deny (default) or redirect_flow.
• status — HTTP status code returned when action is deny.
• message — Custom JSON error message for denied requests.
• flow — Target flow identifier when using redirect_flow.

Configuring the Request Header Filter

The request_header_filter inspects incoming client headers during the request phase before proxying to upstream services.

Basic Configuration Structure

According to proxy/filters/filter/request_header_filter.go, the filter evaluates headers as soon as the request enters the flow.

flow:
  - name: allow-trace
    filter:
      - request_header_filter:
          include:
            - TRACE: true
          action: deny
          status: 403
          message: "Trace header missing"

In this example, only requests containing TRACE: true pass through. Requests without this header receive a 403 Forbidden response with the specified JSON payload. The filter leverages base logic from proxy/filters/filter/request_filter_base.go.

Configuring the Response Header Filter

The response_header_filter evaluates headers returned by upstream services before sending responses to clients.

Basic Configuration Structure

Located at proxy/filters/filter/response_header_filter.go, this plugin processes the response phase of the HTTP transaction.

flow:
  - name: block-nocache
    filter:
      - response_header_filter:
          exclude:
            - Cache-Control: no-cache
          action: deny
          status: 502
          message: "Caching disabled responses are blocked"

This configuration blocks any response containing Cache-Control: no-cache, returning a 502 Bad Gateway status instead of the original response body.

Common Configuration Patterns

Whitelisting with Include Rules

Use the include parameter to create allowlists. The request or response must contain at least one header-value pair from this list to proceed. If no match is found, the configured action triggers.

Blacklisting with Exclude Rules

Use the exclude parameter to create denylists. Any traffic matching a header-value pair in this array immediately triggers the filter action. This is useful for blocking specific user agents or content types.

Flow Redirection

When action is set to redirect_flow, the filter routes matching traffic to an alternate processing pipeline instead of denying it. Specify the target pipeline name in the flow parameter.

Summary

• Both request_header_filter and response_header_filter use identical configuration schemas in the INFINI Gateway source code.
• Configure header matching using include (allowlist) or exclude (denylist) arrays containing <header>: <value> maps.
• Set action to deny for blocking with custom status codes and message payloads, or redirect_flow for alternate routing.
• Reference implementations are located in proxy/filters/filter/request_header_filter.go and proxy/filters/filter/response_header_filter.go, with documentation available in docs/content.en/docs/references/filters/request_header_filter.md.

Frequently Asked Questions

What is the difference between include and exclude in INFINI Gateway header filters?

The include parameter acts as an allowlist: requests or responses must contain at least one of the specified header-value pairs to pass through. The exclude parameter acts as a denylist: traffic matching any specified header-value pair triggers the filter action, which can be denial or redirection to another flow.

Can I redirect traffic to another flow instead of denying it?

Yes. Set the action parameter to redirect_flow and specify the target pipeline name in the flow parameter. This configuration routes matching requests or responses to an alternate flow for further processing rather than returning an HTTP error status.

Where are the header filter implementations located in the INFINI Gateway repository?

The request header filter is implemented in proxy/filters/filter/request_header_filter.go, while the response header filter is in proxy/filters/filter/response_header_filter.go. Both share base functionality from proxy/filters/filter/request_filter_base.go. Official documentation is maintained in docs/content.en/docs/references/filters/request_header_filter.md.

What HTTP status codes can I return when denying requests?

You can specify any valid HTTP status code using the status integer parameter when action is set to deny. Common choices include 403 (Forbidden), 502 (Bad Gateway), or 401 (Unauthorized), depending on your specific security and routing requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}