Item

Note: 🚧 means the concept is not yet implemented.

An item is something that can be created, inspected, and cleaned up by automation.

An itemification defines data types and logic to manage that item.

The Item and associated types are how consumers integrate with the Peace framework. Consumers provide a unique ID, data types, and functions, which will be selectively executed by the framework to provide lean, robust automation, and a good user experience.

This logical breakdown guides automation developers to structure logic to handle cases that are not normally considered of when writing automation. Combined with trait requirements on data types, the framework is able to provide commands, workflow optimizations, and understandable output to ensure a pleasant automation experience.

Data Types

Error: The umbrella error type returned when anything goes wrong when managing the item.
State: Information about a managed item, can be divided into logical and physical state.
Logical state: Part of the state that can be controlled, e.g. application server's existence.
Physical state: Part of the state that cannot be controlled, e.g. application server's instance ID.
Current state: Current State of the managed item, both logical and physical.
Goal state: Logical State that one wants the item to be in.
State difference: Difference between the current Logical state and the Goal state.

Logic – Building Blocks

1. Define an ID.

Item::id

Provide the framework with a unique ID for this item.

These are intended to be safe to use as file names, as well as avoid surprises, and so have been limited to alphanumeric characters and underscores, and cannot begin with a number. This is validated at compile time by using the item_id!("..") macro.

The examples in the peace repository will use snake_case, but the rules are flexible enough to accept PascalCase or camelCase if that is preferred.

Examples

Item that manages a file download: "download".
Item that manages a server: "server_existence".

2. Initialize framework with parameters to manage item.

Item::setup

🚧 parameters are passed in for each command

Provide the framework with enough information to begin managing the item.

This function also instantiates the data types referenced by this Item into the Resources map.

Examples

Item that manages a file download:

Required parameters are the URL to download from, and the destination file path.
Item that manages a server:

Required parameters are the base image ID to launch the server with, and hardware specs.

3. Fetch current item state.

Item::state_current

This may not necessarily be a cheap function, for example if it needs to make web requests that take seconds to complete.

Examples

Item that manages a file download:

Current state is checking a file's existence and contents.
Item that manages a server:

Current state is checking a server's existence and its base image ID.

4. Fetch goal item state.

Item::StateGoalFn

This may not necessarily be a cheap function, for example if it needs to make web requests that take seconds to complete.

Examples

Item that manages a file download:

Goal state is file metadata retrieved from a remote server.
Item that manages a server:

Goal state is one server exists with the specified the base image ID.

5. Return the difference between current and goal states.

Item::StateDiffFn

It is important that both the from and to are shown for values that have changed, and values that have not changed or are not relevant, are not returned.

Examples

Item that manages a file download:

State difference is a change from a file that does not exist, to a file with contents "abc".
Item that manages a server:

State difference is a change from a non-existent server, to a server exists with the specified the base image ID.

6. Ensure that the item is in the goal state.

Transforms the current state to the goal state.

check: Returns whether exec needs to be run to transform the current state into the goal state.
exec: Actual logic to transform the current state to the goal state.
exec_dry: Dry-run transform of the current state to the goal state.

Like exec, but all interactions with external services, or writes to the file system should be substituted with mocks.

7. Clean up the item.

Cleans up the item from existence.

check: Returns whether exec needs to be run to clean up the item.
exec: Actual logic to clean up the item.
exec_dry: Dry-run clean up of the item.

Comparison with `git`

Readers may notice the function breakdown is git-like. The following table compares the concepts:

Subject	Peace	Git
Item	Any consumer defined item.	A directory of files.
Project initialization	`init` command takes in parameters to manage the item.	Uses the current directory or passed in directory.
State	Consumer defined information about the item.	Current state is the latest commit, goal state is the working directory.
State retrieval	On request by user using the `StatesDiscover` command.	Retrieved each time the `status` command is run, cheap since it is all local.
State display	On request using `state` and `goal` commands	`show $revision:path` command shows the state at a particular `$revision`.
State difference	On request using `diff` command	`status` command shows a summary, `show` and `diff` commands shows the state difference.
State application	On request through the `ensure` command.	On request through `commit` and `push` commands.
Environments	Handled by updating initialization parameters.	Defined through `remote` URLs.

The Peace Framework