deploy

type AppStore interface {
	SaveApp(ctx context.Context, a store.App) error
	GetAppByName(ctx context.Context, name string) (store.App, error)
	UpdateServiceApp(ctx context.Context, serviceName, appID string) error
}

type AttemptRecorder interface {
	SetDeployAttemptDigest(ctx context.Context, id, digest, reason string) error
}

type AutoscaleStore interface {
	GetAutoscalePolicy(ctx context.Context, app string) (autoscale.Policy, error)
	SaveAutoscalePolicy(ctx context.Context, p autoscale.Policy, ev autoscale.Event, now time.Time) error
	AutoscaleReplicas(ctx context.Context, app string) (int, bool, error)
}

type BuildCacheProvider interface {
	S3Cache(ctx context.Context, app string) (*build.S3Cache, error)
	RecordBuild(ctx context.Context, app, warning string)
}

type BuildMetricsRecorder interface {
	RecordBuildDuration(ctx context.Context, serviceName string, d time.Duration, at time.Time) error
}

type BuildOnlyRequest struct {
	// Type is "dockerfile" (default) or "railpack".
	Type          string
	SourceDir     string
	BaseDirectory string
	Dockerfile    string
	Tag           string
	Args          map[string]string
}

type BuildSecretSource interface {
	BuildSecrets(ctx context.Context, serviceName string) (pkgregistry.Output, error)
}

type BuildSecretValues interface {
	Exists(ctx context.Context, serviceName, envKey string) (bool, error)
	Resolve(ctx context.Context, serviceName, envKey string) (string, error)
	// BuildEnabled reports whether the secret is opted in for build use.
	BuildEnabled(ctx context.Context, serviceName, envKey string) (bool, error)
}

type CanaryPolicyStore interface {
	SetCanaryPolicy(ctx context.Context, p store.CanaryPolicy) error
	DeleteCanaryPolicy(ctx context.Context, serviceName string) error
}

type CancelOutcome int

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

type FreezeStatus struct {
	Frozen bool
	// Until is when the latest-ending active window closes.
	Until    time.Time
	Reason   string
	WindowID string
}

type FreezeStore interface {
	ListDeployFreezeWindows(ctx context.Context, scopes ...string) ([]store.DeployFreezeWindow, error)
}

type FrozenError struct{ Status FreezeStatus }

type HeldRequest struct {
	Kind        string    `json:"kind"`
	Image       string    `json:"image,omitempty"`
	CheckoutRef string    `json:"checkout_ref,omitempty"`
	CommitLabel string    `json:"commit_label,omitempty"`
	CommitSHA   string    `json:"commit_sha,omitempty"`
	Before      string    `json:"before,omitempty"`
	CommitAt    time.Time `json:"commit_at,omitempty"`
	// Branch lets a newer queued deploy supersede older ones of the same branch.
	Branch string `json:"branch,omitempty"`
	// FreezeNote is set when a manual deploy overrode a freeze window, so the
	// queue does not hold it behind that window again.
	FreezeNote string `json:"freeze_note,omitempty"`
	// Build is a queued manual build's original request body.
	Build json.RawMessage `json:"build,omitempty"`
	// BuildArgs are the trigger build args a replay passes to the build again.
	BuildArgs map[string]string `json:"build_args,omitempty"`
	// PushMirror and HeldRef locate a held push: the mirror and the ref that
	// keeps its commit until the hold is decided.
	PushMirror string `json:"push_mirror,omitempty"`
	HeldRef    string `json:"held_ref,omitempty"`
	// AllowPrivateRepoAuth records the requester's ability to mint repo tokens.
	AllowPrivateRepoAuth bool `json:"allow_private_repo_auth,omitempty"`
}

type HeldStore interface {
	SaveDeployAttempt(ctx context.Context, a store.DeployAttempt) error
	ListHeldDeployAttempts(ctx context.Context) ([]store.DeployAttempt, error)
	TransitionDeployAttempt(ctx context.Context, id, from, to, reason string) (bool, error)
}

type ImageBuilder interface {
	Build(ctx context.Context, req build.Request, progress func(build.ProgressEvent)) (*build.Result, error)

	// BuildRailpack builds a service whose build.Type is
	// spec.BuildRailpack: Railpack's own provider detection replaces a
	// user-authored Dockerfile, scoped to node and golang only (see
	// deployRailpack). A separate method, not a build.Request field,
	// because internal/build's own solve path is genuinely different
	// (Definition-based, not dockerfile.v0-frontend-based; see
	// internal/build/railpack.go's package doc comment).
	BuildRailpack(ctx context.Context, req build.RailpackRequest, progress func(build.ProgressEvent)) (*build.Result, error)
}

