Applications sometimes find themselves managing process flows. These process flows consist of states and inputs that move the process along from one state to another.

For instance, consider a user registration process. When the application creates a new user, that user may start off in a UNVERIFIED state. When the application verifies the user's email address, the user may move to a VERIFIED state. On the other hand, if sufficient time passes and the user is still in the UNVERIFIED state, the application may choose to move the user to a EXPIRED state.

Applications with such needs often end up implementing a state machine to manage the process flow. This service aims to save applications from that implementation effort.

Using this service such applications need only define the state machine that reflects the process flow and then tell the service each time a input is made to the process. The service will take care of properly transitioning to the next state in the flow and return that state to the application. The application may also, at any time, ask the service for the current state of a state machine it created. Furthermore, applications may store arbitrary data along with each state.

The service is currently provided as a REST API.

URIs in the rest of this document start with {baseuri}. This is a placeholder that should be replaced with one of the URIs below, depending on the environment:

POST {baseuri}/v1/state-machines

{
  "initialState": "foo",
  "states": {
    "foo": {
      "transitions": [
        { "match": "1|2|[a-bA-B]","nextState": "bar" },
        { "match": "3","nextState": "baz" }
      ]
    },
    "bar": {
      "data": "data for state bar",
      "transitions": []
    },
    "baz": {
      "data": "data for state baz"
    }
  }
}

201 Created
Location: {baseuri}/v1/state-machine/2345

{
  "meta": {
    "links": {
      "self": "{baseuri}/v1/state-machine/2345"
    }
  }
}

GET {baseuri}/v1/state-machine/2345/current-state

303 See Other
Location: {baseuri}/v1/state-machine/2345/state/1

200 OK

{
  "meta": {
    "links": {
      "self": "{baseuri}/v1/state-machine/2345/state/1",
      "state-machine": "{baseuri}/v1/state-machine/2345"
    }
  },
  "state": {
    "name": "foo"
  }
}

POST {baseuri}/v1/state-machine/2345/input

{
  "input": "2"
}

303 See Other
Location: {baseuri}/v1/state-machine/2345/state/3

200 OK

{
  "links": {
    "self": "{baseuri}/v1/state-machine/2345/state/3",
    "state-machine": "{baseuri}/v1/state-machine/2345"
  },
  "state": {
    "name": "baz",
    "data": "data for state baz"
  }
}

1. Download and install Node.js.

2. Download, install and start PostgreSQL server.

3. Clone this repository to a folder on your computer. The rest of this document will refer to this folder as $PROJECT_ROOT.

4. Install project dependencies.

   cd $PROJECT_ROOT npm install

5. Create the database user. When prompted, enter the password as defined in the config/default.js file.

   createuser statemachine -P

6. Create the database and make the just-created user its owner.

   createdb statemachine -O statemachine

7. Create the database schema.

   node bin/update_db_schema.js

1. Update the project dependencies.

   cd $PROJECT_ROOT npm install

2. Update the database schema.

   node bin/update_db_schema.js

1. Start the REST API server.

   cd $PROJECT_ROOT node restapi/server.js

• Ability to specify input matchers in forms other than regular expressions.
• Language bindings in Node.js, Python and Ruby.
• TCP socket protocol as alternative to REST.