规则 API 参考

规则引擎是 RelayCore 的核心流量控制机制。每条规则由 筛选条件 (Filter) + 执行动作 (Action) + 执行阶段 (Stage) 三要素组成，按优先级顺序在代理流水线中执行。

规则结构

{
  "id": "rule-001",           // 唯一标识
  "name": "Block Tracking",   // 可读名称
  "active": true,             // 是否启用
  "stage": "RequestHeaders",  // 执行阶段
  "priority": 100,            // 优先级（越高越先执行，默认 0）
  "termination": "Continue",  // 后续规则处理方式
  "filter": { ... },          // 匹配条件
  "actions": [ ... ],         // 动作列表（有顺序）
  "constraints": {            // 性能限制（可选）
    "timeout_ms": 5000
  }
}

执行阶段 (Stage)

阶段决定规则何时被评估。同一阶段内按 priority 降序执行：

筛选条件 (Filter)

Filter 决定规则是否生效。支持逐字段匹配和逻辑组合：

全局

L3/L4（Connect 阶段）

L7（HTTP/WS 阶段）

逻辑组合

字符串匹配器 (StringMatcher)

大部分 L7 filter 接受 StringMatcher 作为匹配模式：

执行动作 (Action)

Action 定义匹配后做什么。一条规则可包含多个 Action，按顺序执行。

通用控制

L3/L4 网络层

L7 HTTP — 终端动作（终止代理）

L7 HTTP — 修改动作

L7 HTTP — 转换动作

WebSocket

Body 数据源 (BodySource)

用于 SetRequestBody、SetResponseBody、MockResponse 等需要内容体的动作：

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

Body 转换 (BodyTransform)

// 正则替换
{"type": "RegexReplace", "config": {"pattern": "http://", "replacement": "https://"}}

// JsonPath 设置
{"type": "JsonPathSet", "config": {"path": "$.data.secret", "value": "***"}}

// JsonPath 删除
{"type": "JsonPathDelete", "config": {"path": "$.debug"}}

Mustache 变量替换

Action 的字符串字段支持 Mustache 模板语法，在运行时替换为实际值：

// 示例：MapRemote 使用 Mustache
{
  "type": "MapRemote",
  "config": {
    "url": "https://backend-{{host}}/v2{{request.path}}",
    "preserve_host": false
  }
}

// 示例：UpdateRequestHeader 使用 {{previous}}
{
  "type": "UpdateRequestHeader",
  "config": {
    "name": "X-Custom",
    "value": "{{previous}}; extra-value",
    "add_if_missing": true
  }
}

规则终止 (Termination)

Stop 只影响同一阶段。例如 RequestHeaders 阶段的 Stop 不会阻止 ResponseHeaders 阶段的规则。

RateLimit 详解

{
  "type": "RateLimit",
  "config": {
    "key": "{{ip}}:{{request.path}}",   // 按 IP+路径 组合限速
    "limit": 100,                         // 窗口内最多 100 请求
    "window_ms": 60000                    // 60 秒窗口
  }
}

支持 Mustache 模板作为 key。key 为 "ip" 时等同于 "{{client_ip}}"。

WebSocket 方向

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

管理规则

# 列出当前活跃规则（GET 返回规则数组）
curl http://127.0.0.1:8082/api/v1/rules

# CLI 查看活跃规则
relay-core-cli rules list

# PUT 添加/更新规则
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