Struct GearManager 

pub struct GearManager { /* private fields */ }

Central registry that tracks all running gear instances in the system. Provides discovery, health tracking, and round-robin load balancing.

Always shared as an Arc<GearManager> and NOT Clone: a by-value clone would deep-copy the DashMap directories while sharing the guards, so the registration lock would no longer serialize the map it guards.

Implementations

impl GearManager

pub fn new() -> Self

pub fn with_heartbeat_policy(self, ttl: Duration, grace: Duration) -> Self

pub fn set_grpc_service_owners(&self, owners: HashMap<String, String>)

Install the authoritative gRPC-service-name -> owning-gear map.

A listed name may be advertised only by its owner (enforced in register_instance), closing the hole where a gear could squat another’s service name by registering first; unlisted names keep first-registration ownership. Seeded from operator config, then layered with the compiled-in owners via merge_authoritative_grpc_service_owners — both at startup, before any gear self-registers.

Taken under reg_lock so it can’t interleave with an in-flight register_instance check + commit.

pub fn merge_authoritative_grpc_service_owners( &self, authoritative: HashMap<String, String>, )

Merge a compiled-in service_name -> gear map into the ownership map, overriding any conflicting operator-configured entry.

The compiled binary is ground truth — a gear physically provides the service — so config must not reassign that name elsewhere (that would re-open the squat); a disagreeing entry is overridden and warned. Names absent here (e.g. remote / out-of-process gears) keep their configured owner.

Runs once in the runtime’s gRPC phase before self-registration, under reg_lock like set_grpc_service_owners.

pub fn register_instance( &self, instance: Arc<GearInstance>, ) -> Result<(), GrpcServiceNameConflict>

Register or update a gear instance, enforcing single-gear ownership of every gRPC service name it advertises — atomically.

The ownership check (check_grpc_service_ownership) and the insert run under one registration lock, so two gears cannot both pass an “unowned” check and then both commit the same name — a check-then-write race the per-entry DashMap locks do not prevent. On a conflict the store is left untouched.

Re-registering an existing instance_id is an idempotent endpoint / metadata refresh, NOT a liveness reset: the existing runtime state (last_heartbeat + InstanceState) is carried over onto the new record by preserving the same Arc<RwLock<InstanceRuntimeState>>. Without this, a periodic self-heal re-registration (see oop_registration::presence_loop) would knock a Healthy instance back to Registered, dropping it out of gRPC round-robin until the next heartbeat. It would also race with concurrent update_heartbeat calls.

Errors

Returns GrpcServiceNameConflict if an advertised gRPC service name is owned by, or currently advertised by, another gear.

pub fn mark_ready(&self, gear: &str, instance_id: Uuid)

Mark an instance as ready

pub fn update_heartbeat(&self, gear: &str, instance_id: Uuid, at: Instant)

Update the heartbeat timestamp for an instance

pub fn mark_quarantined(&self, gear: &str, instance_id: Uuid)

Mark an instance as quarantined

pub fn mark_draining(&self, gear: &str, instance_id: Uuid)

Mark an instance as draining (graceful shutdown in progress)

pub fn deregister(&self, gear: &str, instance_id: Uuid)

Remove an instance from the directory

pub fn instances_of(&self, gear: &str) -> Vec<Arc<GearInstance>>

Get all instances of a specific gear

pub fn all_instances(&self) -> Vec<Arc<GearInstance>>

Get all instances across all gears

pub fn evict_stale(&self, now: Instant)

Quarantine or evict stale instances based on heartbeat policy

pub fn pick_instance_round_robin(&self, gear: &str) -> Option<Arc<GearInstance>>

Pick an instance using round-robin selection, preferring healthy instances

pub fn pick_service_round_robin( &self, service_name: &str, ) -> Option<(String, Arc<GearInstance>, Endpoint)>

Pick a service endpoint using round-robin, returning (gear, instance, endpoint). Prefers healthy/ready instances and automatically rotates among them.

pub fn pick_rest_endpoint_round_robin(&self, gear: &str) -> Option<Endpoint>

Resolve a REST endpoint for a gear using round-robin over instances that expose one, preferring healthy/ready instances.

pub fn openapi_spec_of(&self, gear: &str) -> Option<String>

Retrieve the OpenAPI spec of a gear, taken from the first registered instance that published one.

Trait Implementations

impl Debug for GearManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GearManager

fn default() -> Self

Returns the “default value” for a type.