# SERVICE-PROXY KNOWLEDGE BASE

## OVERVIEW

`service-proxy` is an HTTP reverse proxy running in the Data Plane (`tidb-admin` namespace). It routes Regional Control Plane requests to in-cluster TiDB ecosystem services (PD, TiBR, TiCDC, DM, TiFlash) and provides a connectivity-check endpoint.

This file is a map, not a tutorial.

→ **Deep architecture, deployment pipeline, Helm chart**: [`ARCHITECTURE.md`](ARCHITECTURE.md)
→ **Parent service map**: [`../AGENTS.md`](../AGENTS.md)

## STRUCTURE

- `main.go`: process startup, HTTP server wiring.
- `pkg/route/`: URL path matching and backend resolution.
- `pkg/proxy/`: reverse proxy core.
- `pkg/checker/`: `/check` connectivity endpoint, including backend connectivity and KMS master key usability checks.
- `pkg/audit/`: request/response audit logging.
- `pkg/config/`: config loading, file-watcher hot-reload.
- `pkg/secret/`: TLS cert management.
- `pkg/observability/`: Prometheus metrics (:8081).
- `configs/`: example YAML templates.
- `Dockerfile`: container image build.

## WHERE TO LOOK

| Task | Location | Guide |
|------|----------|-------|
| Understand runtime topology and ports | [`ARCHITECTURE.md`](ARCHITECTURE.md) | [Runtime Topology](ARCHITECTURE.md#runtime-topology) |
| Change or add a proxy route | `pkg/route/`, `pkg/proxy/` | [Core Functions](ARCHITECTURE.md#core-functions) |
| Modify connectivity check | `pkg/checker/` | [Core Functions](ARCHITECTURE.md#core-functions) |
| Change audit logging behavior | `pkg/audit/` | [Core Functions](ARCHITECTURE.md#core-functions) |
| Understand Kong ingress paths | [`ARCHITECTURE.md`](ARCHITECTURE.md) | [Ingress Configuration](ARCHITECTURE.md#ingress-configuration) |
| Modify Helm chart | `../dataplane-manager/helm/service-proxy/` | [Helm Chart](ARCHITECTURE.md#helm-chart) |
| Trace CI/CD pipeline | `.github/workflows/service-proxy-*.yaml` (repo root) | [Deployment Pipeline](ARCHITECTURE.md#deployment-pipeline) |
| Understand APPBox task integration | `../dataplane-manager/pkg/controllers/appbox/task/common/service_proxy.go` | [APPBox Task Integration](ARCHITECTURE.md#appbox-task-integration) |
| Find deployment config templates | `app-delivery` repo | [Configuration in app-delivery](ARCHITECTURE.md#configuration-in-app-delivery) |

## COMMANDS

Run from `internal/service-proxy/`:

```bash
make all          # lint → test → build
make build        # bin/service-proxy (supports GOOS/GOARCH)
make test         # go test -race -coverprofile ./...
make lint         # golangci-lint (must pass before PR)
make docker-build IMG=service-proxy:local
make e2e-images   # builds service-proxy:e2e + mock-server:e2e
make e2e-run      # SkyWalking Infra E2E with KinD
```

## LOCAL GUARDRAILS

- Go code must be `gofmt`-clean and idiomatic; keep functions single-purpose.
- Treat credentials as sensitive: audit logs must sanitize bodies/headers and never print secrets.
- Keep unit tests close to code (`pkg/**/*_test.go`), favor table-driven tests, cover failure branches.
- Commit subjects: `service-proxy: ...` or `fix(service-proxy): ...`.
- When changing routes, TLS, or checker behavior, update this file and `ARCHITECTURE.md`.

## RELATED SOURCES

| Document | Purpose |
|----------|---------|
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Runtime topology, deployment pipeline, Helm chart, APPBox integration |
| [`../AGENTS.md`](../AGENTS.md) | Parent `internal/` service map |
| [`../dataplane-manager/ARCHITECTURE.md`](../dataplane-manager/ARCHITECTURE.md) | CRD hierarchy, AppBox component pipeline |