requestHeaderFilter Filter

Select exchanges by inspecting a named request header with exact, contains, prefix, suffix or regex search, optionally case sensitive.

requestHeaderFilter is the workhorse selector when client side metadata is the cleanest way to identify the traffic you want to act on. Pair it with the request header actions to inspect, mutate or strip the value in the same rule pipeline.

When to use this filter

Use requestHeaderFilter when the most reliable selector for the traffic you care about is a header set by the client. Headers carry tokens, client identity, content negotiation hints and feature flags, so they are often more stable than the URL itself.

Typical situations:

Targeting traffic from a specific client version by matching its User-Agent string.
Acting only on requests that carry a specific Accept media type or Authorization scheme.
Detecting custom internal headers used to enable A/B variants or canary builds.

The filter evaluates on the requestHeaderReceivedFromClient scope, so every header is already available when the rule fires. The default operation is Contains, which is convenient for partial matches such as a browser substring.

Real world examples

Tag traffic from a specific client version

Apply a tag to every request issued by Chrome 112 by searching the User-Agent header for a substring.

rules:
- filter:
    typeKind: RequestHeaderFilter
    headerName: User-Agent
    pattern: 'Chrome/112 '
    operation: Contains
  actions:
  - typeKind: ApplyTagAction
    tag:
      value: chrome-112

Reject requests that do not accept JSON

Block any call to the API that declines JSON in its Accept header, a quick way to surface clients that forgot to negotiate properly.

rules:
- filter:
    typeKind: RequestHeaderFilter
    headerName: Accept
    pattern: application/json
    operation: Contains
    inverted: true
  actions:
  - typeKind: RejectWithStatusCodeAction
    statusCode: 406

Mock responses for a canary header

Return a canned response only when the client sends a specific canary header, leaving the rest of the traffic untouched.

rules:
- filter:
    typeKind: RequestHeaderFilter
    headerName: X-Canary
    pattern: 'enabled'
    operation: Exact
  actions:
  - typeKind: MockedResponseAction
    response:
      statusCode: 200
      body:
        type: fromString
        text: '{"variant":"canary"}'
        contentType: application/json

Reference

requestHeaderFilter

Description

Select exchanges according to request header values.

Evaluation scope

Evaluation scope defines the timing where this filter will be applied.

requestHeaderReceivedFromClient This scope occurs the moment fluxzy parsed the request header receiveid from client

YAML configuration name

requestHeaderFilter

Settings

The following table describes the customizable properties available for this filter:

Property	Type	Description	DefaultValue
headerName	string	Header name
pattern	string	The string pattern to search
operation	exact \| contains \| startsWith \| endsWith \| regex	The search operation performed	contains
caseSensitive	boolean	true if the Search should be case sensitive	false
inverted	boolean	Negate the filter result	false

Example of usage

The following examples apply a comment to the filtered exchange

Select exchanges having request header dnt: 1.

rules:
- filter:
    typeKind: RequestHeaderFilter
    headerName: dnt
    pattern: 1
    operation: Exact
  actions:
  - typeKind: ApplyCommentAction
    comment: filter was applied

Select exchanges issued by Chrome 112 by checking User-Agent.

rules:
- filter:
    typeKind: RequestHeaderFilter
    headerName: User-Agent
    pattern: 'Chrome/112 '
    operation: Contains
  actions:
  - typeKind: ApplyCommentAction
    comment: filter was applied

.NET reference

View definition of RequestHeaderFilter for .NET integration.

Frequently asked questions

Is the search case sensitive?

No by default. Set caseSensitive: true when matching tokens, base64 values or other identifiers where case carries meaning.

Which search operations are supported?

Exact, Contains, StartsWith, EndsWith and Regex. The default is Contains, which is convenient for matching a substring inside a longer header value.

Can the filter match repeated header values?

Yes. When a header appears more than once, the filter matches as soon as at least one value satisfies the pattern.

How do I select requests that are missing a header?

Use any pattern with inverted: true. The rule then fires when the named header is absent or its value does not satisfy the pattern.

Learn more about Fluxzy rules

Rule file syntax reference Importing YAML rules into Fluxzy Desktop Using rule files with Fluxzy CLI

Browse all directives