type ImageDeployStore interface {
	SaveDesiredService(ctx context.Context, svc store.DesiredService) error
	SaveDeployAttempt(ctx context.Context, a store.DeployAttempt) error
	FinishDeployAttempt(ctx context.Context, id, status string, finishedAt time.Time, errMsg string) error
}

type ImageResolution struct {
	// Image is the reference to write as desired state: pinned to a
	// registry digest whenever one is known.
	Image string
	// Digest is the content identity recorded in deploy history.
	Digest string
	// LocalID is a local image ID, set only when no registry digest exists.
	LocalID string
	// Reason is one of the store.DigestReason* constants.
	Reason string
	// Note carries the registry error behind a fallback, for the operator.
	Note string
}

type ImageTrigger struct {
	Store    ImageDeployStore
	Nudger   ReconcileNudger
	Resolver docker.ImageResolver
	// Ordered and Sequencer together enable the stale-deploy guard.
	Ordered   OrderedStore
	Sequencer Sequencer
	Logger    *slog.Logger
	Source    string
	// RequireFresh fails instead of deploying a cached image (deploy --pull).
	RequireFresh bool
	// Automatic subjects the deploy to the stale guard; manual ones are exempt.
	Automatic bool
	// Auth authenticates digest resolution against a private registry.
	Auth *docker.RegistryAuth
	// Reason is recorded on the attempt, e.g. a freeze override.
	Reason string
	// RerunOf links the recorded attempt to the one it retries.
	RerunOf string
	// Locks, when set, holds the deploy instead of making it live while the
	// app's publish lock is on. Set it on automatic triggers only.
	Locks PublishLocks
}

type JobStore interface {
	SyncSpecScheduledTasks(ctx context.Context, serviceName string, jobs []store.ScheduledTask, now time.Time, newID func() (string, error)) error
}

type LoadBalancerStore interface {
	SetServiceLoadBalancer(ctx context.Context, service, configJSON string) error
}

type MaintenanceFreezeStore interface {
	FreezeMaintenanceWindows(ctx context.Context, serviceName string, now time.Time) ([]store.DeployFreezeWindow, error)
}

type MultiRequest struct {
	// AppName identifies the store.App every fanned-out service is
	// linked to (created if it doesn't exist yet, reused if it does: see
	// DeploySpec's own doc comment). Each service's own DesiredService
	// name is "<AppName>-<serviceKey>", the flat naming convention
	// internal/api/apps_group.go's own doc comment establishes.
	AppName string
	// Services is app.yaml's services: map, keyed by service name (e.g.
	// "web", "worker").
	Services map[string]spec.Service
	// SourceDir is the local checkout root, shared by every service's
	// build: one git checkout produces every service's image.
	SourceDir string
	CommitSHA string
	// ImageRepoBase is the image name without a tag or per-service
	// suffix, e.g. "levelrail/myapp"; each service tags as
	// "<ImageRepoBase>-<serviceKey>:<CommitSHA>".
	ImageRepoBase string
	// SingleServiceName, when set, replaces "<AppName>-<serviceKey>" as
	// the sole service's name. DeploySpec rejects it alongside more than
	// one service. Set only by "apps create --file"'s build.type: static
	// path (internal/api/apps_multi.go), so the deployed site is named
	// after the app itself rather than a redundant "<app>-<service>"
	// suffix; every other caller leaves it empty.
	SingleServiceName string
	// Preview marks a pull request preview build (see Request.Preview).
	Preview bool
}

type Option func(*Pipeline)

type OrderedStore interface {
	SaveDesiredServiceOrdered(ctx context.Context, svc store.DesiredService, order store.DeployOrder, check store.DeployOrderCheck) error
}

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

type PortAdmitter interface {
	AdmitPublishedPorts(ctx context.Context, desired store.DesiredService) (release func(), err error)
}

type PublishLocks interface {
	GetPublishLock(ctx context.Context, name string) (*store.PublishLock, error)
	SaveHeldBuild(ctx context.Context, deployID string, svc store.DesiredService, at time.Time) error
}

type ReconcileNudger interface {
	Nudge()
}

type RegistryAuthSource interface {
	RegistryAuth(ctx context.Context, credentialID string) (*docker.RegistryAuth, error)
}

type ReleaseHandler func(ctx context.Context, attempt store.DeployAttempt, req HeldRequest) error

