Enum ServiceMessage 

#[non_exhaustive]
pub enum ServiceMessage {
    Ping(PingPayload),
    Enroll(EnrollPayload),
    RequestCertificate(RequestCertificatePayload),
    RenewCertificate(RenewCertificatePayload),
    Disconnecting(DisconnectingPayload),
    ReportHosts(ReportHostsPayload),
    VersionCheckResults(VersionCheckResultsPayload),
    UpdateStarted(UpdateStartedPayload),
    UpdateOutput(UpdateOutputPayload),
    UpdateResult(UpdateResultPayload),
    BatchUpdateResult(BatchUpdateResultPayload),
    DiscoveryResults(DiscoveryResultsPayload),
    StdinAttention(StdinAttentionPayload),
    ServiceTriggerUpdate(ServiceUpdateTriggerPayload),
    ServiceTriggerHostBatchUpdate(ServiceHostBatchUpdateTriggerPayload),
    Register(RegisterPayload),
    ReportPluginConfig(ReportPluginConfigPayload),
    SurfaceRegistration(SurfaceRegistration),
    SurfaceActionResponse(SurfaceActionResponse),
    SurfaceActionRequest(SurfaceActionRequest),
    StoreServiceConfig(StoreServiceConfigPayload),
    DeleteServiceConfig(DeleteServiceConfigPayload),
    WorkloadClaim(WorkloadClaimPayload),
    WorkloadRelease(WorkloadReleasePayload),
    TestPluginConfigResult(TestPluginConfigResultPayload),
    AuditEvent(AuditEventPayload),
    Unknown,
}

Messages sent from a service (agent or MQTT) to the controller.

Forward compatibility

The Unknown variant is a catch-all for message types introduced in newer service builds that an older controller does not yet recognise. When encountered, the controller logs a warning and continues without closing the connection, allowing rolling upgrades where services and controllers are not updated simultaneously.

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.

Ping(PingPayload)

Enroll(EnrollPayload)

RequestCertificate(RequestCertificatePayload)

RenewCertificate(RenewCertificatePayload)

Disconnecting(DisconnectingPayload)

ReportHosts(ReportHostsPayload)

VersionCheckResults(VersionCheckResultsPayload)

UpdateStarted(UpdateStartedPayload)

UpdateOutput(UpdateOutputPayload)

UpdateResult(UpdateResultPayload)

BatchUpdateResult(BatchUpdateResultPayload)

DiscoveryResults(DiscoveryResultsPayload)

StdinAttention(StdinAttentionPayload)

Agent → Controller: the update process appears to be waiting for stdin input.

Sent when the agent detects that the process has produced no output for a sustained period while still running (heuristic: ~10 seconds of silence). The controller broadcasts this to interactive session subscribers and may trigger notifications.

ServiceTriggerUpdate(ServiceUpdateTriggerPayload)

ServiceTriggerHostBatchUpdate(ServiceHostBatchUpdateTriggerPayload)

Service → Controller: trigger a batch update of all outdated software items on a host.

Sent when a Home Assistant user presses “Install” on a host update entity.

Register(RegisterPayload)

Service declares its capabilities immediately on connect.

Sent from on_connected before ServiceSettings is processed. The controller uses this to establish session-level capability flags without relying on DB-stored values (which may be absent on first connect).

ReportPluginConfig(ReportPluginConfigPayload)

Service reports a plugin configuration to the controller.

Sent by agents that detect infrastructure (e.g. PVE nodes) during bootstrap. The controller creates or returns an existing plugin config matching (tenant_id, plugin_type, name) and responds with ReportPluginConfigResponse.

SurfaceRegistration(SurfaceRegistration)

Service declares its surfaces after connecting.

Sent once after connection setup by services that participate in the surface contract.

SurfaceActionResponse(SurfaceActionResponse)

Response to a proxied surface action invocation.

Sent by the service after processing a SurfaceActionRequest from the controller.

SurfaceActionRequest(SurfaceActionRequest)

Service requests a surface action invocation from the controller.

Enables services to call surface actions via the wire protocol and receive the correlated ControllerMessage::SurfaceActionResponse.

StoreServiceConfig(StoreServiceConfigPayload)

Service → Controller: upsert a config entry in the controller DB.

The controller encrypts sensitive values at rest, ACKs, and broadcasts ServiceConfigUpdated to all connected instances of the same service app.

DeleteServiceConfig(DeleteServiceConfigPayload)

Service → Controller: delete a config entry from the controller DB.

The controller deletes, ACKs, and broadcasts ServiceConfigUpdated.

WorkloadClaim(WorkloadClaimPayload)

Service → Controller: request exclusive ownership of config keys.

Sent after ServiceConfigDelivery is processed and whenever the desired config set changes. Uses full replacement semantics. Requires the WorkloadClaims capability.

WorkloadRelease(WorkloadReleasePayload)

Service → Controller: voluntarily release config keys.

Sent when a service no longer wants to serve certain configs. Requires the WorkloadClaims capability.

TestPluginConfigResult(TestPluginConfigResultPayload)

Agent -> Controller: result of a plugin configuration test.

Sent after the agent completes a config test request. The controller uses request_id to correlate with the pending REST API request.

AuditEvent(AuditEventPayload)

Service -> Controller: forwarded semantic audit event.

The controller re-validates the event and silently drops invalid or non-forwardable payloads without closing the connection.

Unknown

Unknown message type from a newer service build.

Deserialized when the type tag does not match any known variant. The payload is discarded. The receiver should log a warning and continue processing other messages.

Trait Implementations

impl Clone for ServiceMessage

fn clone(&self) -> ServiceMessage

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ServiceMessage

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ServiceMessage

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ServiceMessage

impl PartialEq for ServiceMessage

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ServiceMessage

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ServiceMessage

impl WireValidate for ServiceMessage

fn wire_validate(&self) -> Result<(), WireValidationError>

Validate that all fields are within wire protocol size limits.