核心接口（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 等）

Neon proxy云端控制面

启动 proxy 时指定你的控制面地址