rover_nexus_core 0.2.0

// Copyright 2026 Rottinghaus Dynamics
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Internal control-plane message types that are NOT part of the UplinkMsg
//! / InternalCommand wire unions.
//!
//! These travel on dedicated channels
//! and exist so application code can detect transport-level conditions —
//! today, fleet-manager reachability — without polluting the data-plane
//! message unions.

use serde::{Deserialize, Serialize};
use uuid::Uuid;

// Status messages sent from the agent to the server.
// The robot software doesn't see these.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum AgentTelemetry {
    Heartbeat(Heartbeat),
    RobotAck(RobotAck),
}

/// Heartbeat sent robot -> server periodically on a dedicated channel. The
/// server replies with a [`HeartbeatAck`] echoing `seq` and `sent_time_ms`.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Heartbeat {
    pub seq: u64,
    pub sent_time_ms: i64,
}

/// Reply to a [`Heartbeat`], sent server -> robot on a dedicated channel.
/// `seq` and `robot_sent_time_ms` are echoed verbatim so the robot can match
/// the ack and compute RTT.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct HeartbeatAck {
    pub seq: u64,
    pub robot_sent_time_ms: i64,
    pub server_recv_time_ms: i64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum AckStatus {
    Sent,
    AgentReceived,
    AgentRejected,
    RobotReceived,
    RobotRejected,
    RobotStateConfirmed,
}

// From robot to server
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RobotAck {
    pub command_id: Uuid,
    pub status: AckStatus, // received | accepted | rejected
    pub reason: Option<String>,
    pub received_at_ms: i64,
}