execution

type Event struct {
	Kind     EventKind
	NodeID   string
	Message  string
	Stream   string // "stdout" | "stderr"
	ExitCode int
	Err      error
}

type EventKind string

type Executor interface {
	Name() string
	Execute(ctx context.Context, t TaskExec) (<-chan Event, error)
	Cancel(ctx context.Context, execID string) error
}

type FuncTask struct {
	TaskName string
	Fn       func(ctx context.Context, in Input) error
}

type Handover struct {
	Instance    string `json:"instance,omitempty"`
	ExecutionID string `json:"execution_id"`
	Attempt     int    `json:"attempt"`
	After       int64  `json:"after"`
}

type Input struct {
	NodeID string
	With   map[string]any

	// Log emits one line into the event stream. It exists so the task can report
	// progress without knowing about channels or the executor.
	Log func(msg string)
}

type Reattacher interface {
	Reattach(ctx context.Context, t TaskExec, h Handover) (<-chan Event, error)
}

type Registry struct {
	// contains filtered or unexported fields
}

type Task interface {
	Name() string
	Run(ctx context.Context, in Input) error
}

type TaskExec struct {
	ExecutionID string
	NodeID      string

	// Workflow, RunID and Attempt do not change the run — they identify it.
	// In Kubernetes they become the pod's labels, and they are what makes it
	// possible to find "that run's pods" without searching by name.
	Workflow string
	RunID    string

	// The STEP's attempt, within one execution of the run.
	Attempt int

	// TentativaDoRun is the RUN's, counted by the dispatcher. Both go into the
	// pod's name: without the second, a dispatcher retry recreates the run from
	// scratch (the step at attempt 0 again) and runs into the previous pod.
	RunAttempt int

	// MapIndex is which instance of a `for_each:` step this is, or -1
	// (run.Unmapped) for a step that is not mapped. Its zero value is a real
	// index, so whoever builds a TaskExec sets it -- `build` always does.
	MapIndex int

	Command string // a shell line, for the ProcessExecutor
	Action  string // the name in the registry, for the GoExecutor
	With    map[string]any

	// Image is this step's runtime. Empty in local mode (the command runs on the
	// instance itself); required in Kubernetes, where it IS the pod.
	Image string

	// Shell chooses between `sh -c "line"` and plain argv. It matters for a
	// distroless image, which has no shell at all.
	Shell bool

	// The pod's resources, in Kubernetes's format. Ignored in local mode, where
	// a process's limit is the machine's.
	CPU, Memoria       string
	CPUMax, MemoriaMax string

	WorkDir string
	Env     map[string]string

	// Secrets are variables whose value the engine does NOT carry: the map is
	// variable-name -> `secret-name/key`, and the executor is what resolves it.
	//
	// They are kept apart from Env for exactly that reason. If the value arrived
	// resolved here, it would pass through the dispatcher, through the task
	// assembly log and through any TaskExec dump somebody writes later.
	Secrets map[string]string

	// OutputPath is where the step writes what it publishes for the steps that
	// depend on it. It reaches the step as BREVIS_OUTPUT.
	//
	// The RUNNER picks it and the EXECUTOR may override it, because only the
	// executor knows what a path means in its world: a temporary file in the
	// engine's filesystem is meaningless inside a pod, where the answer is
	// /dev/termination-log -- which the engine already reads to get the exit
	// code.
	OutputPath string

	// A zero Timeout means no limit. A timeout was asked for early on, and
	// leaving the default open is deliberate — imposing an arbitrary limit would
	// kill legitimately long tasks.
	Timeout time.Duration
}