Core Concepts: Filters, Actions, and Rules
Fluxzy is an intermediate HTTP agent that acts as a man-in-the-middle proxy. At its core, Fluxzy uses a rule-based system to capture, inspect, and modify HTTP traffic. Understanding three fundamental concepts is essential: Filters, Actions, and Rules.
┌─────────────────────────────────────────────────────────────────┐
│ RULE │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ FILTER │ │ ACTION │ │
│ │ │ │ │ │
│ │ "When should this │──────▶│ "What modification should │ │
│ │ rule apply?" │ │ be performed?" │ │
│ │ │ │ │ │
│ │ Examples: │ │ Examples: │ │
│ │ - Host matches │ │ - Add header │ │
│ │ - Method is POST │ │ - Mock response │ │
│ │ - Path contains │ │ - Delay request │ │
│ └─────────────────────┘ └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Filter
A Filter is a predicate that selects specific HTTP traffic. It evaluates each exchange and returns true (match) or false (no match). When a filter matches, the associated actions are executed.
Filters can match on virtually any aspect of an HTTP exchange:
- Host and Authority: Target specific domains or subdomains
- Request Method: Match GET, POST, PUT, DELETE, etc.
- URL Path: Filter by URL patterns, paths, or query strings
- Headers: Match request or response headers
- Status Code: Filter by HTTP response status
- Content Type: Target JSON, HTML, images, etc.
String Matching Operations
Filters that match string values support multiple operations:
| Operation | Description |
|---|---|
exact |
Exact string match |
contains |
Pattern appears anywhere |
startsWith |
Value starts with pattern |
endsWith |
Value ends with pattern |
regex |
Regular expression match |
Combining Filters
Multiple filters can be combined using FilterCollection with logical operators:
- And: All conditions must match
- Or: Any condition can match
Collections can be nested to create complex matching logic.
Common Filter Types
| Filter | Description | Example Use Case |
|---|---|---|
AnyFilter |
Matches all exchanges | Apply global rules |
HostFilter |
Matches by hostname | Target specific domains |
PathFilter |
Matches by URL path | Filter API endpoints |
MethodFilter |
Matches HTTP method | Target POST requests |
StatusCodeFilter |
Matches response status | Handle errors (4xx, 5xx) |
RequestHeaderFilter |
Matches request headers | Find authenticated requests |
ResponseHeaderFilter |
Matches response headers | Filter by content-type |
HasResponseBodyFilter |
Checks if response has body | Target non-empty responses |
Browse all available filters in the rule search page. Each filter page includes examples and configuration options.
Action
An Action is an operation that modifies the behavior of an HTTP exchange. Actions can alter requests, responses, or the underlying transport configuration.
What Actions Can Do
Actions fall into several categories:
Header Modifications
- Add, remove, or update request headers
- Add, remove, or update response headers
Body Modifications
- Replace request body with custom content
- Replace response body (mocking)
- Transform body content
Transport Modifications
- Force specific IP address resolution (DNS spoofing)
- Add client certificates (mutual TLS)
- Force HTTP version (HTTP/1.1, HTTP/2)
- Skip SSL decryption for specific hosts
Flow Control
- Abort the exchange
- Add artificial delays
- Forward requests to different servers
External Integration
- Execute external processes
- Write to stdout or files
- Set variables for use in other rules
Common Action Types
| Action | Description |
|---|---|
AddRequestHeaderAction |
Append a header to requests |
AddResponseHeaderAction |
Append a header to responses |
DeleteRequestHeaderAction |
Remove a request header |
DeleteResponseHeaderAction |
Remove a response header |
MockedResponseAction |
Return a pre-made response |
ForwardAction |
Redirect to a different server |
DelayAction |
Add latency to the exchange |
AbortAction |
Terminate the connection |
SpoofDnsAction |
Override DNS resolution |
SetClientCertificateAction |
Add client certificate |
ForceHttp11Action |
Downgrade to HTTP/1.1 |
ExecAction |
Execute external process |
StdOutAction |
Write to standard output |
Browse all available actions in the rule search page. Each action page includes examples and configuration options.
Rule
A Rule combines a Filter with one or more Actions. When the filter condition is met, all associated actions execute in order.
┌─────────────┐
HTTP Exchange ───▶│ Filter │
│ (matches?) │
└──────┬──────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
┌────────┐ ┌────────┐
│ YES │ │ NO │
└───┬────┘ └───┬────┘
│ │
▼ │
┌─────────────────┐ │
│ Execute Actions │ │
│ 1. Action A │ │
│ 2. Action B │ │
│ 3. ... │ │
└─────────────────┘ │
│ │
└────────────┬────────────┘
│
▼
Exchange continues
Rule Evaluation Order
When multiple rules are defined:
- Rules are evaluated in the order they appear
- If a filter matches, all its actions execute
- Evaluation continues to the next rule (rules don't short-circuit)
- Multiple rules can match and modify the same exchange
Learn the complete YAML syntax for writing rules in the rule file syntax documentation.
Filter Scope
A FilterScope defines the precise timing in the HTTP exchange lifecycle when a filter or action can be evaluated. This mechanism ensures coherency between filters and actions.
For example, to modify a response header, the response must have been received first. Fluxzy enforces this at configuration time.
HTTP Exchange Lifecycle
CLIENT FLUXZY SERVER
│ │ │
│──── CONNECT Request ────▶│ │
│ │ OnAuthorityReceived │
│ │ (host/port known) │
│ │ │
│ │──── DNS Resolution ─────▶│
│ │ DnsSolveDone │
│ │ │
│──── Request Headers ────▶│ │
│ │ RequestHeaderReceived │
│ │ (method, path, headers) │
│ │ │
│──── Request Body ───────▶│─── Request Forwarded ───▶│
│ │ RequestBodyReceived │
│ │ │
│ │◀── Response Headers ─────│
│ │ ResponseHeaderReceived │
│ │ (status, headers) │
│ │ │
│◀─── Response Body ───────│◀─── Response Body ───────│
│ │ ResponseBodyReceived │
│ │ │
Scope Definitions
| Scope | Timing | Available Information |
|---|---|---|
| OnAuthorityReceived | After CONNECT or first request line | Host, port, protocol |
| DnsSolveDone | After DNS resolution | Resolved IP address |
| RequestHeaderReceivedFromClient | Request headers parsed | Method, path, request headers |
| RequestBodyReceivedFromClient | Full request body received | Complete request |
| ResponseHeaderReceivedFromRemote | Response headers parsed | Status code, response headers |
| ResponseBodyReceivedFromRemote | Full response body received | Complete response |
Scope Compatibility
Filters and actions must have compatible scopes. A filter's scope must occur at or before the action's scope:
┌───────────────────────────────────────────────────────────────────┐
│ VALID COMBINATION │
│ │
│ HostFilter AddResponseHeaderAction │
│ (OnAuthorityReceived) ──▶ (ResponseHeaderReceived) │
│ │
│ Filter evaluates early, action runs when response arrives ✓ │
└───────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐
│ INVALID COMBINATION │
│ │
│ StatusCodeFilter ChangeRequestMethodAction │
│ (ResponseHeaderReceived) ──▶ (RequestHeaderReceived) │
│ │
│ Filter evaluates after action would need to run │
└───────────────────────────────────────────────────────────────────┘
When this rule is violated, you will receive a FilterOutOfScope error.
Streaming Behavior: By default, Fluxzy streams request and response bodies without buffering. This means RequestBodyReceivedFromClient and ResponseBodyReceivedFromRemote scopes may trigger after the body has already been forwarded. Use buffering actions if you need to inspect or modify the complete body.
How the Rule Engine Works
Understanding the rule engine helps you design effective rules:
┌─────────────────────────────────────────────────────────────────────┐
│ RULE ENGINE WORKFLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Exchange arrives at a FilterScope checkpoint │
│ │ │
│ ▼ │
│ 2. For each rule (in order): │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ a. Is filter scope compatible with current checkpoint? │ │
│ │ NO → Skip this rule │ │
│ │ YES → Continue │ │
│ │ │ │
│ │ b. Evaluate filter │ │
│ │ NO MATCH → Skip this rule │ │
│ │ MATCH → Continue │ │
│ │ │ │
│ │ c. Execute all actions for this rule │ │
│ │ (Actions may modify the exchange) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 3. Continue to next rule (no short-circuit) │
│ │ │
│ ▼ │
│ 4. Exchange continues to next stage │
│ │
└─────────────────────────────────────────────────────────────────────┘
Filter Result Caching
For performance, filter evaluation results are cached per exchange. If the same filter appears in multiple rules, it's only evaluated once.
Variable Context
Rules can extract and use variables:
- Named regex capture groups create user variables
- Environment variables are accessible
- Built-in variables provide exchange metadata
See the rule file syntax documentation for variable usage details.
Next Steps
- Learn the rule file syntax for writing YAML rules
- Browse available filters and actions
- Set up rules in Fluxzy Desktop or CLI