Rule API Reference

The rule engine is the core traffic control mechanism in RelayCore. Each rule consists of a Filter (what to match), Action (what to do), and Stage (when to execute), executed by priority in the proxy pipeline.

Rule Structure

{
  "id": "rule-001",           // Unique identifier
  "name": "Block Tracking",   // Human-readable name
  "active": true,             // Whether enabled
  "stage": "RequestHeaders",  // Execution stage
  "priority": 100,            // Priority (higher = earlier, default 0)
  "termination": "Continue",  // How to handle subsequent rules
  "filter": { ... },          // Match condition
  "actions": [ ... ],         // Action list (ordered)
  "constraints": {            // Performance limits (optional)
    "timeout_ms": 5000
  }
}

Execution Stages

The stage determines when a rule is evaluated. Rules within the same stage execute by priority descending:

Stage	Layer	Trigger	Available Filters
`Connect`	L3/L4	TCP connection established	IP/Port/Protocol/TransparentMode
`RequestHeaders`	L7	After request headers parsed	Url/Host/Path/Method/RequestHeader
`RequestBody`	L7	Request body ready	Above + body content
`ResponseHeaders`	L7	Response headers received	StatusCode/ResponseHeader
`ResponseBody`	L7	Response body ready	Above + ResponseBody
`WebSocketMessage`	L7	Each WS frame received	WebSocketMessage

Filters

Filters determine whether a rule applies. Available by stage:

Global

Filter	Description	Example
`All`	Matches all traffic	`{"type": "All"}`

L3/L4 (Connect stage)

`SrcIp`	Source IP (CIDR)	`"192.168.1.0/24"`
`DstPort`	Destination port	`443`
`Protocol`	Transport protocol	`"TCP"`
`TransparentMode`	Whether transparent proxy	`true`

L7 (HTTP/WS stages)

`Url`	Full URL match
`Host`	Domain match
`Path`	URL path match
`Method`	HTTP method
`RequestHeader`	Request header (name + optional value)
`ResponseHeader`	Response header (name + optional value)
`StatusCode`	Response status code
`ResponseBody`	Response body content
`WebSocketMessage`	WebSocket message content

Logical Compositors

`And`	All child filters must match
`Or`	Any child filter matches (1.0 uses any() semantics)
`Not`	Negate the child filter

StringMatcher

Most L7 filters accept a StringMatcher mode:

Mode	Description	Example
`Exact`	Exact match
`Contains`	Substring match
`Prefix`	Starts with
`Suffix`	Ends with
`Regex`	Regular expression
`Glob`	Glob/wildcard pattern

Actions

Actions define what to do when a rule matches. A rule can have multiple actions, executed in order.

Universal Control

`Drop`	Drop connection immediately
`Abort`	RST reset connection
`Delay` {"ms":100}	Latency simulation
`Throttle` {"kbps":1024}	Bandwidth throttle
`Inspect`	Pause flow for manual inspection (requires Tauri UI; no-op in CLI mode)
`Tag`	Tag the flow (visible to scripts)
`SetVariable`	Set a cross-rule variable
`RateLimit`	Rate limit by key

L3/L4 Network

`RedirectIp`	Redirect target IP
`ForwardPort`	Change target port
`SetTtl`	Set IP TTL

L7 HTTP — Terminal (stops proxying)

`MockResponse`	Return mock HTTP response
`MapLocal`	Serve local file as response
`MapRemote`	Forward to different backend
`Redirect`	HTTP redirect

L7 HTTP — Modifications

AddRequestHeader / UpdateRequestHeader / DeleteRequestHeader

AddResponseHeader / UpdateResponseHeader / DeleteResponseHeader

SetRequestMethod / SetRequestUrl

SetRequestBody / SetResponseBody

SetResponseStatus

L7 HTTP — Transformations

TransformRequestBody / TransformResponseBody

WebSocket

`MockWebSocketMessage`	Replace WS message
`DropWebSocketMessage`	Drop WS message

BodySource

For actions that need body content (SetRequestBody, SetResponseBody, MockResponse, MapLocal):

{"type": "Text",   "value": "{\"status\":\"ok\"}"}
{"type": "File",   "value": "/path/to/mock.json"}
{"type": "Base64", "value": "eyJzdGF0dXMiOiJvayJ9"}

BodyTransform

// Regex replace
{"type": "RegexReplace", "config": {"pattern": "http://", "replacement": "https://"}}
// JsonPath set
{"type": "JsonPathSet", "config": {"path": "$.data.secret", "value": "***"}}
// JsonPath delete
{"type": "JsonPathDelete", "config": {"path": "$.debug"}}

Mustache Variable Substitution

String fields in actions support Mustache template syntax, resolved at runtime:

Variable	Resolves to
`{{host}}`	Request target hostname
`{{request.path}}`	Request URL path
`{{request.url}}`	Full request URL
`{{request.method}}`	HTTP method
`{{ip}}` / `{{client_ip}}`	Client IP address
`{{previous}}`	The field's original value before this action
`{{variable.xxx}}`	Value set by SetVariable action
`{{timestamp}}`	Unix millisecond timestamp

Termination

`Continue`	Keep processing subsequent rules (default)
`Stop`	Skip remaining rules in this stage

RateLimit

{
  "type": "RateLimit",
  "config": {
    "key": "{{ip}}:{{request.path}}",
    "limit": 100,
    "window_ms": 60000
  }
}

WebSocket Direction

{"type": "MockWebSocketMessage", "config": {
  "direction": "Incoming",     // or "Outgoing"
  "message": "replaced message"
}}

Managing Rules

# HTTP API
curl -X PUT http://127.0.0.1:8082/api/v1/rules \
  -H "Content-Type: application/json" \
  -d '{"id":"r1","name":"log-api","active":true,"stage":"RequestHeaders",
       "priority":10,"termination":"Continue",
       "filter":{"type":"Url","config":{"mode":"Contains","value":"/api/"}},
       "actions":[{"type":"AddRequestHeader","config":{"name":"X-Logged","value":"true"}}]}'

# MCP tool
mcp: relay-core set_rule --rule rule.json