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
//! HTTP response and request identifier contracts.

use crate::api::error::NetError;
#[cfg(feature = "http-client-http2")]
use crate::api::http::HttpResponseInfo;
use bytes::Bytes;
use http::{HeaderMap, StatusCode};
use serde::de::DeserializeOwned;
use std::fmt;
use std::str::Utf8Error;

/// Monotonic identifier assigned to a request by an HTTP client.
///
/// Automatically assigned identifiers increase without wrapping during a client
/// lifetime. Custom identifiers must be unique among in-flight requests and may
/// be reused after cleanup. Identifiers support cancellation and correlation;
/// they are not server-visible and are not persisted across client restarts.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct HttpRequestId(pub u64);

/// Status and headers received before a buffered response body failed to complete.
///
/// This metadata does not make the request successful. Inspect the accompanying
/// [`NetError`] for the original classification, source and timeout phase. Header
/// values may be sensitive and are intentionally omitted from `Debug` output.
#[derive(Clone)]
pub struct HttpResponseHead {
    /// Response status code returned by the peer.
    pub status: StatusCode,
    /// Response headers, including values supplied by the peer.
    pub headers: HeaderMap,
}

impl fmt::Debug for HttpResponseHead {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HttpResponseHead")
            .field("status", &self.status)
            .field("header_count", &self.headers.len())
            .finish()
    }
}

/// A fully buffered HTTP response delivered to a request callback.
///
/// The body is retained as owned bytes and is intentionally omitted from
/// `Debug` output. Use [`Self::text`] or [`Self::json`] when the payload format
/// is known.
#[derive(Clone)]
pub struct HttpResponse {
    #[cfg(feature = "quality-doctor")]
    quality_ref: Option<crate::api::quality::QualityReportRef>,
    retry_report: Option<crate::api::retry::RetryReport>,
    /// Response status code returned by the peer.
    pub status: StatusCode,
    /// Response headers, including values supplied by the peer.
    pub headers: HeaderMap,
    /// Fully buffered response body.
    pub body: Bytes,
    /// Number of transport attempts used to obtain this response.
    pub attempts: u32,
    /// Identifier assigned to the originating request.
    pub request_id: HttpRequestId,
    #[cfg(feature = "http-client-http2")]
    info: HttpResponseInfo,
}

impl HttpResponse {
    /// Returns the diagnostic reference attached by the producing HTTP operation.
    ///
    /// This identifies the request's observation across its execution and retries,
    /// rather than the response body or a newly allocated response-only report.
    /// Callback or resource-release phases may still be pending when this response
    /// is delivered, so a successful HTTP result does not imply the diagnostic
    /// report has reached its final state.
    ///
    /// `None` means this response carries no reference, for example because it was
    /// manually constructed or collection was Off/dormant, filtered out, or unable
    /// to allocate an observation. The accessor does not activate collection.
    /// Resolve a reference with the same owner's `QualityDoctor::lookup`; the value
    /// neither pins retained history nor proves complete diagnostic coverage.
    #[cfg(feature = "quality-doctor")]
    pub fn quality_ref(&self) -> Option<crate::api::quality::QualityReportRef> {
        self.quality_ref
    }

    #[cfg(feature = "quality-doctor")]
    pub(crate) fn with_quality_ref(
        mut self,
        reference: crate::api::quality::QualityReportRef,
    ) -> Self {
        self.quality_ref = Some(reference);
        self
    }

    /// Final retry statistics, absent only on manually constructed responses.
    pub fn retry_report(&self) -> Option<&crate::api::retry::RetryReport> {
        self.retry_report.as_ref()
    }
    pub(crate) fn with_retry_report(mut self, report: crate::api::retry::RetryReport) -> Self {
        self.retry_report = Some(report);
        self
    }

    /// Return the UTF-8 `Content-Type` header value, if present and valid.
    pub fn content_type(&self) -> Option<&str> {
        self.headers.get(http::header::CONTENT_TYPE)?.to_str().ok()
    }

    /// Check the response status against a caller-selected acceptance policy.
    ///
    /// A rejected status is returned as a typed [`NetError`]; the response body
    /// remains available to callers that need to inspect it before propagating
    /// the error.
    pub fn check_status(&self, policy: crate::api::http::HttpStatusPolicy) -> Result<(), NetError> {
        if policy.accepts(self.status) {
            Ok(())
        } else {
            let error = NetError::from_http_status(self.status);
            #[cfg(feature = "quality-doctor")]
            let error = match self.quality_ref {
                Some(reference) => error.with_quality_ref(reference),
                None => error,
            };
            Err(error)
        }
    }
    /// Construct a buffered response from its transport metadata and body.
    pub fn new(
        status: StatusCode,
        headers: HeaderMap,
        body: Bytes,
        attempts: u32,
        request_id: HttpRequestId,
    ) -> Self {
        Self {
            #[cfg(feature = "quality-doctor")]
            quality_ref: None,
            retry_report: None,
            status,
            headers,
            body,
            attempts,
            request_id,
            #[cfg(feature = "http-client-http2")]
            info: HttpResponseInfo::default(),
        }
    }

