
Understand it
A timeout does not prove that the server performed no work. It can commit a task and lose the response. An unconditional retry then creates a duplicate. Store a stable request key with the original payload and result; on a repeated request, compare the payload before reusing that result.
This lab models the decision without claiming an in-memory map is durable. A new key creates once, the same key and payload replays, and the same key with a different payload conflicts. Missing or blank keys are invalid. Production storage must enforce the key uniqueness and the business write in one transaction. Set an explicit retention policy; expiring a key changes how late retries behave. The SQL and capstone stages demonstrate that the deduplication record belongs beside the committed task.
The route project is Task Ledger: first keep a reproducible source history, then expose its data through a CLI and HTTP boundary, persist it in SQL, diagnose failures and prepare a release. This lesson owns one contract in that project. Run the worked example before changing the starter and explain which input makes the tempting shortcut fail.
Terminal practice: Create one task twice with curl using the same Idempotency-Key header, then change the title while retaining the key.
The compiler lab is independent of the reading question. Edit solution.rs; the app supplies a separate caller with normal, empty and adversarial inputs. A successful unchanged demonstration does not prove your implementation. After the lab, apply the same contract to the route companion project. Its README separates the on-device adapter from the desktop Cargo/TCP profile.
Read the code
pub fn retry_decision(
key: &str,
payload: &str,
previous: Option<(&str, &str)>,
) -> u16 {
if key.trim().is_empty() {
400
} else {
match previous {
Some((old_key, old_payload)) if old_key == key => {
if old_payload == payload {
200
} else {
409
}
}
_ => 201,
}
}
}
fn main() {
assert_eq!(retry_decision("k", "title", None), 201, "case 1");
assert_eq!(retry_decision("", "title", None), 400, "case 2");
assert_eq!(
retry_decision("k", "title", Some(("k", "title"))),
200,
"case 3"
);
assert_eq!(
retry_decision("k", "other", Some(("k", "title"))),
409,
"case 4"
);
assert_eq!(
retry_decision("new", "x", Some(("old", "x"))),
201,
"case 5"
);
println!("worked example passed");
}
The worked implementation exercises bind an idempotency key to one request payload. Its tests demonstrate the stated finite contract.
Practice starter
pub fn retry_decision(key: &str, payload: &str, previous: Option<(&str,&str)>) -> u16 {
todo!("implement the contract")
}
Try it
Return 400 for a blank key; 200 for the same stored key and payload; 409 for the same key with another payload; 201 for a new key. Keep the public signature. Open the compiler lab and edit solution.rs; do not edit the private verification caller.
What success looks like: The separate caller accepts the changed solution and rejects unchanged TODO, a wrong implementation and a printed success message.
Check your understanding
A repeated key arrives with different content. What should happen?
Reveal the answer
- Return a successful response for the unrelated original request
- Always create another task
- Reject the conflict
An idempotency key identifies the original operation, not permission to change its payload.
Go deeper
Common misconception: Return a successful response for the unrelated original request
Reuse a stored result only when the key and original payload agree.
- Identify the boundary: Bind an idempotency key to one request payload. Write down its accepted inputs and observable output.
- Exercise the failure: An idempotency key identifies the original operation, not permission to change its payload.
- Check the independent caller: Return 400 for a blank key; 200 for the same stored key and payload; 409 for the same key with another payload; 201 for a new key.
Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.
Connections
- Encode a Valid JSON Boundary: Escape JSON strings without corrupting Unicode
- Make Invalid Rows Impossible: Enforce domain invariants in a real database