拦截与改写能力

本页列出 RelayCore 内置的所有流量改写能力，每项配一个最小可用的 JSON 示例（直接喂给 PUT /api/v1/rules 或 relay-core-cli rules validate 即可）。完整的 filter 字段说明见 规则 API。

Mock Response

用本地假响应替换上游响应。常用于前端开发、契约测试、错误模拟。

{
  "id": "mock-health",
  "name": "Mock /v1/health",
  "filter": { "path": "/v1/health" },
  "action": {
    "type": "MockResponse",
    "status": 200,
    "headers": { "content-type": "application/json" },
    "body": { "type": "Text", "value": "{\"ok\":true}" }
  },
  "enabled": true
}

Map Local

把 HTTP 请求替换成本地文件。常用于前端联调、离线调试。

{
  "id": "map-local-static",
  "name": "Serve /static from disk",
  "filter": { "path_starts_with": "/static/" },
  "action": {
    "type": "MapLocal",
    "path": "/Users/me/projects/app/static",
    "content_type": null
  },
  "enabled": true
}

Map Remote

URL 重写为另一个地址。常用于将生产流量切到预发环境。

{
  "id": "map-remote-prod-to-staging",
  "name": "api.example.com -> staging",
  "filter": { "host": "api.example.com" },
  "action": {
    "type": "MapRemote",
    "url": "https://api-staging.example.com",
    "preserve_host": false
  },
  "enabled": true
}

Redirect

返回 3xx 重定向。

{
  "id": "redirect-legacy",
  "name": "/old -> /new",
  "filter": { "path": "/old" },
  "action": {
    "type": "Redirect",
    "location": "https://example.com/new",
    "status": 301
  },
  "enabled": true
}

Header 改写

增删改请求/响应头。所有 header 改写都支持 {{previous}} 变量引用改写前的值。

{
  "id": "strip-cookie",
  "name": "Strip Set-Cookie on /api/*",
  "filter": { "path_starts_with": "/api/" },
  "action": { "type": "DeleteResponseHeader", "name": "set-cookie" },
  "enabled": true
}

{
  "id": "add-debug",
  "name": "Add X-Debug header",
  "filter": { "method": "POST" },
  "action": {
    "type": "AddRequestHeader",
    "name": "x-debug",
    "value": "relay-core"
  },
  "enabled": true
}

Body 改写

支持整体替换、正则替换、JSONPath 修改。

{
  "id": "jsonpath-set",
  "name": "Force user.role = admin",
  "filter": { "host": "api.example.com" },
  "action": {
    "type": "TransformRequestBody",
    "transform": {
      "type": "JsonPathSet",
      "path": "$.user.role",
      "value": "\"admin\""
    }
  },
  "enabled": true
}

{
  "id": "regex-replace",
  "name": "Replace token in body",
  "filter": { "path": "/login" },
  "action": {
    "type": "TransformResponseBody",
    "transform": {
      "type": "RegexReplace",
      "pattern": "secret=([^&]+)",
      "replacement": "secret=REDACTED"
    }
  },
  "enabled": true
}

拦截断点

暂停实时流量等待人工决定。规则 set_intercept 创建断点；resume_flow 放行或丢弃。

# 创建一个请求阶段断点
relay-core-cli intercept create
# 等价于
curl -X POST http://127.0.0.1:8082/api/v1/intercepts \
  -H 'Content-Type: application/json' \
  -d '{
    "url_pattern": "api.example.com",
    "phase": "request"
  }'

断点命中时在 TUI Intercepts 面板可见，也可以通过 GET /api/v1/intercepts 查询。放行时可以携带修改：

curl -X POST http://127.0.0.1:8082/api/v1/intercepts/<key>/resume \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "continue",
    "request_headers": { "x-test": "value" }
  }'

支持修改的字段：method、url、request_headers、request_body、status_code、response_headers、response_body、message_content（WebSocket）。

流量重放

用之前捕获的请求/响应再发一次，可改写。

curl -X POST http://127.0.0.1:8082/api/v1/flows/fld_01HX.../replay \
  -H 'Content-Type: application/json' \
  -d '{
    "modifications": {
      "headers": { "x-test": "value" },
      "body": "raw body content"
    }
  }'

# TLS 校验失败时（仅调试！）
curl -X POST 'http://127.0.0.1:8082/api/v1/flows/fld_01HX.../replay?accept_invalid_certs=true'

WebSocket 消息改写

WebSocket 流量有专用的两个 action：

{
  "id": "ws-mock",
  "name": "Mock chat messages",
  "filter": { "host": "chat.example.com" },
  "action": {
    "type": "MockWebSocketMessage",
    "direction": "Incoming",
    "message": "{\"type\":\"welcome\",\"user\":\"bot\"}"
  },
  "enabled": true
}

也可以无条件丢弃某些消息：

{
  "id": "ws-drop-pings",
  "name": "Drop ping frames",
  "action": { "type": "DropWebSocketMessage" },
  "enabled": true
}

L3/L4 Action（未来）

以下 action 类型已注册但未在所有版本中启用，参见 规则 API 了解当前状态：

• RedirectIp — 重定向到不同 IP
• SetTtl — 修改 IP TTL
• ForwardPort — 转发到不同端口