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:

{"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

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.