Implement drain control via an external marker file. The daemon polls
$XDG_CONFIG_HOME/archie/.drain_request.json (the repo's config-home
convention) for a drain request, validates it against the current
instantiation epoch (kernel boot id + PID 1 start time) and, only when
the marker is live, cancels the boot context to trigger the same
graceful shutdown an operator SIGTERM does.
A marker written against a prior instantiation (reboot or PID 1/container
restart) is stale and ignored, so a leftover request never drains a
daemon that came up after it was written. An unreadable marker or epoch
fails closed to no drain. The daemon never invents a new shutdown path.
domain/drain owns the pure decision (Epoch, Marker, Decide);
infrastructure/drain reads the marker file and /proc boot facts;
app/archied wires a poller that cancels the root context on a valid
request.
Path note: the epic named ~/.archie/.drain_request.json, but archied
resolves every per-user path under ${XDG_CONFIG_HOME:-~/.config}/archie
(see AGENTS.md 'Config path'), so the marker lives there too rather than
at a path this daemon never uses.
Refs bead archie-core-1786637496817-266-06b64a72 (drain control: marker
file and instantiation epoch), part of the operations epic
archie-core-1786637496703-262-1e49aef1.
Tests: table-driven Decide (epoch mismatch -> stale, matching -> valid,
nil -> none, unreadable -> stale), marker round-trip from operator JSON,
and monitor (valid -> shutdown, stale/none/error -> no shutdown).
105 lines
4.0 KiB
Go
105 lines
4.0 KiB
Go
// Package drain owns the decision logic for external drain requests.
|
|
//
|
|
// A drain is an operator-initiated request for the daemon to stop accepting
|
|
// new work and shut itself down gracefully. It arrives out-of-band through a
|
|
// marker file (an external trigger such as a maintenance window or a rolling
|
|
// deploy writes it) rather than a signal, because a marker survives the phase
|
|
// in which the process is between restarts and can be validated against the
|
|
// *current* instantiation.
|
|
//
|
|
// The single source of confusion this package rules out is the stale marker: a
|
|
// drain request written before the daemon last restarted must never drain the
|
|
// daemon that came up afterwards. That is handled by pairing each marker with
|
|
// an instantiation epoch (the OS boot id plus PID 1's start time) and only
|
|
// honouring a marker whose epoch matches the current one.
|
|
package drain
|
|
|
|
// Epoch identifies one instantiation of the daemon's process tree. It
|
|
// combines the OS boot id with PID 1's start time (in clock ticks since
|
|
// boot). Two Epochs are equal only when both parts match, so a marker written
|
|
// before a reboot or before a PID 1 restart within the same boot is never
|
|
// mistaken for one written against the current instantiation.
|
|
type Epoch struct {
|
|
// BootID is the content of /proc/sys/kernel/random/boot_id, a UUID that
|
|
// changes on every boot.
|
|
BootID string `json:"boot_id"`
|
|
// PID1Start is field 22 (starttime) of /proc/1/stat, in clock ticks since
|
|
// boot. It distinguishes a container or PID 1 restart that happened
|
|
// without a reboot.
|
|
PID1Start int64 `json:"pid1_start"`
|
|
}
|
|
|
|
// Equal reports whether e and other identify the same instantiation.
|
|
func (e Epoch) Equal(other Epoch) bool {
|
|
return e.BootID == other.BootID && e.PID1Start == other.PID1Start
|
|
}
|
|
|
|
// Empty reports whether the epoch carries no usable identity facts. An empty
|
|
// epoch cannot validate any marker, so callers must fail closed (never drain)
|
|
// rather than trust the marker.
|
|
func (e Epoch) Empty() bool {
|
|
return e.BootID == "" || e.PID1Start <= 0
|
|
}
|
|
|
|
// Marker is the parsed .drain_request.json written by an external drain
|
|
// trigger. Only InstantiationEpoch is load-bearing for the decision; the
|
|
// optional operator fields (Reason, RequestedAt) are informational and do not
|
|
// influence whether the request is honoured.
|
|
type Marker struct {
|
|
// InstantiationEpoch records the epoch of the daemon the request targets.
|
|
InstantiationEpoch Epoch `json:"instantiation_epoch"`
|
|
// Reason is an optional operator note (e.g. "maintenance window").
|
|
Reason string `json:"reason,omitempty"`
|
|
// RequestedAt is an optional RFC 3339 timestamp.
|
|
RequestedAt string `json:"requested_at,omitempty"`
|
|
}
|
|
|
|
// Decision is the validation outcome for a marker against the current epoch.
|
|
type Decision int
|
|
|
|
const (
|
|
// DecisionNone means no drain request is present (no marker, or the source
|
|
// reported nothing). No drain.
|
|
DecisionNone Decision = iota
|
|
// DecisionStale means a marker is present but its epoch does not match the
|
|
// current instantiation -- it was written before the last restart and must
|
|
// be ignored. No drain.
|
|
DecisionStale
|
|
// DecisionValid means a marker is present and its epoch matches the current
|
|
// instantiation: a live drain request that must trigger graceful shutdown.
|
|
DecisionValid
|
|
)
|
|
|
|
func (d Decision) String() string {
|
|
switch d {
|
|
case DecisionNone:
|
|
return "none"
|
|
case DecisionStale:
|
|
return "stale"
|
|
case DecisionValid:
|
|
return "valid"
|
|
default:
|
|
return "unknown"
|
|
}
|
|
}
|
|
|
|
// Decide returns the drain decision for marker against current.
|
|
//
|
|
// A nil marker means no request (DecisionNone). An empty current epoch means
|
|
// the OS identity facts could not be established, so the request is treated as
|
|
// stale -- a daemon that cannot prove the marker is live must not shut itself
|
|
// down on it. Only a marker whose epoch exactly matches a non-empty current
|
|
// epoch is honoured.
|
|
func Decide(current Epoch, marker *Marker) Decision {
|
|
if marker == nil {
|
|
return DecisionNone
|
|
}
|
|
if current.Empty() {
|
|
return DecisionStale
|
|
}
|
|
if !marker.InstantiationEpoch.Equal(current) {
|
|
return DecisionStale
|
|
}
|
|
return DecisionValid
|
|
}
|