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::{
    ConnectionId, OperationId, OperationSnapshot, RequestId, SessionId, TaskEndCause,
    TerminationOutcome, WriteOutcome,
};
use crate::error::ErrorKind;
use crate::module::ws_client::native_pending::NativePending;
use crate::module::ws_client::operation_control::OperationControl;
use crate::{Metadata, NetError, Result};
use std::fmt;
use std::sync::{Arc, Mutex, Weak};
use std::time::Instant;

/// Correlation credentials for one request registration.
///
/// The credential does not keep the pending-request table alive. Its token and
/// table identity prevent a stale handle from terminating a later request that
/// reuses the same protocol request ID.
#[derive(Clone)]
pub struct RequestRegistration {
    /// Application-level identifier used to match a response.
    request_id: RequestId,
    /// Logical session that owns this registration.
    session_id: SessionId,
    /// Time at which the request entered the pending-response table.
    registered_at: Instant,
    /// Generation token distinguishing registrations that reuse a request ID.
    token: u64,
    /// Weak reference to the originating pending table, used for ownership
    /// validation and termination.
    pending: Weak<NativePending>,
    /// Shared response-timing state. The deadline may be established lazily
    /// when the request is written, and is shared by all credential clones.
    timing: Arc<RegistrationTiming>,
}

/// Response-timing state shared by all handles for one registration.
pub(crate) struct RegistrationTiming {
    /// Original response deadline, excluding any bounded manual-dispatch grace
    /// period. `None` means the deadline has not been established yet.
    deadline: Mutex<Option<Instant>>,
}

impl RegistrationTiming {
    pub(crate) fn new(deadline: Option<Instant>) -> Self {
        Self {
            deadline: Mutex::new(deadline),
        }
    }

    pub(crate) fn deadline(&self) -> Result<Option<Instant>> {
        self.deadline
            .lock()
            .map(|value| *value)
            .map_err(NetError::from_poison)
    }

    pub(crate) fn establish(&self, deadline: Instant) -> Result<()> {
        let mut current = self.deadline.lock().map_err(NetError::from_poison)?;
        if current.is_none() {
            *current = Some(deadline);
        }
        Ok(())
    }
}

impl RequestRegistration {
    pub(crate) fn new(
        request_id: RequestId,
        session_id: SessionId,
        registered_at: Instant,
        token: u64,
        pending: Weak<NativePending>,
        timing: Arc<RegistrationTiming>,
    ) -> Self {
        Self {
            request_id,
            session_id,
            registered_at,
            token,
            pending,
            timing,
        }
    }

    /// Returns the application-level identifier used for response matching.
    pub fn request_id(&self) -> &RequestId {
        &self.request_id
    }
    /// Returns the logical session that owns this registration.
    pub fn session_id(&self) -> SessionId {
        self.session_id
    }
    /// Returns when this registration entered the pending table.
    pub fn registered_at(&self) -> Instant {
        self.registered_at
    }

    /// Returns the original response deadline, excluding bounded grace for
    /// manual response dispatch.
    pub fn response_deadline(&self) -> Result<Option<Instant>> {
        self.timing.deadline()
    }

    pub(crate) fn token(&self) -> u64 {
        self.token
    }
    pub(crate) fn pending(&self) -> Weak<NativePending> {
        self.pending.clone()
    }
    pub(crate) fn belongs_to(&self, pending: &NativePending) -> bool {
        std::ptr::eq(self.pending.as_ptr(), pending)
    }
}

impl fmt::Debug for RequestRegistration {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("RequestRegistration")
            .field("request_id", &self.request_id)
            .field("session_id", &self.session_id)
            .field("registered_at", &self.registered_at)
            .field("response_deadline", &self.response_deadline())
            .finish_non_exhaustive()
    }
}

/// Stand-alone snapshot of a pending request at query time.
///
/// The snapshot does not retain the request payload and does not freeze later
/// state transitions.
///
/// `Debug` summarizes the business identifier and metadata while retaining operation diagnostics.
#[derive(Clone)]
pub struct RequestSnapshot {
    /// Identifier of the underlying send operation.
    pub operation_id: OperationId,
    /// Application-level identifier used to match a response.
    pub request_id: RequestId,
    /// Logical session that owns the request.
    pub session_id: SessionId,
    /// Physical connection assigned to the request, or `None` before one is
    /// assigned.
    pub connection_id: Option<ConnectionId>,
    /// Time at which the request entered the pending-response table.
    pub registered_at: Instant,
    /// Original response deadline, excluding manual-dispatch grace; `None`
    /// means no deadline has been established yet.
    pub response_deadline: Option<Instant>,
    /// Copy of the request metadata captured by this query.
    pub metadata: Metadata,
    /// Send-operation snapshot captured by the same query.
    pub operation: OperationSnapshot,
}

