update

package
v0.52.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 13 Imported by: 1

Documentation

Overview

Package update implements the `!update` chat command shared by every relay: update the agent binary (fir) and/or the relay binary on disk, then trigger the relay's graceful SIGHUP reload so the new images are actually running.

A relay holds ONE long-lived agent process, so `fir update` alone changes nothing that is running — only the relay's re-exec (which respawns the agent) picks up the new binary. That is why every successful update here ends in exactly one reload, never a hard restart: a restart loses the messages queued while the process is down, a graceful reload does not.

Surface:

!update                  agent + relay, one reload
!update fir              agent only, then reload
!update relay            relay only, then reload
!update fir --rollback   restore fir.prev, then reload
!update --check          report versions; changes nothing
... --force              cancel in-flight turns first
!upgrade ...             exact alias of !update
!restart [--force]       graceful reload only, no binary change

On a fleet-managed host (Config.Fleet) every update form except --check runs Config.ConvergeCmd instead — see converge.go. `!restart` changes no binary, so it cannot drift a fleet host: it just reloads.

Everything relay-specific is a hook in Config (UpdateAgent, UpdateSelf, CancelAll, WaitIdle, Reload…). The relay decides WHO is asking (Request.Requester) and delivers Result.Text before calling Result.After, so the reply is posted before the reload starts.

Across the reload the outcome is reported by a marker file written just before it: the new image calls Resume at startup, which posts "fir X → Y, relay A → B" into the requesting conversation and deletes the marker.

Index

Constants

View Source
const HelpLine = "- `!update [fir|relay] [--check|--force|--rollback]` — owner only: update fir and/or the relay, then reload gracefully (a fleet host runs its converge command); `!upgrade` is an alias\n" +
	"- `!restart [--force]` — owner only: reload the relay and fir gracefully without updating anything\n"

HelpLine is the `!help` bullet for this command.

Variables

This section is empty.

Functions

func BinVersion

func BinVersion(ctx context.Context, bin string) string

BinVersion runs `bin --version` and returns the last word of its first line ("fir 1.18.4" → "1.18.4", "0.36.0" → "0.36.0"), or "?" when it cannot be run.

func CommandHook

func CommandHook(bin string, args ...string) func(context.Context) (string, error)

CommandHook returns an UpdateAgent/UpdateSelf hook that runs bin with args and returns its combined output.

func IsCommand

func IsCommand(text string) bool

IsCommand reports whether text is an `!update`, `!upgrade` or `!restart` command (any sigil, any case on the verb).

Types

type Config

