pipeline

type Actions interface {
	Build(ctx context.Context, req BuildRequest, log func(line string)) (image string, err error)
	Deploy(ctx context.Context, req DeployRequest, log func(line string)) error
	Promote(ctx context.Context, from, to string, log func(line string)) (image string, err error)
	Rollback(ctx context.Context, service string, log func(line string)) (image string, err error)
	Notify(ctx context.Context, app string, succeeded bool, message string) error
}

type BuildRequest struct {
	App        string
	Ref        string
	SHA        string
	Type       string
	Context    string
	Dockerfile string
	Image      string
	Tag        string
}

type CacheSpec struct {
	Key  string `yaml:"key" json:"key"`
	Path string `yaml:"path" json:"path"`
}

type Combo map[string]string

type Concurrency struct {
	Group            string `yaml:"group" json:"group"`
	CancelInProgress bool   `yaml:"cancel_in_progress,omitempty" json:"cancel_in_progress,omitempty"`
}

type Config struct {
	Store   Store
	Runtime RuntimeResolver
	Actions Actions
	Secrets SecretResolver
	Source  Source
	// RunEnv returns extra environment variables for a run's steps, for
	// example the preview environment a pull request run belongs to. Optional.
	RunEnv func(ctx context.Context, run store.PipelineRun) map[string]string
	// OIDCIssuer mints a job's oidc token; nil means opting a job into
	// oidc fails with a clear error rather than silently getting none.
	OIDCIssuer OIDCIssuer
	// OIDCRequestURL is the base URL for the runtime "request a token
	// for this audience" endpoint (Engine.OIDCTokenRequestHandler),
	// reachable from inside a job's own container, never externally.
	// Empty means a job that lists more than one oidc.audiences entry
	// fails with a clear error instead of getting an unreachable URL.
	OIDCRequestURL string
	Logger         *slog.Logger
	Now            func() time.Time
	NewID          func() string

	// NamePrefix namespaces containers and volumes (the brand short name).
	NamePrefix string
	// GitImage runs the checkout; it needs a POSIX shell and git.
	GitImage        string
	MaxParallelJobs int
	MaxLogLines     int
	StepTimeout     time.Duration
	JobTimeout      time.Duration
	ApprovalTimeout time.Duration
	KeepRuns        int

	// Reporter, when set, posts run state to the git forge as a commit
	// status. ReportTimeout bounds each post.
	Reporter      StatusReporter
	ReportTimeout time.Duration
}

type Definition struct {
	Version     int               `yaml:"version" json:"version"`
	Name        string            `yaml:"name" json:"name"`
	On          Triggers          `yaml:"on" json:"on"`
	Stages      []string          `yaml:"stages,omitempty" json:"stages,omitempty"`
	Env         map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Concurrency *Concurrency      `yaml:"concurrency,omitempty" json:"concurrency,omitempty"`
	// ReportStatus posts run state back to the forge as a commit status.
	// Nil means on, when the app has provider credentials.
	ReportStatus *bool               `yaml:"report_status,omitempty" json:"report_status,omitempty"`
	Timeout      Duration            `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	Templates    map[string]Template `yaml:"templates,omitempty" json:"templates,omitempty"`
	Jobs         map[string]*Job     `yaml:"jobs" json:"jobs"`
	// JobOrder is the order jobs appear in the file, kept for stable display.
	JobOrder []string `yaml:"-" json:"job_order"`
}

type DeployRequest struct {
	Service  string
	Image    string
	Strategy string
	Wait     time.Duration
}

type DirFetcher interface {
	FetchFiles(ctx context.Context, url, token, branch, sha string, dirs []string) (RepoFiles, error)
}

type Duration time.Duration

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

type Event struct {
	Kind   string
	Branch string
	Tag    string
	// Fork marks a pull request whose source is another repository.
	Fork bool
	// HeadRepo is that source repository's full name, for the trigger log.
	HeadRepo string
	// Action is a pull request's normalized action (opened, synchronize).
	Action string
	// Changed lists the files the event touched. ChangedFn, when set, is
	// called at most once to fetch the list when Changed is empty. An
	// empty result means the list is unknown, so path filters pass.
	Changed   []string
	ChangedFn func(ctx context.Context) ([]string, error)
}

type FilterView struct {
	Paths        []string `json:"paths"`
	PathsIgnore  []string `json:"paths_ignore"`
	ReportStatus bool     `json:"report_status"`
	// Split is true when push and pull_request carry different filters. The
	// shown Paths and PathsIgnore are the push trigger's, and writing them
	// through ApplyFilters would overwrite the pull request ones.
	Split bool `json:"split"`
}

type GitFetcher struct{}

type Input struct {
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`
	Default     string   `yaml:"default,omitempty" json:"default,omitempty"`
	Required    bool     `yaml:"required,omitempty" json:"required,omitempty"`
	Options     []string `yaml:"options,omitempty" json:"options,omitempty"`
}

