State Pattern — Hands-on Tasks¶

package main

import (
    "errors"
    "fmt"
)

// OrderState is the behavior interface. Every concrete state implements it.
// The Order itself only forwards — it does not contain any business rule.
type OrderState interface {
    Pay(*Order) error
    Ship(*Order) error
    Cancel(*Order) error
    Name() string
}

// Order is the Context. It carries domain data and a pointer to the
// current state. Methods are one-liners that delegate.
type Order struct {
    ID    string
    state OrderState
}

func NewOrder(id string) *Order {
    // Senior decision: the zero value of Order is not a valid Order.
    // A constructor forces every Order to start in a known state.
    return &Order{ID: id, state: Pending{}}
}

func (o *Order) setState(s OrderState) { o.state = s }
func (o *Order) State() string         { return o.state.Name() }
func (o *Order) Pay() error            { return o.state.Pay(o) }
func (o *Order) Ship() error           { return o.state.Ship(o) }
func (o *Order) Cancel() error         { return o.state.Cancel(o) }

// --- states ---

type Pending struct{}

func (Pending) Name() string                { return "pending" }
func (Pending) Pay(o *Order) error          { o.setState(Paid{}); return nil }
func (Pending) Ship(*Order) error           { return errors.New("can't ship unpaid order") }
func (Pending) Cancel(o *Order) error       { o.setState(Cancelled{}); return nil }

type Paid struct{}

func (Paid) Name() string                   { return "paid" }
func (Paid) Pay(*Order) error               { return errors.New("already paid") }
func (Paid) Ship(o *Order) error            { o.setState(Shipped{}); return nil }
func (Paid) Cancel(o *Order) error          { o.setState(Cancelled{}); return nil }

type Shipped struct{}

func (Shipped) Name() string                { return "shipped" }
func (Shipped) Pay(*Order) error            { return errors.New("already paid") }
func (Shipped) Ship(*Order) error           { return errors.New("already shipped") }
func (Shipped) Cancel(*Order) error         { return errors.New("can't cancel a shipped order") }

type Cancelled struct{}

func (Cancelled) Name() string              { return "cancelled" }
func (Cancelled) Pay(*Order) error          { return errors.New("cancelled") }
func (Cancelled) Ship(*Order) error         { return errors.New("cancelled") }
func (Cancelled) Cancel(*Order) error       { return errors.New("already cancelled") }

// Compile-time interface checks. Cheap insurance.
var (
    _ OrderState = Pending{}
    _ OrderState = Paid{}
    _ OrderState = Shipped{}
    _ OrderState = Cancelled{}
)

func main() {
    o := NewOrder("o-1")
    fmt.Println("start:", o.State())
    _ = o.Pay()
    fmt.Println("after pay:", o.State())
    _ = o.Ship()
    fmt.Println("after ship:", o.State())
    if err := o.Cancel(); err != nil {
        fmt.Println("cancel error:", err)
    }
}

package main

import "fmt"

type Light interface {
    Next(t *TrafficLight)
    Color() string
}

type TrafficLight struct {
    state Light
}

func NewTrafficLight() *TrafficLight {
    return &TrafficLight{state: Red{}}
}

// Senior decision: Tick (not Next) on the Context. The Context drives
// the transition; the state computes the next one.
func (t *TrafficLight) Tick()         { t.state.Next(t) }
func (t *TrafficLight) Color() string { return t.state.Color() }

type Red struct{}

func (Red) Color() string         { return "red" }
func (Red) Next(t *TrafficLight)  { t.state = Green{} }

type Green struct{}

func (Green) Color() string        { return "green" }
func (Green) Next(t *TrafficLight) { t.state = Yellow{} }

type Yellow struct{}

func (Yellow) Color() string        { return "yellow" }
func (Yellow) Next(t *TrafficLight) { t.state = Red{} }

func main() {
    t := NewTrafficLight()
    for i := 0; i < 6; i++ {
        fmt.Println(t.Color())
        t.Tick()
    }
}

package main

import (
    "errors"
    "fmt"
)

type Status int

