updater

type ApplyOptions struct {
	// Target is the installed binary replaced for KindBinary updates.
	// Empty: os.Executable().
	Target string
	// DownloadDir for the artifact. Empty: temp dir.
	DownloadDir string
	// LaunchInstaller starts a downloaded installer/.dmg. Nil: the
	// platform default (exec the installer / `open` on macOS).
	LaunchInstaller func(ctx context.Context, path string) error
	Progress        ProgressFunc
}

type Artifact struct {
	OS       string `json:"os"`   // runtime.GOOS
	Arch     string `json:"arch"` // runtime.GOARCH, or "universal" (macOS)
	Kind     string `json:"kind"` // KindBinary | KindInstaller | KindArchive
	URL      string `json:"url"`
	SHA256   string `json:"sha256"` // hex, lowercase
	Size     int64  `json:"size"`
	Filename string `json:"filename,omitempty"`
}

type AvailableUpdate struct {
	Version     string     `json:"version"`
	Kind        string     `json:"kind"`
	NotesURL    string     `json:"notesUrl,omitempty"`
	Notes       string     `json:"notes,omitempty"`
	PublishedAt *time.Time `json:"publishedAt,omitempty"`
	Staged      bool       `json:"staged"`
}

type Checker interface {
	Check(ctx context.Context) (*Update, error)
	Download(ctx context.Context, upd *Update, dir string, progress ProgressFunc) (string, error)
}

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

type ClusterUpdateStatus struct {
	// LeaseHeld is true while this node holds the cluster update lease
	// for an install.
	LeaseHeld bool `json:"leaseHeld"`
	// LeaseHolder is the node last seen holding the lease (this node's
	// name when LeaseHeld).
	LeaseHolder     string     `json:"leaseHolder,omitempty"`
	Draining        bool       `json:"draining"`
	DrainStarted    *time.Time `json:"drainStarted,omitempty"`
	MaxDrainSeconds int        `json:"maxDrainSeconds"`
}

type Coordinator interface {
	// AcquireUpdate takes, or renews, the update lease for version. ok is
	// false while another node (holder) holds it; err wraps
	// ErrClusterRolledBack for a release that rolled back elsewhere.
	AcquireUpdate(ctx context.Context, version string) (ok bool, holder string, err error)
	// ReleaseUpdate gives the lease back if this node holds it.
	ReleaseUpdate(ctx context.Context) error
	// ReportFailed records that version rolled back on this node.
	ReportFailed(ctx context.Context, version string) error
	// SetDraining takes this node out of (true) or back into (false) the
	// rotation for new sessions.
	SetDraining(draining bool)
}

type Environment struct {
	GOOS        string
	Target      string // running executable
	Dev         bool   // IsDev()
	InContainer bool
	// Supervised: a service manager restarts the process after it exits.
	Supervised bool
	// DirWritable probes the executable's directory (default: DirWritable).
	DirWritable func(dir string) bool
}

type FailedUpdate struct {
	Version string    `json:"version"`
	From    string    `json:"from"`
	At      time.Time `json:"at"`
	Reason  string    `json:"reason"`
	// ReportPending is set by a rollback and cleared once a clustered node
	// has told the other nodes to skip Version. A successful rollback
	// restarts straight into the restored binary, so it is that process
	// (with no update to confirm) that reports.
	ReportPending bool `json:"reportPending,omitempty"`
}

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

type ManagerOptions struct {
	// NewClient builds the feed client for the current settings; it is
	// rebuilt when channel/feed change. Nil or failing at construction:
	// update checks are disabled (startup confirmation still runs).
	NewClient func(config.Updates) (Checker, error)
	// Config returns the live Updates settings.
	Config func() config.Updates
	// CurrentVersion is the running version (default: Version).
	CurrentVersion string
	// Dir is <dataDir>/updates: downloads and marker files.
	Dir string
	// Target is the running server executable that a binary update
	// replaces (default: os.Executable()).
	Target string
	// SelfApply reports whether this install may replace its own binary;
	// NotifyReason explains why not. See SelfApplyCapability.
	SelfApply    bool
	NotifyReason string
	// ActiveSessions returns how many playback / transcode / live TV
	// sessions are in progress. Nil: always idle.
	ActiveSessions func() int
	// RequestRestart asks the app to shut down gracefully and exit so the
	// service manager starts the new binary. Called at most once.
	RequestRestart func(reason string)
	// Boot is the result of ConfirmStartup for this process.
	Boot StartupResult
	// Coordinator, when set (a clustered node that can self-apply),
	// coordinates installs with the other nodes; nil keeps the standalone
	// behaviour (install after the server has been idle for QuietPeriod).
	Coordinator Coordinator
	// NodeName labels this node in status (the lease holder is compared
	// with it); optional.
	NodeName string
	// OnAvailable, when set, hears each release version a check finds,
	// without the manager's lock held. Once it returns nil for a version it
	// is not called for that version again in this process; an error makes
	// the next check that finds the version call it again.
	OnAvailable func(version string) error

	Now             func() time.Time
	Location        *time.Location // maintenance window zone (default time.Local)
	PollInterval    time.Duration
	FirstCheckDelay time.Duration
	RetryInterval   time.Duration
	QuietPeriod     time.Duration
	HealthPeriod    time.Duration
	Tick            time.Duration
	// ApplyBinary / CleanupOld default to the package functions.
	ApplyBinary func(newPath, target string) error
	CleanupOld  func(target string) error
	Logger      *slog.Logger
}