impl fmt::Debug for RequestSnapshot {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("RequestSnapshot")
            .field("operation_id", &self.operation_id)
            .field("request_id", &self.request_id)
            .field("session_id", &self.session_id)
            .field("connection_id", &self.connection_id)
            .field("registered_at", &self.registered_at)
            .field("response_deadline", &self.response_deadline)
            .field("metadata_entries", &self.metadata.len())
            .field("operation", &self.operation)
            .finish()
    }
}

/// Shareable handle for observing or explicitly terminating a request.
///
/// The handle does not retain the request payload. Clones operate on the same
/// operation, while the registration credential keeps termination scoped to
/// the original registration.
#[derive(Clone)]
pub struct RequestHandle {
    /// Shared operation state used to observe write progress and the terminal
    /// result.
    core: Arc<OperationControl>,
    /// Registration credential that prevents terminating a later request with
    /// the same protocol identifier.
    registration: RequestRegistration,
}

impl RequestHandle {
    /// Returns the `WsRequest` diagnostic reference for this request registration.
    ///
    /// The SDK allocates the observation while preparing admission and binds it to
    /// this registration's operation control. It can include queueing, local
    /// transport writing, response matching, and delivery boundaries when those
    /// phases were observed. For a retried logical request, this reference belongs
    /// to an individual registration; the enclosing
    /// [`super::WsRequestOperationHandle::quality_ref`] identifies its parent
    /// logical operation when both observations were retained.
    ///
    /// `None` means no observation was allocated, including Off/dormant or excluded
    /// WebSocket collection, unavailable owner, or exhausted diagnostic capacity.
    /// Reading this value does not activate collection or wait for a response.
    /// Resolve it with the owning engine's `QualityDoctor::lookup`; references
    /// neither pin reports nor guarantee that all phase events were retained.
    #[cfg(feature = "quality-doctor")]
    pub fn quality_ref(&self) -> Option<crate::api::quality::QualityReportRef> {
        self.core.quality_ref()
    }
    #[cfg(feature = "quality-doctor")]
    pub(crate) fn quality_parent(&self, parent: crate::api::quality::QualityReportRef) {
        if let Some(probe) = self.core.quality() {
            probe.parent(parent);
        }
    }
    pub(crate) fn retry_report(&self) -> crate::api::retry::RetryReport {
        self.core.retry_report()
    }

    pub(crate) fn has_selected_result(&self) -> bool {
        self.core.is_finished()
    }

    /// Compete with response/failure selection under the same pending/core
    /// authority, then let the existing response channel publish that winner.
    pub(crate) fn expire_operation_attempt(&self) {
        self.core
            .prepare_termination(self.core.deadline_error(), TaskEndCause::Expired)
            .dispatch();
    }

    pub(crate) fn new(core: Arc<OperationControl>, registration: RequestRegistration) -> Self {
        Self { core, registration }
    }
    /// Returns the identifier of the underlying send operation.
    pub fn id(&self) -> OperationId {
        self.core.id()
    }
    /// Returns the application-level request identifier used for response matching.
    pub fn request_id(&self) -> &RequestId {
        self.registration.request_id()
    }
    /// Returns the registration credential associated with this handle.
    pub fn registration(&self) -> &RequestRegistration {
        &self.registration
    }
    /// Reads a point-in-time snapshot of the request's send operation.
    pub fn state(&self) -> Result<OperationSnapshot> {
        self.core.snapshot()
    }
    /// Requests cancellation before delivery, or after delivery while waiting
    /// for a response. The returned outcome describes the race with completion.
    pub fn cancel(&self) -> Result<TerminationOutcome> {
        self.terminate(
            NetError::from(ErrorKind::Cancelled),
            TaskEndCause::Cancelled,
        )
    }
    /// Marks the request as expired and applies the same race rules as
    /// [`Self::cancel`].
    pub fn expire(&self) -> Result<TerminationOutcome> {
        self.terminate(NetError::from(ErrorKind::TimedOut), TaskEndCause::Expired)
    }
    /// Waits until the underlying message has completed its local write.
    ///
    /// This does not mean that the peer received or processed the message;
    /// response completion is reported by the request's response receiver.
    pub async fn written(&self) -> Result<WriteOutcome> {
        self.core.written().await
    }

    fn terminate(&self, error: NetError, cause: TaskEndCause) -> Result<TerminationOutcome> {
        if let Some(pending) = self.registration.pending.upgrade() {
            pending.terminate(self.request_id(), self.registration.token, error, cause)
        } else if self.core.snapshot()?.result.is_some() {
            Ok(TerminationOutcome::AlreadyFinished)
        } else {
            Err(NetError::from(ErrorKind::EngineDropped))
        }
    }
}

impl fmt::Debug for RequestHandle {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("RequestHandle")
            .field("id", &self.id())
            .field("registration", &self.registration)
            .field("state", &self.state())
            .finish()
    }
}