statemachine

Overview ¶

Package statemachine provides a simple routing state machine implementation. This is useful for implementing complex state machines that require routing logic. The state machine is implemented as a series of state functions that take a Request objects and Request object. The Request returned has the next State to execute or an error. An error causes the state machine to stop and return the error. A nil state causes the state machine to stop.

You may build a state machine using either function calls or method calls. The Request.Data object you define can be a stack or heap allocated object. Using a stack allocated object is useful when running a lot of state machines in parallel, as it reduces the amount of memory allocation and garbage collection required.

State machines of this design can reduce testing complexity and improve code readability. You can read about how here: https://medium.com/@johnsiilver/go-state-machine-patterns-3b667f345b5e

This package is has OTEL support built in. If the Context passed to the state machine has a span, the state machine will create a child span for each state. If the state machine returns an error, the span will be marked as an error.

For complex state machines where you want to leverage concurrent and parallel processing, you may want to use the stagedpipe package at: https://pkg.go.dev/github.com/gostdlib/concurrency/pipelines/stagedpipe

Example:

	package main

	import (
		"context"
		"fmt"
		"io"
		"log"
		"net/http"

		"github.com/gostdlib/ops/statemachine"
	)

	var (
		author = flag.String("author", "", "The author of the quote, if not set will choose a random one")
	)

	// Data is the data passed to through the state machine. It can be modified by the state functions.
	type Data struct {
		// This section is data set before starting the state machine.

		// Author is the author of the quote. If not set it will be chosen at random.
		Author string

		// This section is data set during the state machine.

		// Quote is a quote from the author. It is set in the state machine.
		Quote string

		// httpClient is the http client used to make requests.
		httpClient *http.Client
	}

	func Start(req statemachine.Request[Data]) statemachine.Request[Data] {
		if req.Data.httpClient == nil {
			req.Data.httpClient = &http.Client{}
		}

		if req.Data.Author == "" {
			req.Next = RandomAuthor
			return req
		}
		req.Next = RandomQuote
		return req
	}

	func RandomAuthor(req statemachine.Request[Data]) statemachine.Request[Data] {
		const url = "https://api.quotable.io/randomAuthor" // This is a fake URL
		req, err := http.NewRequest("GET", url, nil)
		if err != nil {
			req.Err = err
			return req
		}

		req = req.WithContext(ctx)
		resp, err := args.Data.httpClient.Do(req)
		if err != nil {
			req.Err = err
			return req
		}
		defer resp.Body.Close()

		if resp.StatusCode != http.StatusOK {
			req.Err = fmt.Errorf("unexpected status code: %d", resp.StatusCode)
			return req
		}
		b, err := io.ReadAll(resp.Body)
		if err != nil {
			req.Err = err
			return req
		}
		args.Data.Author = string(b)
		req.Next = RandomQuote
		return req
	}

	func RandomQuote(req statemachine.Request[Data]) statemachine.Request[Data] {
		const url = "https://api.quotable.io/randomQuote" // This is a fake URL
		req, err := http.NewRequest("GET", url, nil)
		if err != nil {
			req.Err = err
			return req
		}

		req = req.WithContext(ctx)
		resp, err := args.Data.httpClient.Do(req)
		if err != nil {
			req.Err = err
			return req
		}
		defer resp.Body.Close()

		if resp.StatusCode != http.StatusOK {
			req.Err = fmt.Errorf("unexpected status code: %d", resp.StatusCode)
			return req
		}
		b, err := io.ReadAll(resp.Body)
		if err != nil {
			req.Err = err
			return req
		}
		args.Data.Quote = string(b)
		req.Next = nil  // This is not needed, but a good way to show that the state machine is done.
		return req
	}

	func main() {
		flag.Parse()

		req := statemachine.Request{
  			Ctx: context.Background(),
     			Data: Data{
				Author: *author,
				httpClient: &http.Client{},
			},
   			Next: Start,
		}

		err := statemachine.Run("Get author quotes", req)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(data.Author, "said", data.Quote)
	}