Diagnostics: Explain a Failure · 25 min · free lesson

Add Context Without Leaking Secrets

Redact sensitive diagnostic fields.

Core idea

An error should identify the operation without copying credentials into logs.

Diagram for Add Context Without Leaking Secrets: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises redact sensitive diagnostic fields. Its tests demonstrate the stated finite contract.

Understand it

A bare connection failed message loses the operation and request that failed. Add bounded structured context: operation name, request ID and a stable error category. Keep secret fields out of the event. Redacting only one capitalization of Authorization is insufficient when headers are case insensitive.

This lab preserves field order while replacing authorization, cookie, password, token and api_key values with [REDACTED], case insensitively. It does not claim that this small allowlist finds every possible secret in free text. Production code should prefer explicitly selected safe fields and never dump arbitrary request bodies or connection URLs. Diagnostic context is useful only when a person can connect it to a specific operation; a giant unstructured debug print can be harder to use than a short event with a correlation ID.

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: Run the companion error case and inspect its request ID and operation context. Keep Authorization out of retained terminal command examples.

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 safe_fields(fields: &[(&str, &str)]) -> Vec<(String, String)> {
    fields
        .iter()
        .map(|(k, v)| {
            let sensitive = [
                "authorization",
                "cookie",
                "password",
                "token",
                "api_key",
            ]
            .contains(&k.to_ascii_lowercase().as_str());
            (
                k.to_string(),
                if sensitive {
                    "[REDACTED]".to_owned()
                } else {
                    v.to_string()
                },
            )
        })
        .collect()
}

fn main() {
    assert_eq!(
        safe_fields(&[
            ("Authorization", "bearer x"),
            ("request_id", "r1")
        ]),
        vec![
            ("Authorization".to_owned(), "[REDACTED]".to_owned()),
            ("request_id".to_owned(), "r1".to_owned())
        ],
        "case 1"
    );
    assert_eq!(safe_fields(&[]), vec![], "case 2");
    assert_eq!(
        safe_fields(&[("TOKEN", "x"), ("api_key", "y")]),
        vec![
            ("TOKEN".to_owned(), "[REDACTED]".to_owned()),
            ("api_key".to_owned(), "[REDACTED]".to_owned())
        ],
        "case 3"
    );
    assert_eq!(
        safe_fields(&[("operation", "list")]),
        vec![("operation".to_owned(), "list".to_owned())],
        "case 4"
    );
    println!("worked example passed");
}

The worked implementation exercises redact sensitive diagnostic fields. Its tests demonstrate the stated finite contract.

Practice starter

pub fn safe_fields(fields: &[(&str,&str)]) -> Vec<(String,String)> {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Retain field names and order; replace values for authorization,cookie,password,token,api_key with [REDACTED] using ASCII-case-insensitive key matching. Other values stay unchanged. 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

Which event is useful and safer for a failed request?

Reveal the answer
  1. Operation and request ID with explicitly redacted secret fields
  2. Every raw header and the complete body
  3. A password is safe in logs if the request failed

Failure does not make credentials safe to copy into a persistent diagnostic record.

Go deeper

Common misconception: Every raw header and the complete body

An error should identify the operation without copying credentials into logs.

  1. Identify the boundary: Redact sensitive diagnostic fields. Write down its accepted inputs and observable output.
  2. Exercise the failure: Failure does not make credentials safe to copy into a persistent diagnostic record.
  3. Check the independent caller: Retain field names and order; replace values for authorization,cookie,password,token,api_key with [REDACTED] using ASCII-case-insensitive key matching. Other values stay unchanged.

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

Connections

  • Commit Related Changes Atomically: Roll back a failed multi-write operation
  • Propagate One Request Identity: Validate a bounded correlation ID