# TiCDC Metadata in Clinic Data Proxy

## Background

The TiCDC diagnostics skill currently reads changefeed metadata through the
DevOps API. That path uses an operations API token whose scope is broader than
the read-only customer-facing diagnostic contract. DevOps PR 1487 established
the required Dataflow and Dataflow-NG aggregation logic and the trusted gRPC
user metadata contract.

## Goal

Expose read-only TiCDC changefeed list and detail APIs from Clinic Data Service.
Public routes support Dedicated clusters and use the existing TiDB Cloud Kong
authentication, session validation, deploy-type validation, and cluster RBAC.
Internal routes support every non-Dedicated cluster type through Dataflow-NG,
including Premium, BYOC, Starter, and Essential.

## API Contract

Internal routes:

- `GET /data-proxy/api/v1/orgs/{orgId}/clusters/{clusterId}/ticdc/changefeeds`
- `GET /data-proxy/api/v1/orgs/{orgId}/clusters/{clusterId}/ticdc/changefeeds/{changefeedId}`

Public routes:

- `GET /api/v1/orgs/{orgId}/data-proxy/clusters/{clusterId}/ticdc/changefeeds`
- `GET /api/v1/orgs/{orgId}/data-proxy/clusters/{clusterId}/ticdc/changefeeds/{changefeedId}`

List returns `{"changefeeds": [...]}` and detail returns
`{"changefeed": {...}}`. The DTO uses the established snake_case DevOps
metadata fields. Large identifiers, checkpoint TSO, and RCU remain strings.
Downstream configuration is built through an explicit allowlist and never
contains credentials.

## Authorization and Data Flow

Public requests are authenticated by `dbaas_auth` with Bearer JWT,
`x-session-id`, Dedicated deploy-type validation, and Account RBAC. Both public
and internal handlers resolve canonical Clinic metadata and require the
returned org and cluster identities to match the request.

Clinic creates `grpc-metadata-x-dataflow-user` itself. The base64 JSON contains
the authorized org ID, `IsImpersonated=true`, and the resolved project ID. An
empty project ID is represented as project zero for historical clusters; a
non-empty malformed value fails closed. Request headers can never override the
generated identity.

Dedicated requests use Dataflow ConnectorService plus OpsInternalService.
Every non-Dedicated internal request uses the equivalent Dataflow-NG services.
The business list determines membership and internal rows only enrich it.
Detail resolves kernel ID to business ID, retrieves the business record, then
requires its source TiDB cluster ID to equal the already-authorized cluster ID
before returning any metadata.

## Implementation

- Add stable TiCDC DTOs, Dedicated/NG client interfaces, aggregation,
  conversion, credential sanitization, and gRPC user metadata construction.
- Add handlers with 5-second list and 10-second detail deadlines, structured
  lifecycle logs containing trace ID, and stable HTTP error mapping.
- Add required `ticdc.dataflow_addr` and `ticdc.dataflow_ng_addr` configuration;
  there is no feature flag.
- Keep the checked-in local config and the app-delivery dev-cloud, staging, and
  prod-cloud Clinic Data Service configs in sync. The public Kong RBAC mapping
  is added to the active staging and prod-cloud plugin maps; the legacy dev map
  does not currently contain the Public Data Proxy resource family.
- Add public route mappings to the existing Kong RBAC resource map without
  changing session validation rules.
- Pin Dataflow protobuf modules compatible with the DevOps implementation.
  Dataflow-NG generated code still imports the retired
  `go.buf.build/protocolbuffers/go/linuxgit/tidbcloud` module path, so replace
  it with the current `buf.build/gen/go/linuxgit/tidbcloud/protocolbuffers/go`
  module used by DevOps and the Clinic root module. Validate the dependency
  graph with an empty module cache so an existing local copy cannot mask the
  retired upstream path.

## Exclusions and Compatibility

- No pause, resume, restart, update, or delete APIs.
- No duplicate summary-only `/tidbtools/changefeeds` endpoint.
- Public Starter/Essential access remains unsupported; public routes are
  Dedicated-only.
- No change to existing Data Proxy routes or response contracts.
- Migrating the nutshell skill is a separate follow-up after staging validation.

## Test Plan

- Unit-test generated Dataflow metadata, optional project handling, architecture
  selection, list enrichment, sorting, redaction, timeouts, and error mapping.
- Test all four routes and verify public requests reject non-Dedicated metadata.
- Test detail source-cluster equality and cross-cluster kernel-ID rejection.
- Render staging and prod app-delivery overlays and verify Kong resource maps.
- In staging, verify PrivateLink DNS/TCP, Dedicated public list/detail,
  Dedicated/Premium/BYOC/Starter/Essential internal behavior, Pod readiness,
  image, restarts, and structured logs.

## Deployment Boundary

Affected module: `clinic_data_service`; entrypoint: `cmd/api`; image:
`clinic/data-service`. Deploy with Clinic CD component `clinic-data-service`.
Desired-state changes affect the `clinic-data-service` and
`clinic-kong-cluster-plugins` Argo applications in staging and prod-cloud. No
Clinic API, internal-api, NGM, task-manager, or other image deployment is
required.