Getting Started
=====

Supported distros
-----------------

Bonsai is packaged for Alpine Linux:

.. code-block:: sh

	$ doas apk add bonsai

Manual installation
-------------------

Bonsai depends on the Hare toolsuite: `hare`, `hare-json`, `hare-ev`

.. code-block:: sh

	$ git clone https://git.sr.ht/~stacyharper/bonsai
	$ doas make install -C bonsai


Commands
--------

The service is a daemon that maintain the state, and receive events and context changes from the client.

.. code-block:: sh

	$ bonsaid -t my/bonsaid/tree.json -D


The clients connect to the service using a Unix socket.

.. code-block:: sh

	$ bonsaictl -e my_event_name # trigger event
	$ bonsaictl -c foo=bar toto=titi # change context


Source file
-----------

Definitions
+++++++++++

Bonsai is a Finite State Machine structured as a tree. It has been designed to trigger commands when successive events and/or a precise context is accepted.

There is 4 kind of transition with specific acceptance rules :

- event transition: The received event name match the transition one
- context transition: The state context match the transition one
- exec transition: The transition command is run and succeed
- delay transition: The state wait for the delay transition duration. No other accepted event is received while waiting

The state will transition following every accepted transition. If there is no more available transition, the state goes back to the initial position.

Events aren't recursives
++++++++++++++++++++++++

Event input can trigger one or zero event transition. The state will then follow every accepted execs, contexts or delays transitions.

Exec transitions
++++++++++++++++

Exec transition commands are run synchronously. If you don't care about the command status or if you use the command as final trigger, and don't want to hold the bonsai daemon, you should use `["setsid", "-f", …]`.

Hole transitions
++++++++++++++++

Context transitions can be used as "holes" if you don't specify context values, because it will always match. This is particulary usefull just after exec transition that can fail.

How delay are cancelled
+++++++++++++++++++++++

If the state machine is waiting while receiving an event or a context update, it check if there is a accepting event or context transition available. Otherwise it continue to wait.