Overview

Severity: CRITICAL
Defect Class: Cloudflare 2025-11-18 outage class
Current Count: 326 unwrap() calls in production code
Target: 0 unwrap() calls

Background

The Cloudflare network outage on 2025-11-18 (3+ hour downtime) was caused by a single unwrap() panic in production code. This is a known Rust anti-pattern that can cause process termination without recovery.

PMAT rust-project-score identified 326 unwrap() calls in aprender's codebase.

Problem

// ❌ DANGEROUS: Can panic and crash the process
let value = some_option.unwrap();

// ✅ SAFE: Descriptive error message
let value = some_option.expect("Configuration must have value X");

// ✅ BETTER: Proper error handling
let value = some_option.ok_or_else(|| AprenderError::MissingValue)?;

Remediation Plan

Phase 1: Audit and Categorize (Week 1)

• Run: rg "\.unwrap\(\)" src/ --stats
• Categorize by severity:
  • Test-only code (acceptable with #[cfg(test)])
  • Infallible operations (document why unwrap is safe)
  • Recoverable errors (convert to expect or ?)
  • Critical paths (prioritize for immediate fix)

Phase 2: Enforce Policy (Week 1)

• Add to .clippy.toml:

disallowed-methods = [
    { path = "core::option::Option::unwrap", reason = "Use expect() with descriptive message or proper error handling" },
    { path = "core::result::Result::unwrap", reason = "Use expect() with descriptive message or proper error handling" },
]

• Update .pmat-gates.toml: max_unwraps = 0
• Add pre-commit check: cargo clippy -- -D clippy::disallowed-methods

Phase 3: Fix Production Code (Weeks 2-4)

• Convert unwrap() to expect() with descriptive messages
• Convert to proper error handling (?) where appropriate
• Document infallible cases with // SAFETY: comments
• Add #[cfg(test)] guards for test-only unwraps

Phase 4: Verification (Week 4)

• Zero unwraps in src/ (excluding test modules)
• All clippy checks pass with -D clippy::disallowed-methods
• pmat rust-project-score shows unwrap_count = 0
• Documentation updated

Success Criteria

• Zero unwrap() calls in production code (src/, non-test)
• All unwraps in tests properly guarded with #[cfg(test)]
• Clippy enforcement active in pre-commit hooks
• PMAT quality gates updated and passing
• Team documentation on unwrap policy

Resources

• Cloudflare Incident: https://blog.cloudflare.com/
• Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
• PMAT Scoring: pmat rust-project-score (shows unwrap count)

Timeline

Start: Immediately
Target Completion: 4 weeks
Priority: P0 (Critical)

Assignee: Team
Estimated Effort: 40-60 hours