const (
    StatusPending Status = iota
    StatusPaid
    StatusShipped
    StatusCancelled
)

// Stringer: the FSM stores Status, but logs/JSON should show the name.
func (s Status) String() string {
    switch s {
    case StatusPending:
        return "pending"
    case StatusPaid:
        return "paid"
    case StatusShipped:
        return "shipped"
    case StatusCancelled:
        return "cancelled"
    }
    return fmt.Sprintf("unknown(%d)", int(s))
}

type OrderState interface {
    Pay(*Order) error
    Ship(*Order) error
    Cancel(*Order) error
}

type Order struct {
    ID     string
    status Status
}

func NewOrder(id string) *Order { return &Order{ID: id, status: StatusPending} }
func (o *Order) Status() Status { return o.status }

// The Order dispatches through the registry. The registry is built once.
func (o *Order) Pay() error    { return orderStates[o.status].Pay(o) }
func (o *Order) Ship() error   { return orderStates[o.status].Ship(o) }
func (o *Order) Cancel() error { return orderStates[o.status].Cancel(o) }

type pendingState struct{}

func (pendingState) Pay(o *Order) error    { o.status = StatusPaid; return nil }
func (pendingState) Ship(*Order) error     { return errors.New("can't ship unpaid order") }
func (pendingState) Cancel(o *Order) error { o.status = StatusCancelled; return nil }

type paidState struct{}

func (paidState) Pay(*Order) error         { return errors.New("already paid") }
func (paidState) Ship(o *Order) error      { o.status = StatusShipped; return nil }
func (paidState) Cancel(o *Order) error    { o.status = StatusCancelled; return nil }

type shippedState struct{}

func (shippedState) Pay(*Order) error    { return errors.New("already paid") }
func (shippedState) Ship(*Order) error   { return errors.New("already shipped") }
func (shippedState) Cancel(*Order) error { return errors.New("can't cancel shipped") }

type cancelledState struct{}

func (cancelledState) Pay(*Order) error    { return errors.New("cancelled") }
func (cancelledState) Ship(*Order) error   { return errors.New("cancelled") }
func (cancelledState) Cancel(*Order) error { return errors.New("already cancelled") }

// Senior decision: registry built once at package init. Each state is a
// flyweight — one value reused across every Order in the process.
var orderStates = map[Status]OrderState{
    StatusPending:   pendingState{},
    StatusPaid:      paidState{},
    StatusShipped:   shippedState{},
    StatusCancelled: cancelledState{},
}

func main() {
    o := NewOrder("o-1")
    fmt.Println("start:", o.Status())
    _ = o.Pay()
    fmt.Println("after pay:", o.Status())
    _ = o.Ship()
    fmt.Println("after ship:", o.Status())
    if err := o.Cancel(); err != nil {
        fmt.Println("cancel error:", err)
    }
}

package main

import (
    "errors"
    "fmt"
)

type Status int

const (
    StatusPending Status = iota
    StatusPaid
    StatusShipped
    StatusCancelled
    StatusRefunded
)

func (s Status) String() string {
    return [...]string{"pending", "paid", "shipped", "cancelled", "refunded"}[s]
}

type OrderState interface {
    Pay(*Order) error
    Ship(*Order) error
    Cancel(*Order) error
    Refund(*Order) error
}

type Order struct {
    ID     string
    status Status
}

func NewOrder(id string) *Order { return &Order{ID: id, status: StatusPending} }
func (o *Order) Status() Status { return o.status }

func (o *Order) Pay() error    { return orderStates[o.status].Pay(o) }
func (o *Order) Ship() error   { return orderStates[o.status].Ship(o) }
func (o *Order) Cancel() error { return orderStates[o.status].Cancel(o) }
func (o *Order) Refund() error { return orderStates[o.status].Refund(o) }

type pendingState struct{}

func (pendingState) Pay(o *Order) error    { o.status = StatusPaid; return nil }
func (pendingState) Ship(*Order) error     { return errors.New("can't ship unpaid") }
func (pendingState) Cancel(o *Order) error { o.status = StatusCancelled; return nil }
func (pendingState) Refund(*Order) error   { return errors.New("nothing to refund") }

