promotion

type Config map[string]any

type Context struct {
	// UIBaseURL may be used to construct deeper URLs for interacting with the
	// Kargo UI.
	UIBaseURL string
	// WorkDir is the working directory to use for the Promotion.
	WorkDir string
	// Project is the Project that the Promotion is associated with.
	Project string
	// Stage is the Stage that the Promotion is targeting.
	Stage string
	// Promotion is the name of the Promotion.
	Promotion string
	// FreightRequests is the list of Freight from various origins that is
	// requested by the Stage targeted by the Promotion.
	//
	// This information is sometimes useful to Steps that reference a particular
	// artifact. When explicit information about the artifact's origin is absent,
	// Steps may need to examine FreightRequests.
	// This examination helps determine whether any ambiguity exists regarding
	// the artifact's origin. If ambiguity is found, a user may need to resolve
	// it.
	FreightRequests []kargoapi.FreightRequest
	// Freight is the collection of all Freight referenced by the Promotion. This
	// collection contains both the Freight that is actively being promoted and
	// any Freight that has been inherited from the target Stage's current
	// state.
	Freight kargoapi.FreightCollection
	// TargetFreightRef is the actual Freight that triggered this Promotion.
	TargetFreightRef kargoapi.FreightReference
	// StartFromStep is the index of the step from which the promotion should
	// begin execution.
	StartFromStep int64
	// StepExecutionMetadata tracks metadata pertaining to the execution
	// of individual promotion steps.
	StepExecutionMetadata kargoapi.StepExecutionMetadataList
	// State is the current state of the promotion process.
	State State
	// Vars is a list of variable definitions that can be used by the
	// Steps.
	Vars []kargoapi.ExpressionVariable
	// Actor is the name of the actor triggering the Promotion.
	Actor string
}

type Engine interface {
	// Promote executes the specified sequence of Steps and returns a Result
	// that aggregates the results of all steps.
	Promote(context.Context, Context, []Step) (Result, error)
}

type ExprDataCacheFn func() *gocache.Cache

type MockEngine struct {
	PromoteFn func(context.Context, Context, []Step) (Result, error)
}

type MockStepRunner struct {
	// RunFunc is the function that this MockStepRunner should call when Run is
	// called. If set, this function will be called instead of returning RunResult
	// and RunErr.
	RunFunc func(context.Context, *StepContext) (StepResult, error)
	// RunResult is the result that this MockStepRunner should return when Run is
	// called.
	RunResult StepResult
	// RunErr is the error that this MockStepRunner should return when Run is
	// called.
	RunErr error
}

type Result struct {
	// Status is the high-level outcome of the user-defined promotion executed by
	// the Engine.
	Status kargoapi.PromotionPhase
	// Message is an optional message that provides additional context about the
	// outcome of the user-defined promotion executed by the Engine.
	Message string
	// HealthChecks collects health.Criteria returned from the execution of
	// individual Steps by their corresponding StepRunners. These criteria can
	// later be used as input to health.Checkers.
	HealthChecks []health.Criteria
	// If the promotion process remains in-progress, perhaps waiting for a change
	// in some external state, the value of this field will indicate where to
	// resume the process in the next reconciliation.
	CurrentStep int64
	// StepExecutionMetadata tracks metadata pertaining to the execution
	// of individual promotion steps.
	StepExecutionMetadata kargoapi.StepExecutionMetadataList
	// State is the current state of the promotion process.
	State State
	// RetryAfter is an optional, SUGGESTED duration after which a Promotion
	// reporting itself to be in a Running status should be retried. Note: This is
	// unrelated to retrying upon non-terminal failures.
	RetryAfter *time.Duration
}

type State map[string]any

type Step struct {
	// Kind identifies a registered StepRunner that implements the logic for this
	// step of the user-defined promotion process.
	Kind string
	// Alias is an optional identifier for this step of the use-defined promotion
	// process, which must be unique to the process. Output from execution of the
	// step will be keyed to this alias by the Engine and made accessible to
	// subsequent steps.
	Alias string
	// If is an optional expression that, if present, must evaluate to a boolean
	// value. If the expression evaluates to false, the step will be skipped.
	// If the expression does not evaluate to a boolean value, the step will
	// fail.
	If string
	// ContinueOnError is a boolean value that, if set to true, will cause the
	// Promotion to continue executing the next step even if this step fails. It
	// also will not permit this failure to impact the overall status of the
	// Promotion.
	ContinueOnError bool
	// Retry is the retry configuration for the Step.
	Retry *kargoapi.PromotionStepRetry
	// Vars is a list of variables definitions that can be used by the
	// Step.
	Vars []kargoapi.ExpressionVariable
	// Config is an opaque JSON to be passed to the StepRunner executing this
	// step.
	Config []byte
}

