About

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.

Teams usually handle that one of two ways. Some keep a status column and write retry code by hand, which works until the day two edge cases meet. Others adopt a workflow platform, which works too, but brings a server, a database and a second system to run, upgrade and watch, often bigger than the program it serves.

FlowChassis is the piece in between. It is a library. The only thing it adds to your deployment is a file.

What It Does

  • State transitions. A flow is a list of named steps. A run moves from one to the next, or to one a step chooses.
  • Checkpoints. Before a step runs and after it succeeds, a record goes to the journal and is flushed to disk. Records written at the same moment share one flush.
  • Retries. A failed step is tried again after a wait that grows each time, up to a limit you set. The wait is in the journal, so a restart doesn’t cut it short.
  • Compensation. When a run can’t finish, every completed step’s undo runs, newest first. Each undo sees the state exactly as its own step left it.
  • Resume. After a crash the engine reads the journal and carries on. A step that was under way runs again; finished steps don’t.
  • Inspection. The flowchassis command lists runs, shows any run’s full history, checks a journal record by record, and compacts it.

What it leaves out is on purpose: no graphical designer, no dashboard, no server, no cluster. Those are products of their own, and they can sit on top of a kernel like this one.

How It Is Built and Tested

The code is in flowchassis/flowchassis on GitHub, with no dependencies outside the Go standard library. Its README is the manual. The repository also holds the contract, which says exactly what the engine promises, and the journal format.

Most of the testing kills things: worker processes killed with SIGKILL hundreds of times mid-flow, journals cut at every byte of their last record, disks that fill up during a run. The tests run on Linux, macOS and Windows on every change, and every release is built and checked on each of those systems before it goes out. How it was tested has the details, and every number on this site comes from the recorded results in the repository.

Where It Stands

Version 0.1.0 is the first release. The engine, the journal, the command-line tool and the tests are in place. It runs in one process per journal on one machine, and steps run at least once, so a step that calls an outside service should pass the idempotency key the engine gives it.

Questions, ideas and reports are welcome on the contact page.