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 (and allow
updating a fleet-managed host)
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\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: updates are
// refused without --force, because they drift the host from its
// lock. LockFile, when set, is the dist.lock to compare against.
Fleet bool
LockFile string
// 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"`
At time.Time `json:"at"`
}
Marker records an update in flight across the reload.
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
}
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.