brokkr-models::models::work_orders

Rust

Work Orders Module

This module defines structures for managing work orders in the system. Work orders represent transient operations like builds, tests, or backups that are routed to agents for execution.

Data Model

The work order system uses a two-table design:

• work_orders: Active queue for routing and retry management
• work_order_log: Permanent audit trail of completed work orders

Status Flow

Work orders transition through these states:

• PENDING: Ready to be claimed by an agent
• CLAIMED: Currently being processed by an agent
• RETRY_PENDING: Failed but waiting for retry backoff period

On completion (success or max retries exceeded), records move to work_order_log.

Structs

struct WorkOrder

pub

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

Represents an active work order in the queue.

Fields

Name	Type	Description
id	Uuid	Unique identifier for the work order.
created_at	DateTime<Utc>	Timestamp when the work order was created.
updated_at	DateTime<Utc>	Timestamp when the work order was last updated.
work_type	String	Type of work (e.g., “build”, “test”, “backup”).
yaml_content	String	Multi-document YAML content (e.g., Build + WorkOrder definitions).
status	String	Queue status: PENDING, CLAIMED, or RETRY_PENDING.
claimed_by	Option<Uuid>	ID of the agent that claimed this work order (if any).
claimed_at	Option<DateTime<Utc>>	Timestamp when the work order was claimed.
claim_timeout_seconds	i32	Seconds before a claimed work order is considered stale.
max_retries	i32	Maximum number of retry attempts.
retry_count	i32	Current retry count.
backoff_seconds	i32	Base backoff seconds for exponential retry calculation.
next_retry_after	Option<DateTime<Utc>>	Timestamp when RETRY_PENDING work order becomes PENDING again.
last_error	Option<String>	Most recent error message from failed execution attempt.
last_error_at	Option<DateTime<Utc>>	Timestamp of the most recent failure.

struct NewWorkOrder

pub

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

Represents a new work order to be inserted into the database.

Fields

Name	Type	Description
work_type	String	Type of work (e.g., “build”, “test”, “backup”).
yaml_content	String	Multi-document YAML content.
max_retries	i32	Maximum number of retry attempts.
backoff_seconds	i32	Base backoff seconds for exponential retry calculation.
claim_timeout_seconds	i32	Seconds before a claimed work order is considered stale.

Methods

new

pub

fn new(
    work_type: String,
    yaml_content: String,
    max_retries: Option<i32>,
    backoff_seconds: Option<i32>,
    claim_timeout_seconds: Option<i32>,
) -> Result<Self, String>

Creates a new NewWorkOrder instance with validation.

Parameters:

Name	Type	Description
work_type	String	Type of work (e.g., “build”, “test”).
yaml_content	String	Multi-document YAML content.
max_retries	Option<i32>	Maximum retry attempts (optional, defaults to 3).
backoff_seconds	Option<i32>	Base backoff for retries (optional, defaults to 60).
claim_timeout_seconds	Option<i32>	Claim timeout (optional, defaults to 3600).

Returns:

Returns Ok(NewWorkOrder) if valid, otherwise Err with validation error.

Source

    pub fn new(
        work_type: String,
        yaml_content: String,
        max_retries: Option<i32>,
        backoff_seconds: Option<i32>,
        claim_timeout_seconds: Option<i32>,
    ) -> Result<Self, String> {
        // Validate work_type
        if work_type.trim().is_empty() {
            return Err("Work type cannot be empty".to_string());
        }

        // Validate yaml_content
        if yaml_content.trim().is_empty() {
            return Err("YAML content cannot be empty".to_string());
        }

        let max_retries = max_retries.unwrap_or(3);
        let backoff_seconds = backoff_seconds.unwrap_or(60);
        let claim_timeout_seconds = claim_timeout_seconds.unwrap_or(3600);

        if max_retries < 0 {
            return Err("max_retries must be non-negative".to_string());
        }

        if backoff_seconds <= 0 {
            return Err("backoff_seconds must be positive".to_string());
        }

        if claim_timeout_seconds <= 0 {
            return Err("claim_timeout_seconds must be positive".to_string());
        }

        Ok(NewWorkOrder {
            work_type,
            yaml_content,
            max_retries,
            backoff_seconds,
            claim_timeout_seconds,
        })
    }

