HTTP/JSON

HTTP/JSON 介面由 grpc-gateway 提供：路由與 payload 形狀從 proto 的 google.api.http annotations 產生，不手寫 handler。

路由對應

annotation 寫在 rpc 上，例如 sample resource：

rpc GetResource(GetResourceRequest) returns (Resource) {
  option (google.api.http) = {get: "/v1/resources/{id}"};
}

sample resource 的完整對應：

RPC	HTTP
CreateResource	POST /v1/resources
GetResource	GET /v1/resources/{id}
ListResources	GET /v1/resources
UpdateResource	PATCH /v1/resources/{id}
DeleteResource	DELETE /v1/resources/{id}

呼叫與 auth

curl localhost:8080/v1/resources/x \
  -H 'Authorization: Bearer <token>'

沒帶 token 回 401。gateway 與 gRPC、MCP 走同一條攔截器鏈，錯誤 body 由統一錯誤模型輸出，不含內部原因。

Request body 上限

gateway 對 request body 有 1 MB 上限與 30 秒讀取逾時：超限回 413，讀取逾時回 408。

CORS 與 OpenAPI

• server.enable_cors: true 只是總開關；實際的 allowlist 是 server.cors_origins。沒列在 cors_origins 的 origin 拿不到任何 CORS headers——只開 enable_cors 而不設 origins，瀏覽器端照樣被擋。設 "*" 全開，或列明確 origin（也可用 GORTEXA_SERVER__CORS_ORIGINS 逗號分隔覆寫）。預檢 OPTIONS 直接短路。
• server.openapi: true 時在 /openapi.json 提供 OpenAPI spec。spec 是 make gen 的建置產物，啟動時讀一次進記憶體。

回應 headers

回應 headers 走 allowlist：內部 headers 不會漏到外部，X-Request-Id 保留供關聯查詢。