    #[cfg(feature = "http-client-http2")]
    pub(crate) fn with_info(mut self, info: HttpResponseInfo) -> Self {
        self.info = info;
        self
    }

    #[cfg(feature = "http-client-http2")]
    /// Return the protocol and SDK-observable flow-control metadata.
    pub fn info(&self) -> &HttpResponseInfo {
        &self.info
    }

    #[cfg(feature = "http-client-http2")]
    /// Return the protocol observed on the response.
    pub fn protocol(&self) -> crate::api::http::HttpProtocol {
        self.info.protocol
    }

    /// Construct a response returned directly by an HTTP middleware.
    ///
    /// A synthetic response has not reached the transport, so its attempt count is zero.
    #[cfg(feature = "http-client-middleware")]
    pub fn synthetic(
        request_id: HttpRequestId,
        status: StatusCode,
        headers: HeaderMap,
        body: Bytes,
    ) -> Self {
        Self::new(status, headers, body, 0, request_id)
    }

    /// Report whether the status code is in the 2xx success range.
    pub fn is_success(&self) -> bool {
        self.status.is_success()
    }

    /// Interpret the body as UTF-8 without allocating.
    pub fn text(&self) -> Result<&str, Utf8Error> {
        std::str::from_utf8(self.body.as_ref())
    }

    /// Deserialize the body as JSON using `serde_json`.
    pub fn json<T: DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
        serde_json::from_slice(self.body.as_ref())
    }

    /// Return the response status code.
    pub fn status(&self) -> StatusCode {
        self.status
    }

    /// Borrow the response headers.
    pub fn headers(&self) -> &HeaderMap {
        &self.headers
    }

    /// Borrow the buffered response body.
    pub fn body(&self) -> &Bytes {
        &self.body
    }

    /// Return the number of transport attempts used for this response.
    pub fn attempts(&self) -> u32 {
        self.attempts
    }

    /// Return the originating request identifier.
    pub fn request_id(&self) -> HttpRequestId {
        self.request_id
    }
}

impl fmt::Debug for HttpResponse {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HttpResponse")
            .field("status", &self.status)
            .field("header_count", &self.headers.len())
            .field("body_bytes", &self.body.len())
            .field("attempts", &self.attempts)
            .field("request_id", &self.request_id)
            .finish()
    }
}

/// Result delivered to an HTTP request callback after all attempts complete.
///
/// `Ok` contains a fully buffered response. `Err` contains a transport,
/// configuration, cancellation, or retry-exhaustion error; an HTTP status that
/// is merely unsuccessful is still represented by `Ok` until the caller applies
/// [`HttpResponse::check_status`]. A buffered body failure retains the received
/// status and headers in [`NetError::http_response_head`]; the result stays `Err`.
pub type HttpResponseResult = Result<HttpResponse, NetError>;

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

    type TestResult = Result<(), Box<dyn std::error::Error + Send + Sync>>;

    fn check(condition: bool, message: &str) -> TestResult {
        if condition {
            Ok(())
        } else {
            Err(std::io::Error::other(message).into())
        }
    }

    #[test]
    fn response_exposes_status_body_and_json_without_leaking_body_in_debug() -> TestResult {
        let mut headers = HeaderMap::new();
        headers.insert("content-type", HeaderValue::from_static("application/json"));
        let response = HttpResponse::new(
            StatusCode::OK,
            headers,
            Bytes::from_static(br#"{"value":7}"#),
            2,
            HttpRequestId(9),
        );
        check(response.is_success(), "2xx response must be successful")?;
        check(response.attempts() == 2, "attempt count not retained")?;
        check(
            response.request_id() == HttpRequestId(9),
            "request id not retained",
        )?;
        check(response.text()? == r#"{"value":7}"#, "body text mismatch")?;
        let decoded: serde_json::Value = response.json()?;
        check(decoded["value"] == 7, "JSON body was not decoded")?;
        check(
            !format!("{response:?}").contains("value"),
            "response Debug leaked body",
        )
    }

    #[test]
    fn response_result_keeps_http_failures_distinct_from_transport_errors() -> TestResult {
        let result: HttpResponseResult =
            Err(NetError::from(crate::api::error::ErrorKind::TimedOut));
        let error = match result {
            Ok(_) => return Err(std::io::Error::other("transport result was successful").into()),
            Err(error) => error,
        };
        check(
            error.kind() == crate::api::error::ErrorKind::TimedOut,
            "wrong error kind",
        )
    }
}