Pages on FlowChassis.com

About

Mon, 01 Jan 0001 00:00:00 +0000

FlowChassis is a small workflow execution kernel for Go. It runs the steps of a workflow inside your own program, writes down where each run is before and after every step, retries what fails, undoes what can’t finish, and picks every run back up after a crash. It is open source under the Apache License 2.0, and it is a SoftDevStudio.com project.

Why the Project Exists

Plenty of programs do work in steps that must all happen or be put right. An order reserves stock, charges a card and books a courier. A sign-up creates an account, provisions a mailbox and sends a welcome. A device update downloads, verifies, flashes and reboots. Somewhere in the middle, sooner or later, the process dies.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Teams building FlowChassis into their own software, or thinking about it.
Engineers with a failure case the tests should cover, or a platform where it misbehaves.
Anyone with a question about the engine, the journal or the figures on this site.

Write to info@flowchassis.com.

If you are writing about a problem, it helps to include the output of flowchassis version, your operating system, and what flowchassis check says about the journal. flowchassis show JOURNAL RUN prints the history of the run in question.

Download FlowChassis

Mon, 01 Jan 0001 00:00:00 +0000

FlowChassis is a Go library. To use it in a program, add the module:

go get github.com/flowchassis/flowchassis@latest

It needs Go 1.24 or later and nothing else. The quick start has a first flow.

The Command-Line Tool

The flowchassis command lists the runs in a journal, shows any run’s history, checks a journal record by record, compacts it, and runs the crash demo. Each archive below holds the binary with the license files and the README. The links always point to the latest release.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

This page takes you from nothing to a flow that survives being killed. You need Go 1.24 or later.

1. Add the Module

mkdir orders && cd orders
go mod init example.com/orders
go get github.com/flowchassis/flowchassis@latest

2. Write a Flow

A flow is a name and a list of steps. Each step has a Do, and can have an Undo that reverses it. Save this as main.go:

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/flowchassis/flowchassis"
)

func main() {
	e, err := flowchassis.Open("orders.journal", flowchassis.Options{})
	if err != nil {
		log.Fatal(err)
	}
	defer e.Close()

	slow := func(c *flowchassis.Ctx) error {
		time.Sleep(2 * time.Second) // time to press Ctrl-C
		return nil
	}

	err = e.Register(flowchassis.Flow{Name: "order", Steps: []flowchassis.Step{
		{
			Name: "reserve",
			Do: func(c *flowchassis.Ctx) error {
				fmt.Println("reserve stock, attempt", c.Attempt)
				c.Set("reservation", []byte("R-1001"))
				return slow(c)
			},
			Undo: func(c *flowchassis.Ctx) error {
				r, _ := c.Get("reservation")
				fmt.Println("release reservation", string(r))
				return nil
			},
		},
		{
			Name: "charge",
			Do: func(c *flowchassis.Ctx) error {
				fmt.Println("charge card with idempotency key", c.Key, "attempt", c.Attempt)
				return slow(c)
			},
			Undo: func(c *flowchassis.Ctx) error {
				fmt.Println("refund with idempotency key", c.Key)
				return nil
			},
		},
		{
			Name: "ship",
			Do: func(c *flowchassis.Ctx) error {
				if len(os.Args) > 1 && os.Args[1] == "refuse" {
					return flowchassis.Permanent(errors.New("carrier refused the address"))
				}
				fmt.Println("ship")
				return slow(c)
			},
		},
	}})
	if err != nil {
		log.Fatal(err)
	}

	id, err := e.Start("order", "order-1001", []byte(`{"sku":"A-42"}`))
	if err != nil {
		log.Fatal(err)
	}
	run, err := e.Wait(context.Background(), id)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("order-1001 is", run.Status)
}

3. Run It, and Kill It

go run .

While it prints charge card, press Ctrl-C. Then run it again:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Everything FlowChassis 0.1.0 offers, in one page. The package documentation is on pkg.go.dev, and the exact rules are in the contract.

The Engine

Call	What it does
`Open(path, Options)`	Opens or creates the journal file and locks it against other processes
`New(store, Options)`	The same over any `Store`. `NewMemStore` keeps the journal in memory, for tests
`Register(Flow)`	Adds a flow. Runs of it already in the journal start or resume
`Start(flow, id, input)`	Starts a run. An empty id gets a random one. The same id with the same flow and input returns the existing run; with anything else, `ErrConflict`
`Wait(ctx, id)`	Blocks until the run finishes, and returns it
`Get(id)`	One run, as a `RunInfo`
`List()`	Every run, in the order they started
`Cancel(id)`	Stops a run and undoes its completed steps
`Compact(before)`	Rewrites the journal with one record per run, leaving out runs that finished before `before`
`Close()`	Stops the engine. A step interrupted by `Close` runs again on the next open
`Err()`	Why the engine stopped, if a journal write failed

Options has three fields: Workers, the number of runs that execute at once (default 4); Retry, the policy for steps that don’t set one; and Now, a clock for tests.