Skip to main content

Crate essm

Crate essm 

Source
Expand description

§ESSM: Extremely Simple State Machines

A compile-time typestate state machine library for Rust. States are distinct types, transitions are trait implementations. To make states reasonable lean external managed data can be threaded through state transitions by providing a reference to a generic context.

§Design philosophy

ESSM provides safe state transitions via the typestate pattern. It does NOT provide a runtime state machine wrapper, event dispatch, or async drivers; those are the user’s domain. ESSM handles one thing: making sure you can only transition between states that have a defined path, and that the transition hooks (invariants, guards, entry/exit checks) execute in the correct order.

Being extremely simple applies to being the usage which is intended to be very ergonomic and safe (wrong use is a compile error). As well as its implementation which may be surprisingly minimal.

§Intended scope

ESSM is designed for small-to-medium sized state machines. Each transition pair requires a separate trait implementation, this is the cost of compile-time type safety.

§Getting started

Add essm to your Cargo.toml, then import everything:

use essm::*;

This brings in State, Transition, TransitionResult, TransitionInfallible, ErrorState, FailedAt, Primordial, Terminated, Infallible, InitialState, InitialStateInfallible, TerminalState, TerminalStateInfallible, and all other public types in one line.

§Quick example

#[derive(Debug)]
struct Idle;
impl State for Idle {}

#[derive(Debug)]
struct Running;
impl State for Running {}

// Define allowed transitions
impl Transition<Running> for Idle {
    fn change(self, _ctx: &dyn Any) -> TransitionResult<Idle, Running> {
        Ok(Running)
    }
}

impl Transition<Idle> for Running {
    fn change(self, _ctx: &dyn Any) -> TransitionResult<Running, Idle> {
        Ok(Idle)
    }
}

let idle = Idle;
let running: Running = idle.transition();
let idle: Idle = running.transition();

§Bootstrap and termination

ESSM provides an optional bootstrap pattern via predefined Primordial and Terminated pseudo states. These make creation and destruction symetric with state transitions. Every lifecycle event uses the same Transition pipeline.

§Creating initial states

Implement Transition<YourState> for Primordial to define how your first state is created, the InitialState/InitialStateInfallible traits are automatically implemented for any transition from Primordial. They define convenient constructors:


#[derive(Debug)]
struct Red;
impl State for Red {}

impl Transition<Red> for Primordial {
    fn change(self, _: &dyn Any) -> TransitionResult<Primordial, Red> {
        Ok(Red)
    }
}

/// This is calling InitialStateInfallible::new()
let red = Red::new();

§Terminating the machine

Implement Transition<Terminated> for the final state, then call .terminate():


impl Transition<Terminated> for Red {
    fn change(self, _: &dyn Any) -> TransitionResult<Red, Terminated> {
        Ok(Terminated)
    }
}

// this is calling TerminalStateInfallible::terminate()
red.terminate();

§Primordial and Terminated are optional

You are not required to use Primordial or Terminated. States can be constructed directly (e.g., let idle = Idle;) and destroyed by simply letting them go out of scope. This is perfectly valid and often simpler for small state machines or ZST states.

However, when bypassing Primordial and Terminated, you are responsible maintaining the lifecycle contracts manually by calling the respective hooks:

  • state.enter(&ctx) — after constructing a state
  • state.invariant() — for validating a state
  • state.leave(&ctx) — before destroying a state

The InitialState and TerminalState traits automate this for you.

§Data-carrying states

When a state carries data, you can move that data to the next state in change():

struct Parsing { buf: Vec<u8>, pos: usize }
impl State for Parsing {}

struct Ready { buf: Vec<u8> }
impl State for Ready {}

impl Transition<Ready> for Parsing {
    fn change(self, _ctx: &dyn Any) -> TransitionResult<Parsing, Ready> {
        Ok(Ready { buf: self.buf })
    }
}

§impl Drop on state types

Rust forbids partial moves out of Drop-implementing types (E0509), but Transition::change consume self and may move data into the next state. When you need to implement Drop for states, then the most universal workaround is Option::take():

#[derive(Debug)]
struct Parsing {
    buf: Option<Vec<u8>>,
    pos: usize,
}
impl State for Parsing {}

