0001. Per-State Event Handling
Author: David Sutton
<davidsutton@ausocean.org>
Date: 2026-06-04
Context
OceanTV uses state machines (broadcast and hardware state machines) to manage the lifecycle of a broadcast. Event management was previously handled centrally via a handleEvent function that dispatched to typed handler methods for each event type. Each event specific handler than used a type switch on the current state of the state machine to determine transitions.
This approach had several drawbacks:
- Readability Due to the increasing number of events and states as the broadcast manager matured the event handling became a very large file, with many event handler functions all in one place. This made it difficult to trace behaviour of a state, as its transitions were spread over multiple event handler methods.
- Scalability concerns: As new states and events were added, the central switch statements grew linearly, increasing the risk of accidental omission or incorrect handling.
Decision
We will refactor event handling from a state-machine-centralised pattern to a per-state pattern, guided by the following design:
Introduce a
stateWithEventHandlerinterface that states can optionally implement:gotype stateWithEventHandler interface { handleEvent(sm *broadcastStateMachine, event event) }Modify
broadcastStateMachine.handleEventto check whether the current state implements this interface. If it does, the event is delegated to the state; otherwise, the old centralised handling is used as a fallback.Migrate states incrementally: Each state is converted one at a time by adding a
handleEventmethod that encapsulates all events that state can receive and the corresponding transitions. This allows the refactor to proceed as a series of small, reviewable changes.Remove migrated event branches from the centralised handler methods once all states are converted.
Consequences
Positive
- Localised reasoning: All event handling for a state is in one place, making it easy to enumerate every incoming event and outgoing transition.
- Incremental adoption: The interface+fallback mechanism allows piecemeal conversion without a big-bang rewrite.
- Clearer diffs: State changes are confined to the state's own file, reducing noise in the state machine file.
- Easier onboarding: New developers can understand a state's behaviour by reading a single file.
Negative
- Duplicated patterns: Shared event handling logic (e.g., timeout behaviour across "starting" states) may be duplicated rather than centralised.
- Increased boilerplate: Each state requires a
handleEventmethod even if it only handles one or two events. - State coupling: States now reference other states directly in their
handleEventmethods (to callsm.transition), whereas the centralised handler kept transition knowledge in the state machine.
Future Work
- Convert the remaining broadcast states to the per-state pattern.
- Consider whether
stateWithEventHandlershould be promoted to the basestateinterface once all states have been converted. - Evaluate whether a
stateMachineCtxerinterface would allow this pattern to be shared with the hardware state machine.