updater

type CheckFn func(ctx context.Context, opts Options) (*Result, error)

type GateDecision struct {
	// Release gives back whatever the gate took. It is never nil, so callers can
	// defer it without checking, and it does nothing when the gate was never
	// taken.
	Release func()
	// Reason is the machine-readable refusal, empty when OK.
	Reason string
	// Message says the same thing in words, for a client with nothing better
	// to show.
	Message string
	// Forceable means a person may go ahead anyway. It is never true for
	// automatic installs, and never true for anything that risks data rather
	// than the user's session.
	Forceable bool
	// Expires means this is a soft signal that an automatic install may
	// ignore once the version has waited out autoInstallDeadline.
	Expires bool
	// OK means the update may go ahead.
	OK bool
}

type GateDeps struct {
	// IndexingStatus, OptimizationStatus and ScrapingStatus each return a
	// mediadb status string. An error is treated as "not running": a database
	// that cannot answer is a problem for the caller to notice elsewhere, and
	// refusing every update because of it would leave the device unfixable.
	IndexingStatus     func() (string, error)
	OptimizationStatus func() (string, error)
	ScrapingStatus     func() (string, error)

	// BackupActive reports whether a backup, restore or upload is running.
	BackupActive func() bool
	// ReaderWriteActive reports whether a reader is part-way through writing
	// a token.
	ReaderWriteActive func() bool
	// AcquireRestore takes the restore gate, which the install then holds so
	// a restore cannot start underneath it. The release function it returns
	// is carried on the decision.
	AcquireRestore func() (func(), error)
	// AcquireMediaGate stops anything new launching and waits for what is
	// already launching to settle, so the install's own look at what is
	// playing cannot be overtaken by a launch that starts a moment later. The
	// install holds it until the restart.
	//
	// The gate takes this after AcquireRestore, which is the order the rest of
	// the service takes those two locks in. Taking them the other way round is
	// a lock inversion, which is why neither is the caller's to take.
	AcquireMediaGate func(context.Context) (func(), error)

	// ActiveMedia, BackgroundMedia and ActivePlaylist report what the user
	// would lose if the service restarted now.
	ActiveMedia     func() bool
	BackgroundMedia func() bool
	ActivePlaylist  func() bool

	// Power reports where the device's power is coming from.
	Power func() power.Status

	// WaitForIdle blocks until the API has been quiet for a while. Only
	// automatic installs wait for it; a person pressing update is the request
	// that would otherwise stop it ever being idle.
	WaitForIdle func(context.Context) error

	// DeferredSince is when this version was first put off by a soft signal,
	// or the zero time if it has not been. Once that is more than
	// autoInstallDeadline ago the soft signals stop counting.
	DeferredSince func() time.Time

	// Now reads the clock. Tests replace it.
	Now func() time.Time
}

type GateError struct {
	Reason    string
	Message   string
	Forceable bool
}

type Mode string

type Options struct {
	UserDB UpdateBackupper
	// Progress is called as the update moves through its stages, when the
	// caller wants to follow along. Nil reports nothing.
	Progress ProgressFn
	// PreQuiesce runs at the last moment an install can still be called off.
	// The second power check goes here.
	PreQuiesce func(context.Context) error
	// Gate is what the device is busy with. A check uses it to report what
	// would stop an update going ahead right now; nil reports nothing.
	Gate       *GateDeps
	Payload    []updatepayload.File
	PlatformID string
	Channel    string
	DataDir    string
	// DeviceID is this device's identifier, used to work out whether a staged
	// rollout has reached it yet. Empty means only fully released versions
	// count as rolled out.
	DeviceID string
	// Mode is who asked. It decides how the install is recorded and, for
	// automatic installs, that nothing may be forced.
	Mode Mode
	// Managed says a package manager owns this install, which the check
	// reports as the reason OTA updates do not apply here.
	Managed bool
}

type OutcomeReport struct {
	At          time.Time `json:"at"`
	Outcome     string    `json:"outcome"`
	FromVersion string    `json:"fromVersion,omitempty"`
	ToVersion   string    `json:"toVersion,omitempty"`
	Detail      string    `json:"detail,omitempty"`
}

type Progress struct {
	Stage           ProgressStage `json:"stage"`
	Version         string        `json:"version,omitempty"`
	Trigger         string        `json:"trigger,omitempty"`
	Error           string        `json:"error,omitempty"`
	BytesDownloaded int64         `json:"bytesDownloaded,omitempty"`
	BytesTotal      int64         `json:"bytesTotal,omitempty"`
}

type ProgressFn func(Progress)

type ProgressStage string

type Result struct {
	CheckedAt        time.Time
	DeferredSince    time.Time
	LastResult       *OutcomeReport
	Eligibility      string
	ReleaseNotes     string
	Channel          string
	LatestVersion    string
	DeferredReason   string
	BlockedReason    string
	BlockedMessage   string
	CurrentVersion   string
	UpdateAvailable  bool
	RolloutHeld      bool
	BlockedForceable bool
}

type StageOptions struct {
	Release *otameta.Release

	PlatformID     string
	Arch           string
	OS             string
	TargetPath     string
	StagingRoot    string
	CurrentVersion string
	// contains filtered or unexported fields
}

type StagedUpdate struct {
	// Dir is the staging directory holding the archive and the payload.
	// Removing it undoes the whole staging attempt.
	Dir string
	// BinaryPath is the new executable. It came out of an archive whose bytes on
	// disk were checked against the signed manifest immediately before it was
	// read, and it has answered a version probe on this device.
	BinaryPath string
	// ArchivePath is the downloaded archive, kept so a later stage can report
	// what it installed from.
	ArchivePath string
	// Version is the release version, without the tag's leading v.
	Version string
	// contains filtered or unexported fields
}

type UpdateBackupper interface {
	BackupForUpdate(targetVersion string) (database.BackupInfo, func() error, error)
}