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::{AttemptId, ClientId, CycleId, SessionId};
use crate::error::{ErrorKind, ErrorStage};
use crate::{BoxError, HeaderMap, Metadata, NetError, Result};
use std::fmt;
use std::future::Future;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use tokio::sync::{oneshot, Semaphore};

type ProviderOutput = std::result::Result<HandshakeHeaders, BoxError>;
type ProviderFuture = Pin<Box<dyn Future<Output = ProviderOutput> + Send + 'static>>;
type AsyncProvider = dyn Fn(HandshakeAttempt) -> Result<ProviderFuture> + Send + Sync;
type BlockingProvider = dyn Fn(HandshakeAttempt) -> Result<HandshakeHeaders> + Send + Sync;

/// Provider that generates dynamic request headers for each WebSocket handshake.
/// It supports asynchronous and blocking callbacks; clones share the callback,
/// and the SDK converts callback and future panics into classified errors.
#[derive(Clone)]
pub struct HandshakeProvider {
    /// Shared callbacks and how they are executed.
    inner: ProviderKind,
}

/// The internal implementation of the handshake request header provider.
#[derive(Clone)]
enum ProviderKind {
    /// Future returned by the asynchronous callback.
    Async(
        /// Shared asynchronous callback that returns a future for computing
        /// handshake request headers.
        Arc<AsyncProvider>,
    ),
    /// Execute blocking callbacks on separate threads subject to concurrency quotas.
    Blocking(
        /// A shared blocking callback that directly returns handshake request headers or errors.
        Arc<BlockingProvider>,
    ),
}

impl HandshakeProvider {
    /// Creates an asynchronous provider invoked for each handshake attempt.
    ///
    /// Callback panics and future polling failures are converted to classified errors.
    pub fn new<F, Fut>(provider: F) -> Self
    where
        F: Fn(HandshakeAttempt) -> Fut + Send + Sync + 'static,
        Fut: Future<Output = ProviderOutput> + Send + 'static,
    {
        let callback = Owned::new(provider);
        Self {
            inner: ProviderKind::Async(Arc::new(move |attempt| {
                let provider = callback.value.as_ref().ok_or_else(internal_failure)?;
                caught(catch_unwind(AssertUnwindSafe(|| provider(attempt))))
                    .map(|future| Box::pin(future) as ProviderFuture)
            })),
        }
    }

    /// Creates a provider whose callback runs on a dedicated blocking worker.
    ///
    /// The configured blocking-handshake quota limits concurrent callback execution.
    pub fn blocking<F>(provider: F) -> Self
    where
        F: Fn(HandshakeAttempt) -> ProviderOutput + Send + Sync + 'static,
    {
        let callback = Owned::new(provider);
        Self {
            inner: ProviderKind::Blocking(Arc::new(move |attempt| {
                let provider = callback.value.as_ref().ok_or_else(internal_failure)?;
                resolve_provider_outcome(catch_unwind(AssertUnwindSafe(|| provider(attempt))))
            })),
        }
    }

    #[cfg(test)]
    pub(crate) async fn provide(
        &self,
        attempt: HandshakeAttempt,
        slots: Arc<Semaphore>,
    ) -> Result<HandshakeHeaders> {
        self.provide_with_threads(
            attempt,
            slots,
            Arc::new(crate::common::retirement::ThreadRegistry::new()),
        )
        .await
    }

    pub(crate) async fn provide_with_threads(
        &self,
        attempt: HandshakeAttempt,
        slots: Arc<Semaphore>,
        threads: Arc<crate::common::retirement::ThreadRegistry>,
    ) -> Result<HandshakeHeaders> {
        let identity = (attempt.client_id, attempt.session_id, attempt.attempt_id);
        let result = match &self.inner {
            ProviderKind::Async(provider) => {
                let provided = {
                    let _scope = crate::common::retirement::ExecutionScope::enter();
                    provider(attempt)
                };
                // End the synchronous invocation scope before awaiting the future.
                match provided {
                    Ok(future) => GuardedFuture::new(future).await,
                    Err(error) => Err(error),
                }
            }
            ProviderKind::Blocking(provider) => {
                run_blocking_with_spawn(provider.clone(), attempt, slots, |job| {
                    threads.spawn("open-net-ws-context-provider", job)
                })
                .await
            }
        };
        result.map_err(|error| {
            let mut context = error.context().clone();
            context.client_id = Some(identity.0);
            context.session_id = Some(identity.1);
            context.attempt_id = Some(identity.2);
            error.with_context(context)
        })
    }
}