type StepContext struct {
	// UIBaseURL may be used to construct deeper URLs for interacting with the
	// Kargo UI.
	UIBaseURL string
	// WorkDir is the root directory for the execution of a step.
	WorkDir string
	// SharedState is the state shared between steps.
	SharedState State
	// Alias is the alias of the step that is currently being executed.
	Alias string
	// Config is the configuration of the step that is currently being
	// executed.
	Config Config
	// Project is the Project that the Promotion is associated with.
	Project string
	// Stage is the Stage that the Promotion is targeting.
	Stage string
	// Promotion is the name of the Promotion.
	Promotion string
	// PromotionActor is the name of the actor triggering the Promotion.
	PromotionActor string
	// FreightRequests is the list of Freight from various origins that is
	// requested by the Stage targeted by the Promotion. This information is
	// sometimes useful to Step that reference a particular artifact and, in the
	// absence of any explicit information about the origin of that artifact, may
	// need to examine FreightRequests to determine whether there exists any
	// ambiguity as to its origin, which a user may then need to resolve.
	//
	// TODO: krancour: Longer term, if we can standardize the way that Steps
	// express the artifacts they need to work with, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// StepRunner.
	FreightRequests []kargoapi.FreightRequest
	// Freight is the collection of all Freight referenced by the Promotion. This
	// collection contains both the Freight that is actively being promoted as
	// well as any Freight that has been inherited from the target Stage's current
	// state.
	//
	// TODO: krancour: Longer term, if we can standardize the way that Steps
	// express the artifacts they need to work with, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// StepRunner.
	Freight kargoapi.FreightCollection
	// TargetFreightRef is the actual Freight that triggered this Promotion.
	TargetFreightRef kargoapi.FreightReference
}

type StepEnvOption func(map[string]any)

type StepResult struct {
	// Status is the high-level outcome of a Step executed by a StepRunner.
	Status kargoapi.PromotionStepStatus
	// Message is an optional message that provides additional context about the
	// outcome of a Step executed by a StepRunner.
	Message string
	// Output is the opaque output of a Step executed by a StepRunner. The Engine
	// will update the shared state with this output, making it available to the
	// StepRunners executing subsequent Steps.
	Output map[string]any
	// HealthCheck identifies criteria for a health check process. This is
	// returned by some StepRunner upon successful execution of a Step. These
	// criteria can be used later as input to a health.Checker.
	HealthCheck *health.Criteria
	// RetryAfter is an optional, SUGGESTED duration after which a step reporting
	// itself to be in a Running status should be retried. Note: This is unrelated
	// to retrying upon non-terminal failures.
	RetryAfter *time.Duration
}

type StepRunner interface {
	// Run executes an individual Step from a user-defined promotion process using
	// the provided StepContext. Implementations may indirectly modify that
	// context through the returned StepResult to allow StepRunners for subsequent
	// Steps to access the results of this execution.
	Run(context.Context, *StepContext) (StepResult, error)
}

type StepRunnerCapabilities struct {
	KargoClient  client.Client
	ArgoCDClient client.Client
	CredsDB      credentials.Database
}

type StepRunnerCapability string

type StepRunnerMetadata struct {
	// DefaultTimeout is the default soft maximum interval in which a StepRunner
	// that returns a Running status (which typically indicates it's waiting for
	// something to happen) may be retried.
	//
	// The maximum is a soft one because the check for whether the interval has
	// elapsed occurs AFTER the step has run. This effectively means a step may
	// run ONCE beyond the close of the interval.
	//
	// A value of 0 will cause the step to be retried indefinitely unless the
	// ErrorThreshold is reached.
	//
	// This default can be overridden by step-level configuration.
	DefaultTimeout time.Duration
	// DefaultErrorThreshold is the number of consecutive times the step must fail
	// (for any reason) before retries are abandoned and the entire Promotion is
	// marked as failed.
	//
	// If this field is set to a non-positive value, it will be changed to the
	// system-wide default of 1 at registration time.
	//
	// A value of 1 will cause the Promotion to be marked as failed after just
	// a single failure; i.e. no retries will be attempted.
	//
	// This default can be overridden by step-level configuration.
	DefaultErrorThreshold uint32
	// RequiredCapabilities is a list of constants representing special
	// capabilities required by the StepRunner in order to execute a step
	// successfully. The engine executing the StepRunner is responsible for
	// injecting necessary dependencies into the StepRunner when invoking its
	// factory function. By default, StepRunners are not granted any special
	// capabilities.
	RequiredCapabilities []StepRunnerCapability
}

type StepRunnerRegistration struct {
	// Metadata is metadata about StepRunners for the kind of step specified by
	// StepKind.
	Metadata StepRunnerMetadata
	// Factory is a function for instantiating a StepRunner capable of executing
	// the kind of step specified by StepKind.
	Factory func(StepRunnerCapabilities) StepRunner
}

type TerminalError struct {
	Err error
}