Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
125 lines (87 loc) · 3.49 KB

ARCHITECTURE.md

File metadata and controls

125 lines (87 loc) · 3.49 KB

Architecture Overview

Core Components

Task

A Task is a collection of Actions that execute sequentially. Tasks manage execution flow, error handling, and parameter resolution.

type Task struct {
    ID      string
    Name    string
    Actions []ActionWrapper
    Logger  *slog.Logger
    // Optional: build a structured result at the end of execution
    ResultBuilder func(ctx *TaskContext) (interface{}, error)
}

Action

An Action represents a single operation (file I/O, Docker command, system call). Actions implement the ActionInterface with Before/Execute/After lifecycle hooks.

type ActionInterface interface {
    BeforeExecute(ctx context.Context) error
    Execute(ctx context.Context) error
    AfterExecute(ctx context.Context) error
    GetOutput() interface{}
}

ActionWrapper

ActionWrapper is an interface that all actions satisfy. It provides the execution contract, identity, and output access used by the task runner.

type ActionWrapper interface {
    Execute(ctx context.Context) error
    GetID() string
    GetName() string
    GetOutput() interface{}
    GetDuration() time.Duration
    GetLogger() *slog.Logger
    SetID(string)
}

TaskManager

TaskManager orchestrates multiple tasks, manages shared context, and provides task lifecycle control.

Parameter System

Static Parameters

Fixed values known at task creation time.

engine.StaticParameter{Value: "/path/to/file"}

Action Output Parameters

Reference outputs from previous actions within the same task.

engine.ActionOutput("read-action", "content")

Task Output Parameters

Reference outputs from other tasks using the global context.

engine.TaskOutput("build-task", "imageID")

### Action Result Parameters

Use rich results from actions that implement `ResultProvider`.

```go
engine.ActionResult("download-artifact")
engine.ActionResultField("download-artifact", "checksum")

Task Result Parameters

Use rich results from tasks that implement ResultProvider or define a ResultBuilder.

engine.TaskResult("preflight")
engine.TaskResultField("preflight", "UpdateMode")

Execution Flow

  1. Task Creation: Actions are created and added to a task's Actions slice as ActionWrapper values
  2. Parameter Resolution: Parameters are resolved at execution time using the global context
  3. Action Execution: Each action runs Before → Execute → After hooks
  4. Output Storage: Action outputs are stored in the global context for parameter passing
  5. Error Handling: Tasks stop on first error, with special handling for prerequisites

Context Management

The GlobalContext maintains:

  • ActionOutputs: Results from completed actions
  • ActionResults: Rich results from actions implementing ResultProvider
  • TaskOutputs: Results from completed tasks
  • TaskResults: Rich results from tasks implementing ResultProvider (or using ResultBuilder)

Context is shared across tasks via the TaskManager and embedded in the execution context.

Error Handling

  • Prerequisites: Return ErrPrerequisiteNotMet to gracefully abort tasks
  • Execution Errors: Stop task execution and return error details
  • Context Cancellation: Respect context cancellation for timeouts and graceful shutdown

Testing Support

  • Mocks: Complete mock implementations for all interfaces
  • Testable Manager: Enhanced TaskManager with testing hooks
  • Performance Testing: Built-in benchmarking and load testing utilities