Metadata-Version: 2.5
Name: mock-proxy
Version: 0.2.0
Summary: Mock Proxy Service with iptables interception and dynamic rules
Author: Developer
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Testing :: Mocking
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Mock Proxy Service (Mock 代理服务)

一个用于在开发测试过程中拦截第三方/外部 HTTP 接口并模拟返回定制数据的全功能 Mock 代理服务。

解决痛点：业务应用（如工程 A）调用了外部接口 `http://xxx.com/test`，代码中针对此接口报错编写了 catch 容错/降级逻辑，但在实际联调测试时外部接口极少报错。借助本服务，可以在**完全不改动业务代码、不污染业务网络配置**的前提下，通过客户端 Linux `iptables` 安全劫持与服务端规则引擎模拟 500、502、超时或异常响应，并提供现代化的 Web UI 监控看板与 AI Agent Skill 赋能。

---

## 🌟 核心特性

- **无侵入透明劫持**：客户端 Agent 自动在 Linux 本机 `iptables` 中创建隔离的 `MOCK_PROXY_OUTPUT` 专有链，精准 DNAT 劫持目标域名/IP 到服务端。
- **全生命周期安全保障 (Safe Teardown)**：
  - 客户端严格向下兼容 **Python 3.6+**，便于在各类旧版服务器（CentOS 7、Ubuntu 18.04 等）上直接运行。
  - 自动监听退出信号（Ctrl+C / SIGTERM / atexit），进程终止时**100% 自动还原与清理 iptables 规则**。
  - 提供独立急救清理命令：`python -m client.agent clean`。
- **高级多维规则引擎与多服务分派**：
  - 支持 Host 通配符（如 `*.partner.com`）、Path 精确/前缀/正则表达式（如 `^/api/v1/.*$`）、HTTP Method、Query 参数与 Body 匹配。
  - **支持按服务/代理分派生效**：每条规则可指定生效的一个或多个具体服务（如 `order-service-dev`、`payment-uat` 或全局通用 `*`），避免多服务/多环境测试相互干扰。
  - 支持**静态响应**（自定义状态码如 500/502/400、自定义响应头、响应延迟模拟、JSON/文本）。
  - 支持**Python 沙箱动态脚本**（可模拟概率性抛错、基于请求参数动态计算响应内容）。

- **未命中真实透传 (Passthrough)**：未匹配任何 Mock 规则的请求原样转发至真实外部接口，返回真实响应。
- **现代化 Web UI 管理后台 (Vue 3 + Element Plus)**：
  - **Mock 规则管理**：在线配置、规则开关、优先级调整、动态脚本语法高亮与测试。
  - **拦截目标配置**：添加/移除需劫持的外部域名，变更实时推送给所有在线客户端 Agent。
  - **实时抓包控制台 (Live Traffic Inspector)**：类似 Charles/Fiddler 的实时流量流，支持请求头/体对比，以及**“一键从流量生成 Mock 规则”**。
  - **客户端节点状态**：实时观察在线 Agent 节点与心跳。
- **AI Agent Skill 深度集成**：内置 `skills/mock-proxy/SKILL.md`，可供 OpenCode、Claude 及其他 AI 辅助编程 Agent 直接调用，实现“自动配 Mock -> 触发测试 -> 审查抓包 -> 清理还原”的自动化闭环！

---

## 📂 项目目录结构

```text
mock-proxy/
├── server/                     # 服务端核心
│   ├── app.py                  # FastAPI 主服务（集成 REST、WebSocket、静态托管）
│   ├── config.py               # 服务端配置 (端口、数据目录)
│   ├── proxy/                  # 代理引擎模块
│   │   ├── engine.py           # 代理处理与生命周期分发
│   │   ├── matcher.py          # 多维规则匹配引擎
│   │   ├── executor.py         # 动态 Python 脚本沙箱执行器
│   │   └── passthrough.py      # 真实上游透传客户端
│   ├── hub/                    # 管控中心模块
│   │   ├── database.py         # SQLite 异步存储
│   │   ├── ws_manager.py       # WebSocket 广播管理 (Agent & Web UI)
│   │   └── routers/            # REST API 路由 (rules, targets, traffic, agents, skills)
│   └── static/                 # Vue 3 前端生产构建产物
├── client/                     # 客户端 Agent (Python 3.6+ 严格向下兼容)
│   ├── agent.py                # Agent 守护进程命令行入口
│   ├── iptables.py             # Linux iptables 隔离链与安全清理
│   ├── dns_watcher.py          # 动态 DNS 解析监控
│   └── ws_client.py            # WebSocket 策略同步客户端
├── skills/                     # AI Agent Skill 技能定义
│   └── mock-proxy/
│       └── SKILL.md            # 提供给 OpenCode / AI Agent 调用的技能说明与脚本
├── web/                        # Vue 3 + Element Plus 前端工程源码
└── tests/                      # 自动化测试套件 (全量覆盖)
```

---

## 📦 安装方式 (PyPI)

```bash
pip install mock-proxy
```

安装完成后，系统将自带 `mock-proxy-server` 与 `mock-proxy-agent` 两个开箱即用的命令行工具：

