Skip to main content

Chains

How a behavior builds on others and calls them on the same host, what occurs when a step fails, and the building blocks of this build. osapi behavior chain spec get prints the same list.

What a chain is​

A chain​

The behaviors that a behavior calls, and the ones that they call: dns calls netplan, and netplan calls managedfile. The chain has the name of the behavior at its top. It is not declared on its own: Requires on each behavior makes it.

Use: osapi behavior chain list shows each chain; osapi behavior chain get --name <behavior> shows its tree.

The calls of an example​

osapi behavior chain get runs each example of the behavior on the fake host that go test uses, and records each Call: the behavior, the method, the input, and the output or the error. Thus the tree shows what the code does now.

Use: To see what a behavior sends to the behaviors that it calls, before a change or when one fails.

Building on other behaviors​

Use a building block​

A building block is an internal behavior that does one generic job, such as writing a file that osapi manages. Its spans, checks and records come with it. "Building blocks" lists the ones in this binary.

Use: Before a provider does generic work itself: a managed file, a service reload, a call to an outside API. Require the block with Requires, and call it with Call.

Make a building block​

Generic work that no block does yet becomes a new internal behavior. The behavior that needs it requires it.

Use: When the work is not about the one thing that the behavior manages, or a second behavior would need it.

One host, one step​

A behavior acts on one host, in one job. Its building blocks run on the same host, in the same job.

Use: Work across hosts, or in ordered steps, is an osapi-orchestrator workflow, not a behavior.

Calls between behaviors​

Call(ctx, other.Behavior, other.Method, p, in)​

Runs a method of a required behavior in its own span, so the trace shows it as a step. It checks in against its validate tags first, as the API does for a served method: an input that breaks one is an error, and the method does not run.

Use: Each time a provider uses a required behavior. A direct call fails the tests.

host.Require[P](h)​

Returns the provider of a required behavior, in a builder.

Use: In the builder of a behavior that uses Requires.

When a step fails​

The error goes up​

Call returns the error of a step to the provider that called it. The provider returns it, with what it was doing, or handles it. The job fails with the message, and the trace marks the span of the step that failed.

Use: In each provider that calls another behavior.

A step undoes its own change​

A building block that changes the host and then fails puts the host back before it returns the error: netplan gives its file back the content that it had, or removes a new file, when netplan generate refuses it. The caller does not undo the work of a block.

Use: In a building block whose change can fail after it started.

Skipped on a platform​

A behavior that a chain needs, and that cannot run on a platform, makes the behavior at the top report skipped there too.

Use: When a building block declares fewer platforms than the behavior that requires it.

Building blocks​

managedfile​

Files osapi writes on a host and keeps a record of. Methods: get, update, delete.

Use: Require it, and call its methods with Call. osapi behavior get --name managedfile shows its inputs.

netplan​

The netplan files osapi writes, validated and applied. Methods: update, delete, get.

Use: Require it, and call its methods with Call. osapi behavior get --name netplan shows its inputs.

object​

The objects of the object store of the fleet, such as a file uploaded with osapi client file upload. Methods: get.

Use: Require it, and call its methods with Call. osapi behavior get --name object shows its inputs.