Aether

https://mintlify.wiki/BabySid/aether
Admin
Aether is a Go framework for building workflow orchestration systems that implements the Graph...
Tokens:86,047
Snippets:814
Trust Score:5.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Minimal Aether Workflow Example

Source: https://mintlify.wiki/BabySid/aether/concepts/workflow-model

A complete, runnable minimal workflow example demonstrating basic structure, arguments, and a single task. Suitable for playground testing.

```json
{
    "apiVersion": "aether/v1",
    "kind": "Workflow",
    "metadata": {
        "name": "single-task-all-types",
        "annotations": {
            "description": "single task with echo executor covering all 5 output types"
        }
    },
    "spec": {
        "entrypoint": "greet",
        "arguments": {
            "parameters": [
                {"name": "username", "type": "string", "value": "Alice"}
            ]
        },
        "templates": [
            {
                "task": {
                    "name": "greet",
                    "inputs": {
                        "parameters": [
                            {
                                "name": "username",
                                "type": "string",
                                "valueFrom": {"parameter": "workflow.arguments.parameters.username"}
                            }
                        ]
                    },
                    "executor": {
                        "type": "echo"
                    },
                    "outputs": {
                        "parameters": [
                            {"name": "message", "type": "string"}
                        ]
                    }
                }
            }
        ]
    }
}
```

--------------------------------

### Cron Schedule Examples

Source: https://mintlify.wiki/BabySid/aether/reference/cron-workflow-schema

Provides examples of cron expressions for common scheduling needs. Ensure the expression has exactly five whitespace-separated fields.

```text
"0 * * * *" (every hour),
"30 6 * * 1" (every Monday at 06:30),
"@daily"
```

--------------------------------

### List Aggregation Example

Source: https://mintlify.wiki/BabySid/aether/concepts/templates

Example of configuring 'list' aggregation strategy to collect specific output parameters ('status', 'rows') into JSON arrays across all iterations.

```json
{
    "aggregate": {
        "strategy": "list",
        "parameters": ["status", "rows"]
    },
    "outputs": {
        "parameters": [
            {"name": "status", "type": "array"},
            {"name": "rows",   "type": "array"}
        ]
    }
}
```

--------------------------------

### Custom Tenant Variable Source Example

Source: https://mintlify.wiki/BabySid/aether/extensions/other-interfaces

An example implementation of a custom `TenantSource` that provides tenant-specific variables like `tenant.id` and `tenant.tier`. This demonstrates how to inject dynamic, per-run context.

```go
type TenantSource struct {
    TenantID string
    Tier     string
}

func (s *TenantSource) Namespace() string { return "tenant" }

func (s *TenantSource) Vars() map[string]any {
    return map[string]any{
        "tenant.id":   s.TenantID,
        "tenant.tier": s.Tier,
    }
}
```

--------------------------------

### Create and Start Aether Engine in Go

Source: https://mintlify.wiki/BabySid/aether

Wire up the Aether engine with necessary components like store, executor, task broker, and ID generator using functional options. Then, start the engine to launch its background services.

```go
engine, err := aether.New(
    aether.WithStore(myStore),
    aether.WithExecutor(myExecutor),
    aether.WithTaskBroker(myBroker),
    aether.WithIDGenerator(myIDGen),
)
engine.Start(ctx)

```

--------------------------------

### Initialize Aether Engine with MemoryStore

Source: https://mintlify.wiki/BabySid/aether/extensions/store

Example of creating a new Aether engine instance, providing a MemoryStore implementation and other options.

```go
engine, err := aether.New(
    aether.WithStore(NewMemoryStore()),
    // ... other options
)
```

--------------------------------

### Task Template Example

Source: https://mintlify.wiki/BabySid/aether/concepts/templates

An example of a Task template named 'fetch-data' that uses an HTTP executor and defines input parameters for a URL and output parameters for the response body and count.

```json
{
    "task": {
        "name": "fetch-data",
        "inputs": {
            "parameters": [
                {"name": "url", "type": "string"}
            ]
        },
        "executor": {"type": "http"},
        "outputs": {
            "parameters": [
                {"name": "body",  "type": "array"},
                {"name": "count", "type": "int"}
            ]
        }
    }
}
```

--------------------------------

### Example PhaseConditions JSON Configuration

Source: https://mintlify.wiki/BabySid/aether/concepts/phase-lifecycle

An example JSON configuration for `phaseConditions`. It specifies conditions for 'succeeded' and 'failed' phases based on task exit codes.

```json
{
    "phaseConditions": {
        "succeeded": "tasks.run.code == 0 || tasks.run.code == 4",
        "failed":    "tasks.run.code == 1 || tasks.run.code == 2"
    }
}
```

--------------------------------

### Suspend/Resume Hook Lifecycle Example

Source: https://mintlify.wiki/BabySid/aether/guides/hooks

Illustrates the hook sequence for a task that suspends once and then completes successfully. This example defines hooks for onStart, onSuspend, onResume, onSuccess, and onExit.

