brokkr-models::models::agents

Rust

Agent Module

This module defines structures and methods for managing agents in the system.

Data Model

Agents represent the entities responsible for executing tasks and managing deployments. They are stored in the agents table with the following structure:

• id: UUID, primary key
• created_at: TIMESTAMP, when the agent was created
• updated_at: TIMESTAMP, when the agent was last updated
• deleted_at: TIMESTAMP, for soft deletion support
• name: VARCHAR(255), name of the agent
• cluster_name: VARCHAR(255), name of the cluster the agent belongs to
• last_heartbeat: TIMESTAMP, last time the agent sent a heartbeat
• status: VARCHAR(50), current status of the agent
• pak_hash: VARCHAR(255), hash of the agent’s PAK (Pre-shared Authentication Key)
• k8s_reachable: BOOLEAN, nullable; agent’s self-reported Kubernetes API reachability
• k8s_api_latency_ms: INTEGER, nullable; agent’s self-reported Kubernetes API latency
• k8s_reported_at: TIMESTAMPTZ, nullable; server-side ingestion time of the latest k8s report

Usage

Agents are core entities in the system, responsible for executing tasks, managing deployments, and interacting with stacks. They report their status and heartbeats, allowing the system to monitor their health and availability.

Constraints

• Both name and cluster_name must be non-empty strings.
• There should be a unique constraint on the combination of name and cluster_name.

Structs

struct Agent

pub

Derives: Queryable, Selectable, Identifiable, AsChangeset, Debug, Clone, Serialize, Deserialize, Eq, PartialEq, Hash, ToSchema

Represents an agent in the database.

Fields

Name	Type	Description
id	Uuid	Unique identifier for the agent.
created_at	DateTime<Utc>	Timestamp when the agent was created.
updated_at	DateTime<Utc>	Timestamp when the agent was last updated.
deleted_at	Option<DateTime<Utc>>	Timestamp for soft deletion, if applicable.
name	String	Name of the agent.
cluster_name	String	Name of the cluster the agent belongs to.
last_heartbeat	Option<DateTime<Utc>>	Timestamp of the last heartbeat received from the agent.
status	String	Current status of the agent.
pak_hash	String	Hash of the agent’s Pre-shared Authentication Key (PAK).
k8s_reachable	Option<bool>	Latest agent-reported reachability of its own Kubernetes API (BROKKR-T-0227). None when the agent has never reported. The broker trusts this value as-is (it cannot compute it itself).
k8s_api_latency_ms	Option<i32>	Latest agent-reported latency (milliseconds) of the Kubernetes API reachability probe, if the agent measured one. None when unreported.
k8s_reported_at	Option<DateTime<Utc>>	Server-side ingestion time of the most recent K8s connectivity report, so readers can judge the freshness of k8s_reachable / k8s_api_latency_ms. None when the agent has never reported.

struct NewAgent

pub

Derives: Insertable, Debug, Clone, Serialize, Deserialize, ToSchema

Represents a new agent to be inserted into the database.

Fields

Name	Type	Description
name	String	Name of the agent.
cluster_name	String	Name of the cluster the agent belongs to.

Methods

new

pub

fn new(name: String, cluster_name: String) -> Result<Self, String>

Creates a new NewAgent instance.

Parameters:

Name	Type	Description
name	String	Name of the agent. Must be a non-empty string.
cluster_name	String	Name of the cluster the agent belongs to. Must be a non-empty string.

Returns:

Returns Ok(NewAgent) if both parameters are valid non-empty strings, otherwise returns an Err with a description of the validation failure.

Source

    pub fn new(name: String, cluster_name: String) -> Result<Self, String> {
        // Validate name
        if name.trim().is_empty() {
            return Err("Agent name cannot be empty".to_string());
        }

        // Validate cluster_name
        if cluster_name.trim().is_empty() {
            return Err("Cluster name cannot be empty".to_string());
        }

        Ok(NewAgent { name, cluster_name })
    }