type paidState struct{}

func (paidState) Pay(*Order) error         { return errors.New("already paid") }
func (paidState) Ship(o *Order) error      { o.status = StatusShipped; return nil }
func (paidState) Cancel(o *Order) error    { o.status = StatusCancelled; return nil }
func (paidState) Refund(o *Order) error    { o.status = StatusRefunded; return nil }

type shippedState struct{}

func (shippedState) Pay(*Order) error      { return errors.New("already paid") }
func (shippedState) Ship(*Order) error     { return errors.New("already shipped") }
func (shippedState) Cancel(*Order) error   { return errors.New("can't cancel shipped") }
func (shippedState) Refund(o *Order) error { o.status = StatusRefunded; return nil }

type cancelledState struct{}

func (cancelledState) Pay(*Order) error    { return errors.New("cancelled") }
func (cancelledState) Ship(*Order) error   { return errors.New("cancelled") }
func (cancelledState) Cancel(*Order) error { return errors.New("already cancelled") }
func (cancelledState) Refund(*Order) error { return errors.New("nothing to refund") }

// The new state: terminal, rejects everything.
type refundedState struct{}

func (refundedState) Pay(*Order) error    { return errors.New("refunded") }
func (refundedState) Ship(*Order) error   { return errors.New("refunded") }
func (refundedState) Cancel(*Order) error { return errors.New("refunded") }
func (refundedState) Refund(*Order) error { return errors.New("already refunded") }

var orderStates = map[Status]OrderState{
    StatusPending:   pendingState{},
    StatusPaid:      paidState{},
    StatusShipped:   shippedState{},
    StatusCancelled: cancelledState{},
    StatusRefunded:  refundedState{},
}

func main() {
    o := NewOrder("o-1")
    _ = o.Pay()
    _ = o.Ship()
    _ = o.Refund()
    fmt.Println("final:", o.Status())
    if err := o.Refund(); err != nil {
        fmt.Println("expected error:", err)
    }
}

package main

import (
    "errors"
    "fmt"
    "time"
)

type OrderState interface {
    Enter(*Order)
    Exit(*Order)
    Start(*Order) error
    Done(*Order) error
    Name() string
}

type Order struct {
    ID        string
    state     OrderState
    procStart time.Time
    procTotal time.Duration
}

func NewOrder(id string) *Order {
    o := &Order{ID: id}
    o.transition(Pending{})
    return o
}

// transition is the single chokepoint. Exit → swap → Enter. States never
// touch the state pointer themselves; that prevents the "swap-in-the-middle"
// foot-gun listed in junior.md §9.
func (o *Order) transition(next OrderState) {
    if o.state != nil {
        o.state.Exit(o)
    }
    o.state = next
    o.state.Enter(o)
}

func (o *Order) Start() error { return o.state.Start(o) }
func (o *Order) Done() error  { return o.state.Done(o) }
func (o *Order) State() string { return o.state.Name() }

// baseState is a no-op default so individual states only override what
// they care about. Saves four lines per state.
type baseState struct{}

func (baseState) Enter(*Order)       {}
func (baseState) Exit(*Order)        {}
func (baseState) Start(*Order) error { return errors.New("can't start in this state") }
func (baseState) Done(*Order) error  { return errors.New("can't complete in this state") }

type Pending struct{ baseState }

func (Pending) Name() string             { return "pending" }
func (Pending) Start(o *Order) error     { o.transition(Processing{}); return nil }

type Processing struct{ baseState }

func (Processing) Name() string { return "processing" }
func (Processing) Enter(o *Order) {
    o.procStart = time.Now()
    fmt.Println("processing: timer started")
}
func (Processing) Exit(o *Order) {
    o.procTotal += time.Since(o.procStart)
    fmt.Printf("processing: timer stopped, total=%v\n", o.procTotal)
}
func (Processing) Done(o *Order) error { o.transition(Completed{}); return nil }

type Completed struct{ baseState }

func (Completed) Name() string { return "completed" }

