Part 3 of 12 · 1 min read
The job is a small state machine
Legal moves only, so a client can never see or cause an impossible state.
Think of a parcel tracking page: dispatched, in transit, delivered. It never jumps from "dispatched" straight to "delivered" without passing through the states between, and once it says "delivered" it never changes again.
In plain words: a job moves through a fixed list of states, only in the directions the code allows, and a finished job never moves again.
queued -> running -> succeeded
-> failed
queued -> cancelled
The key lines. The server checks every move against this map before making it:
# from code/mini-jobapi/jobapi.py
def _move(self, j, to, now):
if to not in ALLOWED.get(j.state, ()):
raise ValueError(f"illegal transition {j.state}->{to}")
j.state = to
Read it as: before changing state, look up what moves are legal from here. If the requested move is not in that list, refuse it. This is what stops a "succeeded" job from being quietly moved back to "running."
Terminal state
A state a job cannot leave: succeeded, failed or cancelled.
Example: calling cancel on an already-succeeded job does not error; the code checks j.state in TERMINAL and returns 200 without changing anything, because cancelling something already done is harmless.