Add an X-Idempotency-Replayed response header

Nobody has started this yet — be first.

Business impact

Right now a client (or a support engineer reading a captured request/response pair) cannot tell, from the response alone, whether a charge was just executed or is a replay of a previous execution -- both look identical except for the attempts field, which a caller would have to independently know the "right" value for. A dedicated header turns "did this actually charge the customer again or not?" -- a question that comes up in exactly the stressful moments (a customer dispute, a support escalation, debugging a client's own retry logic) where a clear, explicit answer saves real back-and-forth.

Problem

POST /v1/charges responses look the same whether the operation actually ran (idempotency.Proceed) or the response was served from the idempotency store (idempotency.Replay, or an idempotency.InProgress claim that resolved via Wait). There is no header or field indicating which happened.

Current behavior

A charge's first execution and a replayed charge (same Idempotency-Key, same body) return byte-for-byte identical response headers -- nothing distinguishes "this just charged the customer" from "this is a cached replay."

Expected behavior

Every /v1/charges response that did not trigger a fresh execution -- i.e. the Replay branch, and the InProgress branch once claim.Wait resolves successfully -- carries a response header X-Idempotency-Replayed: true. A response from a fresh execution (the Proceed branch) should not carry this header (or should carry it as absent/false -- pick one and be consistent; the test only checks for the presence of "true" on a replayed response).

Steps to reproduce

POST /v1/charges with a fresh Idempotency-Key and body -- the operation actually runs; inspect the response headers. POST the exact same request again (same key, same body) -- the response is served from the idempotency store, not a fresh execution. Observe: neither response carries any header indicating which one was a replay.

Why this matters

This is a small, low-risk addition that directly improves debuggability for exactly the kind of situation ("did we double-charge this customer?") this whole project exists to make provably impossible -- the header makes the proof visible in the response itself, not just in server-side logs.

Suggested approach

handleCharge in internal/server/handlers_charges.go already branches on claim.Status with a switch. Set the header on w (via w.Header().Set(...)) before calling writeStoredResponse, in the idempotency.Replay case and in the idempotency.InProgress case's successful-Wait path. Do not set it in the idempotency.Proceed case.

Acceptance criteria

A charge's first execution response does not carry X-Idempotency-Replayed: true.
The same request replayed (same key, same body) carries X-Idempotency-Replayed: true.
go test ./test/ -run TestTask03 -v passes.

Verification

go test ./test/ -run TestTask03 -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b feat/idempotency-replayed-header

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin feat/idempotency-replayed-header

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Reliability Layer (Idempotency + Retry + DLQ)

Idempotency, retry-with-jitter, and a dead-letter queue, as three standalone Go libraries plus a runnable HTTP demo -- fifteen ways the payments-style plumbing most real systems get subtly wrong quietly breaks.

Fork on GitHub

Download

Setup

Reliability Layer (Idempotency + Retry + DLQ)

git clone <your-fork>
cd GolangDevTraining/reliable
go run ./cmd/server   # memory backend by default -- no Redis or Docker needed
# in another shell:
curl localhost:8080/healthz

The service runs on . Walk through the README's five core scenarios against (plain success, idempotent replay, conflicting-payload rejection, concurrent duplicates collapsing to one execution, and exhausted retries landing in the DLQ) to see the whole system working end to end.