Skill 13 · Rust Best Practices
Subchapter 13.7
references/chapter_07.mdMarkdown8 KBView on GitHub
Models state at compile time, preventing bugs by making illegal states unrepresentable. It takes advantage of the Rust generics and type system to create sub-types that can only be reached if a certain condition is achieved, making some operations illegal at compile time.
Recently it became the standard design pattern of Rust programming. However, it is not exclusive to Rust, as it is achievable and has inspired other languages to do the same swift (opens in a new tab) and typescript (opens in a new tab).
Type State Pattern is a design pattern where you encode different states of the system as types, not as runtime flags or enums. This allows the compiler to enforce state transitions and prevent illegal actions at compile time. It also improves the developer experience, as developers only have access to certain functions based on the state of the type.
Invalid states become compile errors instead of runtime bugs.
use std::{io, path::{Path, PathBuf}};
struct FileNotOpened;
struct FileOpened;
#[derive(Debug)]
struct File<State> {
/// Path to the opened file
path: PathBuf,
/// Open `File` handler
handle: Option<std::fs::File>,
/// Type state manager
_state: std::marker::PhantomData<State>
}
impl File<FileNotOpened> {
/// `open` is the only entry point for this struct.
/// * When called with a valid path, it will return a `File<FileOpened>` with a valid `handler` and `path`
/// * `open` serves as an alternative to `new` and `defaults` methods (usable when your struct needs valid data to exist).
fn open(path: &Path) -> io::Result<File<FileOpened>> {
// If file is invalid, it will return `std::io::Error`
let file = std::fs::File::open(path)?;
Ok(
File {
path: path.to_path_buf(),
// Always valid
handle: Some(file),
_state: std::marker::PhantomData::<FileOpened>
}
)
}
}
impl File<FileOpened> {
/// Reads the content of the `File` as a `String`.
/// `read` can only be called by state `File<FileOpened>`
fn read(&mut self) -> io::Result<String> {
use io::Read;
let mut content = String::new();
let Some(handle)= self.handle.as_mut() else {
unreachable!("Safe to unwrap as state can only be reached when file is open");
};
handle.read_to_string(&mut content)?;
Ok(content)
}
/// Returns the valid path buffer.
fn path(&self) -> &PathBuf {
&self.path
}
}Forces the user to set required fields before calling
.build().
A type-state pattern can have more than one associated states:
use std::marker::PhantomData;
struct MissingName;
struct NameSet;
struct MissingAge;
struct AgeSet;
#[derive(Debug)]
struct Person {
name: String,
age: u8,
email: Option<String>,
}
struct Builder<NameState, AgeState> {
name: Option<String>,
age: u8,
email: Option<String>,
_name_marker: PhantomData<NameState>,
_age_marker: PhantomData<AgeState>,
}
impl Builder<MissingName, MissingAge> {
fn new() -> Self {
Builder { name: None, age: 0, _name_marker: PhantomData, _age_marker: PhantomData, email: None }
}
fn name(self, name: String) -> Builder<NameSet, MissingAge> {
Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData, email: None }
}
fn age(self, age: u8) -> Builder<MissingName, AgeSet> {
Builder { age, _age_marker: PhantomData::<AgeSet>, name: None, _name_marker: PhantomData, email: None }
}
}
impl Builder<NameSet, MissingAge> {
fn age(self, age: u8) -> Builder<NameSet, AgeSet> {
Builder { age, _age_marker: PhantomData::<AgeSet>, name: self.name, _name_marker: PhantomData::<NameSet>, email: None }
}
}
impl Builder<MissingName, AgeSet> {
fn email(self, email: String) -> Self {
Self { name: self.name , age: self.age , email: Some(email) , _name_marker: self._name_marker , _age_marker: self._age_marker }
}
fn name(self, name: String) -> Builder<NameSet, AgeSet> {
Builder { name: Some(name), _name_marker: PhantomData::<NameSet>, age: self.age, _age_marker: PhantomData::<AgeSet>, email: self.email }
}
}
impl Builder<NameSet, AgeSet> {
fn build(self) -> Person {
Person {
name: self.name.unwrap_or_else(|| unreachable!("Name is guarantee to be set")),
age: self.age,
email: self.email,
}
}
}Although a bit more verbose than a usual builder, this guarantees that all necessary fields are present (note that e-mail is optional field only present in the final builder).
// ✅ Valid cases
let person: Person = Builder::new().name("name".to_string()).age(30).build();
let person: Person = Builder::new().age(30).name("name".to_string()).build();
let person: Person = Builder::new().age(30).name("name".to_string()).email("myself@email.com".to_string()).build();
// ❌ Invalid cases
let person: Person = Builder::new().name("name".to_string()).build(); // ❌ Compile error: Age required to `build`
let person: Person = Builder::new().age(30).build(); // ❌ Compile error: Name required to `build`
let person: Person = Builder::new().age(30).email("myself@email.com".to_string()).build(); // ❌ Compile error: Name required to `build`
let person: Person = Builder::new().build();// ❌ Compile error: Name and Age required to `build`Illegal transitions like sending a message before connecting simply don’t compile:
// Mock example
struct Disconnected;
struct Connected;
struct Client<State> {
stream: Option<std::net::TcpStream>,
_state: std::marker::PhantomData<State>
}
impl Client<Disconnected> {
fn connect(addr: &str) -> std::io::Result<Client<Connected>> {
let stream = std::net::TcpStream::connect(addr)?;
Ok(Client {
stream: Some(stream),
_state: std::marker::PhantomData::<Connected>
})
}
}
impl Client<Connected> {
fn send(&mut self, msg: &str) {
use std::io::Write;
let Some(stream) = self.stream.as_mut() else {
unreachable!("Stream is guarantee to be set");
};
stream.write_all(msg.as_bytes())
}
}Use this pattern when it saves bugs, increases safety or simplifies logic, not just for cleverness.