HTTP API

REST + SSE API 需通过 relay-core-cli run --api-port 8082 启用，默认基址 http://127.0.0.1:8082/api/v1/。使用 --api-token <T> 启用 Authorization: Bearer <T> 认证，使用 --api-cors <origins> 允许浏览器跨域访问。仅当显式设置 --api-cors 时才会下发 CORS 头，否则严格同源。

版本与状态

GET /api/v1/version

引擎版本、API 版本与已注册的能力名称列表。

{
  "engine_version": "0.6.0",
  "api_version": "1",
  "capabilities": ["flows", "rules", "intercepts", "mock", "metrics", "status", "events", "scripts"]
}

GET /api/v1/status

运行时生命周期快照——运行时长、当前规则数、未决拦截数等。

流量

GET /api/v1/flows

搜索与分页已捕获流量。所有参数均可选。

GET /api/v1/flows?method=GET&host=api.example.com&limit=10&offset=0

查询参数：

  • host、path、path_contains、method — 子串匹配
  • status_min、status_max — 状态码区间
  • has_error — 仅含错误的流量
  • is_websocket — 仅 WebSocket 流量
  • limit — 返回条数（默认 50，范围 1–200）
  • offset — 分页偏移
{
  "items": [{ "id": "fld_...", "method": "GET", "path": "/users", "status": 200 }],
  "returned": 10,
  "limit": 50,
  "offset": 0
}

在响应离开服务器前会应用 redaction 策略：敏感 query 参数与 header 会被掩码，确保即使观察到敏感信息也不会外泄。

GET /api/v1/flows/:id

返回完整 Flow JSON（含 header 与 body）。同样应用 redaction。

POST /api/v1/flows/:id/replay

重放已捕获流量。请求体可携带修改参数。?accept_invalid_certs=true 在重放时跳过 TLS 校验（仅限调试）。

GET /api/v1/flows/:id/har

将单条流量导出为 HAR 1.2 entry。

GET /api/v1/flows/export/har

批量 HAR 导出，支持与 GET /api/v1/flows 相同的查询参数。

规则

GET /api/v1/rules

列出所有拦截规则。每条返回完整 Rule 对象（id、name、priority、stage、filter、actions、enabled）。

GET /api/v1/rules

PUT /api/v1/rules

按 id 创建或覆盖规则。

PUT /api/v1/rules 
{
  "id": "rul_01HX5K9P3Q8Y2Z7",
  "name": "Log API requests",
  "priority": 100,
  "filter": {
    "method": "GET",
    "host": "*.example.com",
    "path": "/api/*"
  },
  "action": {
    "type": "log"
  },
  "enabled": true
}

DELETE /api/v1/rules/:id

删除规则。

DELETE /api/v1/rules/rul_01HX5K9P3Q8Y2Z7

POST /api/v1/mock

快速创建 MockResponse 规则。Body 字段：url_pattern、status、body、content_type。

拦截

POST /api/v1/intercepts

创建一次性拦截断点。

{
  "url_pattern": "api.example.com",
  "phase": "request"
}

响应中包含生成的 rule_id，后续以此引用该拦截。

GET /api/v1/intercepts

列出待处理拦截（HTTP 与 WebSocket 一起）。

POST /api/v1/intercepts/:key/resume

继续被拦截的流量。Body 支持 action（continue 或 drop）以及任何 FlowModification 字段：method、url、request_headers、request_body、status_code、response_headers、response_body、message_content。

策略与脱敏

GET /api/v1/policy

返回当前 ProxyPolicy，包含 redaction 块以及（若已配置）upstream 块。Upstream auth.password 会被掩码为 ***。

PATCH /api/v1/policy

应用部分更新。两个顶层 key 均可省略：

{
  "redaction": {
    "enabled": true,
    "redact_bodies": true,
    "sensitive_header_names": ["authorization", "x-api-key", "cookie"],
    "sensitive_query_keys": ["token", "api_key", "password"]
  },
  "upstream": {
    "proxy_url": "http://corp-proxy.internal:8080",
    "bypass_hosts": ["*.internal", "127.0.0.1"],
    "fail_open": false
  }
}

默认敏感 header 名：authorization、proxy-authorization、cookie、set-cookie、x-api-key、x-auth-token。

默认敏感 query key：token、access_token、refresh_token、api_key、apikey、password、secret。

Redaction 作用于 HTTP 请求/响应、WebSocket 握手、每条 WebSocket 消息、流量摘要、搜索结果以及 SSE 事件流。运行时切换 upstream.proxy_url 会返回 409 Conflict，需要重启代理才能生效。

脚本

POST /api/v1/script

热加载脚本到运行中的引擎。

{ "script": "// deno-fmt-ignore\nexport default { onRequest(ctx) { /* ... */ } }" }

事件

GET /api/v1/events

实时更新的 Server-Sent Events 流。

GET /api/v1/events

事件类型：

  • flow — 新流量或流量更新（data 字段为完整 Flow JSON）
  • ws-message — 新 WebSocket 消息
  • http-body — body 片段可用，data 字段为 { "flow_id": "..." }，需通过 GET /api/v1/flows/:id 获取完整 body
  • body-budget-exceeded — body 预算耗尽，后续 body 不再发送
  • audit — 控制平面变更（规则变更、拦截解决、脚本重载、策略更新）
  • audit-lagged — 审计通道丢事件，服务器重新同步
  • lagged — 流量/事件通道丢事件，TUI 重新同步
  • lifecycle — 代理启动/停止/重载

指标

GET /api/v1/metrics

JSON 指标快照。字段同 relay-core-cli metrics（见 CLI 参考）。

GET /api/v1/metrics/prometheus

Prometheus 文本格式指标。

# HELP relay_core_flows_total Total number of flows captured
# TYPE relay_core_flows_total counter
relay_core_flows_total 12847

# HELP relay_core_request_duration_ms Request duration in milliseconds
# TYPE relay_core_request_duration_ms histogram
relay_core_request_duration_ms_bucket{le="1"} 10023
relay_core_request_duration_ms_bucket{le="5"} 12500
relay_core_request_duration_ms_bucket{le="10"} 12800
relay_core_request_duration_ms_bucket{le="+Inf"} 12847

脚本引擎指标按 hook 维度发射：relay_core_script_hook_duration_us{hook}、relay_core_script_hook_invocations_total{hook}、relay_core_script_hook_errors_total{hook}，另有 relay_core_script_env_access_total、relay_core_script_fetch_total 与 relay_core_script_fetch_rejected_total。

审计

GET /api/v1/audit

查询控制平面变更审计日志。

GET /api/v1/audit?since_ms=1705276800000&actor=http&kind=policy_updated

查询参数：

  • since_ms、until_ms — 毫秒时间戳；任一可省略
  • actor — runtime、http、tauri、probe、cli
  • kind — rule_changed、intercept_resolved、script_reloaded、policy_updated
  • outcome — success 或 failure

响应为 AuditEvent 数组，每条记录谁在何时做了何种变更，以及变更前/后的差异。