Enum Capability 

#[non_exhaustive]
pub enum Capability {
    GracefulShutdown,
    UpdateTracking,
    SoftwareDiscovery,
    SshRemote,
    UpdateHooks,
    Scheduler,
    DatabaseAccess,
    NatsAccess,
    MasterKeyAccess,
    CaManagement,
    SystemService,
    UiSurfaces,
    InteractiveUpdates,
    ResetData,
    WorkloadClaims,
    Other(String),
}

A protocol capability advertised by a service or controller during connection setup.

Both sides announce their capability sets at the start of each authenticated connection. Each side independently computes the agreed set as the intersection of typed variants only — Other is excluded from intersection.

Wire format

Capabilities are serialized as plain strings (snake_case). Unknown strings from a newer peer become Other(String) for forward compatibility.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

GracefulShutdown

Service participates in the graceful-shutdown protocol: sends Disconnecting before clean exit and honours shutdown_timeout_seconds from ServiceSettings.

Wire string: graceful_shutdown.

UpdateTracking

Service tracks software update state and host connectivity.

The controller uses this capability to route software-state broadcasts and connectivity updates. Also gates MQTT-specific lease coordination for MQTT bridge services.

Wire string: update_tracking.

SoftwareDiscovery

Service supports DiscoverSoftware → DiscoveryResults flow.

The controller gates autodiscovery requests on this capability.

Wire string: software_discovery.

SshRemote

Service manages remote hosts over SSH, rather than running locally.

Identifies an SSH-backed agent. Combined with SoftwareDiscovery, uniquely identifies an SSH agent (vs. a local agent).

Wire string: ssh_remote.

UpdateHooks

Service supports pre-/post-update lifecycle hook plugins (PluginAssignment in ExecuteUpdatePayload). The controller omits hook plugins when absent.

Wire string: update_hooks.

Scheduler

Marker: service is an external task scheduler.

Identifies a service that runs scheduled tasks (version checks, cert checks, auth cleanup, etc.) externally. The controller uses this to detect scheduler presence and disable the embedded scheduler.

Wire string: scheduler.

DatabaseAccess

Service requires direct database access. The controller will include db_url in ServiceCredentialsPayload.

Wire string: database_access.

NatsAccess

Service requires NATS access. The controller will include nats_url in ServiceCredentialsPayload (if NATS is configured).

Wire string: nats_access.

MasterKeyAccess

Service requires the master encryption key. The controller will include master_key_hex in ServiceCredentialsPayload (if encryption is enabled).

Wire string: master_key_access.

CaManagement

Service can request CA certificate rotation via RequestCaRotationPayload. The controller will accept RequestCaRotation messages from services with this capability (via NATS or local delivery).

Wire string: ca_management.

SystemService

Service is a global infrastructure service, not bound to any tenant.

When present in an EnrollPayload, the controller routes enrollment to the system_services table instead of the per-tenant services table.

Credential guard: any service requesting DatabaseAccess, NatsAccess, MasterKeyAccess, or CaManagement without also advertising SystemService will be rejected at enrollment with a 403 error. This prevents regular tenant agents from claiming infrastructure credentials.

Wire string: system_service.

UiSurfaces

Service supports UI surfaces: it will send SurfaceRegistration after connection and respond to surface action messages.

Wire string: ui_surfaces.

InteractiveUpdates

Service supports interactive update sessions: PTY allocation, stdin forwarding, and signal delivery during update execution.

When present, the controller may set interactive: true on ExecuteUpdatePayload and send UpdateStdinData messages to this service. The service allocates a PTY for the update process and keeps stdin open for forwarding.

Wire string: interactive_updates.

ResetData

Service supports the reset-data protocol: truncates local data stores when the controller broadcasts a data reset.

Wire string: reset_data.

WorkloadClaims

Service participates in the workload claim protocol for exclusive config-key ownership.

Services with this capability send WorkloadClaim after receiving ServiceConfigDelivery to request exclusive ownership of config keys. The controller responds with WorkloadClaimResult and routes tenant-scoped messages only to services that hold granted claims.

Wire string: workload_claims.

Other(String)

Unknown capability from a newer peer; never participates in intersection.

Provides forward compatibility: a newer peer may advertise capabilities that an older build does not yet recognise. These are preserved on receipt but never emitted by the current codebase.

Implementations

impl Capability

pub fn as_str(&self) -> &str

Returns the snake_case wire string for this capability.

pub fn is_known(&self) -> bool

Returns true for typed variants; Other returns false.

Only typed variants participate in capability intersection. Other values are forwarded-compatibility markers and must not gate behaviour.

Trait Implementations

impl Clone for Capability

fn clone(&self) -> Capability

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Capability

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Capability

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Capability

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

Formats the value using the given formatter.

impl Eq for Capability

impl FromStr for Capability

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Capability

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Capability

fn cmp(&self, other: &Capability) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Capability

fn eq(&self, other: &Capability) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Capability

fn partial_cmp(&self, other: &Capability) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Capability

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Capability