Struct PlacementControlPlane 

pub struct PlacementControlPlane { /* private fields */ }

The controller.

Implementations

impl PlacementControlPlane

pub fn with_kind_registry(self, kinds: KindRegistry) -> Self

Replace the workload-kind registry (default: KindRegistry::builtin).

pub fn new( key: SigningKey, gate: Arc<dyn GateBackend>, chain: Arc<ChainManager>, exchange: Arc<ArtifactExchange>, anchors: TrustAnchors, connector: Arc<dyn CtlConnector>, ) -> Self

Controller for the node owning key. Every decision is chained.

pub fn with_membership(self, m: Arc<ClusterMembership>) -> Self

Use membership peer state for liveness.

pub fn with_config(self, cfg: PlaneConfig) -> Self

Replace the tunables.

pub fn node_id(&self) -> &str

This controller’s node id.

pub fn targets(&self) -> Vec<TargetInfo>

Known targets.

pub fn hosts(&self) -> Vec<ServiceAdvertisement>

Nodes advertising workload-host.

pub fn placements(&self) -> Vec<PlacementRecord>

Placed instances.

pub fn view(&self) -> Vec<LiveNodeFacts>

The verified facts the engine will see, with liveness. Runtimes a node has no adapter route for are hidden (a node without a workload-host advertisement offers none).

pub async fn add_target( &self, addr: &str, tier: FactsTier, ) -> Result<String, PlaneError>

Learn (or refresh) the target at addr: signed describe, verify and cache its signed facts under tier, merge its advertisement. Returns its node id. Whatever key answers is accepted (first use); see Self::add_target_expecting to require a key.

pub async fn add_target_expecting( &self, addr: &str, tier: FactsTier, expect: Option<[u8; 32]>, ) -> Result<String, PlaneError>

Self::add_target, refusing any answer not signed by expect when given. Trust is bound to the node key: an operator tier is only ever given to the key the operator pinned, or to the key first seen at that address, never to whoever answers there later.

pub async fn refresh(&self)

Re-describe every known target, requiring the key it was learned with; unreachable ones are marked so the engine sees them as not alive. A node whose address now answers with another key (it was replaced, or someone else took the address) is marked unreachable and the new key is not learned: it gets no tier until the operator pins it (OperatorPeer::key).

pub async fn call( &self, node_id: &str, m: &str, decision_id: Option<String>, body: Value, ) -> Result<Value, PlaneError>

A signed call to a known node (no payload serving).

impl PlacementControlPlane

pub async fn node_admin( &self, node_id: &str, m: &str, body: Value, ) -> Result<Value, PlaneError>

Send node-admin method m to node_id and return its result.

impl PlacementControlPlane

pub fn set_tier(&self, node_id: &str, tier: FactsTier) -> bool

Set the operator-assigned tier of a known target (targets map and facts cache). False if the node is not known.

pub async fn apply_operator_peers( &self, peers: &[OperatorPeer], keep: &[&str], ) -> Vec<(String, PlaneError)>

Make the known targets match the operator’s peers. Returns one error per peer that could not be learned (it is retried on the next sync).

impl PlacementControlPlane

pub fn lifecycle_of(&self, instance_id: &str) -> Option<LifecycleState>

Lifecycle state the controller holds for instance_id.

pub fn life_summary(&self, instance_id: &str) -> Option<Value>

{state, restarts, reschedules, has_error} the controller holds for instance_id; in memory only, no peer is contacted. The error text is withheld (it can carry paths and peer detail).

pub async fn lifecycle_tick(&self) -> Vec<LifecycleEvent>

One pass of the controller lifecycle; see the module docs.

pub fn spawn_lifecycle(self: &Arc<Self>, period: Duration) -> JoinHandle<()>

Run Self::lifecycle_tick every period for as long as the runtime lives.

impl PlacementControlPlane

pub async fn place(&self, order: &PlaceOrder) -> Result<PlaceReport, PlaneError>

Decide (and unless dry_run, dispatch) one placement, with the default lifecycle policy (see Self::place_with).

pub async fn place_with( &self, order: &PlaceOrder, policy: LifecyclePolicy, ) -> Result<PlaceReport, PlaneError>

Self::place, recording what the lifecycle needs to reschedule the instance if its node is lost: the order, and policy (whether it may move at all).

pub async fn instance( &self, m: &str, instance_id: &str, ) -> Result<Value, PlaneError>

Gate an instance transition on the controller (chained) and send it.

impl PlacementControlPlane

pub fn unsettled(&self) -> Vec<PlacementRecord>

Decisions still unsettled.

pub async fn settle_unsettled(&self) -> usize

Ask each target holding an unsettled decision what became of it: adopt the instances it produced (chained as adopted), forget it if it produced none, keep it while in flight or unreachable. Returns the number of instances adopted.

impl PlacementControlPlane

pub fn add_seed( &self, node_id: &str, host: Arc<WorkloadHost>, tier: TrustTier, ) -> Result<(), PlaneError>

Register a Seed adapter under its operator-assigned node id and trust tier (governance sees that tier, not a default).

pub async fn place_store_pin( &self, o: &StorePinOrder, ) -> Result<PlacementRecord, PlaneError>

Place an operator-pinned store cog on a Seed. Pinned by construction: the node is the operator-assigned id.

impl PlacementControlPlane

pub fn with_state_file( self, path: impl Into<PathBuf>, ) -> Result<Self, PlaneError>

Persist to path after every change, restoring what it holds now. A missing file starts empty; a malformed one is refused (the caller decides; nothing is overwritten).

pub fn forget_instances(&self, ids: &[String]) -> usize

Drop the controller’s records of ids (instances a revocation took down on this node, see super::host_revoke), and their Seed handles, and save. Returns how many records were removed.