Rust API Design

Common Trait Implementations

Types MUST eagerly implement common traits. Rust’s orphan rule means a downstream crate cannot supply the implementation you left out.

Required Traits Checklist

All public types MUST implement these traits where applicable:

// MINIMUM: Every public type needs Debug
#[derive(Debug)]
pub struct Config {
    timeout: Duration,
    retries: u32,
}

// RECOMMENDED: Add Clone, PartialEq, Eq when semantically valid
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserId(pub u64);

// FOR HASH MAPS: Add Hash when type will be used as a key
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct CacheKey {
    namespace: String,
    id: u64,
}

// FOR VALUE OBJECTS: Add Copy when the type is small and Copy-safe
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Point {
    x: i32,
    y: i32,
}

Serde Support

Libraries SHOULD provide Serde support behind a feature flag:

# Cargo.toml
[features]
default = []
serde = ["dep:serde"]

[dependencies]
serde = { version = "1.0", features = ["derive"], optional = true }

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Config {
    pub timeout_ms: u64,
    pub retries: u32,
}

API Design and Documentation

Public APIs MUST follow the Rust API Guidelines. crefft vendors the full text under reference/rust/; this section carries the rules that apply to every crate and links to the detailed page for each one.

Naming

Names MUST follow RFC 430 casing and the standard conversion prefixes.²

Convention	Rule	Example
Casing (C-CASE)	UpperCamelCase types, snake_case values, SCREAMING_SNAKE_CASE constants	struct CacheKey, fn parse_retries, const MAX_RETRIES
Conversions (C-CONV)	as_ borrowed, to_ expensive, into_ owned	as_str, to_owned, into_bytes
Getters (C-GETTER)	No get_ prefix except for a single obvious accessor	fn timeout(&self), not fn get_timeout(&self)
Iterators (C-ITER)	iter, iter_mut, into_iter	fn iter(&self) -> Iter<'_, T>
Iterator types (C-ITER-TY)	Type name matches the method	iter() returns Iter
Features (C-FEATURE)	No placeholder words	serde, not use-serde or with-serde
Word order (C-WORD-ORDER)	Consistent across the crate	SocketAddrV4/SocketAddrV6, not V4SocketAddr

// GOOD: the prefix states the cost, and the getter has no `get_`.
impl Config {
    pub fn timeout(&self) -> Duration { self.timeout }
    pub fn as_str(&self) -> &str { &self.name }
    pub fn into_parts(self) -> (String, Duration) { (self.name, self.timeout) }
}

// BAD: `get_` prefix, and `to_parts` implies a cheap borrow of an owned value.
impl Config {
    pub fn get_timeout(&self) -> Duration { self.timeout }
    pub fn to_parts(self) -> (String, Duration) { (self.name, self.timeout) }
}

Documentation

Every public item MUST carry rustdoc. Documentation MUST state error, panic, and safety conditions, and examples MUST use ? rather than unwrap.³

/// Converts a port number, rejecting values outside the `u16` range.
///
/// # Errors
///
/// Returns [`PortRangeError`] when `value` exceeds `u16::MAX`.
///
/// # Examples
///
/// ```
/// use core_api::PortNumber;
///
/// let port = PortNumber::try_from(8080_u32)?;
/// assert_eq!(u16::from(port), 8080);
/// # Ok::<(), core_api::PortRangeError>(())
/// ```
fn try_from(value: u32) -> Result<Self, Self::Error> {
    u16::try_from(value).map(Self).map_err(|_| PortRangeError(value))
}

// BAD: no `# Errors`, and the example panics instead of propagating. A reader
// cannot tell what makes this fail, and `cargo test --doc` proves nothing
// about the error path.
/// Converts a port number.
///
/// ```
/// let port = PortNumber::try_from(8080u32).unwrap();
/// ```

Doc examples are tests. cargo test --doc MUST run in CI, so an example that stops compiling fails the build rather than rotting in place.

Manifests MUST carry the full metadata set (C-METADATA): description, license, repository, documentation, homepage, keywords, categories. Items that are public only for macro expansion MUST be hidden with #[doc(hidden)] (C-HIDDEN).

Dyn Compatibility

Traits that MAY usefully be used as dyn Trait MUST stay dyn-compatible (the property formerly called object safety): no generic methods, no Self return by value, no Self: Sized supertrait.⁴ Where both are wanted, provide the generic API as a blanket extension over the dyn-compatible core.

// GOOD: dyn-compatible core, generics moved to a free function.
pub trait Sink {
    fn write_line(&mut self, line: &str) -> std::io::Result<()>;
}

pub fn write_all<S: Sink + ?Sized>(sink: &mut S, lines: &[&str]) -> std::io::Result<()> {
    lines.iter().try_for_each(|line| sink.write_line(line))
}

pub fn make(boxed: Box<dyn Sink>) -> Box<dyn Sink> { boxed }

// BAD: the generic method makes `dyn Sink` impossible:
// "the trait `Sink` is not dyn compatible".
pub trait Sink {
    fn write_all<I: IntoIterator<Item = &'static str>>(&mut self, lines: I);
}

Type Safety

Arguments MUST convey meaning through types rather than bare bool or Option (C-CUSTOM-TYPE), and newtypes SHOULD be used to make distinct quantities distinct (C-NEWTYPE).⁵

// GOOD: unmistakable at the call site.
pub enum Overwrite { Yes, No }
pub fn save(path: &Path, overwrite: Overwrite) -> io::Result<()> { /* ... */ }

save(path, Overwrite::Yes)?;

// BAD: `save(path, true, false)` is unreadable and silently swappable.
pub fn save(path: &Path, overwrite: bool, fsync: bool) -> io::Result<()> { /* ... */ }

The full checklist, including predictability, dependability, and debuggability rules not repeated here, is in reference/rust/checklist.md.