HTTP API: Explicit Contracts · 25 min · free lesson

Retry Without Duplicating Tasks

Bind an idempotency key to one request payload.

Core idea

Reuse a stored result only when the key and original payload agree.

Diagram for Retry Without Duplicating Tasks: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises bind an idempotency key to one request payload. Its tests demonstrate the stated finite contract.

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")
}

Open local example in Playground ↗

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
  1. Return a successful response for the unrelated original request
  2. Always create another task
  3. 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.

  1. Identify the boundary: Bind an idempotency key to one request payload. Write down its accepted inputs and observable output.
  2. Exercise the failure: An idempotency key identifies the original operation, not permission to change its payload.
  3. 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