State Machines

Why State Machines?

• Every time a browser sends an HTTP request, the server processes it through a fixed sequence of steps:
  • Read the incoming bytes
  • Match the URL to a handler
  • Run that handler
  • Write a response back
• An experienced developer holds this picture in their head; a finite state machine puts it in the code
• The core idea:
  • a fixed set of states the system can be in
  • a fixed set of events that can arrive
  • a transition function that says "if I am in state S and event E arrives, move to state N"
• Any event that has no entry in the table for the current state is invalid, which is how the machine enforces legal behavior
• State machines appear everywhere: TCP connection handling, UI workflow steps, and characters in video games

The States and Events

• An HTTP request lifecycle has six states:

pub type State {
    Idle
    Reading
    Routing
    Handling
    Sending
    Done
}

pub type Event {
    Connect
    Data(String)
    Match(String)
    NoMatch
    Response(Int)
    Sent
}

• Idle waits for a new connection
• Reading receives incoming bytes from the network
• Routing matches the request path to a registered handler
• Handling runs the application code for that handler
• Sending writes the response bytes back to the client
• Done signals that the response was delivered
• The events that drive those transitions:
  • Connect: a new TCP connection arrives
  • Data(String): the request line (method and path) has been read
  • Match(String): a route handler was found for the path
  • NoMatch: no handler matched (the server will return 404)
  • Response(Int): the handler finished with an HTTP status code
  • Sent: all response bytes were flushed to the network
• Carrying data inside event variants (Data, Match, Response) lets callers attach context even if the transition function ignores it for the purpose of deciding which state comes next

The Transition Function

pub fn step(state: State, event: Event) -> Result(State, String) {
    case state, event {
        Idle, Connect -> Ok(Reading)
        Reading, Data(_) -> Ok(Routing)
        Routing, Match(_) -> Ok(Handling)
        Routing, NoMatch -> Ok(Sending)
        Handling, Response(_) -> Ok(Sending)
        Sending, Sent -> Ok(Done)
        _, _ ->
            Error(
                "cannot handle "
                <> string.inspect(event)
                <> " in state "
                <> string.inspect(state),
            )
    }
}

• case state, event matches on both values simultaneously without wrapping them in a tuple
• Each valid pair maps to Ok(next_state); everything else maps to an Error carrying a message
• string.inspect renders the state and event without a custom formatter
• Only six transitions are valid; the _, _ arm rejects all other combinations
• This is the complete rule table of the machine, written as a single pattern match

Running a Sequence of Events

pub fn run(state: State, events: List(Event)) -> Result(State, String) {
    case events {
        [] -> Ok(state)
        [event, ..rest] ->
            case step(state, event) {
                Error(msg) -> Error(msg)
                Ok(next) -> run(next, rest)
            }
    }
}

• run applies a list of events to a starting state, returning the final state or the first error
• Base case: no events remain, so the current state is the result
• Recursive case: apply step to the first event; if it fails, return the error immediately; otherwise recurse with the new state and the remaining events
• Once a bad event arrives, no further events are processed

The Happy Path and the 404 Path

    let happy_path = [
        Connect,
        Data("GET /users"),
        Match("users_handler"),
        Response(200),
        Sent,
    ]
    io.println("Happy path: " <> string.inspect(run(Idle, happy_path)))

    let not_found = [Connect, Data("GET /nope"), NoMatch, Sent]
    io.println("Not found: " <> string.inspect(run(Idle, not_found)))

    let bad = [Connect, Sent]
    io.println("Bad event: " <> string.inspect(run(Idle, bad)))

• The happy path moves through all six states: Idle → Reading → Routing → Handling → Sending → Done
• The 404 path skips Handling entirely: NoMatch transitions directly from Routing to Sending, because there is no handler to run
• Both paths end at Ok(Done)
• The bad path tries Sent while still in Reading, which is nonsense, and gets an Error explaining exactly what went wrong

Testing

pub fn idle_connect_test() {
    step(Idle, Connect)
    |> should.equal(Ok(Reading))
}

pub fn reading_data_test() {
    step(Reading, Data("GET /users"))
    |> should.equal(Ok(Routing))
}

pub fn routing_match_test() {
    step(Routing, Match("users_handler"))
    |> should.equal(Ok(Handling))
}

pub fn routing_not_found_test() {
    step(Routing, NoMatch)
    |> should.equal(Ok(Sending))
}

pub fn handling_response_test() {
    step(Handling, Response(200))
    |> should.equal(Ok(Sending))
}

pub fn sending_sent_test() {
    step(Sending, Sent)
    |> should.equal(Ok(Done))
}

pub fn invalid_transition_test() {
    step(Idle, Sent)
    |> should.be_error()
}

pub fn happy_path_test() {
    let events = [
        Connect,
        Data("GET /users"),
        Match("users_handler"),
        Response(200),
        Sent,
    ]
    run(Idle, events)
    |> should.equal(Ok(Done))
}

pub fn not_found_path_test() {
    let events = [Connect, Data("GET /nope"), NoMatch, Sent]
    run(Idle, events)
    |> should.equal(Ok(Done))
}

pub fn stops_on_error_test() {
    let events = [Connect, Sent]
    run(Idle, events)
    |> should.be_error()
}

• Each single-step test calls step directly with one state and one event
• should.equal(Ok(Reading)) verifies the exact next state
• should.be_error() checks that an invalid transition is rejected without caring about the error message text
• The run tests verify complete event sequences, which is closer to how the machine is actually used in production

Check Understanding

Exercises