autoupdate

package
v0.37.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 15 Imported by: 1

Documentation

Overview

Package autoupdate keeps a relay current without an operator typing `!update`: it polls for a newer release, stages and verifies it, asks the relay's owners for approval through a Surface (one chat message, edited in place), applies it at the next idle point through the relay's graceful reload, and rolls back on its own when the new image fails its health gate.

Modes (Config.Mode, the relay's `auto_update` setting):

off     never polls
notify  posts the offer; the download happens on approval
stage   downloads + verifies first, then posts the offer (default)
auto    stages and applies with no prompt — refused on a fleet host

Safety rails, all here so every relay gets the same ones:

  • the old binary is kept as <bin>.prev;
  • after the re-exec the new image must pass Config.HealthProbe (resume its inherited queue, one successful round-trip) within Config.HealthTimeout, else it restores .prev, blocks the version, reloads, and the old image reports why;
  • at most one automatic apply per Config.Cooldown; after a rollback nothing applies automatically until an owner acts;
  • a newer release supersedes a pending offer (one prompt, not two);
  • quiet hours hold an approved apply until they end.

A fleet-managed host (Config.Fleet) never resolves versions itself: the trigger is dist.lock drift ("lock wants vX, running vY"), and approval runs the relay's `!update` converge path (Config.Updater).

Resolution goes through distkit's anonymous /releases/latest redirect, which spends no GitHub API quota (so no ETag dance is needed); download, sha256 verification and the atomic swap are distkit's too.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	Mode Mode
	// Dist is the relay's distkit configuration (Repo, Binary…).
	// Version is overwritten with RelayVersion.
	Dist distkit.Config

	RelayName    string
	RelayVersion string
	// RelayBin is the binary that gets swapped. Default os.Executable.
	RelayBin string

	// AgentName/AgentBin/AgentVersion/UpdateAgent cover the fir-skew
	// case: a release whose notes say "requires fir >= X" while the
	// running agent is older is offered and applied with the agent as
	// one unit, one reload.
	AgentName    string
	AgentBin     string
	AgentVersion func() string
	UpdateAgent  func(ctx context.Context) (string, error)

	// Owners are the ids whose decisions count.
	Owners []string
	// StateDir holds autoupdate.json.
	StateDir string
	Surface  Surface
	// ConvID is the relay conversation token offers live in. A fleet
	// converge reports there after its reload (update.Resume).
	ConvID string

	// Fleet marks a converge-managed host; LockFile is its dist.lock.
	// Updater runs the converge on approval.
	Fleet        bool
	LockFile     string
	RelayLockKey string
	AgentLockKey string
	Updater      *update.Updater

	// Idle reports that no turn is in flight. Default: always idle (the
	// graceful reload drains anyway).
	Idle func() bool
	// Reload triggers the graceful reload (SIGHUP). Required.
	Reload func() error
	// HealthProbe is retried by the new image until it succeeds or
	// HealthTimeout passes: the relay resumes its inherited queue and
	// makes one real round-trip. Default: healthy once started.
	HealthProbe func(ctx context.Context) error

	// QuietHours "HH:MM-HH:MM" in local time; no apply starts inside.
	QuietHours string

	Interval      time.Duration // poll period, default 6h
	Jitter        time.Duration // ± around Interval, default 30m
	Tick          time.Duration // pending-apply check, default 1m
	HealthTimeout time.Duration // default 2m
	Cooldown      time.Duration // between automatic applies, default 24h
	RemindAfter   time.Duration // one reminder, default 72h
	Snooze        time.Duration // the "tomorrow" delay, default 24h

	// Seams. Defaults: distkit.Check/Download, GitHub release notes,
	// time.Now, a timer, math/rand.
	Check    func(ctx context.Context) (*distkit.Status, error)
	Download func(ctx context.Context, rel *distkit.Release, dir string) (string, error)
	Notes    func(ctx context.Context, tag string) (string, error)
	Now      func() time.Time
	Sleep    func(ctx context.Context, d time.Duration) error
	Rand     func(n int64) int64
	Logf     func(format string, args ...any)
}

Config wires a Manager to one relay.

type Decision

type Decision int

Decision is an owner's answer to an offer.

const (
	// ApplyNow applies at the next idle point.
	ApplyNow Decision = iota + 1
	// Tomorrow applies at the first idle point a day from now.
	Tomorrow
	// SkipVersion drops the offer and never offers that version again.
	SkipVersion
)

The three answers a relay maps its reactions/buttons onto.

type Manager

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

Manager runs the auto-update loop for one relay.

func New

func New(cfg Config) (*Manager, error)

New validates cfg and fills defaults.

func (*Manager) Decide

func (m *Manager) Decide(ctx context.Context, msgID, who string, d Decision) bool

Decide records an owner's decision on the offer message msgID. It reports whether the decision was taken: false for a non-owner, an unknown message, or a settled offer.

func (*Manager) Mode

func (m *Manager) Mode() Mode

Mode reports the effective mode (auto degrades to stage on a fleet host).

func (*Manager) Poll

func (m *Manager) Poll(ctx context.Context)

Poll checks once for a new release (or, on a fleet host, for dist.lock drift) and posts or supersedes the offer. Run calls it on its schedule; a relay may call it for an immediate check.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context)

Run resumes an apply in progress (health gate / rollback report), then polls until ctx ends. Call it once, in its own goroutine, after the relay can post.

func (*Manager) Status

func (m *Manager) Status() string

Status renders the pending state for `!update --check`.

func (*Manager) Tick

func (m *Manager) Tick(ctx context.Context)

Tick applies an approved offer once it is due, outside quiet hours, and the relay is idle.

type Mode

type Mode string

Mode is the `auto_update` setting.

const (
	Off    Mode = "off"
	Notify Mode = "notify"
	Stage  Mode = "stage"
	Auto   Mode = "auto"
)

The four modes. The zero value parses as Stage.

func ParseMode

func ParseMode(s string) (Mode, error)

ParseMode parses an `auto_update` value; "" means Stage.

type Surface

type Surface interface {
	Post(ctx context.Context, text string) (id string, err error)
	Edit(ctx context.Context, id, text string) error
}

Surface is how a relay shows the offer. Post creates the one message (returning its id); every later state is an Edit of it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL