Files
archie/internal/releaseupdate/service.go
T
sam 72d80f1dfc fix(releaseupdate): don't treat empty available as deferred
Service.Check matched deferred[component.ID] == component.Available, and a
never-deferred recipient's absent entry is the empty string -- equal to an
empty Available emitted for a component with no update. Guard on a real
(non-empty) available version before applying the deferral, so an
up-to-date recipient is not told their update is deferred. No WIRE/DELETE
decision applies: this is a correctness fix on a live consumer, not
unreachable code.
2026-09-15 12:53:25 +10:00

308 lines
11 KiB
Go

// Package releaseupdate provides deployment-neutral release discovery,
// per-user deferrals, and installation orchestration.
package releaseupdate
import (
"context"
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
"strconv"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/installtype"
)
// Catalog discovers the currently installed and newest available releases.
// Deployment-specific adapters (a package manager, image registry, or custom
// release feed) implement it outside the chat gateway.
type Catalog interface {
Check(context.Context) (Snapshot, error)
}
// Installer applies an approved update. It reports only work it has actually
// started; callers remain responsible for telling users the final result.
// The returned Result covers only the synchronous phase (fetch/build/
// install) -- whether a subsequent restart actually came up healthy is
// reported later, out of band, via a Report (see pending_report.go).
type Installer interface {
Install(context.Context, Snapshot, InstallMeta, func(string)) (Result, error)
}
type Component struct {
ID string
Label string
Installed string
Available string
Changelog string
// InstallType and Reference describe how this component is actually
// deployed -- "binary"/"container"/"embedded"/"external", and a
// deployment-specific pointer such as an image digest or a NATS URL.
// The external check command that populates Installed/Available cannot
// know either of these: it reports what version exists, not how this
// particular instance was installed. See Service.Enrich, which fills
// them in from sources that actually know (this process's own build
// stamp, an observed archie-agent version, deployment configuration for
// a third-party dependency this repo doesn't build).
InstallType string
Reference string
}
type Snapshot struct {
Components []Component
Deferred bool
}
func (s Snapshot) Available() []Component {
available := make([]Component, 0, len(s.Components))
for _, component := range s.Components {
if component.Available != "" && component.Available != component.Installed {
available = append(available, component)
}
}
return available
}
// SameAvailable reports whether two snapshots offer the same component
// versions. Metadata such as changelogs may change without changing the
// release the operator is approving, so only installable versions matter.
func SameAvailable(left, right Snapshot) bool {
leftAvailable, rightAvailable := left.Available(), right.Available()
if len(leftAvailable) != len(rightAvailable) {
return false
}
versions := make(map[string]string, len(leftAvailable))
for _, component := range leftAvailable {
versions[component.ID] = component.Available
}
for _, component := range rightAvailable {
if versions[component.ID] != component.Available {
return false
}
}
return true
}
// Service persists a user's decision to defer an exact available version. A
// later version is deliberately shown again rather than being silently hidden.
type Service struct {
Catalog Catalog
Installer Installer
StatePath string
// InstallType gates Install: it must be a value the release pipeline
// actually stamps (see package installtype), never "" or
// installtype.Unknown, or Install refuses to run the configured
// Installer at all. The composition root wires this from
// installtype.Type() -- Service itself never reads that package
// directly, so a test can exercise every InstallType without touching
// process-wide state.
InstallType string
// Enrich supplies InstallType/Reference for a known component ID (see
// ComponentDaemon, ComponentAgent, ComponentNATS), using sources the
// external check command has no way to know -- this process's own
// compiled-in installtype.Type(), an archie-agent version actually
// observed at runtime (daemon.AgentStatus), or deployment configuration
// for a third-party dependency archie doesn't build. Optional: nil (or
// a component ID Enrich doesn't recognise, or an empty installType
// return) leaves whatever the check command itself reported untouched,
// so a check command that DOES report its own value is never silently
// overwritten.
Enrich func(componentID string) (installType, reference string)
mu sync.Mutex
installing bool
}
func (s *Service) Check(ctx context.Context, recipient int64) (Snapshot, error) {
if s == nil || s.Catalog == nil {
return Snapshot{}, errors.New("update discovery is not configured")
}
snapshot, err := s.Catalog.Check(ctx)
if err != nil {
return Snapshot{}, fmt.Errorf("check for updates: %w", err)
}
if s.Enrich != nil {
for index := range snapshot.Components {
component := &snapshot.Components[index]
if installType, reference := s.Enrich(component.ID); installType != "" {
component.InstallType = installType
component.Reference = reference
}
}
}
if s.StatePath == "" {
return snapshot, nil
}
s.mu.Lock()
defer s.mu.Unlock()
state, err := loadDeferrals(s.StatePath)
if err != nil {
return Snapshot{}, err
}
deferred := state[strconv.FormatInt(recipient, 10)]
for index := range snapshot.Components {
component := &snapshot.Components[index]
if component.Available != "" && deferred[component.ID] == component.Available {
component.Available = ""
snapshot.Deferred = true
}
}
return snapshot, nil
}
// Defer records only the exact versions the caller displayed. It refuses a
// changed catalog rather than silently suppressing a release the user never saw.
func (s *Service) Defer(ctx context.Context, recipient int64, expected Snapshot) error {
if s == nil || s.Catalog == nil {
return errors.New("update discovery is not configured")
}
if s.StatePath == "" {
return errors.New("update deferral storage is not configured")
}
s.mu.Lock()
defer s.mu.Unlock()
snapshot, err := s.Catalog.Check(ctx)
if err != nil {
return fmt.Errorf("check updates before deferring: %w", err)
}
state, err := loadDeferrals(s.StatePath)
if err != nil {
return err
}
key := strconv.FormatInt(recipient, 10)
if state[key] == nil {
state[key] = make(map[string]string)
}
if !SameAvailable(snapshot, expected) {
return errors.New("available releases changed; check again")
}
for _, component := range expected.Available() {
state[key][component.ID] = component.Available
}
return saveDeferrals(s.StatePath, state)
}
// ErrUnknownInstallType is returned by Install when InstallType is unset or
// installtype.Unknown -- there is no way to know, without it, whether the
// configured Installer is even the right kind of update for how this
// instance was actually deployed.
var ErrUnknownInstallType = errors.New("refusing to install: install type is unknown")
// ErrInstallInProgress is returned by Install when another install is
// already running. Telegram and the web dashboard each keep their own
// local "already in progress" flag for a quick UI response, but both are
// wired to the same Service in production -- this is the one guard that
// actually sees both, since a caller-local bool would let one adapter start
// a second install while the other's is still copying binaries.
var ErrInstallInProgress = errors.New("an update is already in progress")
// installTimeout bounds an install after it has been deliberately detached
// from the caller's context (see below) -- otherwise a hung installer
// script would hold the in-progress lock forever.
const installTimeout = 30 * time.Minute
// Install runs the configured Installer. The context it hands the
// Installer is intentionally NOT ctx: ctx belongs to whatever triggered the
// update (a chat message handler cancelled by /restart, an HTTP request
// cancelled by a client disconnect), and exec.CommandContext SIGKILLs its
// child the instant that context is cancelled. The install script backs up
// and overwrites the live binaries with plain, non-atomic copies -- a kill
// mid-copy can leave the daemon unable to start, with the one thing that
// could roll that back (the watchdog) never launched because the script
// never reached that line. Detaching the install from ctx, bounded by
// installTimeout instead, is what actually makes the caller's own
// lifecycle safe to interrupt without corrupting an in-flight update.
func (s *Service) Install(ctx context.Context, snapshot Snapshot, meta InstallMeta, progress func(string)) (Result, error) {
if s == nil || s.Installer == nil {
return Result{}, errors.New("update installation is not configured")
}
if s.InstallType == "" || s.InstallType == installtype.Unknown {
return Result{}, ErrUnknownInstallType
}
s.mu.Lock()
if s.installing {
s.mu.Unlock()
return Result{}, ErrInstallInProgress
}
s.installing = true
s.mu.Unlock()
defer func() {
s.mu.Lock()
s.installing = false
s.mu.Unlock()
}()
installCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), installTimeout)
defer cancel()
return s.Installer.Install(installCtx, snapshot, meta, progress)
}
func (s *Service) CanInstall() bool { return s != nil && s.Installer != nil }
type deferrals map[string]map[string]string
func loadDeferrals(path string) (deferrals, error) {
data, err := os.ReadFile(path)
if errors.Is(err, os.ErrNotExist) {
return make(deferrals), nil
}
if err != nil {
return nil, fmt.Errorf("read update deferrals: %w", err)
}
var state deferrals
if err := json.Unmarshal(data, &state); err != nil {
return nil, fmt.Errorf("decode update deferrals: %w", err)
}
return state, nil
}
func saveDeferrals(path string, state deferrals) error {
data, err := json.Marshal(state)
if err != nil {
return fmt.Errorf("encode update deferrals: %w", err)
}
return writeFileAtomic(path, data)
}
// writeFileAtomic writes data to path via a temp file in the same
// directory, synced and renamed into place, so a reader never observes a
// partially written file. Shared by saveDeferrals and WritePendingReport --
// both are small JSON state files under the same operational directory
// (cfg.WorkDir) with the same durability requirement.
func writeFileAtomic(path string, data []byte) error {
dir := filepath.Dir(path)
if err := os.MkdirAll(dir, 0o700); err != nil {
return fmt.Errorf("create state directory: %w", err)
}
file, err := os.CreateTemp(dir, ".update-state-*")
if err != nil {
return fmt.Errorf("create temp state file: %w", err)
}
tempPath := file.Name()
defer func() { _ = os.Remove(tempPath) }()
if err := file.Chmod(0o600); err != nil {
_ = file.Close()
return fmt.Errorf("protect state file: %w", err)
}
if _, err := file.Write(data); err != nil {
_ = file.Close()
return fmt.Errorf("write state file: %w", err)
}
if err := file.Sync(); err != nil {
_ = file.Close()
return fmt.Errorf("sync state file: %w", err)
}
if err := file.Close(); err != nil {
return fmt.Errorf("close state file: %w", err)
}
if err := os.Rename(tempPath, path); err != nil {
return fmt.Errorf("replace state file: %w", err)
}
return nil
}