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 Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager runs the auto-update loop for one relay.
func (*Manager) Decide ¶
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) Poll ¶
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 ¶
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.