impl fmt::Debug for HandshakeProvider {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mode = match self.inner {
            ProviderKind::Async(_) => "async",
            ProviderKind::Blocking(_) => "blocking",
        };
        formatter
            .debug_struct("HandshakeProvider")
            .field("mode", &mode)
            .finish_non_exhaustive()
    }
}

/// Identity and caller metadata for one handshake attempt, exposed to dynamic
/// header callbacks and connection events. `Debug` reports only the metadata
/// entry count and never its contents.
#[derive(Clone)]
pub struct HandshakeAttempt {
    /// The ID of the client instance that initiated the handshake.
    pub client_id: ClientId,
    /// The connection session ID to which this attempt belongs.
    pub session_id: SessionId,
    /// The connection or reconnection cycle identifier to which this attempt belongs.
    pub cycle_id: CycleId,
    /// Identifies this specific handshake attempt.
    pub attempt_id: AttemptId,
    /// Shared metadata inherited from connection options; the SDK does not automatically send this as a request header.
    pub metadata: Arc<Metadata>,
}

impl fmt::Debug for HandshakeAttempt {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HandshakeAttempt")
            .field("client_id", &self.client_id)
            .field("session_id", &self.session_id)
            .field("cycle_id", &self.cycle_id)
            .field("attempt_id", &self.attempt_id)
            .field("metadata_count", &self.metadata.len())
            .finish()
    }
}

/// Additional request headers and an optional credential-version marker returned
/// by the dynamic handshake provider. `Debug` reports only the header count and
/// version length, never their contents.
#[derive(Clone)]
pub struct HandshakeHeaders {
    /// Additional request headers for this handshake. They must not override
    /// SDK-managed `Host`, `Connection`, `Upgrade`, `Sec-WebSocket-Key`, or
    /// `Sec-WebSocket-Version` headers.
    pub headers: HeaderMap,
    /// Credential version used to correlate connection and failure events, up to 256 UTF-8 bytes;
    /// `None` means no version is provided, and the SDK does not automatically add this field to the request header.
    pub credential_version: Option<String>,
}

impl HandshakeHeaders {
    /// Creates handshake headers with no credential-version marker.
    pub fn new(headers: HeaderMap) -> Self {
        Self {
            headers,
            credential_version: None,
        }
    }
}

impl fmt::Debug for HandshakeHeaders {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HandshakeHeaders")
            .field("header_count", &self.headers.len())
            .field(
                "credential_version_bytes",
                &self.credential_version.as_ref().map(String::len),
            )
            .finish()
    }
}

pub(crate) fn validate_headers(headers: &HeaderMap) -> Result<()> {
    use http::header::{CONNECTION, HOST, SEC_WEBSOCKET_KEY, SEC_WEBSOCKET_VERSION, UPGRADE};
    if [
        HOST,
        CONNECTION,
        UPGRADE,
        SEC_WEBSOCKET_KEY,
        SEC_WEBSOCKET_VERSION,
    ]
    .iter()
    .any(|name| headers.contains_key(name))
    {
        return Err(NetError::input(
            "headers",
            "must not override SDK-managed WebSocket handshake headers",
        ));
    }
    Ok(())
}

/// Wraps user values held by the SDK so they can be released without holding
/// internal locks, while preventing destructor panics from escaping. Values
/// handed to the caller are removed from this wrapper and then follow normal
/// ownership rules.
struct Owned<T> {
    /// Value not yet handed over or released; `None` means this wrapper no
    /// longer owns a value.
    value: Option<T>,
}

impl<T> Owned<T> {
    fn new(value: T) -> Self {
        Self { value: Some(value) }
    }
    fn take(&mut self) -> Result<T> {
        self.value.take().ok_or_else(internal_failure)
    }
}

impl<T> Drop for Owned<T> {
    fn drop(&mut self) {
        retire(self.value.take());
    }
}

fn retire<T>(value: T) -> bool {
    match catch_unwind(AssertUnwindSafe(|| drop(value))) {
        Ok(()) => false,
        Err(payload) => {
            crate::log_e!(crate::common::log::log_def::LogType::WSC;
                "ws.handshake.retire", "arg_value|stage|error", "redacted", "provider", "user_value_cleanup_panicked");
            dispose_payload(payload);
            true
        }
    }
}