func main() {
    o := NewOrder("o-1")
    fmt.Println("state:", o.State())
    _ = o.Start()
    time.Sleep(25 * time.Millisecond)
    _ = o.Done()
    fmt.Println("final state:", o.State(), "procTotal:", o.procTotal)
}

package main

import "fmt"

type stateFn func(*lexer) stateFn

type lexer struct {
    input  string
    pos    int
    fields []string
    buf    []byte
}

func newLexer(s string) *lexer { return &lexer{input: s} }

func (l *lexer) run() {
    // Senior decision: state is a function pointer, not an enum. No
    // interface dispatch, no allocation per transition. This is why the
    // stdlib lexer (text/template/parse/lex.go) is shaped like this.
    for state := lexField; state != nil; {
        state = state(l)
    }
}

func (l *lexer) flushField() {
    l.fields = append(l.fields, string(l.buf))
    l.buf = l.buf[:0]
}

func lexField(l *lexer) stateFn {
    for {
        if l.pos >= len(l.input) {
            l.flushField()
            return nil
        }
        c := l.input[l.pos]
        switch c {
        case ',':
            l.pos++
            l.flushField()
            // stay in lexField for the next field
            return lexField
        case '"':
            // Only allowed at the start of a field.
            if len(l.buf) != 0 {
                l.buf = append(l.buf, c)
                l.pos++
                continue
            }
            l.pos++
            return lexQuoted
        default:
            l.buf = append(l.buf, c)
            l.pos++
        }
    }
}

func lexQuoted(l *lexer) stateFn {
    for {
        if l.pos >= len(l.input) {
            // Unterminated quote: in production, surface an error.
            l.flushField()
            return nil
        }
        c := l.input[l.pos]
        if c == '"' {
            // Possible escape: "" inside a quoted field becomes a single ".
            if l.pos+1 < len(l.input) && l.input[l.pos+1] == '"' {
                l.buf = append(l.buf, '"')
                l.pos += 2
                continue
            }
            l.pos++ // consume closing quote
            return lexField
        }
        l.buf = append(l.buf, c)
        l.pos++
    }
}

func main() {
    cases := []string{
        `a,b,c`,
        `"hello, world",foo,bar`,
        `"she said ""hi""",done`,
        ``,
    }
    for _, in := range cases {
        l := newLexer(in)
        l.run()
        fmt.Printf("%-30q -> %q\n", in, l.fields)
    }
}

package main

import (
    "errors"
    "fmt"
)

type Transition struct {
    From, Event, To string
    Action          func(*Machine) error // nil = no side effect
}

type Machine struct {
    state string
    table []Transition
}

func NewMachine(initial string, table []Transition) *Machine {
    return &Machine{state: initial, table: table}
}

func (m *Machine) State() string { return m.state }

// ErrInvalid is returned when no row matches (state, event). Typed so
// callers can distinguish "wrong event" from "action failed".
var ErrInvalid = errors.New("invalid transition")

func (m *Machine) Send(event string) error {
    for _, t := range m.table {
        if t.From != m.state || t.Event != event {
            continue
        }
        // Senior decision: run Action FIRST. If it fails, do not swap.
        // The FSM stays in From. Document this; the alternative (swap then
        // act) requires compensation logic on Action failure.
        if t.Action != nil {
            if err := t.Action(m); err != nil {
                return fmt.Errorf("action %s->%s: %w", t.From, t.To, err)
            }
        }
        m.state = t.To
        return nil
    }
    return fmt.Errorf("%w: %s on %s", ErrInvalid, event, m.state)
}

// UnreachableStates returns states that appear in `to` columns but no
// `from` columns lead to them. Useful in CI to catch dead transitions.
func UnreachableStates(initial string, table []Transition) []string {
    reachable := map[string]bool{initial: true}
    changed := true
    for changed {
        changed = false
        for _, t := range table {
            if reachable[t.From] && !reachable[t.To] {
                reachable[t.To] = true
                changed = true
            }
        }
    }
    seen := map[string]bool{}
    for _, t := range table {
        seen[t.From] = true
        seen[t.To] = true
    }
    var dead []string
    for s := range seen {
        if !reachable[s] {
            dead = append(dead, s)
        }
    }
    return dead
}

