execution

type ContextPersister interface {
	RecordContext(ctx context.Context, runID uuid.UUID, step run.StepKey, attempt int,
		published json.RawMessage) error
}

type ContextReader interface {
	PublishedContext(ctx context.Context, runID uuid.UUID) (map[string]json.RawMessage, error)
}

type History interface {
	StepHasSucceeded(ctx context.Context, workflowSlug, nodeID string, exceto uuid.UUID) (bool, error)

	// AlreadySucceeded returns the INSTANCES of THIS run that finished well in
	// an earlier attempt of it, so a retry re-runs only what failed.
	//
	// Keyed by instance and not by node, because a mapped step's twenty
	// partitions do not fail together: a retry has to redo the two that broke
	// and leave the other eighteen alone.
	//
	// A different question from StepHasSucceeded, which asks about EARLIER
	// RUNS. Confusing the two would make a step skip itself forever after its
	// first good day, so they are separate methods rather than one with a
	// flag.
	AlreadySucceeded(ctx context.Context, runID uuid.UUID) (map[run.StepKey]bool, error)
}

type LoadNumbers struct {
	Rows, Records, Ignored, BytesOut int64
	LoadMs                           int64

	BytesIn             int64
	Pages, HTTPAttempts int
	ExtractMs           int64
}

type Persister interface {
	IniciarTask(ctx context.Context, runID uuid.UUID, step run.StepKey, attempt int) error
	TerminarTask(ctx context.Context, runID uuid.UUID, step run.StepKey, attempt int,
		status run.Status, exit *int, failure string, log string) error

	// RecordStages records the phases of an SDK step while it runs. It is
	// what makes the screen advance before the step finishes.
	RecordStages(ctx context.Context, runID uuid.UUID, step run.StepKey, attempt int,
		sdkVersion string, stages json.RawMessage) error

	// RecordLoad keeps what one attempt of an SDK pipeline measured, so the
	// trend can be read without unpacking a year of JSONB.
	//
	// Called once, when the step ends, and only for a step that ran a load to
	// completion -- unlike RecordStages, which runs on every marked line
	// because the screen has to advance while the step is alive.
	RecordLoad(ctx context.Context, runID uuid.UUID, step run.StepKey,
		workflow string, n LoadNumbers) error

	// MarkSkipped records a step whose trigger rule was not satisfied, with the
	// reason. Required rather than optional: a skipped step that leaves no row
	// is invisible, and "did not run and nobody can tell why" is the state this
	// whole feature exists to remove.
	MarkSkipped(ctx context.Context, runID uuid.UUID, step run.StepKey, attempt int,
		reason string) error
}

type RecordedStage = Stage

type Reporter interface {
	Evento(execution.Event)
}

type Runner struct {
	Processo execution.Executor // serves `run:`; may be nil when there are only Go tasks
	Go       execution.Executor // serves `action:`; may be nil

	WorkDir string
	Env     map[string]string
	Report  Reporter

	// Timeout per node. Zero means no limit.
	Timeout time.Duration

	// MaxAttempts per node. Zero or 1 means a single attempt.
	MaxAttempts int
	BackoffBase time.Duration

	// Persist and RunID are used together: without both, per-step state is not
	// recorded and the DAG in the UI shows up with no execution state.
	Persist Persister

	// ContextDir is where a step's published context is written on the ENGINE's
	// filesystem, for the executors that read a real file.
	//
	// Empty is the normal case and does NOT turn the feature off: Run creates a
	// temporary directory per run and removes it at the end. It was "empty
	// means off" for one commit, and the consequence was that the whole feature
	// worked in tests and did nothing for a user, because nothing outside a
	// test ever set it. A capability that has to be switched on by a field
	// nobody knows about is a capability nobody has.
	//
	// Set it to pin the location -- a test that wants to read the files back.
	ContextDir string

	RunID uuid.UUID

	// Params are this run's values. They reach the step's command through a
	// template (see execution.Render) and the step's environment, so a
	// fetcher using the SDK sees them without being handed an argument.
	Params map[string]string

	// Trigger says why this Run exists: schedule, manual or backfill.
	Trigger string

	// LogicalDate is the slot this Run stands for. Nil on a manual trigger.
	LogicalDate *time.Time

	// Auto are the run's automatic params: the clock to read instead of now(),
	// the window it covers, how late it was, and whether the run before it
	// failed. The engine works them out so no pipeline has to.
	Auto run.AutoParams

	// Historico decides whether a step is running for the first time. Nil means
	// there is no way to know -- and then the step gets first=false, because
	// creating a table without being sure is worse than not creating it.
	History History

	// Vagas caps how many STEPS run at once -- in Kubernetes, how many pods
	// exist simultaneously. Nil means no limit.
	//
	// It has to be shared across every Runner in the process, which is why it
	// is injected rather than created here: the ceiling belongs to the CLUSTER,
	// not to one workflow. Without it, the dispatcher's concurrency limit
	// counted RUNS -- five runs with three parallel steps each gave fifteen
	// pods, not five.
	Slots chan struct{}

	// TentativaDoRun is this RUN's attempt, counted by the dispatcher. It goes
	// into the pod name so a retry does not find the previous attempt's pod.
	RunAttempt int

	// Pods runs steps as pods in Kubernetes. When present it serves every step
	// that declares `image:` -- and the same DAG runs as a pod in the cluster
	// and as a process on a laptop, with no change to the YAML.
	Pods execution.Executor

	// Hosts serves the steps that declare `host:`, keyed by the name in the
	// YAML. Empty is the normal case.
	//
	// A MAP and not a single executor, because one installation talks to
	// several machines and each is a different agent at a different address.
	// The YAML names one of them, and a name with no entry is refused with the
	// list of what exists -- an installation-level fact belongs in an
	// installation-level message, not in a step that silently ran somewhere
	// else.
	Hosts map[string]execution.Executor

	// Metrics records per-step numbers. Nil means nothing is measured, which is
	// what `brevis run` on a laptop wants: it has no endpoint to scrape.
	//
	// The STEP is measured here and the RUN is measured by the dispatcher,
	// which is the only place that knows a failure was the last attempt rather
	// than one of three.
	Metrics *metrics.Metrics
	// contains filtered or unexported fields
}

type Stage struct {
	Index    int            `json:"indice"`
	TaskName string         `json:"nome"`
	State    string         `json:"estado"`
	Ms       *int64         `json:"ms,omitempty"`
	At       string         `json:"em"`
	Numbers  map[string]any `json:"numeros,omitempty"`
}

type StepError struct {
	NodeID   string
	ExitCode int
	Message  string

	// Saida is the last few lines of stderr. Only the last ones, and not all of
	// them, because a chatty process would fill the database's error column --
	// and the cause is almost always at the end.
	Output []string
}

type StepMetric struct {
	Name  string
	Kind  string
	Value float64
}