Diagnostics: Explain a Failure · 25 min · free lesson

Propagate One Request Identity

Validate a bounded correlation ID.

Core idea

Use the same validated ID across a request and its child operations.

Diagram for Propagate One Request Identity: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises validate a bounded correlation id. Its tests demonstrate the stated finite contract.

Understand it

Async work interleaves. Two requests can emit similar messages on one thread, so thread identity alone does not connect the messages that belong together. Give an operation one request ID, propagate it through database calls and retries, and record child work under the same parent context.

An incoming ID is untrusted data. Accept only a bounded ASCII token here, using letters, digits, dash and underscore; otherwise use a generated fallback supplied by the caller. Reject line breaks so an identifier cannot inject a fake log record. Do not treat a correlation ID as authentication or an idempotency key. Clients can choose or repeat it, and tracing systems have their own full trace-context format. This exercise isolates a small application request-ID policy rather than pretending to implement W3C traceparent.

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: Send curl -i -H "X-Request-ID: req_42" http://127.0.0.1:8080/health and follow the same ID through the diagnostic output.

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 request_id(incoming: Option<&str>, fallback: &str) -> String {
    match incoming {
        Some(v)
            if !v.is_empty()
                && v.len() <= 64
                && v.bytes().all(|b| {
                    b.is_ascii_alphanumeric() || b == b'-' || b == b'_'
                }) =>
        {
            v.to_owned()
        }
        _ => fallback.to_owned(),
    }
}

fn main() {
    assert_eq!(
        request_id(Some("req_42-A"), "generated"),
        "req_42-A",
        "case 1"
    );
    assert_eq!(request_id(None, "generated"), "generated", "case 2");
    assert_eq!(
        request_id(
            Some(
                "evil
record"
            ),
            "new"
        ),
        "new",
        "case 3"
    );
    assert_eq!(request_id(Some("🦀"), "new"), "new", "case 4");
    assert_eq!(
        request_id(Some(&"a".repeat(65)), "new"),
        "new",
        "case 5"
    );
    assert_eq!(request_id(Some(""), "new"), "new", "case 6");
    println!("worked example passed");
}

The worked implementation exercises validate a bounded correlation id. Its tests demonstrate the stated finite contract.

Practice starter

pub fn request_id(incoming: Option<&str>, fallback: &str) -> String {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Accept incoming IDs with 1..=64 bytes composed only of ASCII letters,digits,dash,underscore. Otherwise return the supplied fallback, which the caller guarantees is valid. 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

Does a client-supplied request ID authenticate the caller?

Reveal the answer
  1. Yes, a unique-looking string proves identity
  2. It makes SQL authorization unnecessary
  3. No, it is diagnostic context

Correlation identifies related events, not who is allowed to perform an operation.

Go deeper

Common misconception: Yes, a unique-looking string proves identity

Use the same validated ID across a request and its child operations.

  1. Identify the boundary: Validate a bounded correlation ID. Write down its accepted inputs and observable output.
  2. Exercise the failure: Correlation identifies related events, not who is allowed to perform an operation.
  3. Check the independent caller: Accept incoming IDs with 1..=64 bytes composed only of ASCII letters,digits,dash,underscore. Otherwise return the supplied fallback, which the caller guarantees is valid.

Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.

Connections

  • Add Context Without Leaking Secrets: Redact sensitive diagnostic fields
  • Measure the Tail, Not Just the Average: Compute an explicitly defined latency percentile