upgradesched

type AckError struct{ IDs []string }

type AttemptInfo struct {
	ID      string
	Outcome string
	Error   string
}

type Breaking struct {
	ID          string
	Version     string
	Summary     string
	RequiresAck bool
}

type Candidate struct {
	Tag         string
	PublishedAt time.Time
}

type Config struct {
	// Grace is how long after a manual run_at the scheduler keeps retrying.
	Grace time.Duration
	// RetryInterval is the minimum gap between fire-time re-checks.
	RetryInterval time.Duration
	// StartTimeout is how long a fired upgrade may show no attempt before it
	// is reported as not started.
	StartTimeout time.Duration
	// MaxAhead bounds how far in the future a manual schedule may be.
	MaxAhead time.Duration
	// MinLead is the shortest time between now and a scheduled run.
	MinLead time.Duration
}

type Host interface {
	// Latest is the newest release on the configured channel. It returns the
	// candidate together with ErrEdgeTarget when that is an edge image.
	Latest(ctx context.Context) (Candidate, bool, error)
	// Plan describes target, or returns ErrReleaseNotFound.
	Plan(ctx context.Context, target string) (Plan, error)
	// Preflight evaluates the checks for target, bypassing release caches.
	Preflight(ctx context.Context, target string) (PreflightResult, error)
	// BackupNow takes a control plane backup and returns its name.
	BackupNow(ctx context.Context) (string, error)
	// Apply starts the host upgrade.
	Apply(ctx context.Context, target string, ack []string, initiator string) error
	// Running reports whether a self-upgrade is in progress on the host.
	Running(ctx context.Context) bool
	// Attempt finds the newest recorded attempt started by initiator.
	Attempt(ctx context.Context, initiator string) (AttemptInfo, bool, error)
}

type Notifier interface {
	Notify(ctx context.Context, channelIDs []string, text string) error
}

type Plan struct {
	Current        string
	Target         string
	Breaking       []Breaking
	NotesAvailable bool
	CanApply       bool
	CannotApplyWhy string
	PublishedAt    time.Time
}

type Policy struct {
	Mode              string
	Window            Window
	MinReleaseAgeDays int
	Paused            bool
	NotifyChannelIDs  []string
}

type PreflightResult struct {
	Checks  []upgrade.Check
	Blocked bool
	// Edge is set when the target is an edge container image, which is never
	// installable by an upgrade.
	Edge bool
}

type Request struct {
	// Target is the release tag, empty for the newest on the channel.
	Target string
	// At is the earliest run time. Ignored when Window is set.
	At time.Time
	// Window runs in the next maintenance window instead of at At.
	Window bool
	// Timezone is the zone the operator thinks in, recorded for display.
	Timezone string
	Ack      []string
	MajorAck bool
	// Replace cancels a pending or blocked schedule first.
	Replace bool
	Actor   string
}

type Scheduler struct {
	Store    Store
	Host     Host
	Windows  func(ctx context.Context) ([]alerting.MaintenanceWindow, error)
	Notifier Notifier
	Config   Config
	Logger   *slog.Logger
	Now      func() time.Time
	// Current returns the running version.
	Current func() string
	// Audit records a scheduler-initiated change in the audit log.
	Audit func(ctx context.Context, detail string)
	// NewID returns a schedule id.
	NewID func() string
	// contains filtered or unexported fields
}

type Span struct {
	Start time.Time
	End   time.Time
}

type Store interface {
	GetUpgradePolicy(ctx context.Context) (store.UpgradePolicy, error)
	SetUpgradeDecision(ctx context.Context, tag, decision, at string) error
	InsertUpgradeSchedule(ctx context.Context, s store.UpgradeSchedule) error
	ActiveUpgradeSchedule(ctx context.Context) (*store.UpgradeSchedule, error)
	ListUpgradeSchedules(ctx context.Context, limit int) ([]store.UpgradeSchedule, error)
	UpdateUpgradeSchedule(ctx context.Context, s store.UpgradeSchedule, from ...string) (bool, error)
}

type Verdict struct {
	OK     bool
	Code   string
	Reason string
	// WaitUntil is set when the only thing missing is time.
	WaitUntil time.Time
}

type Window struct {
	Cron     string
	Duration time.Duration
	Timezone string
}