workbench

README

= Workbench - Trento Agent Operators

This library contains the code for `+agent-operators+`. An `+operator+`
is a unit of code that can perform write operations on target machines.

Each operator knows how to execute actions and how to roll them back in
case of failure.

== Install

Install the library

`+go get github.com/trento-project/workbench+`

Install the cli tool

`+go install github.com/trento-project/workbench+`

== Moving Parts

=== Operator

.flowchart
image::flow_chart.png[flowchart]

An operator is a unit of code that can perform write operations on
target machines. +
A write operation can either fail or succeed. If it succeeds, the
operation displays a diff highlighting the changes before and after the
commit phase.

The operator accepts arguments to specify how to perform the operations.
The arguments are in the form of a `+map[string]any+`, and each operator
knows how to extract and validate them. +
It follows a transactional approach, where each operation has distinct
stages:

* PLAN +
* COMMIT +
* VERIFY +
* ROLLBACK

The documentation for each of the operators can be found in the
operators go source.

==== PLAN

The goal of the PLAN stage is to collect information about the
operations and verify prerequisites. +
This is also the phase where information for diffing is gathered by
collecting the `+before+` state.

Additionally, during this phase, it is important to ensure that any
resources modified during the COMMIT phase are backed up. This allows
restoration during the ROLLBACK phase or manual recovery by system
administrators if the rollback fails.

If an error occurs during the PLAN phase, no rollback is needed; the
operation is simply aborted with the plan error.

==== COMMIT

The COMMIT phase executes the actual write operations on the system,
utilizing the information collected during the PLAN phase. +
If an error occurs during this phase, a rollback is triggered.

The COMMIT phase should be idempotent. If a requested change has already
been applied, the commit operation is simply skipped without returning
an error. +
Idempotency should be implemented appropriately based on the type of
operations to be performed.

==== VERIFY

The VERIFY phase ensures that the actions applied during the COMMIT
phase have produced the expected results on the system. +
If an error occurs during this phase, the rollback process is initiated.

This phase is also when the `+after+` state is recorded for the diff,
highlighting changes made during the commit phase.

==== ROLLBACK

The ROLLBACK phase must implement mechanisms to revert any changes made
during the COMMIT phase. +
It can use information collected during the PLAN phase to restore the
system to its previous state. +
The rollback implementation may vary depending on the type of operation
performed during the COMMIT phase. +
Be sure to provide clear error messages and log actions appropriately.

If the rollback fails, the error is returned without further action.

=== Executor

The Executor is a wrapper around an operator. The operator implements
the phase interface and must be wrapped in an Executor.

The Executor manages operations transactionally. +
For library users, the Executor is transparent—using an Operator means
it is already wrapped within an Executor.

=== Registry

The Registry holds all available operators. Each operator has a version.
By default, if no version is specified when requesting an operator, the
latest version is fetched from the Registry.

To use an operator, it must be fetched using the `+GetOperatorBuilder+`
function, providing the operator name as an argument.

[source,go]
----
builder, err := registry.GetOperatorBuilder(operatorName)
op := builder("test-cli", opArgs)
report := op.Run(ctx)
// the report contains the success or the error of the execution
----

The operator name follows this format: `+<operatorname>@<version>+`.

The Registry returns an Operator Builder:

[source,go]
----
type OperatorBuilder func(operationID string, arguments OperatorArguments) Operator
----

The `+operationID+` is a unique identifier for the operation, and
`+arguments+` are modeled as `+map[string]any+`.

=== CLI

The Workbench library also exposes a `+CLI+` to run operators without
importing the library. The CLI is intended only for testing and
development purposes.

The CLI follows the same rules as the library, implementing only the
operators exposed by the registry.

==== Usage

....
Usage:
  workbench [OPTIONS]

Application Options:
  -a, --arguments=  JSON arguments for an operator
  -v, --verbose     Log verbosity

Help Options:
  -h, --help        Show this help message
....

The CLI accepts the name of an operator as an argument, following the
same convention `+<operatorname>@<version>+`, and requires the `+-a+`
option to pass the arguments.

The arguments must be provided as a JSON string.

==== Example

[source,bash]
----
sudo ./workbench -a '{"solution": "HANA"}' saptuneapplysolution
----

Using `+sudo+` may be necessary depending on the type of operator being
executed. +
In this example, the `+saptuneapplysolution+` operator is called with
the argument `+solution+` set to `+HANA+`.

The CLI will perform the operations, log any errors, and finally display
the diff when the execution succeeds.