upgrade

type Attempt struct {
	ID           string    `json:"id"`
	From         string    `json:"from"`
	To           string    `json:"to"`
	Image        string    `json:"image"`
	Tag          string    `json:"tag,omitempty"`
	StartedAt    time.Time `json:"started_at"`
	StartedBy    string    `json:"started_by"`
	Automatic    bool      `json:"automatic"`
	BackupID     string    `json:"backup_id,omitempty"`
	SkipBackup   bool      `json:"skip_backup"`
	State        string    `json:"state"`
	FinishedAt   time.Time `json:"finished_at,omitzero"`
	Reason       string    `json:"reason,omitempty"`
	Logs         string    `json:"logs,omitempty"`
	SnapshotAt   time.Time `json:"snapshot_at,omitzero"`
	SnapshotGone bool      `json:"snapshot_gone"`
	// Recorded is set once a Pando has written the outcome to the audit log.
	Recorded bool `json:"recorded"`
}

type Database interface {
	Snapshot(ctx context.Context) error
	Restore(ctx context.Context) error
}

type Plan struct {
	Current  string `json:"current"`
	Target   string `json:"target"`
	Possible bool   `json:"possible"`
	// Reasons say why it is not possible, each with what to change (R-105).
	Reasons []string `json:"reasons"`
	Image   string   `json:"image,omitempty"`
	Tag     string   `json:"tag,omitempty"`
	// Breaking are the versions in between that may break what works now
	// (R-360), with their notes. Non-empty means the target version must be
	// typed to confirm.
	Breaking []update.Release `json:"breaking"`
	// Unavailable while it lasts: every app, because the proxy is in Pando.
	Note string `json:"note"`
}

type Request struct {
	Version string `json:"version"`
	// ConfirmBreaking is the target version, typed, when Plan.Breaking is not
	// empty (R-360).
	ConfirmBreaking string `json:"confirm_breaking,omitempty"`
	// Passphrase encrypts the full backup taken first (R-358).
	Passphrase secret.Value `json:"passphrase"`
	// SkipBackup says, explicitly, to go ahead without one.
	SkipBackup bool `json:"skip_backup,omitempty"`
	// Automatic is the schedule's (R-361): no backup, only the copy.
	Automatic bool `json:"-"`
}

type Service struct {
	Version string
	Updates interface {
		Status(ctx context.Context) (update.Status, error)
	}
	// Verify checks the target version's image signature and returns its
	// digest (R-357).
	Verify func(ctx context.Context, version string) (string, error)
	// Runtime is the runtime Pando runs on, with its capabilities.
	Runtime func(ctx context.Context) (api.RuntimeAdapter, error)
	Policy  func(ctx context.Context) (policy.Document, error)
	// CanCopy checks the database account may take the rollback copy.
	CanCopy func(ctx context.Context) error
	// Backup takes and records a full backup, returning its ID (R-358).
	Backup func(ctx context.Context, p authz.Principal, passphrase secret.Value) (string, error)
	// Recipients are the people holding install.upgrade (R-362).
	Recipients func(ctx context.Context) ([]string, error)
	// DropSnapshot removes the rollback copy after the soak.
	DropSnapshot func(ctx context.Context) error
	Notify       func(ctx context.Context, n api.Notification) error
	Audit        func(ctx context.Context, e audit.Event)
	// Replicas counts the live Pando processes serving this install. An
	// in-place upgrade is for one (issue #72).
	Replicas func(ctx context.Context) (int, error)
	// Hosts counts the cluster's hosts, this one included (R-414). An
	// in-place upgrade is for an install on one (R-359, R-417).
	Hosts func(ctx context.Context) (int, error)

	DatabaseURL  secret.Value
	WorkDir      string
	Port         string
	ReadyTimeout time.Duration
	Soak         time.Duration
	Clock        clock.Clock
	Logger       *zap.Logger
}

type Swap interface {
	Stop(ctx context.Context) error
	Recreate(ctx context.Context, image string) error
	Ready(ctx context.Context, timeout time.Duration) error
	// Version is the version the new container's image says it is, from its
	// org.opencontainers.image.version label; empty when it has none.
	Version(ctx context.Context) (string, error)
	Logs(ctx context.Context) string
	Discard(ctx context.Context)
	Restore(ctx context.Context) error
	Finish(ctx context.Context, image, tag string) error
}