Rule Engine

The rule engine is the core of HTTPeep. Every other feature — mocking, throttling, breakpoints, DNS overrides — is implemented as a stage in the same deterministic pipeline: Match → Actions → Resolve → Response. You define rules once, and they apply automatically to every matching request from that point forward. Rules are stored as YAML files you can version-control, share with your team, and reuse across projects.

Pipeline overview

flowchart LR
    A[Incoming request] --> B{Match}
    B -->|No match| C[Pass through]
    B -->|Match| D[Request Actions]
    D --> E{Resolve}
    E -->|Pass Through| F[Origin server]
    E -->|Map Remote| G[Different host]
    E -->|Map Local| H[Local files]
    F & G & H --> I[Response Actions]
    I --> J[Client]

Each stage runs in order. If a request matches a rule, it proceeds through request actions, then a resolve outlet, then response actions. If no rule matches, the request passes through to the origin unmodified.

Stage 1 — Match

Match conditions determine which requests a rule applies to. You can combine multiple conditions; all specified conditions must be satisfied for a rule to match.

Domain matching

match:
  domains:
    - type: exact
      value: api.example.com

match:
  domains:
    - type: wildcard
      value: "*.example.com"

match:
  domains:
    - type: template
      value: "{env}.api.example.com"

Other match conditions

stopAfterMatched

When stopAfterMatched: true, HTTPeep stops evaluating subsequent rules after this rule matches. This is useful when you want a rule to act as a short-circuit for a specific domain or path without interference from lower-priority rules.

Stage 2 — Request actions

Request actions run before the request is forwarded. You can chain multiple actions; they execute in the order listed.

Stage 3 — Resolve

The resolve stage determines where the request ultimately goes. Every rule has exactly one resolve outlet.

Stage 4 — Response actions

Response actions run after the resolve stage returns a response. You can filter by status code or Content-Type to apply actions selectively.

Execution logs

Every stage of the pipeline is logged. In the session detail panel, the Rule tab shows which rule matched, which actions ran, which resolve outlet was used, and any response actions applied. Nothing is a black box — you can trace exactly what happened to any request.

Full YAML example

The following rule maps all HTTPS traffic to api.example.com to a local directory of mock files, then adds a 500 ms delay and throttles the download to 384 KB/s:

# rule.yaml - Frontend Mock API
- id: rule_mnhi5xkt
  description: "Frontend Mock API"
  enabled: true
  builtin: false
  stopAfterMatched: false
  match:
    domains:
      - type: exact
        value: api.example.com
    originProtocol: https
  requestActions: []
  resolve:
    type: map_local_dir
    filePath: /Users/chris/mocks/api
    headers:
      x-httpeep-debug: '1'
  responseActions:
    - type: delay_response
      id: action_1775140499860
      enabled: true
      delayMs: 500
    - type: throttle_response
      id: action_1775591855867
      enabled: true
      speed:
        max: 384
        burst: 768

Rule storage and team sharing

All rules are stored as plain YAML files under ~/.httpeep/rules/:

~/.httpeep/rules/
├── rule.yaml           # Main rule configuration
├── bypass.yaml         # Bypass configuration
├── dns_override.yaml   # DNS override configuration
├── external_proxy.yaml # External proxy configuration
└── rate_limit.yaml     # Rate limit configuration

Because rules are files, you can:

• Version-control them with Git to track every change
• Share them with teammates by committing to a shared repository
• Branch rule sets per project or environment
• Review rule changes through pull requests before applying them
• Export and import rules for quick migration between machines