```json
{
  "name": "approval",
  "template": "suspend-task",
  "hooks": {
    "onStart":   { "template": "hook-task" },
    "onSuspend": { "template": "hook-task" },
    "onResume":  { "template": "hook-task" },
    "onSuccess": { "template": "hook-task" },
    "onExit":    { "template": "hook-task" }
  }
}
```

--------------------------------

### Engine Initialization with TaskBroker Option

Source: https://mintlify.wiki/BabySid/aether/extensions/broker

Demonstrates how to initialize the Aether engine using the `WithTaskBroker` option. This option is mandatory for the engine to start.

```go
engine, err := aether.New(
    aether.WithStore(store),
    aether.WithTaskBroker(broker),
    aether.WithIDGenerator(idgen),
    aether.WithExecutor(echoExecutor),
)
```

--------------------------------

### Minimal Executor Example

Source: https://mintlify.wiki/BabySid/aether/reference/executor-interface

A minimal example of an executor plugin demonstrating Type(), Schema(), and Execute() methods.

```APIDOC
## Minimal executor example

```go
type EchoPlugin struct{}

func (p *EchoPlugin) Type() string { return "echo" }

func (p *EchoPlugin) Schema() model.ExecutorSchema {
    return executor.SchemaOf[struct{}, executor.DynamicOutputs]("echo", "v1", "Echoes inputs as outputs")
}

func (p *EchoPlugin) Execute(ctx context.Context, req *executor.ExecuteRequest) (*model.ExecOutputs, error) {
    // Read the special "outputs" parameter declared in the workflow
    var outputs []model.Parameter
    if req.Inputs != nil {
        for _, p := range req.Inputs.Parameters {
            if p.Name == "outputs" {
                // parse and return declared outputs
            }
        }
    }
    return &model.ExecOutputs{
        Code:       model.ExecCodeSucceeded,
        Parameters: outputs,
    }, nil
}
```
```

--------------------------------

### Example Completed Workflow Execution Output

Source: https://mintlify.wiki/BabySid/aether/quickstart

This is an example of the output generated by `engine.Get` for a completed workflow execution, showing the overall status and details of individual tasks.

```text
Workflow 1 finished: phase=Succeeded progress=1/1
  task=greet phase=Succeeded
    message (string) = "Hello, Alice!"
    code (int) = 200
    ok (bool) = true
    tags (array) = ["greet","demo"]
    meta (object) = {"version":"1.0"}
```

--------------------------------

### Basic CronWorkflow Example

Source: https://mintlify.wiki/BabySid/aether/reference/cron-workflow-schema

This example demonstrates a basic CronWorkflow that triggers every hour and runs a single echo task. It is derived from the engine's integration test suite.

