// file: crates/common/game-realtime-transport-lib/src/error.rs
// version: 1

/// Stable transport-neutral category for a realtime operation failure.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TransportErrorKind {
    /// An endpoint or transport configuration is invalid.
    InvalidConfiguration,
    /// A client connection could not be established.
    Connect,
    /// A server endpoint could not be bound.
    Bind,
    /// A server could not accept an incoming connection.
    Accept,
    /// An operation exceeded its configured deadline.
    Timeout,
    /// A payload exceeds the configured transport bound.
    MessageTooLarge,
    /// The transport cannot currently accept more outbound data within its configured bounds.
    Backpressure,
    /// The requested operation requires a connection that is already closed.
    Closed,
    /// An underlying I/O operation failed.
    Io,
    /// The backend reported a protocol-level or transport-specific failure.
    Protocol,
    /// The operation was explicitly aborted or cancelled when that distinction is observable.
    Aborted,
}

impl core::fmt::Display for TransportErrorKind {
    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        return match self {
            crate::TransportErrorKind::InvalidConfiguration => formatter.write_str("invalid configuration"),
            crate::TransportErrorKind::Connect => formatter.write_str("connect failure"),
            crate::TransportErrorKind::Bind => formatter.write_str("bind failure"),
            crate::TransportErrorKind::Accept => formatter.write_str("accept failure"),
            crate::TransportErrorKind::Timeout => formatter.write_str("operation timed out"),
            crate::TransportErrorKind::MessageTooLarge => formatter.write_str("message too large"),
            crate::TransportErrorKind::Backpressure => formatter.write_str("transport backpressure"),
            crate::TransportErrorKind::Closed => formatter.write_str("connection closed"),
            crate::TransportErrorKind::Io => formatter.write_str("I/O failure"),
            crate::TransportErrorKind::Protocol => formatter.write_str("protocol failure"),
            crate::TransportErrorKind::Aborted => formatter.write_str("operation aborted"),
        };
    }
}

/// Transport-neutral operation failure with a stable category and diagnostic detail.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct TransportError {
    detail: String,
    kind: crate::TransportErrorKind,
}

impl TransportError {
    /// Creates a transport failure from a stable category and backend-neutral diagnostic detail.
    #[must_use]
    pub fn new(kind: crate::TransportErrorKind, detail: impl Into<String>) -> Self {
        return Self { detail: detail.into(), kind };
    }

    /// Borrows the diagnostic detail associated with the failure.
    #[must_use]
    pub fn detail(&self) -> &str {
        return self.detail.as_str();
    }

    /// Returns the stable transport-neutral failure category.
    #[must_use]
    pub fn kind(&self) -> crate::TransportErrorKind {
        return self.kind;
    }
}

impl core::fmt::Display for TransportError {
    fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        return write!(formatter, "{}: {}", self.kind, self.detail);
    }
}

impl std::error::Error for TransportError {}