# Full-sync HTTP control API

The handler imports no queue or storage implementations. Inject the five
contract interfaces in `Dependencies`: `RunLister`, `RunReader`,
`FailurePager`, `ReplayRequester`, and `ActionReader`. The replay service owns durable
idempotency and execution; the HTTP layer does not cache requests or launch work.

Use `NewRunReader(live, archive, rounds)` to compose `LiveRunReader`,
`ArchivedRunReader`, and `RoundStatsReader` into a `RunReader`. Live metadata
wins and returns `source: "live"`; only `ErrNotFound` from live metadata permits
archive fallback, returning `source: "archive"`. Live storage errors and round
lookup errors propagate. Archive and round readers may be nil to disable those
lookups. A failure listing always calls `FailurePager` directly, never archives.

## Routes and responses

All routes require `Authorization: Bearer <configured token>`. Missing, wrong,
or ambiguous credentials return 401 with a `WWW-Authenticate` challenge. An
empty configured token is a startup configuration error. Responses use JSON and
`Cache-Control: no-store`.

| Method | Route | Success body |
| --- | --- | --- |
| GET | `/internal/v1/full-sync-runs?syncKind=&limit=` | 200 `contract.RunList` |
| GET | `/internal/v1/full-sync-runs/{runId}` | 200 `contract.RunView` |
| GET | `/internal/v1/full-sync-runs/{runId}/failures?cursor=&limit=` | 200 `contract.FailurePage` |
| POST | `/internal/v1/full-sync-runs/{runId}/replay` | 202 `contract.ReplayAccepted` |
| GET | `/internal/v1/full-sync-actions/{actionId}` | 200 `contract.ReplayAction` |

Run list results merge active Redis metadata with flat `run-<runId>.json`
archives under the configured archive root. Active Redis metadata wins when an
ID exists in both sources. `syncKind` accepts `traffic_usage` or `sim_status`;
`limit` defaults to 50 and is capped at 100.

Failure limits use the contract rules: absent, empty, or zero selects 100;
positive values up to 500 are accepted; other values are rejected. Repeated
cursor/limit parameters and malformed query encoding are rejected. Cursors are
opaque and passed unchanged after URL decoding. The pager validates cursor
contents and run binding. Empty pages serialize `items: []` and preserve
`nextCursor`; only an empty next cursor signals completion.

Replay requires a single `Idempotency-Key` header and a JSON body such as
`{"requestedBy":"operator"}`. The body is limited to 64 KiB, must contain one
JSON object with no unknown fields, and must satisfy `ReplayRequest.Validate`.
If supplied, Content-Type must be `application/json` (parameters are allowed).
The exact `requestedBy` value is preserved for fingerprinting. Repeated accepted
requests return the service's existing action/target and current status with
202. The adapter constructs `statusUrl` and the `Location` header from actionId.

All application errors use this envelope, without storage error details:

```json
{"error":{"code":"invalid_argument","message":"Invalid request"}}
```

| Condition | HTTP status | Error code |
| --- | --- | --- |
| Invalid path, query, header, body, or `ErrInvalidArgument` | 400 | `invalid_argument` |
| Missing/wrong bearer credentials | 401 | `unauthorized` |
| Unknown route/resource or `ErrNotFound` | 404 | `not_found` |
| Unsupported route method | 405 | `method_not_allowed` |
| `ErrConflict` (including changed idempotent request), `ErrLeaseLost` | 409 | `conflict` |
| `ErrFailureDetailsUnavailable` | 410 | `failure_details_unavailable` |
| Oversized replay body | 413 | `body_too_large` |
| `ErrBusy` | 503 | `busy` |
| Other service errors or unencodable service output | 500 | `internal_error` |

## Lifecycle

`NewHandler(token, deps)` can be mounted by an existing HTTP server. For an
independent listener, construct `NewServer(Config{Addr: address, BearerToken:
token}, deps)` and call `Start(workerCtx)`. `Start` binds synchronously and
returns address-in-use and other startup errors directly. `Addr()` exposes the
bound address, including an OS-assigned port when configured with port zero.

Call `Wait()` after Start, normally in the worker's supervision goroutine. It
returns serving or shutdown failures; it also returns startup failures if Start
failed. The server is single-use and rejects a second Start. Wait can have
multiple callers but must not be called before Start.

Canceling `workerCtx` closes the listener and drains active HTTP requests.
Active request contexts stay usable during the drain. `ShutdownTimeout` defaults
to ten seconds; if it expires, active connections are closed and Wait returns
an error wrapping `context.DeadlineExceeded`. Normal cancellation with a
successful drain returns nil. No worker wiring or configuration-file changes
are part of this package.

## Verification

```text
gofmt -l internal/fullsync/httpapi
go test ./internal/fullsync/...
go test ./internal/fullsync/httpapi -cover
go vet ./internal/fullsync/...
```

Tests use contract mocks and local HTTP listeners, requiring no Redis or archive
files. `go test -race ./internal/fullsync/...` additionally requires a supported
C compiler and CGO enabled.