type Releaser struct {
	Store    HeldStore
	Freeze   FreezeStore
	Handlers map[string]ReleaseHandler
	Logger   *slog.Logger
	Now      func() time.Time
}

type Request struct {
	// ServiceName identifies the service, matching the name the
	// application controller (1.3) reconciles under.
	ServiceName string
	// Service is the app.yaml service block: build config, port, env,
	// resources, health.
	Service spec.Service
	// SourceDir is the local checkout root, the build context.
	SourceDir string
	// CommitSHA tags the built image, and is what a future rollback
	// command points desired.Image back at.
	CommitSHA string
	// ImageRepo is the image name without a tag, e.g. "levelrail/thesvg".
	// Naming policy (namespacing, registry prefix) is the caller's
	// decision, not this package's.
	ImageRepo string

	// AttemptID, when set, receives the resolved digest (WithAttemptRecorder).
	AttemptID string
	// Order enables the stale-deploy guard (WithOrderedStore); nil skips it.
	Order *store.DeployOrder
	// RequireFreshImage fails an image deploy whose registry is unreachable
	// instead of falling back to the cached image.
	RequireFreshImage bool
	// Commit, when set, runs right before desired state is written and can
	// veto it (ErrCanceled), the last point a deploy is cancelable.
	Commit func() error
	// NoCache disables BuildKit's layer cache for a dockerfile build.
	NoCache bool
	// Preview marks a pull request preview build, which may not use
	// build.secrets unless APP_PREVIEW_BUILD_SECRETS is true.
	Preview bool
}

type RolloutPolicyStore interface {
	SetRolloutPolicy(ctx context.Context, p store.RolloutPolicy) error
	DeleteRolloutPolicy(ctx context.Context, serviceName string) error
}

type SecretChecker interface {
	Exists(ctx context.Context, serviceName, envKey string) (bool, error)
}

type SecretScanHook interface {
	BeforeDeploy(ctx context.Context, app, attemptID, root string, env map[string]string) error
}

type Sequencer interface {
	NextDeploySequence(ctx context.Context, serviceName string) (int64, error)
}

type ServiceOutcome struct {
	ServiceKey  string
	ServiceName string
	Image       string
	Err         error
}

type ServiceStore interface {
	SaveDesiredService(ctx context.Context, svc store.DesiredService) error
	// GetRegistryCredentialByName resolves build.type: image's optional
	// registryCredential field (a name, spec.Build.RegistryCredential's
	// own doc comment on why not an ID) at deploy time, in deployImage.
	GetRegistryCredentialByName(ctx context.Context, name string) (store.RegistryCredential, error)
	// GetDesiredDatabase resolves a { from: "<database>.<field>" } env
	// var's database at deploy time (validateEnv), so an app referencing
	// an unknown database fails the deploy itself rather than only
	// surfacing later as a reconcile failure.
	GetDesiredDatabase(ctx context.Context, name string) (*store.DesiredDatabase, error)
}

type SpendCapStore interface {
	SaveSpendCap(ctx context.Context, c spendcap.Cap, ev spendcap.Event, now time.Time) error
}

type SpendGuardHook interface {
	BeforeDeploy(ctx context.Context, app string) error
}

type StaticExtractor interface {
	ExtractDir(ctx context.Context, tag, srcPath, destDir string) error
}

type StaticHolds interface {
	SaveHeldStaticBuild(ctx context.Context, deployID string, site store.StaticSite, at time.Time) error
}

type StaticPublishHook func(ctx context.Context, app string) error

type StaticPublishRecorder interface {
	SetDeployAttemptDigest(ctx context.Context, id, digest, reason string) error
	SetDeployAttemptRollout(ctx context.Context, id, state string) error
	RecordGateEvent(ctx context.Context, e store.DeployGateEvent) error
}

type StaticRetentionStore interface {
	ListDeployAttempts(ctx context.Context, serviceName string) ([]store.DeployAttempt, error)
	ListStaticSites(ctx context.Context) ([]store.StaticSite, error)
	GetPublishLock(ctx context.Context, name string) (*store.PublishLock, error)
}

type StaticSiteStore interface {
	SaveStaticSite(ctx context.Context, site store.StaticSite) error
}

type StaticTreeStats struct {
	Digest string
	Files  int
	Bytes  int64
}

type SupersededError struct {
	// Reason is store.DeployReasonSuperseded or store.DeployReasonStale.
	Reason  string
	Message string
}

type SupplyChainHook interface {
	AfterBuild(ctx context.Context, app, attemptID string, att build.Attestations) error
}

type VaultConfigChecker interface {
	VaultConfigured(ctx context.Context) (bool, error)
}