API Reference

---

This page documents the main Go API for iapetus. It covers the core structs, interfaces, and extension points. For YAML usage, see the YAML Reference.

Workflow Struct 🗂️

The Workflow struct defines a collection of tasks, their dependencies, and global configuration. It is the top-level object for running a workflow.

type Workflow struct {
    Name    string              // Name of the workflow
    Steps   []*Task             // List of tasks (steps)
    Backend string              // Default backend for all tasks (e.g., "bash", "docker")
    EnvMap  map[string]string   // Environment variables for all tasks
    // ... hooks, logger, etc.
}

Fields: - Name: Human-readable workflow name. - Steps: List of tasks (see below). - Backend: Default backend for all steps (can be overridden per-task). - EnvMap: Environment variables for all steps (can be overridden per-task). - Hooks, logger, and other advanced fields are available for extensibility.

Example

wf := iapetus.NewWorkflow("my-wf", zap.NewNop())
wf.Backend = "bash"
wf.EnvMap = map[string]string{"FOO": "bar"}
wf.AddTask(*task)
wf.Run()

Task Struct 🏃

A Task represents a single step in a workflow. Each task can have its own command, arguments, environment, timeout, assertions, and backend.

type Task struct {
    Name     string                // Name of the task (unique in workflow)
    Command  string                // Command to execute (e.g., "echo")
    Args     []string              // Arguments for the command
    Timeout  time.Duration         // Max execution time (default: 30s, can override per-task)
    Retries  int                   // Number of retry attempts on failure
    Depends  []string              // Names of tasks this task depends on
    EnvMap   map[string]string     // Environment variables for this task
    Image    string                // Container image (for containerized backends)
    Asserts  []func(*Task) error   // List of assertion functions
    Backend  string                // Backend for this task (overrides workflow default)
}

Fields: - Name: Unique name for the task. - Command: The executable or shell command. - Args: Arguments to pass to the command. - Timeout: Maximum allowed execution time (default: 30s). - Retries: Number of times to retry on failure. - Depends: List of task names this task depends on (for DAG execution). - EnvMap: Environment variables for this task (overrides workflow-level vars). - Image: Docker image (for Docker backend). - Asserts: List of assertion functions (see below). - Backend: Backend to use for this task (overrides workflow default).

Example

task := iapetus.NewTask("hello", 5*time.Second, nil).
    AddCommand("echo").
    AddArgs("Hello, world!").
    AssertOutputContains("Hello")
task.Timeout = 10 * time.Second
task.Retries = 2
task.EnvMap = map[string]string{"FOO": "bar"}
task.Backend = "docker"
task.Image = "alpine:3.18"

Backend Interface & Plugins 🔌

The Backend interface allows you to add new ways to run tasks (e.g., Docker, Kubernetes, SSH). Built-in backends include Bash and Docker.

type Backend interface {
    RunTask(task *Task) error
    ValidateTask(task *Task) error
    GetName() string
    GetStatus() string
}

• RunTask: Executes the given task and populates its result fields.

• ValidateTask: Checks if the task is valid for this backend (e.g., required fields).

• GetName: Returns the backend’s name (for registry and diagnostics).

• GetStatus: Returns a status string (e.g., “available”, “unavailable”).

Registering a Backend

iapetus.RegisterBackend("my-backend", &MyBackend{})

Example Plugin

type MyBackend struct{}
func (b *MyBackend) RunTask(task *iapetus.Task) error { /* ... */ }
func (b *MyBackend) ValidateTask(task *iapetus.Task) error { return nil }
func (b *MyBackend) GetName() string { return "my-backend" }
func (b *MyBackend) GetStatus() string { return "available" }

Assertion Functions ✅

Assertions are checks that validate the result of a task. You can use built-in assertions or write your own.

Built-in assertions:

• AssertExitCode(expected int)

• AssertOutputEquals(expected string)

• AssertOutputContains(substr string)

• AssertOutputJsonEquals(expected string, skipJsonNodes …string)

• AssertOutputMatchesRegexp(pattern string)

Custom assertion example

func AssertMyCheck(expected string) func(*iapetus.Task) error {
    return func(t *iapetus.Task) error {
        if t.Actual.Output != expected {
            return fmt.Errorf("want %q, got %q", expected, t.Actual.Output)
        }
        return nil
    }
}

Hooks 🪝

Hooks let you run custom logic on task events. Use hooks for logging, metrics, or notifications.

• AddOnTaskStartHook(func(*Task))

• AddOnTaskSuccessHook(func(*Task))

• AddOnTaskFailureHook(func(*Task, error))

• AddOnTaskCompleteHook(func(*Task))

YAML Schema Reference 📄

For YAML usage, see the YAML Reference. Example:

name: my-wf
backend: bash # default backend for all steps
env_map:
  FOO: bar
steps:
  - name: hello
    command: echo
    args: ["hello"]
    timeout: 5s
    backend: docker # optional, overrides workflow backend
    image: alpine:3.18
    env_map:
      BAR: baz
    raw_asserts:
      - output_contains: hello

Supported assertion types in YAML:

• exit_code: 0

• output_equals: “foo”

• output_contains: “bar”

• output_json_equals: ‘{“foo”: 1}’

• output_matches_regexp: ‘^foo.*$’

• skip_json_nodes: [“foo.bar”] (for JSON assertions)

For more, see the GoDoc.

---