Skip to main content

Module cluster

Module cluster 

Source
Expand description

astrs up, astrs down and the cluster half of astrs status (blueprint §17’s Lifecycle row, §4.2’s process model, §16’s token, §24.2’s runtime directory).

  astrs up
    ├─ <working dir>/.astrs-token        generate (0600) or reuse   §16
    ├─ spawn self: `astrs coordinator --announce --pidfile …`
    │      └─ wait for <runtime>/coordinator.pid to name an address
    ├─ greet it as a CLI (Hello{role=Cli,token}) — proof, not hope
    └─ spawn self: `astrs daemon --coordinator <addr> --pidfile …`
           └─ wait for <runtime>/daemon.pid

  astrs status ─► pidfiles + one `Check` over the wire
  astrs down   ─► Destroy ─► SIGTERM ─► grace ─► SIGKILL ─► rm pidfiles

§One binary, two more processes

up spawns this same executable with the hidden verbs (crate::command::serve) rather than looking for astrs-coordinator and astrs-daemon on PATH. That is what makes a deployment one file to copy (§4.2) and what makes up work from a cargo run target, a container layer, or a test’s CARGO_BIN_EXE_astrs without any of them having to install anything.

§These children must outlive their parent

Exactly opposite to astrs run’s orphan guard. astrs run wants every child dead the moment the CLI dies; astrs up returns to the shell immediately and the cluster must survive that — and must survive the Ctrl-C that ends the next foreground command in that terminal. Each child therefore gets its own process group (so a terminal’s SIGINT never reaches it) and is explicitly not given astrs_wire::ENV_RUN_PARENT_PID. astrs down is the way to stop them, and the pidfile is how it finds them.

§Nothing here trusts a pid alone

A pidfile can outlive its process and a pid can be recycled, so status confirms a coordinator by greeting it over the wire and only falls back to the kill(pid, 0) probe for the daemon, which has no CLI-facing listener of its own.

Structs§

ClusterStatus
What astrs status found.
DownArgs
astrs down’s arguments, already parsed and resolved.
DownReport
What one astrs down did.
ProcessStatus
What one cluster process is doing.
StatusArgs
astrs status’s arguments when no dataflow is named.
UpArgs
astrs up’s arguments, already parsed and resolved.
UpReport
What one astrs up did.

Enums§

StopOutcome
How one process was stopped.

Constants§

READY_POLL
How often the parent looks for a child’s pidfile while waiting.
READY_TIMEOUT
How long a spawned child has to bind its listener and write its pidfile before astrs up gives up on it.
STOP_GRACE
How long a stopping cluster process has after SIGTERM before SIGKILL.
STOP_POLL
How often a stopping process is re-checked while the grace runs.

Functions§

down
Takes a cluster down: dataflows first, then the daemon, then the coordinator.
log_path
The file each spawned child’s stdout and stderr are redirected into.
status
Probes this machine’s cluster: both pidfiles, and one greeting.
up
Brings a cluster up: a coordinator, and (unless --no-daemon) this machine’s daemon.