fn dispose_payload(payload: Box<dyn std::any::Any + Send>) {
    // Only a second unwind while destroying a caught panic payload is abandoned.
    if let Err(secondary) = catch_unwind(AssertUnwindSafe(|| drop(payload))) {
        crate::log_e!(crate::common::log::log_def::LogType::WSC;
            "ws.handshake.dispose_payload", "arg_payload|stage|error", "redacted", "provider", "panic_payload_cleanup_panicked");
        std::mem::forget(secondary);
    }
}

fn internal_failure() -> NetError {
    NetError::from(ErrorKind::Internal).with_stage(ErrorStage::Provider)
}

fn callback_failure() -> NetError {
    NetError::from(ErrorKind::CallbackPanicked).with_stage(ErrorStage::Provider)
}

fn caught<T>(outcome: std::thread::Result<T>) -> Result<T> {
    outcome.map_err(|payload| {
        dispose_payload(payload);
        callback_failure()
    })
}

fn resolve_provider_outcome(
    outcome: std::thread::Result<ProviderOutput>,
) -> Result<HandshakeHeaders> {
    resolve_provider_output(caught(outcome)?)
}

fn resolve_provider_output(output: ProviderOutput) -> Result<HandshakeHeaders> {
    let mut headers = Owned::new(output.map_err(NetError::provider)?);
    if let Some(version) = headers
        .value
        .as_ref()
        .and_then(|headers| headers.credential_version.as_deref())
    {
        super::value_limits::validate_credential_version(version)
            .map_err(|error| error.with_stage(ErrorStage::Provider))?;
    }
    headers.take()
}

/// Future wrapper that isolates panics while an asynchronous handshake callback
/// is polled or dropped.
struct GuardedFuture {
    /// User future protected during completion, failure, or cancellation cleanup.
    future: Owned<ProviderFuture>,
}

impl GuardedFuture {
    fn new(future: ProviderFuture) -> Self {
        Self {
            future: Owned::new(future),
        }
    }

    fn complete_poll(
        &mut self,
        outcome: std::thread::Result<Poll<ProviderOutput>>,
    ) -> Poll<Result<HandshakeHeaders>> {
        match caught(outcome) {
            Ok(Poll::Pending) => Poll::Pending,
            Ok(Poll::Ready(output)) => {
                let mut output = Owned::new(output);
                if retire(self.future.value.take()) {
                    return Poll::Ready(Err(callback_failure()));
                }
                Poll::Ready(output.take().and_then(resolve_provider_output))
            }
            Err(error) => {
                retire(self.future.value.take());
                Poll::Ready(Err(error))
            }
        }
    }
}

impl Future for GuardedFuture {
    type Output = Result<HandshakeHeaders>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        let _scope = crate::common::retirement::ExecutionScope::enter();
        let Some(future) = self.future.value.as_mut() else {
            return Poll::Ready(Err(internal_failure()));
        };
        let outcome = catch_unwind(AssertUnwindSafe(|| future.as_mut().poll(cx)));
        self.complete_poll(outcome)
    }
}

impl Drop for GuardedFuture {
    fn drop(&mut self) {
        let _scope = crate::common::retirement::ExecutionScope::enter();
        retire(self.future.value.take());
    }
}

async fn run_blocking_with_spawn(
    provider: Arc<BlockingProvider>,
    attempt: HandshakeAttempt,
    slots: Arc<Semaphore>,
    spawn: impl FnOnce(Box<dyn FnOnce() + Send + 'static>) -> std::io::Result<()>,
) -> Result<HandshakeHeaders> {
    let permit = slots.try_acquire_owned().map_err(|error| {
        NetError::with_source(ErrorKind::ResourceExhausted, error).with_stage(ErrorStage::Provider)
    })?;
    let (sent, received) = oneshot::channel();
    let job = Box::new(move || {
        let _permit = permit;
        let result = provider(attempt);
        // The real closure retains its quota through provider-capture and rejected-result cleanup.
        retire(provider);
        if let Err(result) = sent.send(Owned::new(result)) {
            drop(result);
        }
    });
    spawn(job).map_err(|error| {
        NetError::with_source(ErrorKind::RuntimeUnavailable, error).with_stage(ErrorStage::Provider)
    })?;
    let mut output = received.await.map_err(|error| {
        NetError::with_source(ErrorKind::RuntimeUnavailable, error).with_stage(ErrorStage::Provider)
    })?;
    output.take()?
}

#[cfg(test)]
#[path = "handshake_tests.rs"]
mod tests;