type Config struct {
	// RelayName is the relay's binary/display name, e.g. "zulip-acp".
	RelayName string
	// RelayVersion is the compiled-in version of the running relay.
	RelayVersion string
	// RelayBin is the relay binary on disk. Default: os.Executable.
	RelayBin string
	// AgentName is the agent's display name. Default "fir".
	AgentName string
	// AgentBin is the resolved agent binary on disk. Required for
	// anything touching the agent (including --rollback's fir.prev).
	AgentBin string

	// Owners lists the requester ids allowed to run !update (including
	// --check). Empty means nobody.
	Owners []string
	// StateDir holds the lock file and the reload marker.
	StateDir string

	// Fleet marks a host managed by converge/dist.lock. An update there
	// runs ConvergeCmd (a shell command: resolve the newest versions,
	// commit the lock, apply it) instead of updating binaries in place,
	// which would drift the host from its lock. With no ConvergeCmd a
	// fleet host refuses `!update`. LockFile, when set, is the
	// dist.lock to compare against.
	Fleet       bool
	LockFile    string
	ConvergeCmd string
	// ConvergeWrap is an argv prefix for the converge job, e.g.
	// `systemd-run --user --scope --quiet` so the job leaves the relay's
	// cgroup and survives a hard restart of the relay's unit.
	ConvergeWrap []string
	// ConvergeTimeout bounds how long the job is watched. Default 30m.
	// PollInterval is how often its rc file is checked. Default 2s.
	ConvergeTimeout time.Duration
	PollInterval    time.Duration
	// Sleep waits d or until ctx is done. Default: a timer.
	Sleep func(ctx context.Context, d time.Duration) error
	// SecretEnvNames are dropped from the converge job's environment:
	// it needs none of the relay's credentials.
	SecretEnvNames []string
	// Logf logs errors that have no reply to go to. Optional.
	Logf func(format string, args ...any)
	// RelayLockKey / AgentLockKey are the dist.lock keys. Defaults:
	// RelayName with "-" → "_", and AgentName.
	RelayLockKey string
	AgentLockKey string

	// UpdateAgent and UpdateSelf perform the on-disk updates and
	// return their combined output. Required.
	UpdateAgent func(ctx context.Context) (string, error)
	UpdateSelf  func(ctx context.Context) (string, error)

	// AgentVersion reports the RUNNING agent's version (e.g. from the
	// ACP initialize agentInfo). Optional.
	AgentVersion func() string
	// AgentPID returns the running agent's pid (0 if none). Optional.
	AgentPID func() int

	// CancelAll cancels every in-flight turn and returns a human label
	// per cancelled conversation. WaitIdle blocks until no turn is in
	// flight or ctx is done. Both are needed for --force.
	CancelAll func() []string
	WaitIdle  func(ctx context.Context) error
	// DrainTimeout bounds WaitIdle after CancelAll. Default 30s.
	DrainTimeout time.Duration

	// Reload triggers the graceful reload. Default: SIGHUP to self.
	Reload func() error
	// Version returns the version printed by bin. Default runs
	// `bin --version` and takes the last word of the first line.
	Version func(ctx context.Context, bin string) string
	// ProcExe resolves a pid's executable. Default reads /proc/<pid>/exe.
	ProcExe func(pid int) string
	// Now is the clock. Default time.Now.
	Now func() time.Time
}

Config wires an Updater to one relay.

type Marker

type Marker struct {
	ConvID    string    `json:"conv_id"`
	Requester string    `json:"requester"`
	Who       string    `json:"who,omitempty"`
	OldAgent  string    `json:"old_agent"`
	OldRelay  string    `json:"old_relay"`
	Rollback  bool      `json:"rollback,omitempty"`
	Restart   bool      `json:"restart,omitempty"`
	At        time.Time `json:"at"`
	// Converge marks a fleet host's converge job: the report waits for
	// the job, not just for the reload. OldLock is dist.lock before it.
	Converge bool              `json:"converge,omitempty"`
	OldLock  map[string]string `json:"old_lock,omitempty"`
}

Marker records an update in flight across the reload.

type Op

type Op struct {
	Agent, Relay bool
	Check        bool
	Force        bool
	Rollback     bool
	// Restart is `!restart`: reload only, no binary change.
	Restart bool
}

Op is a parsed `!update` invocation.

func Parse

func Parse(text string) (Op, error)

Parse parses the text of an `!update` command. The caller has already established IsCommand(text).

type Request

type Request struct {
	ConvID    string // opaque relay conversation token, echoed by Resume
	Requester string // the relay's id for the sender, matched against Owners
	Who       string // display name for the report; optional
	Text      string // the raw message
	// Post posts into the requesting conversation after Handle has
	// returned. A fleet host's converge job reports through it when it
	// ends without a reload.
	Post func(text string) error
}

Request is one `!update` invocation.

type Result

type Result struct {
	Text  string
	After func() error
}

Result is what the relay renders. When After is non-nil the relay must post Text first and then call After, which triggers the reload.

type Updater

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

Updater runs `!update` for one relay.

func New

func New(cfg Config) *Updater

New constructs an Updater, filling defaults.

func (*Updater) Handle

func (u *Updater) Handle(ctx context.Context, req Request) Result

Handle runs one `!update`.

func (*Updater) Resume

func (u *Updater) Resume(ctx context.Context, post func(convID, text string) error) error

Resume is called once by the new image at startup. If an update marker exists it posts the outcome into the requesting conversation via post and deletes the marker (even when post fails, so a broken conversation cannot make every future start re-post). No marker is not an error.

Jump to

Keyboard shortcuts

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