ahrav/safe-over-unsafe

Safe API Design Over Unsafe Rust

Module privacy is the soundness boundary — not the unsafe keyword. The unsafe {} block is a syntax marker; the real safety mechanism is private fields behind a safe public API, within a module (or crate) where all code is trusted.

When to Use

• Designing a new type backed by MaybeUninit, raw pointers, or FFI
• Adding unsafe blocks to existing code for performance
• Reviewing unsafe code for soundness
• Implementing Send/Sync/Drop for types with unsafe internals

Design Checklist

Follow every step. Skipping any step is how soundness bugs happen.

1. Establish the Safety Boundary

• Private fields, private module, safe public API. Every public method — safe or not — is part of the soundness proof. Changing < to <= in a safe bounds check can make all unsafe blocks unsound.
• Consider crate-level isolation. Consumer crate uses #![forbid(unsafe_code)]; unsafe lives in a dedicated crate.
• Enable lints at the crate root:

  #![deny(unsafe_op_in_unsafe_fn)]
  #![deny(clippy::undocumented_unsafe_blocks)]
  

2. Document Invariants at the Type Level

Two kinds of invariants exist — conflating them causes bugs:

• Validity invariant: Must hold at ALL times. Violation is instant UB even if the value is never "used." (Example: bool must be 0 or 1.)
• Safety invariant: Must hold at API boundaries. May be temporarily violated internally. (Example: Vec's len <= cap.)

Document both in a module-level //! or struct-level /// doc comment:

/// # Invariants
/// - `len <= CAPACITY` (safety)
/// - Slots `[head..head+len)` (mod cap) are initialized (safety)
/// - Initialized slots contain valid `T` values (validity)

3. Enforce at Compile Time First

Every invariant should be evaluated: can this be a const assertion, a NonZero type, or a typestate transition instead of a runtime check?

const { assert!(N > 0 && N.is_power_of_two()) }; // compile-time

Compile-time enforcement eliminates entire bug classes. Runtime debug_assert! is the fallback — use assert! in public API preconditions that guard unsafe code in the implementation.

4. Write SAFETY Comments as Proof Sketches

Every // SAFETY: comment must argue invariant preservation, not just state a fact. Use this structure:

// SAFETY: [what unsafe operation is being performed]
// Invariant: [which safety invariant holds here — and WHY from the code path]
// Implies: [which validity invariant this satisfies for the unsafe op]
// Preserved: [what invariants remain intact after this operation]

Bad: // SAFETY: index is in bounds Good: // SAFETY: physical = idx & MASK, so physical < CAPACITY (mask clears // high bits). The element is initialized because idx < self.len, and our // safety invariant guarantees slots [head..head+len) are initialized. // This satisfies assume_init_ref's requirement that the value is valid T.

For unsafe fn, use # Safety doc sections documenting caller obligations.

5. Get Variance, PhantomData, and Send/Sync Right

Incorrect Send/Sync is the #1 real-world unsafe soundness bug (tokio RUSTSEC-2025-0023, lock_api RUSTSEC-2020-0070, windows RUSTSEC-2022-0008).

| Situation | Action | |-----------|--------| | Type uses [MaybeUninit<T>; N] | Auto-derive is correct. No PhantomData needed. | | Type uses raw pointers | Add PhantomData<T> for owned data (covariant, correct Send/Sync). | | Need manual Send/Sync | Red flag. Bound generics: unsafe impl<T: Send + Sync> Sync for MyType<T> {} | | Unsure about variance | If the type owns T, it should be covariant (like Vec). Use PhantomData<T>. |

Always prefer auto-derivation. Add compile-time assertions:

const _: () = {
    fn assert_send<T: Send>() { fn requires_send<S: Send>() {} requires_send::<MyType<T>>(); }
    fn assert_sync<T: Sync>() { fn requires_sync<S: Sync>() {} requires_sync::<MyType<T>>(); }
};

6. Handle Panic Safety

If an operation modifies state in multiple steps and any step can panic (e.g., T::drop(), T::clone()), use the decrement-before-drop or guard pattern:

// Decrement-before-drop: len reflects reality even if drop panics
while self.len > 0 {
    self.len -= 1;
    unsafe { self.buf[self.len].assume_init_drop(); }
}

Test with a deliberately-panicking Drop impl via catch_unwind.

7. Defend Against Generic Parameters

Unsafe code cannot trust safe trait implementations. T::drop() can panic. T::clone() can panic. Ord impls can be inconsistent. Write defensively so broken trait impls cause wrong results, never UB.

Verification Layers

All three are required. No single tool is sufficient.

| Layer | Tool | What It Catches | Required | |-------|------|----------------|----------| | Dynamic UB | cargo +nightly miri test | Aliasing, uninit, alignment, use-after-free | Every test run | | Aliasing model | MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test | Tree Borrows violations | CI | | Reference model | proptest vs known-correct safe impl (e.g., VecDeque) | Logic errors, edge cases | Every test run | | Drop correctness | DropTracker with Arc<AtomicUsize> | Double-drop, leaks | Every test run | | Bounded proof | Kani proof harnesses | Exhaustive invariant verification | Critical code |

Risk Checklist

Before declaring unsafe code "done," verify each:

• [ ] No manual unsafe impl Send/Sync without restrictive bounds on generics
• [ ] All values crossing safe→unsafe boundary are validated
• [ ] MaybeUninit: using write() for init, tracking init state, never mem::uninitialized
• [ ] Multi-step operations handle panics (guard/decrement-before-drop pattern)
• [ ] len/capacity updated atomically with the memory operation
• [ ] Public API preconditions use assert! (not just debug_assert!)
• [ ] PhantomData matches ownership semantics (covariant for owned data)
• [ ] Miri passes under both Stacked Borrows and Tree Borrows

Pattern Catalog

| Pattern | When to Use | Exemplar | |---------|------------|----------| | Private fields + safe API | Always | std Vec | | Crate-level #![forbid(unsafe_code)] | Multi-crate projects | Fuchsia, gossip-rs | | Compile-time const assertions | Numeric invariants | RingBuffer power-of-2 | | MaybeUninit + init tracking | Uninitialized storage | std MaybeUninit docs | | PhantomData for variance | Raw pointer containers | Rustonomicon Vec | | Guard struct for panic safety | Multi-step mutations | hashbrown HashMap | | Typestate (generic state param) | State-dependent operations | serde Serializer | | Sealed trait | Fixed impl set | zerocopy | | unsafe trait as capability gate | External impls needed | bytemuck Pod | | Lifetime-encoded validity | Temporal access control | crossbeam-epoch Guard |

References

1. Rustonomicon: Working with Unsafe
2. Ralf Jung: The Scope of Unsafe
3. Unsafe Code Guidelines: Glossary
4. std::mem::MaybeUninit
5. Miri
6. Kani Rust Verifier
7. Stacked Borrows (POPL 2020)
8. Tree Borrows
9. Fuchsia Unsafe Guidelines
10. Rust API Guidelines
11. RustSec Advisory Database