type ManagerStatus struct {
	Enabled            bool             `json:"enabled"`
	DisabledReason     string           `json:"disabledReason,omitempty"`
	Current            string           `json:"current"`
	Available          *AvailableUpdate `json:"available,omitempty"`
	Capability         string           `json:"capability"`
	CapabilityReason   string           `json:"capabilityReason,omitempty"`
	State              string           `json:"state"`
	AutoUpdate         bool             `json:"autoUpdate"`
	Requested          bool             `json:"requested"`
	Force              bool             `json:"force"`
	LastCheck          *time.Time       `json:"lastCheck,omitempty"`
	NextCheck          *time.Time       `json:"nextCheck,omitempty"`
	LastError          string           `json:"lastError,omitempty"`
	Window             Window           `json:"window"`
	ActiveSessions     int              `json:"activeSessions"`
	IdleSince          *time.Time       `json:"idleSince,omitempty"`
	QuietPeriodSeconds int              `json:"quietPeriodSeconds"`
	Confirming         bool             `json:"confirming"`
	FailedVersion      string           `json:"failedVersion,omitempty"`
	FailedReason       string           `json:"failedReason,omitempty"`
	Note               string           `json:"note,omitempty"`
	// Cluster is the rolling-update state of a clustered node.
	Cluster *ClusterUpdateStatus `json:"cluster,omitempty"`
}

type Manifest struct {
	Version     string    `json:"version"`
	Channel     string    `json:"channel"`
	PublishedAt time.Time `json:"publishedAt,omitempty"`
	// IssuedAt and ExpiresAt bound replay of a signed feed. Pointers preserve
	// the canonical encoding of legacy manifests during signature checks.
	IssuedAt  *time.Time `json:"issuedAt,omitempty"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	NotesURL  string     `json:"notesUrl,omitempty"`
	Notes     string     `json:"notes,omitempty"`
	// MinVersion, when set, is the oldest installed version that may
	// update directly to this release (older installs must reinstall).
	MinVersion string     `json:"minVersion,omitempty"`
	Artifacts  []Artifact `json:"artifacts"`
	// Signature is base64 ed25519 over SigningBytes(). Empty when the
	// signature is detached (served from "<manifest URL>.sig").
	Signature string `json:"signature,omitempty"`
}

type Options struct {
	// FeedURL is the manifest URL, feed base, or a template containing
	// "{channel}". See ManifestURL for resolution. Empty: DefaultFeedBase.
	FeedURL string
	// Channel: "stable" (default) or "beta".
	Channel string
	// CurrentVersion is the running version. Empty: the build Version.
	CurrentVersion string
	// PublicKey verifies manifests. Nil: the compiled-in key (required).
	PublicKey ed25519.PublicKey
	// HTTPClient for feed + artifact fetches. Nil: a 30s-timeout client
	// for manifests; downloads set their own per-request deadline via ctx.
	HTTPClient *http.Client
	// GOOS/GOARCH override artifact selection (tests, cross-tooling).
	GOOS, GOARCH string
	// PreferKinds overrides artifact kind preference (e.g. installer-only
	// on macOS where the .dmg is the product).
	PreferKinds []string
	Logger      *slog.Logger
}

type Pending struct {
	From      string    `json:"from"`
	To        string    `json:"to"`
	Target    string    `json:"target"`
	AppliedAt time.Time `json:"appliedAt"`
	Attempts  int       `json:"attempts"`
}

type ProgressFunc func(downloaded, total int64)

type Semver struct {
	Major, Minor, Patch uint64
	Pre                 []string // prerelease identifiers, empty for a release
	// contains filtered or unexported fields
}

type StartupOptions struct {
	// Dir is the updates directory holding pending.json / failed.json.
	Dir string
	// Target is the running executable; used when the marker has none and
	// for leftover cleanup. Empty: os.Executable().
	Target string
	// CurrentVersion is the running build's version.
	CurrentVersion string
	// MaxAttempts before rollback. <= 0: DefaultMaxStartAttempts.
	MaxAttempts int
	Now         func() time.Time
	// Rollback / CleanupOld default to the package functions.
	Rollback   func(target string) error
	CleanupOld func(target string) error
	Logger     *slog.Logger
}

type StartupResult struct {
	// Confirming is the marker of a just-installed update that this
	// process (the new version) must confirm by running healthily.
	Confirming *Pending
	// RolledBack is set when the previous binary was restored. When
	// RestartRequired is also set the process must exit so the service
	// manager starts the restored binary.
	RolledBack      *FailedUpdate
	RestartRequired bool
	// Note is a human-readable summary for logs and the admin status.
	Note string
}

type Update struct {
	Manifest *Manifest
	Artifact *Artifact
}

type Window struct {
	Start string `json:"start"`
	End   string `json:"end"`
	Open  bool   `json:"open"`
}