fsm: add fsm module

This commit adds a module for a finite state machine. The goal of the
module is to provide a simple, easy to use, and easy to understand
finite state machine. The module is designed to be used in future
loop subsystems. Additionally a state visualizer is provided to
help with understanding the state machine.

Author: sputn1ck

.golangci.yml

@@ -133,5 +133,10 @@ issues:
 
       # Allow fmt.Printf() in loop
       - path: cmd/loop/*
+        linters:
+          - forbidigo
+
+      # Allow fmt.Printf() in stateparser
+      - path: fsm/stateparser/*
         linters:
           - forbidigo

Makefile

@@ -134,4 +134,7 @@ sqlc-check: sqlc
 	@$(call print, "Verifying sql code generation.")
 	if test -n "$$(git status --porcelain '*.go')"; then echo "SQL models not properly generated!"; git status --porcelain '*.go'; exit 1; fi
 
-
+fsm:
+	@$(call print, "Generating state machine docs")
+	./scripts/fsm-generate.sh;
+.PHONY: fsm

fsm/example_fsm.go

@@ -0,0 +1,129 @@
+package fsm
+
+import (
+	"fmt"
+)
+
+// ExampleService is an example service that we want to wait for in the FSM.
+type ExampleService interface {
+	WaitForStuffHappening() (<-chan bool, error)
+}
+
+// ExampleStore is an example store that we want to use in our exitFunc.
+type ExampleStore interface {
+	StoreStuff() error
+}
+
+// ExampleFSM implements the FSM and uses the ExampleService and ExampleStore
+// to implement the actions.
+type ExampleFSM struct {
+	*StateMachine
+
+	service ExampleService
+	store   ExampleStore
+}
+
+// NewExampleFSMContext creates a new example FSM context.
+func NewExampleFSMContext(service ExampleService,
+	store ExampleStore) *ExampleFSM {
+
+	exampleFSM := &ExampleFSM{
+		service: service,
+		store:   store,
+	}
+	exampleFSM.StateMachine = NewStateMachine(exampleFSM.GetStates())
+
+	return exampleFSM
+}
+
+// States.
+const (
+	InitFSM         = StateType("InitFSM")
+	StuffSentOut    = StateType("StuffSentOut")
+	WaitingForStuff = StateType("WaitingForStuff")
+	StuffFailed     = StateType("StuffFailed")
+	StuffSuccess    = StateType("StuffSuccess")
+)
+
+// Events.
+var (
+	OnRequestStuff = EventType("OnRequestStuff")
+	OnStuffSentOut = EventType("OnStuffSentOut")
+	OnStuffSuccess = EventType("OnStuffSuccess")
+)
+
+// GetStates returns the states for the example FSM.
+func (e *ExampleFSM) GetStates() States {
+	return States{
+		Default: State{
+			Transitions: Transitions{
+				OnRequestStuff: InitFSM,
+			},
+		},
+		InitFSM: State{
+			Action: e.initFSM,
+			Transitions: Transitions{
+				OnStuffSentOut: StuffSentOut,
+				OnError:        StuffFailed,
+			},
+		},
+		StuffSentOut: State{
+			Action: e.waitForStuff,
+			Transitions: Transitions{
+				OnStuffSuccess: StuffSuccess,
+				OnError:        StuffFailed,
+			},
+		},
+
+		StuffFailed: State{
+			Action: NoOpAction,
+		},
+
+		StuffSuccess: State{
+			Action: NoOpAction,
+		},
+	}
+}
+
+// InitStuffRequest is the event context for the InitFSM state.
+type InitStuffRequest struct {
+	Stuff       string
+	respondChan chan<- string
+}
+
+// initFSM is the action for the InitFSM state.
+func (e *ExampleFSM) initFSM(eventCtx EventContext) EventType {
+	req, ok := eventCtx.(*InitStuffRequest)
+	if !ok {
+		return e.HandleError(
+			fmt.Errorf("invalid event context type: %T", eventCtx),
+		)
+	}
+
+	err := e.store.StoreStuff()
+	if err != nil {
+		return e.HandleError(err)
+	}
+
+	req.respondChan <- req.Stuff
+
+	return OnStuffSentOut
+}
+
+// waitForStuff is an action that waits for stuff to happen.
+func (e *ExampleFSM) waitForStuff(eventCtx EventContext) EventType {
+	waitChan, err := e.service.WaitForStuffHappening()
+	if err != nil {
+		return e.HandleError(err)
+	}
+
+	go func() {
+		<-waitChan
+		err := e.SendEvent(OnStuffSuccess, nil)
+		if err != nil {
+			log.Errorf("unable to send event: %v", err)
+		}
+	}()
+
+	return NoOp
+}

fsm/example_fsm.md

@@ -0,0 +1,12 @@
+```mermaid
+stateDiagram-v2
+[*] --> InitFSM: OnRequestStuff
+InitFSM
+InitFSM --> StuffFailed: OnError
+InitFSM --> StuffSentOut: OnStuffSentOut
+StuffFailed
+StuffSentOut
+StuffSentOut --> StuffFailed: OnError
+StuffSentOut --> StuffSuccess: OnStuffSuccess
+StuffSuccess
+```

fsm/example_fsm_test.go

@@ -0,0 +1,218 @@
+package fsm
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+type mockStore struct {
+	storeErr error
+}
+
+func (m *mockStore) StoreStuff() error {
+	return m.storeErr
+}
+
+type mockService struct {
+	respondChan chan bool
+	respondErr  error
+}
+
+func (m *mockService) WaitForStuffHappening() (<-chan bool, error) {
+	return m.respondChan, m.respondErr
+}
+
+func newInitStuffRequest() *InitStuffRequest {
+	return &InitStuffRequest{
+		Stuff:       "stuff",
+		respondChan: make(chan<- string, 1),
+	}
+}
+
+func TestExampleFSM(t *testing.T) {
+	testCases := []struct {
+		name                    string
+		expectedState           StateType
+		eventCtx                EventContext
+		expectedLastActionError error
+
+		sendEvent    EventType
+		sendEventErr error
+
+		serviceErr error
+		storeErr   error
+	}{
+		{
+			name:          "success",
+			expectedState: StuffSuccess,
+			eventCtx:      newInitStuffRequest(),
+			sendEvent:     OnRequestStuff,
+		},
+		{
+			name:                    "service error",
+			expectedState:           StuffFailed,
+			eventCtx:                newInitStuffRequest(),
+			sendEvent:               OnRequestStuff,
+			serviceErr:              fmt.Errorf("service error"),
+			expectedLastActionError: errors.New("service error"),
+		},
+		{
+			name:                    "store error",
+			expectedLastActionError: errors.New("store error"),
+			storeErr:                errors.New("store error"),
+			sendEvent:               OnRequestStuff,
+			expectedState:           StuffFailed,
+			eventCtx:                newInitStuffRequest(),
+		},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+
+		t.Run(tc.name, func(t *testing.T) {
+			respondChan := make(chan string, 1)
+			if req, ok := tc.eventCtx.(*InitStuffRequest); ok {
+				req.respondChan = respondChan
+			}
+
+			serviceRespondChan := make(chan bool, 1)
+			serviceRespondChan <- true
+
+			service := &mockService{
+				respondChan: serviceRespondChan,
+				respondErr:  tc.serviceErr,
+			}
+
+			store := &mockStore{
+				storeErr: tc.storeErr,
+			}
+
+			exampleContext := NewExampleFSMContext(service, store)
+			cachedObserver := NewCachedObserver()
+
+			exampleContext.RegisterObserver(cachedObserver)
+
+			err := exampleContext.SendEvent(tc.sendEvent, tc.eventCtx)
+			require.Equal(t, tc.sendEventErr, err)
+
+			require.Equal(t, tc.expectedLastActionError,
+				exampleContext.LastActionError)
+
+			err = cachedObserver.WaitForState(context.Background(),
+				time.Second, tc.expectedState)
+			require.NoError(t, err)
+		})
+	}
+}
+
+// getTestContext returns a test context for the example FSM and a cached
+// observer that can be used to verify the state transitions.
+func getTestContext() (*ExampleFSM, *CachedObserver) {
+	service := &mockService{
+		respondChan: make(chan bool, 1),
+	}
+	service.respondChan <- true
+
+	store := &mockStore{}
+
+	exampleContext := NewExampleFSMContext(service, store)
+	cachedObserver := NewCachedObserver()
+
+	exampleContext.RegisterObserver(cachedObserver)
+
+	return exampleContext, cachedObserver
+}
+
+// TestExampleFSMFlow tests different flows that the example FSM can go through.
+func TestExampleFSMFlow(t *testing.T) {
+	testCases := []struct {
+		name              string
+		expectedStateFlow []StateType
+		expectedEventFlow []EventType
+		storeError        error
+		serviceError      error
+	}{
+		{
+			name: "success",
+			expectedStateFlow: []StateType{
+				InitFSM,
+				StuffSentOut,
+				StuffSuccess,
+			},
+			expectedEventFlow: []EventType{
+				OnRequestStuff,
+				OnStuffSentOut,
+				OnStuffSuccess,
+			},
+		},
+		{
+			name: "failure on store",
+			expectedStateFlow: []StateType{
+				InitFSM,
+				StuffFailed,
+			},
+			expectedEventFlow: []EventType{
+				OnRequestStuff,
+				OnError,
+			},
+			storeError: errors.New("store error"),
+		},
+		{
+			name: "failure on service",
+			expectedStateFlow: []StateType{
+				InitFSM,
+				StuffSentOut,
+				StuffFailed,
+			},
+			expectedEventFlow: []EventType{
+				OnRequestStuff,
+				OnStuffSentOut,
+				OnError,
+			},
+			serviceError: errors.New("service error"),
+		},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+
+		t.Run(tc.name, func(t *testing.T) {
+			exampleContext, cachedObserver := getTestContext()
+
+			if tc.storeError != nil {
+				exampleContext.store.(*mockStore).storeErr = tc.storeError
+			}
+
+			if tc.serviceError != nil {
+				exampleContext.service.(*mockService).
+					respondErr = tc.serviceError
+			}
+
+			go func() {
+				err := exampleContext.SendEvent(OnRequestStuff,
+					newInitStuffRequest())
+
+				require.NoError(t, err)
+			}()
+
+			// Wait for the final state.
+			err := cachedObserver.WaitForState(context.Background(),
+				time.Second, tc.expectedStateFlow[len(tc.expectedStateFlow)-1])
+			require.NoError(t, err)
+
+			allNotifications := cachedObserver.GetCachedNotifications()
+
+			for index, notification := range allNotifications {
+				require.Equal(t, tc.expectedStateFlow[index],
+					notification.NextState)
+				require.Equal(t, tc.expectedEventFlow[index],
+					notification.Event)
+			}
+		})
+	}
+}