phytrace_sdk/transport/

traits.rs

//! Transport trait definitions.
//!
//! Defines the common interface for all transport implementations.

use async_trait::async_trait;
use std::fmt::Debug;

use crate::error::PhyTraceResult;
use crate::models::event::UdmEvent;

/// Transport layer trait for sending events.
///
/// Implementations should handle:
/// - Connection management
/// - Authentication
/// - Serialization
/// - Error handling and retries (optional, can be handled by reliability layer)
#[async_trait]
pub trait Transport: Send + Sync + Debug {
    /// Send a single event.
    async fn send(&self, event: &UdmEvent) -> PhyTraceResult<SendResult>;

    /// Send a batch of events.
    async fn send_batch(&self, events: &[UdmEvent]) -> PhyTraceResult<BatchResult>;

    /// Check if the transport is connected/ready.
    async fn is_connected(&self) -> bool;

    /// Connect to the remote endpoint.
    async fn connect(&mut self) -> PhyTraceResult<()>;

    /// Disconnect from the remote endpoint.
    async fn disconnect(&mut self) -> PhyTraceResult<()>;

    /// Get transport statistics.
    fn stats(&self) -> TransportStats;

    /// Get transport name for logging.
    fn name(&self) -> &str;
}

/// Result of sending a single event.
#[derive(Debug, Clone)]
pub struct SendResult {
    /// Whether the send was successful.
    pub success: bool,

    /// HTTP status code (if applicable).
    pub status_code: Option<u16>,

    /// Response message.
    pub message: Option<String>,

    /// Time taken in milliseconds.
    pub latency_ms: u64,

    /// Whether the event was accepted by the server.
    pub accepted: bool,
}

impl SendResult {
    /// Create a successful result.
    pub fn success(latency_ms: u64) -> Self {
        Self {
            success: true,
            status_code: Some(200),
            message: None,
            latency_ms,
            accepted: true,
        }
    }

    /// Create a failed result.
    pub fn failure(status_code: Option<u16>, message: impl Into<String>) -> Self {
        Self {
            success: false,
            status_code,
            message: Some(message.into()),
            latency_ms: 0,
            accepted: false,
        }
    }

    /// Check if the error is retryable.
    pub fn is_retryable(&self) -> bool {
        match self.status_code {
            Some(code) => {
                // Retry on server errors (5xx) and some client errors
                code >= 500 || code == 429 || code == 408
            }
            None => true, // Network errors are typically retryable
        }
    }
}

/// Result of sending a batch of events.
#[derive(Debug, Clone)]
pub struct BatchResult {
    /// Total events in batch.
    pub total: usize,

    /// Successfully sent events.
    pub succeeded: usize,

    /// Failed events.
    pub failed: usize,

    /// Time taken in milliseconds.
    pub latency_ms: u64,

    /// Individual results (if available).
    pub individual_results: Option<Vec<SendResult>>,
}

impl BatchResult {
    /// Create a fully successful batch result.
    pub fn all_success(total: usize, latency_ms: u64) -> Self {
        Self {
            total,
            succeeded: total,
            failed: 0,
            latency_ms,
            individual_results: None,
        }
    }

    /// Create a fully failed batch result.
    pub fn all_failed(total: usize, _message: &str) -> Self {
        Self {
            total,
            succeeded: 0,
            failed: total,
            latency_ms: 0,
            individual_results: None,
        }
    }

    /// Check if all events succeeded.
    pub fn all_succeeded(&self) -> bool {
        self.succeeded == self.total
    }

    /// Check if all events failed.
    pub fn all_failed_check(&self) -> bool {
        self.failed == self.total
    }

    /// Get success rate as a percentage.
    pub fn success_rate(&self) -> f64 {
        if self.total == 0 {
            100.0
        } else {
            (self.succeeded as f64 / self.total as f64) * 100.0
        }
    }
}

/// Transport statistics.
#[derive(Debug, Clone, Default)]
pub struct TransportStats {
    /// Total events sent.
    pub events_sent: u64,

    /// Successful sends.
    pub events_succeeded: u64,

    /// Failed sends.
    pub events_failed: u64,

    /// Bytes sent.
    pub bytes_sent: u64,

    /// Total latency in milliseconds.
    pub total_latency_ms: u64,

    /// Number of retries.
    pub retries: u64,

    /// Number of connections made.
    pub connections: u64,

    /// Number of connection errors.
    pub connection_errors: u64,
}

impl TransportStats {
    /// Calculate average latency.
    pub fn average_latency_ms(&self) -> f64 {
        if self.events_succeeded == 0 {
            0.0
        } else {
            self.total_latency_ms as f64 / self.events_succeeded as f64
        }
    }

    /// Calculate success rate.
    pub fn success_rate(&self) -> f64 {
        if self.events_sent == 0 {
            100.0
        } else {
            (self.events_succeeded as f64 / self.events_sent as f64) * 100.0
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_send_result() {
        let success = SendResult::success(50);
        assert!(success.success);
        assert!(success.accepted);

        let failure = SendResult::failure(Some(500), "Server error");
        assert!(!failure.success);
        assert!(failure.is_retryable());

        let not_retryable = SendResult::failure(Some(400), "Bad request");
        assert!(!not_retryable.is_retryable());
    }

    #[test]
    fn test_batch_result() {
        let result = BatchResult::all_success(10, 100);
        assert!(result.all_succeeded());
        assert_eq!(result.success_rate(), 100.0);

        let partial = BatchResult {
            total: 10,
            succeeded: 7,
            failed: 3,
            latency_ms: 150,
            individual_results: None,
        };
        assert!(!partial.all_succeeded());
        assert_eq!(partial.success_rate(), 70.0);
    }

    #[test]
    fn test_transport_stats() {
        let stats = TransportStats {
            events_sent: 100,
            events_succeeded: 95,
            events_failed: 5,
            total_latency_ms: 4750,
            ..Default::default()
        };

        assert_eq!(stats.average_latency_ms(), 50.0);
        assert_eq!(stats.success_rate(), 95.0);
    }
}