struct WorkOrderLog

pub

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

Represents a completed work order in the audit log.

Fields

Name	Type	Description
id	Uuid	Original work order ID.
work_type	String	Type of work.
created_at	DateTime<Utc>	Timestamp when the work order was created.
claimed_at	Option<DateTime<Utc>>	Timestamp when the work order was claimed.
completed_at	DateTime<Utc>	Timestamp when the work order completed.
claimed_by	Option<Uuid>	ID of the agent that executed this work order.
success	bool	Whether the work completed successfully.
retries_attempted	i32	Number of retry attempts before completion.
result_message	Option<String>	Result message (image digest on success, error details on failure).
yaml_content	String	Original YAML content for debugging/reconstruction.

struct NewWorkOrderLog

pub

Derives: Insertable, Debug, Clone, Serialize, Deserialize

Represents a new work order log entry to be inserted.

Fields

Name	Type	Description
id	Uuid	Original work order ID.
work_type	String	Type of work.
created_at	DateTime<Utc>	Timestamp when the work order was created.
claimed_at	Option<DateTime<Utc>>	Timestamp when the work order was claimed.
claimed_by	Option<Uuid>	ID of the agent that executed this work order.
success	bool	Whether the work completed successfully.
retries_attempted	i32	Number of retry attempts before completion.
result_message	Option<String>	Result message.
yaml_content	String	Original YAML content.

Methods

from_​work_​order

pub

fn from_work_order(
    work_order: &WorkOrder,
    success: bool,
    result_message: Option<String>,
) -> Self

Creates a new log entry from a completed work order.

Source

    pub fn from_work_order(
        work_order: &WorkOrder,
        success: bool,
        result_message: Option<String>,
    ) -> Self {
        NewWorkOrderLog {
            id: work_order.id,
            work_type: work_order.work_type.clone(),
            created_at: work_order.created_at,
            claimed_at: work_order.claimed_at,
            claimed_by: work_order.claimed_by,
            success,
            retries_attempted: work_order.retry_count,
            result_message,
            yaml_content: work_order.yaml_content.clone(),
        }
    }

struct WorkOrderTarget

pub

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

Represents a work order target (agent routing).

Fields

Name	Type	Description
id	Uuid	Unique identifier for the target entry.
work_order_id	Uuid	ID of the work order.
agent_id	Uuid	ID of the eligible agent.
created_at	DateTime<Utc>	Timestamp when the target was created.

struct NewWorkOrderTarget

pub

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

Represents a new work order target to be inserted.

Fields

Name	Type	Description
work_order_id	Uuid	ID of the work order.
agent_id	Uuid	ID of the eligible agent.

Methods

new

pub

fn new(work_order_id: Uuid, agent_id: Uuid) -> Result<Self, String>

Creates a new work order target.

Source

    pub fn new(work_order_id: Uuid, agent_id: Uuid) -> Result<Self, String> {
        if work_order_id.is_nil() {
            return Err("Invalid work order ID".to_string());
        }
        if agent_id.is_nil() {
            return Err("Invalid agent ID".to_string());
        }
        Ok(NewWorkOrderTarget {
            work_order_id,
            agent_id,
        })
    }

Constants

Name	Type	Value	Description
WORK_ORDER_STATUS_PENDING	&str	"PENDING"	Valid work order statuses
WORK_ORDER_STATUS_CLAIMED	&str	"CLAIMED"
WORK_ORDER_STATUS_RETRY_PENDING	&str	"RETRY_PENDING"
WORK_TYPE_BUILD	&str	"build"	Valid work types