- **启动服务端**：`mock-proxy-server --port 8000 --proxy-port 8888`
- **启动客户端**：`sudo mock-proxy-agent run --server <服务端IP> --service <服务名>`
- **急救清理**：`sudo mock-proxy-agent clean`

---

## 🚀 快速启动指南 (源码开发)

### 1. 启动 Mock Proxy 服务端

依赖环境：Python 3.10+、uv（或 pip）

```bash
# 进入项目目录
cd /home/coder/project/mock-proxy

# 使用 uv 同步安装依赖并启动服务
uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
```
- **Web UI 管理后台**：打开浏览器访问 `http://<服务器IP>:8000`
- **代理端口（Proxy Engine）**：监听 `0.0.0.0:8888`

---

### 2. 启动客户端 Agent（业务应用所在机器）

依赖环境：Linux 宿主机、Python 3.6+（需 sudo 权限配置 iptables）

```bash
# 启动常驻守护进程（连接服务端同步目标并管理 iptables，可通过 --service 标识所属业务服务/环境）
sudo python3 -m client.agent run --server <服务端IP> --hub-port 8000 --proxy-port 8888 --service order-service-dev

# 若在本地测试或无 root 权限环境演练，可附加 --dry-run 模式：
python3 -m client.agent run --server 127.0.0.1 --service order-service-dev --dry-run
```


#### 急救清理与状态查看
如果 Agent 意外被强杀导致网络拦截未解除，可随时执行独立急救命令：
```bash
# 一键检测并安全清除所有 MOCK_PROXY_* iptables 规则链
sudo python3 -m client.agent clean

# 查看当前 iptables 生效规则
sudo python3 -m client.agent status
```

---

## 🧪 典型测试场景演示：模拟第三方接口 500 异常

假设工程 A 代码中有如下逻辑：
```python
try:
    resp = requests.get("http://xxx.com/test", timeout=3)
    resp.raise_for_status()
    data = resp.json()
except requests.exceptions.RequestException as e:
    # 这是我们要重点验证的容错捕获逻辑
    logger.error("第三方接口异常，执行本地降级策略")
    return fallback_data()
```

### 验证步骤：
1. **添加拦截目标**：
   在 Web 界面【拦截目标配置】中，添加域名 `xxx.com`（端口 80）。此时客户端 Agent 会自动将发往 `xxx.com:80` 的流量劫持转发到 Mock 服务端。
2. **配置 Mock 规则**：
   在 Web 界面【Mock 规则管理】中新建规则：
   - 目标 Host：`xxx.com`
   - 请求路径：`/test`
   - 状态码：`500`
   - 响应体：`{"code": "ERR_REMOTE", "message": "Third party unavailable"}`
3. **触发业务请求**：
   运行工程 A，工程 A 发起请求 `http://xxx.com/test`，直接收到 Mock 返回的 500 错误。
4. **实时观测与验证**：
   - 查看工程 A 控制台，确认 catch 异常处理逻辑被成功触发并执行降级！
   - 打开 Web 界面【实时流量监控】，可清晰看到该次调用的时间、Method、URL、匹配的规则名称及返回结果。

---

## 🔒 HTTPS 外部接口代理（免安装根证书模式）

对于外部第三方的 HTTPS 接口（如支付、短信网关等），无需在客户端机器及各运行容器中安装繁琐的自签根证书（Root CA），直接将业务工程中配置的第三方接口 Base URL 指向代理前缀网关即可：

- **真实目标接口**：`https://api.partner.com/v1/pay/create?id=123`
- **业务工程配置**：`http(s)://<mock-proxy>:8000/proxy/api.partner.com/v1/pay/create?id=123`

### 特性支持：
- **完整支持所有方法**：支持 `POST`、`GET`、`PUT`、`DELETE`、`PATCH`。
- **POST Body 完整透传**：支持 JSON、表单数据及二进制流。
- **统一规则匹配**：Web UI 中配置的目标 Host `api.partner.com`、Path `/v1/pay/create` 规则对前缀网关完全通用。
- **未命中真实 HTTPS 透传**：未命中 Mock 时，代理服务端使用 TLS SNI 向上游发起真实 HTTPS 请求，并原样返回结果。


---

## 🤖 AI Agent 调用说明 (OpenCode / LLM Skill)

本系统原生支持被 AI Agent 动态调用。AI 智能体可读取 `skills/mock-proxy/SKILL.md`，或者通过服务端接口获取调用定义：

```bash
# 获取技能说明文档
curl http://localhost:8000/api/agent-skills/SKILL.md

# 获取标准函数调用 Schema
curl http://localhost:8000/api/agent-skills/tools
```

AI 智能体在自动排查或编写降级逻辑时，可以直接发起 HTTP 请求配置 Mock 规则进行自闭环测试验证。

---

## 🧪 运行自动化测试

```bash
uv run pytest -v
```
所有 24 项测试（包含配置、HTTP/HTTPS 透传、多维规则引擎、脚本沙箱、服务分派隔离、前缀网关、iptables 链构建、REST API 及端到端闭环）均全量通过。

完整的 Web UI 操作步骤与浏览器测试记录见：[`docs/manual/web-ui-usage.md`](docs/manual/web-ui-usage.md)。