```json
{
  "apiVersion": "aether/v1",
  "kind": "CronWorkflow",
  "metadata": {
    "name": "cron-basic",
    "annotations": {
      "description": "Basic CronWorkflow: fires once, inner workflow completes successfully"
    }
  },
  "spec": {
    "schedule": "0 * * * *",
    "workflowSpec": {
      "entrypoint": "main",
      "templates": [
        {
          "task": {
            "name": "main",
            "inputs": {
              "parameters": [
                {
                  "name": "outputs",
                  "value": [
                    { "name": "result", "type": "string", "value": "cron-ok" }
                  ]
                }
              ]
            },
            "executor": { "type": "echo" },
            "outputs": {
              "parameters": [{ "name": "result", "type": "string" }]
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Full-featured CronWorkflow Example

Source: https://mintlify.wiki/BabySid/aether/reference/cron-workflow-schema

A comprehensive example of a CronWorkflow, including detailed scheduling options like timezone, start/end times, concurrency policy, deadlines, and history limits. This workflow is configured for nightly reports.

```json
{
  "apiVersion": "aether/v1",
  "kind": "CronWorkflow",
  "metadata": {
    "name": "nightly-report",
    "namespace": "analytics",
    "labels": { "team": "data-eng" }
  },
  "spec": {
    "schedule": "0 2 * * *",
    "timezone": "America/New_York",
    "startAt": "2026-01-01T00:00:00Z",
    "endAt":   "2027-01-01T00:00:00Z",
    "concurrencyPolicy": "Forbid",
    "startingDeadlineSeconds": 300,
    "successfulJobsHistoryLimit": 7,
    "failedJobsHistoryLimit": 3,
    "suspend": false,
    "workflowSpec": {
      "entrypoint": "generate-report",
      "timeout": "45m",
      "templates": [
        {
          "task": {
            "name": "generate-report",
            "executor": { "type": "shell" },
            "outputs": {
              "parameters": [{ "name": "report-url", "type": "string" }]
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Install Aether Module

Source: https://mintlify.wiki/BabySid/aether/quickstart

Add the Aether module to your Go project to begin using the core engine. This command ensures the module is available for import.

```bash
go get github.com/BabySid/aether
```

```bash
go list github.com/BabySid/aether
```

--------------------------------

### Partial Update Convention Example

Source: https://mintlify.wiki/BabySid/aether/extensions/store

Demonstrates the nil-field partial update rule where only non-nil pointer fields are written to the store, preventing accidental overwrites.

```go
// store/memory_store.go (simplified)
if run.Status != nil {
    s := *run.Status
    existing.Status = &s
}
if run.Message != nil {
    s := *run.Message
    existing.Message = &s
}
// Deadline, Outputs, Metrics follow the same pattern
```

--------------------------------

### Install Aether Module in Go

Source: https://mintlify.wiki/BabySid/aether

Add the Aether module to your Go project. The core engine has no external dependencies.

```go
go get github.com/BabySid/aether@latest

```

--------------------------------

### Handle Task Started Callback

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Invoked when a worker begins executing a task. It transitions the task's state, records start times, and fires relevant hooks. This method uses token-based optimistic locking for idempotency.

```go
func (e *Engine) OnTaskStarted(ctx context.Context, taskRunID string)
```

--------------------------------

### Example Usage of OutputFrom

Source: https://mintlify.wiki/BabySid/aether/reference/executor-interface

Demonstrates how to use `OutputFrom` within an `Execute` method to serialize a custom output struct into `*model.ExecOutputs`. Ensure the output struct fields have appropriate `json` tags.

```go
type HttpOutput struct {
    StatusCode int    `json:"status_code"`
    Body       string `json:"body"`
}

func (p *HttpPlugin) Execute(ctx context.Context, req *executor.ExecuteRequest) (*model.ExecOutputs, error) {
    // ... do work ...
    out, err := executor.OutputFrom(HttpOutput{StatusCode: 200, Body: responseBody})
    if err != nil {
        return nil, err
    }
    out.Code = model.ExecCodeSucceeded
    return out, nil
}
```

--------------------------------

### SchemaOf Example Usage

Source: https://mintlify.wiki/BabySid/aether/reference/executor-interface

Shows how to generate an ExecutorSchema for an EchoPlugin using SchemaOf. This defines the configuration and output structure for the executor.

```go
type EchoConfig struct{}
type EchoOutput struct {
    Message string `json:"message" desc:"The echoed message"`
}

func (p *EchoPlugin) Schema() model.ExecutorSchema {
    return executor.SchemaOf[EchoConfig, EchoOutput]("echo", "v1", "Echoes inputs back as outputs")
}
```

--------------------------------

### Hook Reference Format Example

Source: https://mintlify.wiki/BabySid/aether/guides/hooks

Demonstrates the standard format for referencing a hook template within a workflow definition. It shows how to specify the template to execute for a given hook, such as 'onSuccess'.

```json
{
  "onSuccess": { "template": "my-notification-task" }
}
```

--------------------------------

### Example DAG Definition with Task Dependencies

Source: https://mintlify.wiki/BabySid/aether/concepts/templates

Illustrates a basic DAG structure with three tasks: 'fetch', 'transform', and 'notify'. The 'transform' task depends on 'fetch', and 'notify' depends on 'transform', defining the execution order.

```json
{
    "dag": {
        "name": "main",
        "tasks": [
            {"name": "fetch",     "template": "fetch-data"},
            {
                "name": "transform",
                "template": "transform-data",
                "dependencies": ["fetch"],
                "arguments": {
                    "parameters": [
                        {"name": "raw",   "valueFrom": {"parameter": "tasks.fetch.outputs.parameters.body"}},
                        {"name": "count", "valueFrom": {"parameter": "tasks.fetch.outputs.parameters.count"}}
                    ]
                }
            },
            {
                "name": "notify",
                "template": "send-notify",
                "dependencies": ["transform"],
                "arguments": {
                    "parameters": [
                        {"name": "summary", "valueFrom": {"parameter": "tasks.transform.outputs.parameters.summary"}}
                    ]
                }
            }
        ]
    }
}
```

--------------------------------

### BindInputs Example Usage

Source: https://mintlify.wiki/BabySid/aether/reference/executor-interface

Demonstrates binding request inputs to a typed HttpConfig struct. This is useful for configuring executors based on runtime parameters.

```go
type HttpConfig struct {
    URL    string `json:"url"`
    Method string `json:"method"`
}

func (p *HttpPlugin) Execute(ctx context.Context, req *executor.ExecuteRequest) (*model.ExecOutputs, error) {
    var cfg HttpConfig
    if err := executor.BindInputs(req.Inputs, &cfg); err != nil {
        return nil, err
    }
    // use cfg.URL, cfg.Method
}
```

--------------------------------

### Inject LocalBroker with WithTaskBroker Option

Source: https://mintlify.wiki/BabySid/aether/reference/broker-interface

Example of creating a new Aether engine and injecting a custom LocalBroker using the WithTaskBroker option. This is a required option.

```go
broker := NewLocalBroker(engine.OnTaskStarted, engine.OnTaskCompleted)

engine, err := aether.New(
    aether.WithTaskBroker(broker), // required
    // ...
)
```

--------------------------------

### CronWorkflow Metadata Example

Source: https://mintlify.wiki/BabySid/aether/reference/cron-workflow-schema

Illustrates the structure for metadata fields, including name, namespace, version, labels, and annotations. Ensure the name follows DNS-1123 label rules.

```yaml
metadata:
  name: "my-cron-workflow"
  namespace: "default"
  version: "1.0"
  labels:
    app: "my-app"
  annotations:
    description: "My scheduled workflow"
```

--------------------------------

### NewLocalBroker Constructor

Source: https://mintlify.wiki/BabySid/aether/extensions/broker

Constructor for the LocalBroker, initializing its channels and maps for managing task assignments and contexts. It requires start and completion handlers.

```go
// cmd/playground/local_broker.go

type LocalBroker struct {
    startHandler broker.StartHandler
    handler      broker.CompletionHandler

    mu       sync.Mutex
    closed   bool
    taskCh   chan *broker.TaskAssignment
    taskCtxs map[string]context.Context    // taskRunID → execution context
    cancels  map[string]context.CancelFunc // taskRunID → cancel func

    worker *LocalWorker
}

func NewLocalBroker(startHandler broker.StartHandler, handler broker.CompletionHandler) *LocalBroker {
    return &LocalBroker{
        startHandler: startHandler,
        handler:      handler,
        taskCh:       make(chan *broker.TaskAssignment, 64),
        taskCtxs:     make(map[string]context.Context),
        cancels:      make(map[string]context.CancelFunc),
    }
}
```

--------------------------------

### Define DAG Entrypoints

Source: https://mintlify.wiki/BabySid/aether/guides/dag-workflows

Use the 'entrypoints' field to specify which tasks are the starting points for DAG execution. Tasks not reachable from any entrypoint will not be executed.

```json
{
  "dag": {
    "name": "main",
    "entrypoints": ["task-a"],
    "tasks": [
      { "name": "task-a", "template": "node-a" },
      { "name": "task-b", "template": "node-b", "dependencies": ["task-a"] },
      { "name": "task-c", "template": "node-c" },
      { "name": "task-d", "template": "node-d", "dependencies": ["task-c"] }
    ]
  }
}
```

--------------------------------

### CronWorkflow Spec Example

Source: https://mintlify.wiki/BabySid/aether/reference/cron-workflow-schema

Demonstrates the specification for a cron workflow, including schedule, timezone, and history limits. Set `suspend: true` to pause triggers.

```yaml
spec:
  schedule: "*/5 * * * *"
  timezone: "America/New_York"
  startAt: "2026-01-01T00:00:00Z"
  endAt: "2026-12-31T23:59:59Z"
  concurrencyPolicy: "Forbid"
  successfulJobsHistoryLimit: 5
  failedJobsHistoryLimit: 3
  suspend: false
```

--------------------------------

### Executor Registry Management Functions

Source: https://mintlify.wiki/BabySid/aether/reference/executor-interface

Provides functions for managing registered plugins and their schemas. Use Register to add plugins and Get to retrieve them.

```go
func NewRegistry() *Registry
func (r *Registry) Register(plugin Plugin) error
func (r *Registry) RegisterSchema(schema model.ExecutorSchema)
func (r *Registry) Get(executorType string) (Plugin, bool)
func (r *Registry) GetSchema(executorType string) (model.ExecutorSchema, bool)
func (r *Registry) Types() []string
func (r *Registry) Schemas() []model.ExecutorSchema
```

--------------------------------

### Cancellation Hooks Example (Workflow Level)

Source: https://mintlify.wiki/BabySid/aether/guides/hooks

Defines cancellation hooks for a workflow, including onStart, onCancel, and onExit. This configuration is applied at the workflow level.

```json
{
  "spec": {
    "hooks": {
      "onStart":  { "template": "hook-task" },
      "onCancel": { "template": "hook-task" },
      "onExit":   { "template": "hook-task" }
    }
  }
}
```

--------------------------------

### Interpolation Syntax Examples

Source: https://mintlify.wiki/BabySid/aether/concepts/parameter-binding

Use these placeholders within string fields in arguments and when expressions to dynamically inject values from the evaluation environment. Keys not found are left as-is.

```yaml
{{inputs.parameters.name}}
```

```yaml
{{tasks.TASK_NAME.outputs.parameters.PARAM_NAME}}
```

```yaml
{{workflow.parameters.NAME}}
```

```yaml
{{loop_iter.index}}
```

```yaml
{{loop_iter.item}}
```

```yaml
{{loop_iter.FIELD}}
```

--------------------------------

### Loop Template Structure Example

Source: https://mintlify.wiki/BabySid/aether/guides/loops

Defines a loop template named 'run-loop' that iterates over static items, processes each file with 'process-file', and aggregates 'status' and 'rows' outputs into arrays. Concurrency is set to 2.

```json
{
  "loop": {
    "name": "run-loop",
    "items": ["jan.csv", "feb.csv", "mar.csv"],
    "concurrency": 2,
    "body": "process-file",
    "arguments": {
      "parameters": [
        { "name": "filename", "value": "{{iterator.item}}" },
        { "name": "index",    "value": "{{iterator.index}}" }
      ]
    },
    "aggregate": {
      "strategy": "list",
      "parameters": ["status", "rows"]
    },
    "outputs": {
      "parameters": [
        { "name": "status", "type": "array" },
        { "name": "rows",   "type": "array" }
      ]
    }
  }
}
```

--------------------------------

### Initialize Aether with a Store

Source: https://mintlify.wiki/BabySid/aether/reference/store-interface

Use `aether.WithStore` to inject a data store when initializing the Aether engine. This is a required option.

```go
engine, err := aether.New(
    aether.WithStore(myStore), // required
    // ...
)
```

--------------------------------

### Build and Start Aether Engine

Source: https://mintlify.wiki/BabySid/aether/quickstart

Initializes the Aether engine with necessary components like a store, executor registry, ID generator, and task broker. Ensure `eng.Start(ctx)` is called before submitting workflows and is paired with a deferred `eng.Stop()`.

```go
var err error
eng, err = aether.New(
	aether.WithStore(memStore),
	aether.WithExecutorRegistry(reg),
	aether.WithIDGenerator(NewAtomicIDGen()),
	aether.WithTaskBroker(brok),
)
if err != nil {
	log.Fatalf("create engine: %v", err)
}

if err := eng.Start(ctx); err != nil {
	log.Fatalf("start engine: %v", err)
}

return eng, finishCh
```

--------------------------------

### Task Template Example

Source: https://mintlify.wiki/BabySid/aether/reference/template-types

Defines a reusable Task template named 'greet'. It specifies input parameters, including a 'username' resolved from workflow arguments and a static 'outputs' parameter. The task uses an 'echo' executor and declares output parameters.

```json
{
  "task": {
    "name": "greet",
    "inputs": {
      "parameters": [
        { "name": "username", "type": "string",
          "valueFrom": { "parameter": "workflow.arguments.parameters.username" } },
        {
          "name": "outputs",
          "value": [
            { "name": "message", "type": "string", "value": "Hello, Alice!" },
            { "name": "code",    "type": "int",    "value": 200 }
          ]
        }
      ]
    },
    "executor": { "type": "echo" },
    "outputs": {
      "parameters": [
        { "name": "message", "type": "string" },
        { "name": "code",    "type": "int" }
      ]
    }
  }
}
```

--------------------------------

### Engine Option: WithStore

Source: https://mintlify.wiki/BabySid/aether/extensions/store

Details the `WithStore` engine option, which is mandatory for initializing the engine. The engine will panic if no store implementation is provided.

```APIDOC
## Engine Option: WithStore

### Function Signature

```go
func WithStore(s store.Store) Option
```

### Description

`WithStore` is a required option for the engine. The engine will panic during `New()` if no store implementation is provided.

### Usage Example

```go
engine, err := aether.New(
    aether.WithStore(NewMemoryStore()),
    // ... other options
)
```
```

--------------------------------

### LocalBroker StartTask and CompleteTask Methods

Source: https://mintlify.wiki/BabySid/aether/extensions/broker

Handles task lifecycle events. StartTask invokes the engine's OnTaskStarted handler, while CompleteTask cleans up task state and invokes the engine's OnTaskCompleted handler.

```go
func (b *LocalBroker) StartTask(ctx context.Context, taskRunID string, _ string) error {
    if b.startHandler != nil {
        b.startHandler(ctx, taskRunID)
    }
    return nil
}

func (b *LocalBroker) CompleteTask(ctx context.Context, result *broker.TaskResult) error {
    b.CleanupTask(result.TaskRunID)
    if b.handler != nil {
        b.handler(ctx, result)
    }
    return nil
}
```

--------------------------------

### Worker-side Methods

Source: https://mintlify.wiki/BabySid/aether/reference/broker-interface

Methods for worker processes to fetch, start, and complete tasks.

```APIDOC
### FetchTask(ctx, workerID)

Pulls a pending task for execution. This is typically a blocking or long-poll call.

Returns `(nil, context.DeadlineExceeded)` or `(nil, context.Canceled)` when the context expires before a task is available.

#### Parameters
* **workerID** (string) - Required - Identifies the calling worker for affinity or logging purposes.

### StartTask(ctx, taskRunID, workerID)

Reports that a worker has begun executing a task. Must be called before any actual computation starts. The implementation delivers this event to the engine — either by directly invoking the `StartHandler` (local) or publishing to a queue (distributed).

The engine transitions the task and its ancestor containers from `Ready` to `Running` when this is received.

### CompleteTask(ctx, result)

Reports the final execution result after the task finishes. The implementation delivers this to the engine — either directly via `CompletionHandler` or through a queue.

#### Parameters
* **result** (*TaskResult) - Required - The task result including outputs and exit code.
```

--------------------------------

### Get Workflow Execution

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Retrieves the current execution state of a workflow run. Non-blocking.

```APIDOC
## GET /workflows/{workflowID}

### Description
Retrieves the current execution state of a workflow run. Non-blocking.

### Method
GET

### Endpoint
/workflows/{workflowID}

### Parameters
#### Path Parameters
- **workflowID** (string) - Required - The `runID` returned by `Submit`.

#### Request Body
- **ctx** (context.Context) - Required - Request context.

### Response
#### Success Response (200)
- **WorkflowExecution** (*WorkflowExecution) - Read-only snapshot of the workflow run state. See [WorkflowExecution](#workflowexecution) below for field documentation.

#### Error Response
- **error** (error) - `store.ErrNotFound` (wrapped) if the `workflowID` does not exist.
```

--------------------------------

### Engine Lifecycle Management

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Manages the lifecycle of the engine's background services, including starting and stopping.

```APIDOC
## Start

### Description
Launches the engine's background services (timeout watchdog, cron scheduler). Returns immediately; all goroutines run until `Stop` is called or the parent `ctx` is cancelled. Pair every `Start` call with a `Stop` call.

If a `timeout.Watcher` is configured, `Start` begins the watchdog loop that periodically scans for tasks and workflows that have exceeded their deadlines.

If a `cron.Scheduler` is configured, `Start` re-registers all non-suspended CronWorkflows loaded from the store (crash recovery) and begins the cron loop.

### Method
POST

### Endpoint
/engine/start

### Parameters
#### Request Body
- **ctx** (context.Context) - Required - Parent context. When cancelled, all background goroutines exit.

### Response
#### Success Response (200)
- **status** (string) - Indicates successful start.

#### Error Response (500)
- **error** (error) - Returned if the timeout watcher or cron scheduler fails to start.

### Request Example
```json
{
  "ctx": "<context_details>"
}
```

### Response Example
```json
{
  "status": "Engine started successfully"
}
```

## Stop

### Description
Shuts down all background services started by `Start`. Safe to call concurrently or multiple times; only the first call takes effect. Stops the timeout watcher and cron scheduler if configured.

### Method
POST

### Endpoint
/engine/stop

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Indicates successful stop.

### Response Example
```json
{
  "status": "Engine stopped successfully"
}
```
```

--------------------------------

### Direct Path Lookup for Value

Source: https://mintlify.wiki/BabySid/aether/concepts/parameter-binding

Example of using `valueFrom` with `path` for a direct lookup of an EvalVars key, such as 'loop_iter.index'.

```json
{"name": "idx", "valueFrom": {"path": "loop_iter.index"}}
```

--------------------------------

### Reference Secret Key for Value

Source: https://mintlify.wiki/BabySid/aether/concepts/parameter-binding

Example of using `valueFrom` with `secretKeyRef` to retrieve a value from a secret named 'my-secret'.

```json
{"name": "api-key", "valueFrom": {"secretKeyRef": {"name": "my-secret", "key": "api-key"}}}
```

--------------------------------

### Start Engine Services

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Launches background services like the timeout watchdog and cron scheduler. This function should be paired with a `Stop` call. It returns immediately, with goroutines running until the parent context is cancelled or `Stop` is called.

```go
func (e *Engine) Start(ctx context.Context) error
```

--------------------------------

### Platform-Specific Task Execution with `when`

Source: https://mintlify.wiki/BabySid/aether/guides/conditional-branching

Branch task execution based on system variables like `system.os`. This example demonstrates detecting the OS and running platform-specific tasks using `when` conditions that check the output of an OS detection task.

```json
{
  "dag": {
    "name": "main",
    "tasks": [
      {
        "name": "detect-os",
        "template": "os-detector",
        "arguments": {
          "parameters": [
            { "name": "os", "valueFrom": { "parameter": "system.os" } }
          ]
        }
      },
      {
        "name": "run-on-mac",
        "template": "mac-task",
        "dependencies": ["detect-os"],
        "when": "tasks.detect-os.outputs.parameters.os == \"darwin\""
      },
      {
        "name": "run-on-linux",
        "template": "linux-task",
        "dependencies": ["detect-os"],
        "when": "tasks.detect-os.outputs.parameters.os == \"linux\""
      }
    ]
  }
}
```

--------------------------------

### Triggering Suspension with Echo Executor

Source: https://mintlify.wiki/BabySid/aether/guides/suspend-resume

Example of how to configure a task to suspend using the `echo` executor based on an input parameter.

```APIDOC
## Triggering Suspension from the Executor

The playground `echo` executor suspends when the input parameter `suspend` is `true`. In a real executor, you would return `ExecCodeSuspended` directly.

### Request Example

```json
{
  "dag": {
    "name": "pipeline",
    "tasks": [
      { "name": "prepare", "executor": { "type": "echo" } },
      {
        "name": "await-approval",
        "dependencies": ["prepare"],
        "inputs": {
          "parameters": [
            { "name": "suspend", "value": true },
            {
              "name": "outputs",
              "value": [
                { "name": "approved", "type": "bool", "value": true }
              ]
            }
          ]
        },
        "executor": { "type": "echo" }
      },
      {
        "name": "finalize",
        "dependencies": ["await-approval"],
        "executor": { "type": "echo" }
      }
    ]
  }
}
```

When `await-approval` suspends, `finalize` stays in `PhaseCreated`. The workflow remains alive, but `finalize` cannot run until `await-approval` is resolved.
```

--------------------------------

### Configure Tenant Variables Source

Source: https://mintlify.wiki/BabySid/aether/extensions/other-interfaces

Use `WithVarsSource` to provide runtime environment data or stable per-engine context that does not change between task executions.

```go
aether.WithVarsSource(&TenantSource{TenantID: "acme", Tier: "enterprise"})
```

--------------------------------

### Reference Task Output Parameter

Source: https://mintlify.wiki/BabySid/aether/concepts/parameter-binding

Example of using `valueFrom` with `parameter` to reference an output parameter from a task named 'fetch'.

```json
{"name": "raw", "valueFrom": {"parameter": "tasks.fetch.outputs.parameters.body"}}
```

--------------------------------

### Evaluate Expression for Dynamic Value

Source: https://mintlify.wiki/BabySid/aether/concepts/parameter-binding

Example of using `valueFrom` with `expression` to dynamically set a parameter's value based on a condition.

```json
{"name": "label", "valueFrom": {"expression": "tasks.run.outputs.parameters.code > 0 ? 'failed' : 'ok'"}}
```

--------------------------------

### Engine Constructor - New

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Creates a new Engine instance with the specified functional options. It's crucial to provide all required options to avoid errors.

```APIDOC
## New Engine Constructor

### Description
Creates a new Engine with the given options. Returns `ErrValidation` if any required dependency is missing.

### Method
`New`

### Endpoint
N/A (Constructor)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Options
**Required options** (omitting any of these causes `New` to return an error):

- **WithStore(s store.Store)** (Option) - Required - Sets the state persistence backend. All workflow and task run state is written here. See [Store Interface](/reference/store-interface).
- **WithExecutor(plugin executor.Plugin)** (Option) - Required - Registers an executor plugin. Call multiple times to register multiple types. At least one executor must be registered. See [Executor Interface](/reference/executor-interface).
- **WithIDGenerator(gen idgen.Generator)** (Option) - Required - Sets the unique ID generator used to produce `RunID` values for workflow and task runs.
- **WithTaskBroker(b broker.TaskBroker)** (Option) - Required - Sets the task dispatch bridge between the engine and workers. See [Broker Interface](/reference/broker-interface).

**Optional options:**

- **WithExecutorRegistry(reg *executor.Registry)** (Option) - Optional - Sets a pre-built executor registry. Use when you already have an `*executor.Registry` shared with a broker and want to avoid registering each plugin twice.
- **WithExprEvaluator(eval expr.Evaluator)** (Option) - Optional - Sets the expression evaluator used for `when` conditions, `repeatCondition` expressions, `phaseConditions`, and retry expressions. Without this, expression fields are ignored (no conditional branching).
- **WithArtifactStore(a artifact.Repository)** (Option) - Optional - Sets the artifact repository. Currently stored but not yet wired into task execution; reserved for the artifact upload/download feature.
- **WithSecretStore(s secret.Provider)** (Option) - Optional - Sets the secret provider used to resolve `valueFrom.secretKeyRef` references in workflow parameters.
- **WithHookNotifier(h hook.Notifier)** (Option) - Optional - Sets the hook notification backend. When configured, the engine calls the notifier when workflow-level and task-level hooks fire.
- **WithErrorSink(s errsink.ErrorSink)** (Option) - Optional - Sets the error observation sink. The engine reports internal non-fatal errors (hook failures, store errors in void callbacks) here for external monitoring. Scheduling behaviour is identical whether or not a sink is configured.
- **WithTimeoutWatcher(w timeout.Watcher)** (Option) - Optional - Sets the timeout watchdog. Required to enforce `spec.timeout` and per-task `timeout` fields. The watchdog calls `OnTaskTimeout` and `OnWorkflowTimeout` when deadlines are exceeded.
- **WithVarsSource(p vars.Source)** (Option) - Optional - Registers a global variable source available in all workflow templates. Call multiple times to layer multiple providers (per-call providers have higher priority). Intended for stable, run-independent data such as system metadata.
- **WithWorkerRegistry(r worker.Registry)** (Option) - Optional - Sets the worker registration and discovery backend. Used by distributed broker implementations to route tasks to workers that support a given executor type.
- **WithCronScheduler(s cron.Scheduler)** (Option) - Optional - Sets the cron scheduling backend. Required to use any `*CronWorkflow` method. Without it, those methods return `ErrNotSupported`.

### Request Example
```go
engine, err := aether.New(
    aether.WithStore(memstore.New()),
    aether.WithExecutor(myPlugin),
    aether.WithIDGenerator(idgen.NewAtomic()),
    aether.WithTaskBroker(myBroker),
    aether.WithTimeoutWatcher(timeout.NewPolling(5*time.Second)),
    aether.WithCronScheduler(cron.NewScheduler()),
)
if err != nil {
    log.Fatal(err)
}
```

### Response
#### Success Response (200)
- **Engine** (*Engine) - A pointer to the newly created Engine instance.
- **error** (error) - An error if the engine could not be created (e.g., missing required options).

#### Response Example
```json
{
  "engine": "<engine_instance>",
  "error": null
}
```
```

--------------------------------

### Import Aether Package

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Import the main aether package for engine functionality.

```go
import "github.com/BabySid/aether"

```

--------------------------------

### Callback Types

Source: https://mintlify.wiki/BabySid/aether/extensions/broker

Callback function types used to connect the broker to the engine's lifecycle handlers for task start and completion.

```APIDOC
## Callback Types

### Description
These function types are used to link the broker's actions to the engine's internal lifecycle management.

### StartHandler
- **Signature**: `func(ctx context.Context, taskRunID string) error`
- **Description**: Callback invoked when a task begins execution. The engine's `OnTaskStarted` method typically satisfies this signature.

### CompletionHandler
- **Signature**: `func(ctx context.Context, result *TaskResult) error`
- **Description**: Callback invoked when a task finishes execution. The engine's `OnTaskCompleted` method typically satisfies this signature.

**Note**: These types are primarily for local broker implementations. Distributed implementations often use message queues and separate consumers.
```

--------------------------------

### Configure Loop with `itemsFrom`

Source: https://mintlify.wiki/BabySid/aether/guides/loops

Set up a loop template to consume a list of items using `itemsFrom`. The `items-list` input parameter is bound to the `itemsFrom` expression, allowing the engine to spawn iterations for each item in the list.

```json
{
  "loop": {
    "name": "dynamic-loop",
    "inputs": {
      "parameters": [
        { "name": "items-list", "type": "array" }
      ]
    },
    "itemsFrom": "{{inputs.parameters.items-list}}",
    "body": "worker",
    "arguments": {
      "parameters": [
        { "name": "file", "value": "{{iterator.item}}" }
      ]
    },
    "aggregate": {
      "strategy": "list",
      "parameters": ["processed"]
    },
    "outputs": {
      "parameters": [
        { "name": "processed", "type": "array" }
      ]
    }
  }
}
```

--------------------------------

### Get Cron Workflow Execution State

Source: https://mintlify.wiki/BabySid/aether/reference/engine-api

Returns the execution state of a CronWorkflow and all WorkflowRuns it has triggered. Requires the cronID obtained from SubmitCronWorkflow.

```go
func (e *Engine) GetCronWorkflow(ctx context.Context, cronID string) (*CronWorkflowExecution, error)
```

--------------------------------

### Start Scheduler Background Services

Source: https://mintlify.wiki/BabySid/aether/extensions/other-interfaces

Launches the scheduler's background services. Returns immediately. Background work runs until `Stop` is called. Safe to call only once; idempotent implementations may log a warning on repeated calls.

--------------------------------

### Define CronWorkflowStore Interface

Source: https://mintlify.wiki/BabySid/aether/extensions/store

Interface for managing persistent records of scheduled cron workflows. Used to re-register cron schedules on engine start.

```go
type CronWorkflowStore interface {
    CreateCronWorkflow(ctx context.Context, record *CronWorkflowRecord) error
    GetCronWorkflow(ctx context.Context, cronID string) (*CronWorkflowRecord, error)
    UpdateCronWorkflow(ctx context.Context, record *CronWorkflowRecord) error
    DeleteCronWorkflow(ctx context.Context, cronID string) error
    ListCronWorkflows(ctx context.Context) ([]*CronWorkflowRecord, error)
}
```

--------------------------------

### Extended Aether Engine Wiring with Optional Interfaces

Source: https://mintlify.wiki/BabySid/aether/architecture

Demonstrates wiring the Aether engine with a comprehensive set of optional interfaces, including expression evaluation, timeout watching, variable sourcing, hook notification, and secret storage.

```go
eng, err := aether.New(
    aether.WithStore(memStore),
    aether.WithExecutorRegistry(reg),
    aether.WithIDGenerator(NewAtomicIDGen()),
    aether.WithTaskBroker(brok),
    aether.WithExprEvaluator(NewSimpleEvaluator()),
    aether.WithTimeoutWatcher(newPollingWatcher(memStore, 500*time.Millisecond)),
    aether.WithVarsSource(&vars.SystemSource{}),
    aether.WithHookNotifier(myNotifier),
    aether.WithSecretStore(mySecretStore),
)
```
Tokens:
Raw