open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
use super::{
    ClientId, ConnectionId, DeliveryEvidence, Message, MessageLane, OperationId, OperationPhase,
    Request, SessionId, TaskSuccess,
};
use crate::{error::ErrorKind, NetError, Result};
use std::sync::Arc;

/// Terminal event emitted for an admitted message or request operation.
#[derive(Clone, Debug)]
pub struct TaskEvent {
    /// Client that owns the operation.
    pub client_id: ClientId,
    /// Logical session that owns the operation.
    pub session_id: SessionId,
    /// Identifier of this send or request operation.
    pub operation_id: OperationId,
    /// Physical connection associated with the operation, if one was bound.
    pub connection_id: Option<ConnectionId>,
    /// Original message or request shared with observers.
    pub source: TaskSource,
    /// Send lane used by the operation.
    pub lane: MessageLane,
    /// Processing phase immediately before the terminal result became effective.
    pub phase: OperationPhase,
    /// Strongest delivery evidence known when the operation ended.
    pub delivery: DeliveryEvidence,
    /// Cause that ended the operation.
    pub cause: TaskEndCause,
    /// The single effective success or error result; success does not imply business acceptance by the peer.
    pub result: Result<TaskSuccess>,
}

/// Original task input shared by cloned events without copying the payload.
#[derive(Clone)]
pub enum TaskSource {
    /// Metadata for a logical request whose wire payload is generated per attempt.
    /// The factory and idempotency key are deliberately excluded.
    RequestOperation(Arc<crate::Metadata>),
    /// A message send that has no response tracking.
    Message(
        /// Original message shared by the task and observers.
        Arc<Message>,
    ),
    /// A request whose business response is tracked.
    Request(
        /// Original request and metadata shared by the task and observers.
        Arc<Request>,
    ),
}

impl std::fmt::Debug for TaskSource {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Message(message) => f.debug_tuple("Message").field(message).finish(),
            Self::Request(request) => f.debug_tuple("Request").field(request).finish(),
            Self::RequestOperation(metadata) => f
                .debug_struct("RequestOperation")
                .field("metadata_entries", &metadata.len())
                .finish(),
        }
    }
}

impl TaskSource {
    /// Counts the owned variable-size input once for the shared payload budget.
    pub(crate) fn payload_bytes(&self) -> Result<usize> {
        match self {
            Self::RequestOperation(metadata) => {
                metadata.iter().try_fold(0usize, |bytes, (key, value)| {
                    bytes
                        .checked_add(key.len())
                        .and_then(|size| size.checked_add(value.len()))
                        .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))
                })
            }
            Self::Message(message) => Ok(message.len()),
            Self::Request(request) => {
                let mut bytes = request
                    .message()
                    .len()
                    .checked_add(request.id().as_str().len())
                    .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
                for (key, value) in request.metadata() {
                    bytes = bytes
                        .checked_add(key.len())
                        .and_then(|size| size.checked_add(value.len()))
                        .ok_or_else(|| NetError::from(ErrorKind::ItemTooLarge))?;
                }
                Ok(bytes)
            }
        }
    }
}

/// Reason why a message or request reached its terminal state.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TaskEndCause {
    /// Local write completed, or a matching final response was received.
    Completed,
    /// Explicit cancellation, cancellation-group cancellation, or owner drop.
    Cancelled,
    /// The operation deadline or processing timeout elapsed.
    Expired,
    /// The connection ended before the operation could continue.
    Disconnected,
    /// Client or engine shutdown terminated the operation.
    Shutdown,
    /// Another processing error caused failure.
    Failed,
}

/// Owning subscription receiver for terminal task events.
pub type TaskEvents = crate::subscription::EventReceiver<TaskEvent>;