State Design Pattern in Rust

1. Why Do We Need This? (Problem Statement & Status Quo)

When building applications where an entity's behavior changes depending on its internal state, developers often write extensive conditional logic (match or if/else statements) scattered throughout their codebase. As business requirements evolve, adding new states or modifying transitions introduces fragility, making code difficult to maintain and extend.

The State Design Pattern solves this by encapsulating state-specific behavior into distinct state objects. The primary entity delegates state-dependent operations to these objects, cleanly separating concerns. However, implementing traditional object-oriented (OO) design patterns in Rust presents unique challenges because Rust's strict ownership, borrowing, and type systems differ fundamentally from traditional garbage-collected OO languages like Java or C++.

2. Core Mental Model: The Blog Post Workflow

To understand how the state pattern operates, consider the lifecycle of a professional publishing platform managing a blog post. A post must travel strictly through a defined sequence of states rather than jumping arbitrarily between behaviors.

Real-Life Analogy

Think of a physical manuscript being processed by a publishing house:

1. Draft State (Writer's Desk): The author writes, erases, and adds text freely. The manuscript is private and cannot be printed or read by the public.
2. Pending Review State (Editor's Desk): The author submits the manuscript. Changes are locked down while an editor reviews it. It still cannot be published or printed.
3. Published State ( Bookstore Shelf): Once approved by the editor, the book is published, making its content publicly accessible for reading and printing.

The State Transition Flow (OO Approach)

New Post (Draft State)
   |
   | calls add_text() (modifies content)
   | calls request_review()
   v
Pending Review State
   |
   | calls request_review() (no-op)
   | calls approve()
   v
Published State
   |
   | calls content() (returns actual text)

3. Naive vs. Better Approach

• The Naive Approach (Procedural & Conditional): Storing a simple enum (enum State { Draft, PendingReview, Published }) inside a struct and writing giant match self.state blocks inside every single method (add_text, request_review, approve, content). This violates the Open/Closed Principle because every new state requires modifying every single match statement across the codebase.
• The Better Approach (Object-Oriented State Pattern): Defining a common State trait, creating separate structs for each state (Draft, PendingReview, Published), and delegating behavior directly to the active state trait object. The Post struct remains completely agnostic of how states behave or transition.

4. Step-by-Step Evolution: Implementing the OO State Pattern

Let's build out the blog post workflow step-by-step using trait objects and dynamic dispatch in Rust.

Step 4.1: Defining the Post Struct and State Trait

First, we create our library crate (lib.rs). The Post struct holds an optional trait object representing its current state, along with a private string for its content.

pub struct Post {
    state: Option<Box<dyn State>>,
    content: String,
}

pub trait State {
    // Request review consumes ownership of self, invalidating the old state
    fn request_review(self: Box<Self>) -> Box<dyn State>;
    fn approve(self: Box<Self>) -> Box<dyn State>;
    
    // Default implementation returns an empty string slice
    fn content<'a>(&self, _post: &'a Post) -> &'a str {
        ""
    }
}

Note: Why is state an Option<Box<dyn State>>? In Rust, when we want to transition states by consuming ownership of the old state (self: Box<Self>), we need to move the state out of the Post struct. Rust does not allow unpopulated struct fields, so wrapping it in an Option lets us use .take() to temporarily extract it, leaving None in its place.

Step 4.2: Implementing the Draft State and Post Constructor

A new post always starts in the Draft state with empty content.

pub struct Draft {}

impl State for Draft {
    fn request_review(self: Box<Self>) -> Box<dyn State> {
        Box::new(PendingReview {})
    }

    fn approve(self: Box<Self>) -> Box<dyn State> {
        // Can't approve a draft before review is requested
        self
    }
}

impl Post {
    pub fn new() -> Post {
        Post {
            state: Some(Box::new(Draft {})),
            content: String::new(),
        }
    }

    pub fn add_text(&mut self, text: &str) {
        self.content.push_str(text);
    }
}

Step 4.3: Implementing PendingReview and Published States

Next, we add the remaining states and wire up the transition logic.

pub struct PendingReview {}

impl State for PendingReview {
    fn request_review(self: Box<Self>) -> Box<dyn State> {
        // Already in review, return self
        self
    }

    fn approve(self: Box<Self>) -> Box<dyn State> {
        Box::new(Published {})
    }
}

