Safe API Design Over Unsafe Rust

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).

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.

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

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