Rule File Syntax

The rule file is a YAML configuration that defines how Fluxzy processes HTTP traffic. It works with Fluxzy Desktop, CLI, and the .NET library.

File Structure

A rule file contains a rules array. Each rule pairs a filter with one or more actions:

rules:
  - filter:
      typeKind: FilterType
      # filter properties...
    actions:
      - typeKind: ActionType
        # action properties...

Basic Example

rules:
  # Rule 1: Add cookie to requests matching example.com
  - filter:
      typeKind: HostFilter
      pattern: example.com
      operation: endsWith
    actions:
      - typeKind: SetRequestCookieAction
        name: my-session-cookie
        value: my-session-value

  # Rule 2: Add header and force HTTP/1.1 for POST requests
  - filter:
      typeKind: PostFilter
    actions:
      - typeKind: AddResponseHeaderAction
        headerName: X-Proxy
        headerValue: Passed through fluxzy
      - typeKind: ForceHttp11Action

Key points:

The root rules element must be unique
Each rule has one filter and one or more actions
Rules are evaluated in order of appearance
Filter and action names are case-insensitive
The Filter and Action suffixes can be omitted (e.g., Host instead of HostFilter)

Browse all available filters and actions in the rule search page. Each page includes configuration options and examples.

Filter Syntax

Simple Filters

Most filters use pattern and operation properties for string matching:

filter:
  typeKind: HostFilter
  pattern: api.example.com
  operation: exact

String Operations:

Operation	Description
`exact`	Exact string match
`contains`	Pattern appears anywhere in value
`startsWith`	Value starts with pattern
`endsWith`	Value ends with pattern
`regex`	Regular expression match

Case Sensitivity:

filter:
  typeKind: PathFilter
  pattern: /API/
  operation: contains
  caseSensitive: true  # default is false

Combining Filters with FilterCollection

Use FilterCollection to combine multiple filters with logical operators:

# AND: All conditions must match
filter:
  typeKind: FilterCollection
  operation: And
  children:
    - typeKind: HostFilter
      pattern: api.example.com
    - typeKind: MethodFilter
      pattern: POST

# OR: Any condition can match
filter:
  typeKind: FilterCollection
  operation: Or
  children:
    - typeKind: HostFilter
      pattern: api.example.com
    - typeKind: HostFilter
      pattern: api.backup.com

Nested Collections:

# (Host matches AND Method is POST) OR Path starts with /admin
filter:
  typeKind: FilterCollection
  operation: Or
  children:
    - typeKind: FilterCollection
      operation: And
      children:
        - typeKind: HostFilter
          pattern: api.example.com
        - typeKind: MethodFilter
          pattern: POST
    - typeKind: PathFilter
      pattern: /admin
      operation: startsWith

Inverting Filters

Use inverted: true to negate any filter:

# Match all hosts EXCEPT example.com
filter:
  typeKind: HostFilter
  pattern: example.com
  inverted: true

Common Filter Patterns

Match by HTTP Method:

# Using MethodFilter
filter:
  typeKind: MethodFilter
  pattern: POST

# Using pre-made filters
filter:
  typeKind: GetFilter    # GET requests only

filter:
  typeKind: PostFilter   # POST requests only

Match by Status Code:

filter:
  typeKind: StatusCodeFilter
  statusCodes:
    - 404
    - 500
    - 502
    - 503

Match by Request Header:

filter:
  typeKind: RequestHeaderFilter
  headerName: Authorization
  pattern: Bearer
  operation: startsWith

Match by Response Content-Type:

filter:
  typeKind: ResponseHeaderFilter
  headerName: Content-Type
  pattern: application/json
  operation: contains

Action Syntax

Header Actions

Add Request Header:

actions:
  - typeKind: AddRequestHeaderAction
    headerName: X-Custom-Header
    headerValue: custom-value

Add Response Header:

actions:
  - typeKind: AddResponseHeaderAction
    headerName: X-Proxy
    headerValue: Fluxzy

Update Existing Header:

actions:
  - typeKind: UpdateRequestHeaderAction
    headerName: User-Agent
    headerValue: "MyApp/1.0 ({{previous}})"  # {{previous}} = original value
    addIfMissing: false

Delete Header:

actions:
  - typeKind: DeleteRequestHeaderAction
    headerName: X-Unwanted-Header

Mocking Responses

Return a pre-made response without contacting the server:

Plain Text Response:

actions:
  - typeKind: MockedResponseAction
    response:
      statusCode: 200
      body:
        text: "Hello, World!"

JSON Response:

actions:
  - typeKind: MockedResponseAction
    response:
      statusCode: 200
      headers:
        - name: Content-Type
          value: application/json
      body:
        text: '{"status": "success", "data": []}'
        type: json

Response from File:

actions:
  - typeKind: MockedResponseAction
    response:
      statusCode: 200
      body:
        origin: file
        fileName: /path/to/response.json
        type: json

Error Responses:

actions:
  - typeKind: MockedResponseAction
    response:
      statusCode: 503
      body:
        text: "Service temporarily unavailable"

Flow Control Actions

Add Delay:

actions:
  - typeKind: DelayAction
    duration: 2000  # milliseconds

Abort Connection:

actions:
  - typeKind: AbortAction

Forward to Different Server:

actions:
  - typeKind: ForwardAction
    url: https://backup-server.example.com

Transport Actions

Force HTTP/1.1:

actions:
  - typeKind: ForceHttp11Action

Skip SSL Decryption:

actions:
  - typeKind: SkipSslTunnelingAction

Spoof DNS:

