Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000..f17311098 --- /dev/null +++ b/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/404.html b/404.html new file mode 100644 index 000000000..1b6ed985b --- /dev/null +++ b/404.html @@ -0,0 +1,225 @@ + + +
+ + +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Automation, like most subjects, has many questions to ask and answer. The following is a selection of issues that are common in this space:
+A lot of the responsibility and weight of these questions is placed on automation teams. Issues that originate from many separate systems surface through the automation, and are often reported to the automation team, potentially resulting in burnout.
+For users, it is frustrating when it is difficult to understand what the automation is doing, where one is in the process, and how long it takes. This is amplified when the process errs after a lot of waiting – if it ever ends. Can one recover from errors, or end up feeling lost?
+Amidst the chaos, pressure, and expectation, have a little.. peace ✌️.
+ +The purpose of the Peace framework is to bring people joy and peace of mind in automation development and usage. This is an active effort to take away mental and emotional stress and frustration experienced with software.
+For maintainers, Peace aims to guide developers to build and support resilient automation.
+For users, Peace aims to make automation work surprisingly well, and reduce the feeling of being lost or frustrated when things don't go according to plan.
+ +The main priority is to take care of people. This is correlated to the following measurable dimensions:
+If these outputs trend in a favourable direction, then surveying people's well-being and satisfaction should show similar outcomes.
+The following input dimensions are considered when designing the Peace framework:
+By keeping these dimensions in mind:
+For development, the framework gives people confidence that what they build is of quality, by guiding them to consider and handle cases commonly experienced by users. Through feature gates, developers are protected from mental overload by allowing parts of the automation to be developed incrementally, without risk of diverging from the ideal.
+For users, the framework provides tools to observe the state and have predictable outcomes, so that they can be confident in making decisions. It also lowers the chances and cost of failure. This reduces the fear of making mistakes, as the effort of recovery is also lowered.
+From a business perspective, increased morale, increased performance, and decreased wastage are all benefits that allow results to be achieved faster and in a reliable manner.
+Each page in this section demonstrates the examples compiled as WASM applications.
+If you are running this book locally, you may compile all examples before visiting the pages using the following command:
+for example in $(ls examples)
+do wasm-pack build \
+ --target web \
+ --out-dir "../../doc/src/examples/pkg" \
+ --release \
+ "examples/${example}"
+done
+
+
+ This example manages a file download into the browser's memory.
+ + +++🚧 This example is a work in progress
+
Peace framework web application lifecycle example
+This example demonstrates management of a web application's lifecycle. This +includes:
+This page records ideas that I'd like, but there isn't enough mental capacity and time to design and work on them yet.
+Each item is a node.
+User can select which nodes to run – these may be a subset of the flow.
+User can select beginning and ending nodes – and these can be in reverse order.
+ +Note: Graphviz is compiled to WASM and published by hpcc-systems/hpcc-js-wasm. May be able to use that to render.
+graphviz-visual-editor is a library that allows basic editing of a graphviz graph. It's not yet developed to a point that is intuitive for users.
+End users may want to see what was previously deployed.
+If we retain a ${profile}/.history
directory with all previous execution information, it allows:
Perhaps we should make the API be, on visit
, return a list of identifiers for things to clean up.
+#![allow(unused)] +fn main() { +/// An ID +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Id<'s>(Cow<'s, str>); + +/// Single line description, hard limit of 200 characters. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct DescShort<'s>(Cow<'s, str>); +}
MultiProfile
Cmd scope profile sort functionUsers may want to sort profiles in the profile directory differently to their alphabetical / lexicographical sorting.
+This may be dependent on profile params – sort env based on env type, last execution time – profile history.
+When an item ensure does multiple writes, there is a possibility of not all of those writes occur during execution:
+In the last case, we cannot safely write state to disk, so a StateCurrent
discover is needed to bring StatesCurrentStored
up to date. However, the previous two cases, it is possible for Item
s to return State
that has been partially ensured, without making any further outgoing calls -- i.e. infer StatesEnsured
based on the successful writes so far.
Note that this places a burden on the Item
implementor to return the partial state ensured (which may conflict with keeping the State
simple), as well as make the ApplyFns::exec
return value more complex.
The trade off may not be worthwhile.
+Implementors may add/remove/modify items in flows.
+Peace needs to be designed such that these changes do not cause already-existent flows to not be loadable, i.e. when:
+states_*.yaml
contains state for which an item no longer exists in the flow.
states_*.yaml
does not contain state for an item that is newly added to the flow.
states_*.yaml
contains state whose fields are different to a new version of an item.
This one can be addressed by having State
be an enum, with versioned variants.
Also see 14.
+For items that cost, it is useful to have an expiry time that causes it to be deleted.
+The tokio-graceful-shutdown
library can be used to introduce interrupt safety into item executions. This is particularly useful for write functions.
See the is_shutdown_requested
method in particular.
DiffCmd
originally was written to diff the current and goal states. However, with the second use case of "diff states between two profiles", it is also apparent that other related functionality is useful:
Because of diffable params, and [#94], the Item
should likely have:
type Params: ItemParams + Serialize + DeserializeOwned
.fn item_params_diff(..)
.fn item_params_diff(..)
should likely have a similar signature to fn state_diff(..)
, whereby if one uses XData<'_>
, the other should as well for consistency:
MultiProfileSingleFlow
commands, a diff for item params which contains a referential value (e.g. "use the some_predecessor.ip_address()
") may(?) need information about some_predecessor
through Resources
/ Data
.We should work out the design of that before settling on what state_diff
and item_params_diff
's function parameters will be. See Design Thoughts on [#94] for how it may look like.
An Item
's params may not necessarily be mandatory. From the Params
type (and corresponding trait), Peace may:
Item
implementor provides a defaultParamsSpec
for each field to be the default, or a mapping function.When new workspace params are added, or new items are added to a flow, existing *_params.yaml
, item_params.yaml
, and states_*.yaml
may not contain values for those newly added params / items.
Automation software should be able to:
+When workspace params / items are removed from a flow, leftover params / state are no longer used. However, we may want to do one of:
+Instead of requiring Item::State
to store the params used when applied, maybe we should store the params used in the last ensure alongside that item's state.
Users are concerned with the current state of the item. They also may be concerned with the parameters used to produce that state. Requiring item implementors to store paths / IP addresses within the state that has been ensured feels like unnecessary duplication.
+However, when comparing diffs, we would hope either:
+Also:
+apply_check
needs to have both the old and new params to determine whether apply needs to be executed.State
as the output API, should not necessarily include params.Perhaps there should be a (dest_parameters, Item::State)
current state, and a (src_parameters, Item::State)
goal state. That makes sense for file downloads if we care about cleaning up the previous dest_path
, to move a file to the new dest_path
.
Or, all dest parameters should be in Item::State
, because that's what's needed to know if something needs to change.
Another thought:
+states_*.yaml
should store this per item:
Also see 8.
+Generate dot diagram using graphviz with full resolution, and then convert to tiles, then display different styling depending on the state of each item.
+data
and params{,_partial}
into FnCtx
Item
functions take in FnCtx
, data
, and item params
as separate arguments.
This was done to:
+Item::Params
, or Item::ParamsPartial
.However, functions don't necessarily need runtime fn_ctx
or data
, making it noise in the signature.
Should we combine all 3 into FnCtx
? It would make FnCtx
type parameterized over Params
and ParamsPartial
.
Referential lookup of values in state / item params. ([#94])
+AWS SDK is not WASM ready -- includes mio
unconditionally through tokio
(calls UDP). (aws-sdk-rust#59)
AWS SDK does not always include error detail -- S3 head_object
. (aws-sdk-rust#227)
Progress output should enable-able for state current / goal discover / clean functions.
+Flow params are annoying to register every time we add another item. Maybe split end user provided params from item params.
+Blank item needs a lot of rework to be easier to implement an item. ([67], [#96])
+For ApplyCmd
, collect StateCurrent
, StateGoal
, StateDiff
in execution report.
AWS errors' code
and message
should be shown to the user.
Progress limit should not be returned in ApplyFns::check
, but sent through progress_sender.limit(ProgressLimit)
. This simplifies check
, and allows state current/goal discovery to set the limits easily.
Consolidate StatesDiscoverCmd
and ApplyCmd
, so the outcome of a command is generic. Maybe use a trait and structs, instead of enum variants and hardcoded inlined functions, so that it is extendable.
Add an ListKeysAligned
presentable type so Presenter
s can align keys of a list dynamically.
Remove the peace_cfg::State
type.
Contextual presentable strings, for states and diffs.
+What command is this called for:
+Easy API functions for diffing -- current vs goal, between profiles' current states.
+What about diffing states of different state versions?
+Maybe this is already taken care of -- state_diff
is already passed in both State
s, so implementors had to manage it already.
fd -Ftd 'app_cycle' -x bash -c 'mv $0 ${0/app_cycle/envman}' {}
+fd -Ftf 'app_cycle' -x bash -c 'mv $0 ${0/app_cycle/envman}' {}
+sd -s 'app_cycle' 'envman' $(fd -tf)
+sd -s 'app cycle' 'envman' $(fd -tf)
+sd -s 'App Cycle' 'Env Man' $(fd -tf)
+sd -s 'AppCycle' 'EnvMan' $(fd -tf)
+cargo fmt --all
+
+
+