impl Drop for Parsing {
    fn drop(&mut self) {
        // Called after change() — buf is None if transition succeeded
    }
}

#[derive(Debug)]
struct Ready { buf: Vec<u8> }
impl State for Ready {}

impl Transition<Ready> for Parsing {
    fn change(mut self, _ctx: &dyn Any) -> TransitionResult<Parsing, Ready> {
        // take `buf` out of the option, leave `None` in self
        let buf = self.buf.take().unwrap();
        // self will be dropped at the end of this scope
        Ok(Ready { buf })
    }
}

core::mem::take() is an alternative for T: Default types (no Option wrapper needed).

External crates: The derive_destructure2 crate provides proc macros (#[derive(destructure)], #[derive(remove_trait_impls)]) that let you destructure Drop types directly. The drop-with-owned-fields crate offers a safe ManuallyDrop wrapper.

Unsafe approach: For zero-cost repackaging, wrap the self in ManuallyDrop, ptr::read each field, and handle dropping of unused fields manually.

Prefer TerminalState for structured teardown or rely on Rust’s automatic drop for Drop-implementing fields (Vec, String, Box).

§Transition pipeline

Each transition() executes methods in a fixed order:

1. self.invariant()                 : invariant check on source state integrity (no context)
2. self.leave(&ctx)                 : on-exit check
3. self.guard(&ctx)                 : pure predicate
4. let next = self.change(&ctx)     : produce next state
5. next.enter(&ctx)                 : on-entry check
6. next.invariant()                 : invariant check on target state integrity (no context)

All methods except for change() have no-op blanket implementations they only need to be implemented when needed and are zero cost otherwise.

Call try_transition() for the zero-argument convenience path (context is ()). Use try_transition_with() to pass a context that threads through the entire pipeline; hooks can use it.

let idle = Idle;
let running: Running = idle.transition();

With a user-defined context — set the Transition’s Ctx type:

struct MyCtx { counter: u32 }
let idle = Idle;
let ctx = MyCtx { counter: 0 };
let running: Running = idle.transition_with(&ctx);

§Error recovery

In ESSM, errors are states. When a transition fails, it returns an ErrorState which implements State. This means you can transition FROM an error back to a valid state:

#[derive(Debug)] enum MyError { Bad }
impl StateError for MyError {}

#[derive(Debug, Default)] struct Idle;
impl State for Idle {}

#[derive(Debug)] struct Working { should_fail: bool }
impl State for Working {}

#[derive(Debug)] struct Done;
impl State for Done {}

impl Transition<Working, MyError, Infallible> for Idle {
}
impl Transition<Done, MyError, Infallible> for Working {
}

// Recover from any `ErrorState<MyError, ..>` back to Idle
impl<Origin, Next> Transition<Idle> for ErrorState<MyError, Origin, Next> {
    fn change(self, _ctx: &dyn Any) -> TransitionResult<Self, Idle> {
        Ok(Idle)
    }
}

let idle = Idle;
let working: Working = idle.try_transition().unwrap();

// Transition fails -- but the error IS a state
match working.try_transition() {
    Ok(done) => { /* success */ }
    Err(error_state) => {
        // Recover: transition from the error back to Idle
        let idle: Idle = error_state.try_transition().unwrap();
    }
}

On failure, try_transition() returns an ErrorState that carries both the original error and a FailedAt wrapping the state that survived. Use ErrorState::err_origin, ErrorState::err_next, or ErrorState::err to construct errors from your change() implementation.

§Custom error types

You can define your own error types instead of using Infallible. For example, the vending machine example defines a VendError enum to signal insufficient credit:

#[derive(Debug)]
enum VendError { NotEnoughCredit }
impl StateError for VendError {}

The HasCredit → Dispensing transition checks the credit balance and returns VendError::NotEnoughCredit via ErrorState::err_origin if the balance is too low. Because the origin state (HasCredit) is preserved in the ErrorState, the caller can recover by extracting it and continuing.

Custom errors should implement StateError which marks them convertible into itself.

§Recovery pattern

Since ErrorState implements State, you can implement Transition from an ErrorState back to a valid state. Recovery can restore the original state via the FailedAt::Origin (or FailedAt::Next) variant:


#[derive(Debug)] enum VendError { NotEnoughCredit }
impl StateError for VendError{}

#[derive(Debug)] struct HasCredit { amount: u32 }; impl State for HasCredit {}
#[derive(Debug)] struct Dispensing { item: &'static str, change: u32 }; impl State for Dispensing {}

// Recovery: ErrorState → HasCredit, restoring the original state
impl Transition<HasCredit> for ErrorState<VendError, HasCredit, Dispensing> {
    fn change(self, _ctx: &dyn Any) -> TransitionResult<Self, HasCredit> {
        match self.at {
            FailedAt::Origin(state) => Ok(state),  // restore original HasCredit
            _ => panic!("expected origin in recovery"),
        }
    }
}

This pattern lets you attempt a fallible transition, recover from failure by restoring the original state, and retry with different inputs.

§Customizing transitions

The pipeline is defined by Transition’s default methods. Override the hooks, not the pipeline:

HookTraitPurpose
invariant()Stateinvariant check on state integrity
leave()StateOn-exit check, immutable context
guard()TransitionPure predicate: is the transition allowed?
change()TransitionProduce the next state from the current one
enter()StateOn-entry check, immutable context

§no_std

ESSM is #![no_std] by default. Tests use std behind #[cfg(test)].

§Status, Plans and Thoughts

This crate is still in development, significant/breaking changes may and will happen until this note is removed.

  • Since associated types can not have defaults we have to use generics, eventually this will become a breaking change where the Error types become associated types once defaults are stable.
  • While the current way to have errors on states and transitions is universal, it can be less ergonomic to use. We need to think if we want to simplify this, eg. State being non generic, its methods returning bool. Somehow the transition then needs to synthesize a Error on failures.
  • I started a declarative macro DSL for easy state transitions like:
    ⓘ
    essm!{
        state A;
        state B;
        initial A;
        transition A->B;
        terminal B;
    }
    With generics and error types this becoming pretty complicated. We need to reevaluate if this should be done as proc macro (using unsynn).

§LLM usage

  • Design and planning: Completely human. Architecture decisions, API design, trait boundaries, and the transition pipeline are human-authored.
  • Implementation: Hybrid. Core traits and library code are human-authored with LLM assistance for bootratapping. Eventually most llm code got rewritten manually
  • Contributions: Will be judged by completeness and quality alone (test coverage, documentaton).
  • Documentation and examples: Partially LLM-generated, human-reviewed. README, doctests, and example programs are drafted with LLM assistance and verified by human review.

Structs§

ErrorState
Wraps an error with information about what state survived the failed transition.
Primordial
The state before all states. Bootstrap mechanism for the state machine.
Terminated
The terminal state. The state a machine enters when it is done.

Enums§

FailedAt
Indicates at what point a transition failed and what state survived.

Traits§

Any
Re-export Infallible and Any so users can import everything via use essm::*;. When using wildcard imports, allow the Clippy lint:
InitialState
Convenience constructors for states that can be created from Primordial.
InitialStateInfallible
Convenience constructors for states that can be infallibly crated from Primordial.
MapErr
Error to Error conversion For states that are generic over different error types we need error to error conversions.
State
A type that is used as state in a state-machine must implement State. States are generic over the error type their methods may raise. Error defaults to Infallible to simplify creation of state machines. Context is passed as ‘&dyn Any’ and must be downcasted for use, side effects on the context need interior mutability. Context is not optional but can be ignored and transitions without context. We use the unit value () in that case. Context is not an Option because in almost any cases where a context is used, it is required and must be of the correct type. Failing to do so is a programming error, not a runtime error.
StateError
Marker trait that enables no-op E->E conversions. Any user defined error type must either impl StateError for UserError{} or impl MapErr<UserError> for UserError { fn map_err(self)->Self{self}}. The first is more convenient to do.
TerminalState
Convenience destructors for states that can be transitioned to Terminated.
TerminalStateInfallible
Extension trait providing infallible termination methods for states where Error = Infallible.
Transition
The state transition trait. Users implement this to define allowed transitions.
TransitionInfallible
Extension trait providing infallible transition methods for states where Error = Infallible.

Type Aliases§

Infallible
Re-export Infallible and Any so users can import everything via use essm::*;. When using wildcard imports, allow the Clippy lint:
TransitionResult
The canonical return type of a state transition.