pub struct Published {}

impl State for Published {
    fn request_review(self: Box<Self>) -> Box<dyn State> {
        self
    }

    fn approve(self: Box<Self>) -> Box<dyn State> {
        self
    }

    fn content<'a>(&self, post: &'a Post) -> &'a str {
        &post.content
    }
}

Step 4.4: Adding Methods to Post for State Manipulation

Now we expose public methods on Post that delegate actions down to the underlying state object.

impl Post {
    pub fn content(&self) -> &str {
        // as_ref() gets an Option<&Box<dyn State>>, unwrap() gets the box, 
        // and dot notation dispatches to the State trait method.
        self.state.as_ref().unwrap().content(self)
    }

    pub fn request_review(&mut self) {
        if let Some(s) = self.state.take() {
            self.state = Some(s.request_review());
        }
    }

    pub fn approve(&mut self) {
        if let Some(s) = self.state.take() {
            self.state = Some(s.approve());
        }
    }
}

5. Real-World Practical Pitfalls & Edge Cases

When implementing the OO State Pattern in Rust, developers frequently run into specific borrow checker and architectural hurdles:

• Lifetime Parameter Mismatches: When implementing the content method on the State trait, returning a string slice tied to the lifetime of Post requires explicit lifetime annotations ('a) to satisfy Rust's compiler:
  RUST

  Copy

  fn content<'a>(&self, post: &'a Post) -> &'a str;
  

• Coupling Between States: If business requirements change to add a Scheduled state between PendingReview and Published, the PendingReview state must be modified directly. States become tightly coupled to their adjacent transition targets.
• Code Duplication: Methods like request_review and approve often require boilerplate state-take-and-replace logic inside the Post struct. Macros can be utilized to reduce this repetition if the state machine grows very large.

6. Alternative Approach: Encoding States into the Type System

Because Rust features powerful algebraic data types and ownership semantics, emulating traditional object-oriented patterns can sometimes fight against the language's strengths. Instead of hiding states behind trait objects, we can encode states directly into the type system.

How Type-State Encoding Works

By representing each state as a distinct struct type (DraftPost, PendingReviewPost, Post), invalid operations become compile-time errors rather than runtime checks.

pub struct Post {
    content: String,
}

pub struct DraftPost {
    content: String,
}

impl DraftPost {
    pub fn new() -> DraftPost {
        DraftPost {
            content: String::new(),
        }
    }

    pub fn add_text(&mut self, text: &str) {
        self.content.push_str(text);
    }

    // Consumes DraftPost and returns PendingReviewPost
    pub fn request_review(self) -> PendingReviewPost {
        PendingReviewPost {
            content: self.content,
        }
    }
}

pub struct PendingReviewPost {
    content: String,
}

impl PendingReviewPost {
    // Consumes PendingReviewPost and returns the final published Post
    pub fn approve(self) -> Post {
        Post {
            content: self.content,
        }
    }
}

impl Post {
    pub fn content(&self) -> &str {
        &self.content
    }
}

Usage in main.rs (Variable Shadowing)

fn main() {
    let mut draft = DraftPost::new();
    draft.add_text("I ate a salad for lunch today");

    // Using variable shadowing to transition types safely
    let post = draft.request_review().approve();

    assert_eq!("I ate a salad for lunch today", post.content());
}

7. Comparison: OO State Pattern vs. Type-State Pattern

8. Summary and Key Takeaways

• Object-Oriented Design in Rust: Rust supports OO patterns through structs, traits, and trait objects (dyn Trait), enabling dynamic dispatch when necessary.
• State Encapsulation: The State Design Pattern delegates state-specific logic to separate state structs, keeping the primary entity (Post) clean and decoupled from business rule changes.
• Optional State Management: Wrapping state trait objects in Option<Box<dyn State>> allows safe extraction and replacement of state using .take().
• Ownership as State Validation: Consuming self: Box<Self> ensures that old states are invalidated upon transition, preventing illegal reuse.
• The Power of Type-Encoding: Rust allows developers to encode states directly into unique types, transforming runtime logic bugs into compile-time guarantees.
• Idiomatic Trade-offs: While OO patterns work in Rust, leveraging Rust's ownership model and type system often yields safer, more performant code without runtime dispatch overhead.