actions:
  - typeKind: SpoofDnsAction
    remoteHostIp: 192.168.1.100

Add Client Certificate:

actions:
  - typeKind: SetClientCertificateAction
    clientCertificate:
      pkcs12File: /path/to/certificate.pfx
      pkcs12Password: certificate-password

Using Variables

Variables allow dynamic values in rule configurations. Access variables using the ${prefix.name} syntax.

Variable Prefixes

Prefix	Description	Example
`user`	User-defined variables	`${user.myToken}`
`env`	Environment variables	`${env.API_KEY}`
`authority`	Current authority info	`${authority.host}`
`exchange`	Current exchange info	`${exchange.method}`
`global`	Global context	`${global.filterScope}`

Environment Variables

Access process environment variables:

actions:
  - typeKind: AddRequestHeaderAction
    headerName: Authorization
    headerValue: Bearer ${env.API_TOKEN}

Predefined Variables

Built-in variables for the current exchange:

Variable	Description
`authority.host`	Destination hostname
`authority.port`	Destination port
`authority.secure`	`true` if HTTPS
`exchange.id`	Exchange identifier
`exchange.url`	Full URL
`exchange.method`	Request method
`exchange.path`	Path and query string
`exchange.status`	Response status code
`global.filterScope`	Current filter scope

Example - Dynamic header based on host:

actions:
  - typeKind: AddRequestHeaderAction
    headerName: X-Forwarded-Host
    headerValue: ${authority.host}

Extracting Variables with Regex

Use named capture groups in regex patterns to extract values:

rules:
  - filter:
      typeKind: RequestHeaderFilter
      headerName: Authorization
      pattern: Bearer (?<TOKEN>.+)
      operation: regex
    actions:
      - typeKind: StdOutAction
        text: "Found token: ${user.TOKEN}"

The captured group TOKEN becomes accessible as ${user.TOKEN}.

Setting Variables with SetVariableAction

Define variables for use in subsequent rules:

rules:
  - filter:
      typeKind: PostFilter
    actions:
      - typeKind: SetVariableAction
        scope: responseHeaderReceivedFromRemote
        name: requestMethod
        value: POST

Variable names are case-insensitive
Variables can only hold string values
Predefined variables return empty string if not available

Practical Examples

Add Authentication to All API Requests

rules:
  - filter:
      typeKind: HostFilter
      pattern: api.myservice.com
    actions:
      - typeKind: AddRequestHeaderAction
        headerName: Authorization
        headerValue: Bearer ${env.API_TOKEN}
      - typeKind: AddRequestHeaderAction
        headerName: X-Client-Version
        headerValue: "1.0.0"

Mock a REST API Endpoint

rules:
  - filter:
      typeKind: FilterCollection
      operation: And
      children:
        - typeKind: PathFilter
          pattern: /api/users
          operation: exact
        - typeKind: GetFilter
    actions:
      - typeKind: MockedResponseAction
        response:
          statusCode: 200
          headers:
            - name: Content-Type
              value: application/json
          body:
            text: |
              [
                {"id": 1, "name": "Alice"},
                {"id": 2, "name": "Bob"}
              ]
            type: json

Simulate Network Latency

rules:
  - filter:
      typeKind: HostFilter
      pattern: slow-service.example.com
    actions:
      - typeKind: DelayAction
        duration: 3000

Block Tracking Domains

rules:
  - filter:
      typeKind: FilterCollection
      operation: Or
      children:
        - typeKind: HostFilter
          pattern: analytics.example.com
        - typeKind: HostFilter
          pattern: tracking.example.com
    actions:
      - typeKind: AbortAction

Redirect API Calls to Local Server

rules:
  - filter:
      typeKind: HostFilter
      pattern: api.production.com
    actions:
      - typeKind: SpoofDnsAction
        remoteHostIp: 127.0.0.1
        remoteHostPort: 8080

Extract and Log Bearer Tokens

rules:
  - filter:
      typeKind: RequestHeaderFilter
      headerName: Authorization
      pattern: "Bearer (?<token>[A-Za-z0-9._-]+)"
      operation: regex
    actions:
      - typeKind: StdOutAction
        text: "[${exchange.method}] ${authority.host} - Token: ${user.token}"

Conditionally Mock Based on Path

rules:
  # Mock /api/v1/users
  - filter:
      typeKind: PathFilter
      pattern: /api/v1/users
      operation: startsWith
    actions:
      - typeKind: MockedResponseAction
        response:
          statusCode: 200
          body:
            origin: file
            fileName: ./mocks/users.json
            type: json

  # Mock /api/v1/products
  - filter:
      typeKind: PathFilter
      pattern: /api/v1/products
      operation: startsWith
    actions:
      - typeKind: MockedResponseAction
        response:
          statusCode: 200
          body:
            origin: file
            fileName: ./mocks/products.json
            type: json

Skip SSL for Internal Services

rules:
  - filter:
      typeKind: FilterCollection
      operation: Or
      children:
        - typeKind: HostFilter
          pattern: .internal.corp
          operation: endsWith
        - typeKind: HostFilter
          pattern: localhost
    actions:
      - typeKind: SkipSslTunnelingAction

Loading Rule Files

Fluxzy CLI

fluxzy start -r rules.yaml

Fluxzy Desktop

Open Rules panel
Click Import and select your YAML file
Enable the imported rules

Fluxzy.Core (.NET)

var setting = FluxzySetting.CreateDefault();
setting.AddRulesFromFile("rules.yaml");

Next Steps

Understand core concepts (filters, actions, rules)
Browse the rule search page for all available filters and actions
Set up rules in Fluxzy Desktop or CLI