func logAction(label string) func(*Machine) error {
    return func(m *Machine) error {
        fmt.Printf("[action] %s (state=%s)\n", label, m.state)
        return nil
    }
}

var orderFSM = []Transition{
    {"pending", "pay", "paid", logAction("charge card")},
    {"pending", "cancel", "cancelled", nil},
    {"paid", "ship", "shipped", logAction("notify warehouse")},
    {"paid", "cancel", "cancelled", logAction("issue refund")},
    {"paid", "refund", "refunded", logAction("issue refund")},
    {"shipped", "refund", "refunded", logAction("issue refund")},
}

func main() {
    m := NewMachine("pending", orderFSM)
    for _, ev := range []string{"pay", "ship", "refund", "pay"} {
        if err := m.Send(ev); err != nil {
            fmt.Println("err:", err)
            continue
        }
        fmt.Println("state:", m.State())
    }
    fmt.Println("unreachable:", UnreachableStates("pending", orderFSM))
}

package main

import (
    "errors"
    "fmt"
)

var (
    ErrGuard   = errors.New("guard failed")
    ErrAction  = errors.New("action failed")
    ErrInvalid = errors.New("invalid transition")
)

type Order struct {
    state  string
    Amount int
    Paid   bool
}

type Transition struct {
    From, Event, To string
    Guard           func(*Order) error
    Action          func(*Order) error
}

type Machine struct {
    o     *Order
    table []Transition
}

func NewMachine(o *Order, table []Transition) *Machine {
    return &Machine{o: o, table: table}
}

func (m *Machine) State() string { return m.o.state }

func (m *Machine) Send(event string) error {
    for _, t := range m.table {
        if t.From != m.o.state || t.Event != event {
            continue
        }
        if t.Guard != nil {
            if err := t.Guard(m.o); err != nil {
                // Wrapped so errors.Is(err, ErrGuard) works.
                return fmt.Errorf("%w: %v", ErrGuard, err)
            }
        }
        if t.Action != nil {
            if err := t.Action(m.o); err != nil {
                return fmt.Errorf("%w: %v", ErrAction, err)
            }
        }
        m.o.state = t.To
        return nil
    }
    return fmt.Errorf("%w: %s on %s", ErrInvalid, event, m.o.state)
}

// Fake credit-card charge. In real life this is an HTTP call.
// We make it fail when Amount > 10_000 to demonstrate the Action branch.
func fakeCharge(o *Order) error {
    if o.Amount > 10_000 {
        return errors.New("card declined")
    }
    o.Paid = true
    return nil
}

func mustHavePositiveAmount(o *Order) error {
    if o.Amount <= 0 {
        return fmt.Errorf("amount must be > 0, got %d", o.Amount)
    }
    return nil
}

var orderFSM = []Transition{
    {"pending", "pay", "paid", mustHavePositiveAmount, fakeCharge},
    {"paid", "ship", "shipped", nil, nil},
}

func main() {
    // Case 1: guard fails (amount = 0).
    o1 := &Order{state: "pending", Amount: 0}
    m1 := NewMachine(o1, orderFSM)
    err := m1.Send("pay")
    fmt.Println("amount=0:", err, "is-guard:", errors.Is(err, ErrGuard))
    fmt.Println("state unchanged:", o1.state)

    // Case 2: action fails (amount too large).
    o2 := &Order{state: "pending", Amount: 100_000}
    m2 := NewMachine(o2, orderFSM)
    err = m2.Send("pay")
    fmt.Println("amount huge:", err, "is-action:", errors.Is(err, ErrAction))
    fmt.Println("state unchanged:", o2.state)

    // Case 3: happy path.
    o3 := &Order{state: "pending", Amount: 500}
    m3 := NewMachine(o3, orderFSM)
    if err := m3.Send("pay"); err != nil {
        fmt.Println("unexpected:", err)
    }
    fmt.Println("happy path state:", o3.state, "paid:", o3.Paid)
}