核心接口（ControlPlaneApi trait）
proxy 通过 ControlPlaneApi trait 与控制面通信，共有 4 个方法：
- get_role_access_control --- 获取角色密码
-
HTTP: GET {base}/get_endpoint_access_control?session_id=...&endpointish=<endpoint>&role=<role>
-
Header: Authorization: Bearer <control_plane_token>
-
响应体 (GetEndpointAccessControl):
{
"role_secret": "<SCRAM secret>",
"allowed_ips": "8.8.8.8", "10.0.0.0/8",
"allowed_vpc_endpoint_ids": "vpce-xxx",
"block_public_connections": false,
"block_vpc_connections": false,
"project_id": 123,
"account_id": 1,
"rate_limits": {
"connection_attempts": { "tcp": {"rps": 10, "burst": 20} }
}
}
-
注意: 如果 endpoint 不存在或无权限，返回 HTTP 404（proxy 会视为无密码 = 允许无密码连接）
-
role_secret 是 SCRAM 格式的密码哈希（SCRAM-SHA-256$<iterations>:<salt>:<stored_key>:<server_key>）
- wake_compute --- 获取计算节点连接信息
-
HTTP: GET {base}/wake_compute?session_id=...&endpointish=<endpoint>
-
响应体 (WakeCompute):
{
"address": "192.168.1.100:5432",
"server_name": null,
"aux": {
"endpoint_id": "ep-xxx",
"project_id": "proj-xxx",
"branch_id": "br-xxx",
"compute_id": "compute-xxx",
"cold_start_info": "warm"
}
}
-
cold_start_info 枚举值: warm / vm_pool_hit / vm_pool_miss / unknown
-
address 格式: host:port（支持 IPv6 ::1:5432）
-
server_name 非空时 proxy 启用 SSL
- get_endpoint_jwks --- 获取 JWT 验证规则（可选，JWT 认证时才会调用）
-
HTTP: GET {base}/endpoints/{endpoint}/jwks?session_id=...
-
响应体 (EndpointJwksResponse):
{
"jwks": [
{
"id": "rule-1",
"jwks_url": "https://auth.example.com/.well-known/jwks.json",
"provider_name": "auth0",
"jwt_audience": "my-app",
"role_names": 1, 2
}
]
}
- 不使用 JWT 认证时可以返回空数组
管理通道（PostgreSQL 协议）
proxy 还暴露了一个本地管理 API（mgmt.rs），这是一个 PostgreSQL 兼容的连接，用于控制台重定向认证流程（console redirect auth）。
-
接受 PostgreSQL 客户端连接
-
查询体是一个 JSON 字符串，格式为 KickSession:
{
"session_id": "abc123",
"result": {
"Success": {
"host": "127.0.0.1",
"port": 5432,
"dbname": "postgres",
"user": "user",
"password": "pass",
"aux": { ... }
}
}
}
- 如果你不走 console_redirect 认证流程，这个不需要实现。 默认使用 control plane token 认证时不会触发这个机制。
最小化实现总结
| 功能 | 必须? | 说明 |
|---|---|---|
| GET /get_endpoint_access_control | ✅ 必须 | 提供角色密码 + IP 访问控制 |
| GET /wake_compute | ✅ 必须 | 提供计算节点地址 |
| GET /endpoints/{ep}/jwks | ❌ 可选 | 仅 JWT 认证时需要 |
| PostgreSQL mgmt 接口 | ❌ 可选 | 仅 console redirect 流程需要 |
最简要求：只需实现两个 HTTP GET 端点，支持 Bearer token 认证即可。proxy 内置了缓存、锁、限流等机制，控制面不需要关心这些。
proxy 代码中客户端侧已经完全实现，它调用的是外部控制面服务。梳理如下：
已有实现（proxy 作为客户端）
| 组件 | 文件 | 角色 |
|---|---|---|
| ControlPlaneApi trait | control_plane/mod.rs:164 | 定义接口（4个方法） |
| NeonControlPlaneClient | control_plane/client/cplane_proxy_v1.rs | 生产实现 --- 发 HTTP 请求到控制面 |
| MockControlPlane | control_plane/client/mock.rs | 开发测试实现 --- 查本地 PostgreSQL |
| ControlPlaneClient enum | control_plane/client/mod.rs | 组合以上，对外暴露 |
proxy 侧不需要你写任何代码，它已经能：
-
调用 get_role_access_control → GET {base}/get_endpoint_access_control?endpointish=...&role=...
-
调用 wake_compute → GET {base}/wake_compute?endpointish=...
-
调用 get_endpoint_jwks → GET {base}/endpoints/{ep}/jwks
-
管理缓存、锁、限流、重试
需要你实现的（外部服务）
你需要构建一个独立的 HTTP 服务，响应上述 GET 请求。proxy 启动时通过 --control-plane-endpoint 参数指向你的服务地址。
启动 proxy 时指定你的控制面地址
proxy --control-plane-endpoint https://your-control-plane.local \
--control-plane-token <your-token>
总结
-
proxy 已经实现了所有调用逻辑（HTTP 请求发送、响应解析、缓存、错误处理）
-
你需要实现的只是一个 HTTP 服务，返回符合协议格式的 JSON 响应
-
这个服务不需要是 PostgreSQL，可以是任意 Web 框架（FastAPI、Express、Gin 等）