# User-Scoped Data Proxy Cluster List

## Background and Goal

`GET /api/v1/orgs/:orgId/data-proxy/clusters` previously delegated to the
Clinic internal metadata API and returned every cluster in the organization.
The public route must instead return only the clusters visible to the caller's
TiDB Cloud user. The internal canonical route remains an organization-wide
metadata capability.

## Target Contract

The public route calls the TiDB management HTTP API
`/api/v2023/clusterManagement/v1beta2/tidbs` with `orgId`, `pageSize`, and
`skip`. It forwards the inbound `Authorization` and trace headers only; it does
not log or persist credentials. Each tidb-mgmt HTTP call records its credential-free
request URL and pagination parameters, plus outcome, upstream status, duration, and
result counts. HTTP API `tidbId` values and `totalSize` are
the authorization and pagination source of truth. Clinic internal org-scoped
metadata lookups enrich each allowed ID into the established `items`, `page`,
`pageSize`, and `total` response format.

`query` and `showDeleted=true` are rejected with 400 for this public route
because the HTTP API contract cannot implement their previous semantics. The
internal `/data-proxy/api/v1/orgs/:orgId/clusters` route retains its existing
filters and full-organization behavior.

## Implementation and Safety

- Add the optional `tidb_mgmt_http_base` configuration. The confirmed
  prod-cloud app-delivery endpoint is configured; staging and dev remain
  fail-closed until their owner supplies their HTTP API endpoints. Any configured
  endpoint is validated as an absolute HTTP(S) URL without userinfo, query, or
  fragment.
- Add a typed HTTP API client with bounded response reads, no redirect following,
  typed status errors, and no upstream error-body exposure.
- Fail closed if the HTTP API emits an invalid ID or Clinic metadata is unavailable,
  missing, or does not match the requested organization and HTTP API cluster ID.
- Map authentication, authorization, rate limiting, timeout, and invalid
  upstream responses to the Data Proxy API error format.

## Validation and Release Boundary

Run focused tests for the HTTP API client, `clustercontext`, handlers, config, and
router. Staging verification uses two users with different access to one org
and confirms pagination, totals, and no authorization data in service logs.

Affected source module: `clinic_data_service`; entrypoint: `cmd/api/main.go`;
image: `clinic/data-service`.

Required deployment modules: Clinic Data Service CD and app-delivery
`clinic-data-service` prod-cloud overlay. Staging and dev need their confirmed
HTTP API base URLs before functional rollout. No Clinic internal-api, NGM, or Kong
plugin image deployment is required.