type Issue struct {
	Path    string `json:"path"`
	Line    int    `json:"line"`
	Message string `json:"message"`
}

type Job struct {
	Name            string            `yaml:"name,omitempty" json:"name,omitempty"`
	Stage           string            `yaml:"stage,omitempty" json:"stage,omitempty"`
	Needs           StringList        `yaml:"needs,omitempty" json:"needs,omitempty"`
	If              string            `yaml:"if,omitempty" json:"if,omitempty"`
	Image           string            `yaml:"image,omitempty" json:"image,omitempty"`
	Node            string            `yaml:"node,omitempty" json:"node,omitempty"`
	Env             map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Matrix          *Matrix           `yaml:"matrix,omitempty" json:"matrix,omitempty"`
	Resources       *Resources        `yaml:"resources,omitempty" json:"resources,omitempty"`
	Timeout         Duration          `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	Retries         int               `yaml:"retries,omitempty" json:"retries,omitempty"`
	ContinueOnError bool              `yaml:"continue_on_error,omitempty" json:"continue_on_error,omitempty"`
	Checkout        *bool             `yaml:"checkout,omitempty" json:"checkout,omitempty"`
	Cache           []CacheSpec       `yaml:"cache,omitempty" json:"cache,omitempty"`
	OIDC            *OIDCRequest      `yaml:"oidc,omitempty" json:"oidc,omitempty"`
	Steps           []Step            `yaml:"steps" json:"steps"`
}

type ManualTrigger struct {
	Inputs map[string]Input `yaml:"inputs,omitempty" json:"inputs,omitempty"`
}

type Matrix struct {
	Vars    map[string]StringList `yaml:",inline" json:"vars,omitempty"`
	Include []map[string]string   `yaml:"include,omitempty" json:"include,omitempty"`
	Exclude []map[string]string   `yaml:"exclude,omitempty" json:"exclude,omitempty"`
}

type MergeGroupTrigger struct {
	Branches StringList `yaml:"branches,omitempty" json:"branches,omitempty"`
}

type OIDCIssuer func(ctx context.Context, req OIDCTokenRequest) (string, error)

type OIDCRequest struct {
	// Audience is the token's "aud" claim, the value the cloud
	// provider's trust policy expects (e.g. "sts.amazonaws.com").
	// Pre-minted at job start and injected as PIPELINE_OIDC_TOKEN.
	Audience string `yaml:"audience,omitempty" json:"audience,omitempty"`
	// Audiences lists every additional audience this job may request a
	// token for at runtime, one at a time, via PIPELINE_OIDC_REQUEST_URL
	// (Audience is always implicitly allowed too). A job that needs
	// tokens for more than one audience in the same run (e.g. one step
	// calling AWS, another GCP) uses this instead of pre-minting every
	// combination up front.
	Audiences []string `yaml:"audiences,omitempty" json:"audiences,omitempty"`
}

type OIDCTokenRequest struct {
	Audience   string
	Subject    string
	Repo       string
	Ref        string
	PipelineID string
}

type PRTrigger struct {
	Branches StringList `yaml:"branches,omitempty" json:"branches,omitempty"`
	// Types limits which pull request actions start a run: opened,
	// reopened, synchronize. Empty means all three.
	Types       StringList `yaml:"types,omitempty" json:"types,omitempty"`
	Paths       StringList `yaml:"paths,omitempty" json:"paths,omitempty"`
	PathsIgnore StringList `yaml:"paths_ignore,omitempty" json:"paths_ignore,omitempty"`
	// Forks is block (the default), approve (hold the run until an
	// approver releases it), or allow.
	Forks string `yaml:"forks,omitempty" json:"forks,omitempty"`
}

type RefTrigger struct {
	Branches    StringList `yaml:"branches,omitempty" json:"branches,omitempty"`
	Paths       StringList `yaml:"paths,omitempty" json:"paths,omitempty"`
	PathsIgnore StringList `yaml:"paths_ignore,omitempty" json:"paths_ignore,omitempty"`
}

type RepoFiles struct {
	SHA   string
	Dir   string
	Files map[string][]byte
	// Oversize lists files skipped for exceeding maxSyncFileSize, by size.
	Oversize map[string]int64
}

type ReportReceipt struct {
	Provider string
	// URL is the dashboard page the status links to, empty when the
	// control plane has no dashboard URL configured.
	URL string
}

type ReportRequest struct {
	App         string
	Pipeline    string
	RunID       string
	RunNumber   int
	SHA         string
	Ref         string
	State       string
	Description string
	// Context labels the status so several pipelines stay distinct.
	Context string
}

type Resources struct {
	Memory string  `yaml:"memory,omitempty" json:"memory,omitempty"`
	CPU    float64 `yaml:"cpu,omitempty" json:"cpu,omitempty"`
}

type Runtime interface {
	Create(ctx context.Context, spec docker.ContainerSpec) (string, error)
	Start(ctx context.Context, id string) error
	Remove(ctx context.Context, id string, force bool) error
	ListByPrefix(ctx context.Context, prefix string) ([]docker.ContainerState, error)
	EnsureVolume(ctx context.Context, name string) error
	ExecWithInput(ctx context.Context, containerID string, cmd []string, stdin io.Reader) (io.ReadCloser, error)
}

type RuntimeResolver func(nodeID string) (Runtime, error)

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

type Scope struct {
	Vars      map[string]string
	Success   bool
	Failure   bool
	Cancelled bool
}

type SecretResolver interface {
	Resolve(ctx context.Context, app, key string) (string, error)
}

type Source interface {
	RepoInfo(ctx context.Context, app string) (url, token string, err error)
}

type StartOptions struct {
	Trigger string
	Actor   string
	Ref     string
	SHA     string
	Inputs  map[string]string
	// BaseBranch is a pull request's target branch, which trigger filters
	// match against instead of the source branch in Ref.
	BaseBranch string
	// Hold, when set, creates the run held for approval with this reason:
	// no job starts and no secret is read until an approver releases it.
	Hold string
}

type StatusReporter interface {
	ReportRun(ctx context.Context, req ReportRequest) (ReportReceipt, error)
}

type Step struct {
	ID              string            `yaml:"id,omitempty" json:"id,omitempty"`
	Name            string            `yaml:"name,omitempty" json:"name,omitempty"`
	Run             string            `yaml:"run,omitempty" json:"run,omitempty"`
	Uses            string            `yaml:"uses,omitempty" json:"uses,omitempty"`
	With            map[string]string `yaml:"with,omitempty" json:"with,omitempty"`
	Env             map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Secrets         []string          `yaml:"secrets,omitempty" json:"secrets,omitempty"`
	If              string            `yaml:"if,omitempty" json:"if,omitempty"`
	Timeout         Duration          `yaml:"timeout,omitempty" json:"timeout,omitempty"`
	Retries         int               `yaml:"retries,omitempty" json:"retries,omitempty"`
	ContinueOnError bool              `yaml:"continue_on_error,omitempty" json:"continue_on_error,omitempty"`
}

type Store interface {
	GetPipeline(ctx context.Context, id string) (store.Pipeline, error)
	ListPipelines(ctx context.Context, app string) ([]store.Pipeline, error)
	CreatePipelineRun(ctx context.Context, r store.PipelineRun) (store.PipelineRun, error)
	GetPipelineRun(ctx context.Context, id string) (store.PipelineRun, error)
	ListActivePipelineRuns(ctx context.Context) ([]store.PipelineRun, error)
	ListPipelineRunsInGroup(ctx context.Context, group string) ([]store.PipelineRun, error)
	SetPipelineRunStatus(ctx context.Context, id, status, reason string, started, finished *time.Time) error
	RequestPipelineRunCancel(ctx context.Context, id string) error
	CreatePipelineJobs(ctx context.Context, jobs []store.PipelineJob) error
	ListPipelineJobs(ctx context.Context, runID string) ([]store.PipelineJob, error)
	SetPipelineJobStatus(ctx context.Context, id, status, reason, nodeID string, attempt int, started, finished *time.Time) error
	SetPipelineJobOutputs(ctx context.Context, id, outputsJSON string) error
	SetPipelineStepStatus(ctx context.Context, jobID string, idx int, status, reason string, exitCode *int, attempt int, started, finished *time.Time) error
	AppendPipelineLogs(ctx context.Context, lines []store.PipelineLogLine) error
	CreatePipelineApproval(ctx context.Context, a store.PipelineApproval) error
	ListPipelineApprovals(ctx context.Context, runID string) ([]store.PipelineApproval, error)
	PrunePipelineRuns(ctx context.Context, keep int) (int64, error)
	AddPipelineTriggerLog(ctx context.Context, e store.PipelineTriggerLog) error
	DecidePipelineRunHold(ctx context.Context, id string, approved bool, by string, now time.Time) (bool, error)
}

type StringList []string

type SyncConfig struct {
	Store   SyncStore
	Source  Source
	Fetcher DirFetcher
	// BrandName is the brand short name for the branded pipeline directory.
	BrandName string
	Logger    *slog.Logger
	Now       func() time.Time
	NewID     func() string
}

type SyncItem struct {
	File    string `json:"file"`
	Name    string `json:"name"`
	Outcome string `json:"outcome"`
	Message string `json:"message,omitempty"`
}

type SyncResult struct {
	SHA   string     `json:"sha"`
	Dir   string     `json:"dir,omitempty"`
	Items []SyncItem `json:"items"`
}

type SyncStore interface {
	ListPipelines(ctx context.Context, app string) ([]store.Pipeline, error)
	SavePipeline(ctx context.Context, p store.Pipeline) (store.Pipeline, error)
	GetPipelineSync(ctx context.Context, app string) (store.PipelineSync, error)
	SavePipelineSync(ctx context.Context, s store.PipelineSync) error
	GetGitSource(ctx context.Context, serviceName string) (*store.GitSource, error)
}

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

type TagTrigger struct {
	Patterns StringList `yaml:"patterns,omitempty" json:"patterns,omitempty"`
}

type Template struct {
	Params []string `yaml:"params,omitempty" json:"params,omitempty"`
	Steps  []Step   `yaml:"steps" json:"steps"`
}

type Triggers struct {
	Push        *RefTrigger        `yaml:"push,omitempty" json:"push,omitempty"`
	PullRequest *PRTrigger         `yaml:"pull_request,omitempty" json:"pull_request,omitempty"`
	Tag         *TagTrigger        `yaml:"tag,omitempty" json:"tag,omitempty"`
	MergeGroup  *MergeGroupTrigger `yaml:"merge_group,omitempty" json:"merge_group,omitempty"`
	Manual      *ManualTrigger     `yaml:"manual,omitempty" json:"manual,omitempty"`
	Schedule    []string           `yaml:"schedule,omitempty" json:"schedule,omitempty"`
	API         bool               `yaml:"api,omitempty" json:"api,omitempty"`
}

type VolumeRemover interface {
	RemoveVolume(ctx context.Context, name string) error
}