[Coding Guideline]: Require wrapping unsafe code in safe abstractions

[AchimKriso]

Chapter

Unsafety

Guideline Title

All unsafe code shall be contained inside a sound safe abstraction

Category

Required

Status

Draft

Release Begin

unclear

Release End

latest

FLS Paragraph ID

fls_jep7p27kaqlp

Decidability

Undecidable

Scope

Module

Tags

undefined-behavior

Amplification

A safe abstraction is considered sound, when it is impossible to build a safe program using the safe abstraction that invokes undefined behavior.

Safe abstractions shall be kept as small as possible and only include features that cannot be built on top in safe Rust.

Exception(s)

No response

Rationale

Unsound safe abstractions leak the possibility for undefined behavior to safe Rust.
With violations of this rule, it would no longer suffice to only focus on unsafe modules as the root cause of undefined behavior

Because safe abstractions are more difficult to review compared to safe code due to the subtle semantics of unsafe operations, their size shall be minimized.

Non-Compliant Example - Prose

The following module with a safe API uses unsafe code and is therefore considered a safe abstraction.
However, when passing a data slice with an index that is outside the range of the slice, the safe function will cause undefined behavior.

Non-Compliant Example - Code

pub mod bad {
pub fn get_value(data: &[i32], index: usize) -> i32 {
unsafe {
data.get_unchecked(usize)
}
}
}

Compliant Example - Prose

This safe module checks that its argument are valid, (i.e., they satisfy the safety precondition of the unsafe operation) before performing the unsafe operation.

Compliant Example - Code

pub mod good {
pub fn get_value(data: &[i32], index: usize) -> i32 {
assert!(usize < data.len());
unsafe {
data.get_unchecked(usize)
}
}
}