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 ¶
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 ¶
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 ¶
CommandHook returns an UpdateAgent/UpdateSelf hook that runs bin with args and returns its combined output.
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.
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 ¶
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 (*Updater) Resume ¶
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.