Designing lifecycles as state machines

Designing a lifecycle as a state machine means deciding, before writing code, every state an object can be in, every event that moves it, who sends each event, and what the object does when an event comes twice or never comes at all. Those last two cases are where many lifecycle bugs come from: a payment callback delivered twice, a seat hold that nobody confirms, a timer that fires after the customer has already paid. A good design answers each one with an explicit transition, writes every move into a history, and treats a resent request as a question already answered. This lesson finds the states and events of a cinema seat hold from its requirements, then runs the design against a clock that the code is given, so a test moves time instead of waiting for it.

Four questions that find the events

Requirements usually describe the happy path: a customer picks up to six seats, which are held for 8 minutes while they pay, and a successful payment confirms them. To find the rest of the lifecycle, ask four questions of every state. For a held seat, the answers are the design:

1. What can happen next? List every event the state might receive, wanted or not. Here the payment succeeds or fails, the customer cancels, or the time runs out, so four events leave held.
2. Who sends it? A person, another system or the clock. Here the payment provider, the customer and the clock all send events, and those from systems and the clock arrive at awkward moments.
3. What if it happens twice? Networks resend, people double-click and payment providers retry their callbacks. Here a resent success must not confirm the seats or charge the customer again.
4. What if it never happens? Then something else must end the state, usually a deadline. Here the customer walks away, so after 8 minutes the hold expires and the seats go back on sale.

The fourth question is the easiest to miss, because nobody types that event: the deadline belongs to the hold itself, and the clock delivers it.

A seat hold, run against a clock it is given

The hold below never reads the computer’s clock. It receives a clock object with a now() method, so the script can move time to any second it likes. The hold stores its deadline as an absolute time, and every event checks the deadline before anything else, because the scheduler that should expire the hold may run late or not at all.

"""A cinema seat hold: held for 8 minutes while the customer pays, then confirmed, released or
expired. The hold reads the time only from the clock it is given, so this script moves a fake
clock instead of waiting."""

HOLD_SECONDS = 8 * 60


class FakeClock:
    """A clock that the caller moves by hand. now() counts seconds from the start of the run."""

    def __init__(self):
        self.seconds = 0

    def now(self):
        return self.seconds

    def move_to(self, minutes, seconds=0):
        self.seconds = minutes * 60 + seconds


class Refused(Exception):
    """An event that the hold's current state does not accept."""


class SeatHold:
    def __init__(self, seats, clock):
        self.seats = seats
        self.clock = clock
        self.state = "held"
        self.expires_at = clock.now() + HOLD_SECONDS
        self.trail = [(clock.now(), "held", "customer")]

    def _move(self, to, actor):
        self.state = to
        self.trail.append((self.clock.now(), to, actor))

    def tick(self):
        """The clock's event: a scheduler calls it, and a hold past its deadline expires."""
        if self.state == "held" and self.clock.now() >= self.expires_at:
            self._move("expired", "clock")

    def confirm(self, payment_id):
        """The payment provider's event: the customer has paid."""
        self.tick()  # no event may act on a hold that should already have expired
        if self.state != "held":
            raise Refused(f"confirm({payment_id}) refused: the hold is {self.state}")
        self._move("confirmed", f"payment {payment_id}")

    def release(self, actor):
        """The customer's event, or a failed payment's: the seats go back on sale."""
        self.tick()
        if self.state != "held":
            raise Refused(f"release refused: the hold is {self.state}")
        self._move("released", actor)


def clock_text(seconds):
    return f"{seconds // 60}:{seconds % 60:02d}"


def show(title, hold, notes=()):
    print(title)
    for at, state, actor in hold.trail:
        print(f"  {clock_text(at)}  {state:<10} by {actor}")
    for note in notes:
        print(f"  {note}")


def run(title, steps):
    """steps: (minutes, seconds, action) in time order, with action one of the hold's events."""
    clock = FakeClock()
    hold = SeatHold(["F7", "F8"], clock)
    notes = []
    for minutes, seconds, action in steps:
        clock.move_to(minutes, seconds)
        try:
            action(hold)
        except Refused as refusal:
            notes.append(f"{clock_text(clock.now())}  {refusal}")
    show(title, hold, notes)


run("1. Paid with a second to spare", [(7, 59, lambda h: h.confirm("P-1"))])
run("2. Nobody pays: the scheduler ticks at 7:59 and at 8:00",
    [(7, 59, SeatHold.tick), (8, 0, SeatHold.tick)])
run("3. The customer gives up", [(2, 30, lambda h: h.release("customer"))])
run("4. The provider sends the same success twice",
    [(3, 10, lambda h: h.confirm("P-4")), (3, 50, lambda h: h.confirm("P-4"))])
run("5. A success that arrives after the deadline", [(8, 5, lambda h: h.confirm("P-5"))])

1. Paid with a second to spare
  0:00  held       by customer
  7:59  confirmed  by payment P-1
2. Nobody pays: the scheduler ticks at 7:59 and at 8:00
  0:00  held       by customer
  8:00  expired    by clock
3. The customer gives up
  0:00  held       by customer
  2:30  released   by customer
4. The provider sends the same success twice
  0:00  held       by customer
  3:10  confirmed  by payment P-4
  3:50  confirm(P-4) refused: the hold is confirmed
5. A success that arrives after the deadline
  0:00  held       by customer
  8:05  expired    by clock
  8:05  confirm(P-5) refused: the hold is expired

Runs 1 to 3 are the expected paths, and run 2 checks the boundary: at 7:59 the hold is still held, and at exactly 8:00 it expires. The last two runs show what the four questions predicted. In run 4 the provider resent a success that had already confirmed the seats, and the design answered with an error, so the provider is told that a payment it completed has failed. In run 5 no scheduler tick came at 8:00, so the late success itself found the hold past its deadline, expired it and was refused, and the customer has paid for seats they do not have. Both are refusals of real events, and both need more design, not more if statements.

What a complete lifecycle design adds

Five techniques turn this sketch into a design that holds up in production, and each one answers a failure above:

• An append-only transition history records every move with its time, its actor and a reason; the current state is the last entry.
• Idempotent transitions answer a resent request id with the result it got the first time, instead of an error or a second effect.
• Conflict detection refuses a known request id that arrives with a different event, because that is a client bug, not a retry.
• Timeout policies decide, as a business rule, what happens to an event that arrives just after a deadline.
• Compensating transitions undo a reservation on purpose, with a reason, when a later step fails.

Recording every transition, and retries that change nothing Pro: opens with a Pro, Premium or Ultimate pass

Timeouts, late events and compensation, tested without sleeping Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• Ask four questions of every state: what can happen next, who sends it, what if it happens twice, and what if it never happens.
• The clock is an event source. Store each deadline with its object and check it on every event, so that tests move time instead of waiting.
• An event that arrives twice or late is an ordinary input, and the design, not chance, decides what it does.