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
//! Optional HTTP/2 policy, tuning, and response metadata.

use crate::api::error::{ErrorStage, NetError};
use http::Version;
use std::fmt;
use std::time::Duration;

const MAX_HTTP2_WINDOW: u32 = i32::MAX as u32;
const MIN_HTTP2_FRAME: u32 = 16_384;
const MAX_HTTP2_FRAME: u32 = 16_777_215;

/// Selects the HTTP protocol versions an HTTP client may use.
///
/// Redirect target authorization and downgrade prevention are configured
/// independently through [`crate::api::http::RedirectPolicy`] and
/// [`crate::api::http::HttpTransportSecurity`]. Every mode prevents HTTPS-to-HTTP
/// redirects by default.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
pub enum HttpVersionPolicy {
    /// Negotiate h2 with HTTPS ALPN and fall back to HTTP/1.1.
    #[default]
    Auto,
    /// Use HTTP/1.1 only.
    Http1Only,
    /// Require HTTPS ALPN to negotiate h2, including every followed redirect.
    /// Cleartext redirect targets are rejected before connecting or replaying a body.
    Http2Only,
}

/// HTTP/2 transport tuning applied when the `http-client-http2` feature is enabled.
///
/// The fields are private so invalid protocol values cannot be assembled without passing
/// [`HttpClientConfig::with_http2`](crate::api::http::HttpClientConfig::with_http2).
#[derive(Clone, Default)]
pub struct Http2Config {
    adaptive_window: bool,
    initial_stream_window: Option<u32>,
    initial_connection_window: Option<u32>,
    max_frame_size: Option<u32>,
    max_header_list_size: Option<u32>,
    keep_alive: Option<Http2KeepAlive>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct Http2KeepAlive {
    interval: Duration,
    timeout: Duration,
    while_idle: bool,
}

impl fmt::Debug for Http2Config {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Http2Config")
            .field("adaptive_window", &self.adaptive_window)
            .field("initial_stream_window", &self.initial_stream_window)
            .field("initial_connection_window", &self.initial_connection_window)
            .field("max_frame_size", &self.max_frame_size)
            .field("max_header_list_size", &self.max_header_list_size)
            .field("keep_alive", &self.keep_alive)
            .finish()
    }
}

impl Http2Config {
    /// Construct the default HTTP/2 configuration.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enable or disable adaptive HTTP/2 flow-control windows.
    pub fn adaptive_window(mut self, enabled: bool) -> Self {
        self.adaptive_window = enabled;
        self
    }

    /// Set the initial per-stream flow-control window.
    pub fn initial_stream_window(mut self, bytes: u32) -> Self {
        self.initial_stream_window = Some(bytes);
        self
    }

    /// Set the initial connection-level flow-control window.
    pub fn initial_connection_window(mut self, bytes: u32) -> Self {
        self.initial_connection_window = Some(bytes);
        self
    }

    /// Set the maximum HTTP/2 frame payload size.
    pub fn max_frame_size(mut self, bytes: u32) -> Self {
        self.max_frame_size = Some(bytes);
        self
    }

    /// Set the maximum received HTTP/2 header-list size.
    pub fn max_header_list_size(mut self, bytes: u32) -> Self {
        self.max_header_list_size = Some(bytes);
        self
    }

    /// Configure HTTP/2 PING keep-alive behavior.
    pub fn keep_alive(mut self, interval: Duration, timeout: Duration, while_idle: bool) -> Self {
        self.keep_alive = Some(Http2KeepAlive {
            interval,
            timeout,
            while_idle,
        });
        self
    }

    pub(crate) fn validate(&self) -> Result<(), NetError> {
        if self
            .initial_stream_window
            .is_some_and(|value| value == 0 || value > MAX_HTTP2_WINDOW)
        {
            return Err(invalid_http2_config("http2.initial_stream_window"));
        }
        if self
            .initial_connection_window
            .is_some_and(|value| value == 0 || value > MAX_HTTP2_WINDOW)
        {
            return Err(invalid_http2_config("http2.initial_connection_window"));
        }
        if self
            .max_frame_size
            .is_some_and(|value| !(MIN_HTTP2_FRAME..=MAX_HTTP2_FRAME).contains(&value))
        {
            return Err(invalid_http2_config("http2.max_frame_size"));
        }
        if self.max_header_list_size.is_some_and(|value| value == 0) {
            return Err(invalid_http2_config("http2.max_header_list_size"));
        }
        if self
            .keep_alive
            .is_some_and(|value| value.interval.is_zero() || value.timeout.is_zero())
        {
            return Err(invalid_http2_config("http2.keep_alive"));
        }
        Ok(())
    }

    pub(crate) fn configure_builder(
        &self,
        mut builder: reqwest::ClientBuilder,
    ) -> reqwest::ClientBuilder {
        if let Some(value) = self.initial_stream_window {
            builder = builder.http2_initial_stream_window_size(value);
        }
        if let Some(value) = self.initial_connection_window {
            builder = builder.http2_initial_connection_window_size(value);
        }
        if self.adaptive_window {
            builder = builder.http2_adaptive_window(true);
        }
        if let Some(value) = self.max_frame_size {
            builder = builder.http2_max_frame_size(value);
        }
        if let Some(value) = self.max_header_list_size {
            builder = builder.http2_max_header_list_size(value);
        }
        if let Some(keep_alive) = self.keep_alive {
            builder = builder
                .http2_keep_alive_interval(keep_alive.interval)
                .http2_keep_alive_timeout(keep_alive.timeout)
                .http2_keep_alive_while_idle(keep_alive.while_idle);
        }
        builder
    }

    pub(crate) fn configured_stream_window(&self) -> Option<u32> {
        self.initial_stream_window
    }

    pub(crate) fn configured_connection_window(&self) -> Option<u32> {
        self.initial_connection_window
    }
}

/// Protocol version observed on a response.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum HttpProtocol {
    /// HTTP/1.0 response.
    Http10,
    /// HTTP/1.1 response.
    Http11,
    /// HTTP/2 response.
    Http2,
    /// A synthetic response or a version added by a future transport.
    Unknown,
}

impl HttpProtocol {
    pub(crate) fn from_http_version(version: Version) -> Self {
        match version {
            Version::HTTP_10 => Self::Http10,
            Version::HTTP_11 => Self::Http11,
            Version::HTTP_2 => Self::Http2,
            _ => Self::Unknown,
        }
    }
}

/// SDK-observable HTTP/2 configuration and response-delivery counters.
///
/// Window values are the local configured initial values. They are not a claim about the
/// peer's current window or SETTINGS state, which reqwest does not expose.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct Http2FlowControlSnapshot {
    /// Initial stream window configured locally, if explicitly set.
    pub configured_stream_window: Option<u32>,
    /// Initial connection window configured locally, if explicitly set.
    pub configured_connection_window: Option<u32>,
    /// Whether the transport adaptively manages its flow-control windows.
    pub adaptive_window: bool,
    /// Number of response bytes delivered to the SDK caller so far.
    pub body_bytes_delivered: u64,
    /// Number of response chunks delivered to the SDK caller so far.
    pub body_chunks_delivered: u64,
}

/// Metadata retained for both buffered and streaming responses.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct HttpResponseInfo {
    /// Protocol version observed on the actual response.
    pub protocol: HttpProtocol,
    /// Local HTTP/2 configuration and delivery counters, when the response used HTTP/2.
    pub flow_control: Option<Http2FlowControlSnapshot>,
}

impl Default for HttpResponseInfo {
    fn default() -> Self {
        Self {
            protocol: HttpProtocol::Unknown,
            flow_control: None,
        }
    }
}

impl HttpResponseInfo {
    pub(crate) fn from_response(version: Version, config: &Http2Config) -> Self {
        let protocol = HttpProtocol::from_http_version(version);
        let flow_control = (protocol == HttpProtocol::Http2).then_some(Http2FlowControlSnapshot {
            configured_stream_window: config.configured_stream_window(),
            configured_connection_window: config.configured_connection_window(),
            adaptive_window: config.adaptive_window,
            body_bytes_delivered: 0,
            body_chunks_delivered: 0,
        });
        Self {
            protocol,
            flow_control,
        }
    }
}

fn invalid_http2_config(field: &'static str) -> NetError {
    NetError::config(field, "invalid HTTP/2 configuration").with_stage(ErrorStage::Configuration)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::api::error::{ErrorKind, ErrorStage};

    fn assert_invalid(config: Http2Config, field: &str) {
        let error = config
            .validate()
            .expect_err("invalid HTTP/2 config was accepted");
        assert_eq!(error.kind(), ErrorKind::InvalidConfig);
        assert_eq!(error.context().stage, Some(ErrorStage::Configuration));
        assert_eq!(
            error.config_error().map(|detail| detail.field()),
            Some(field)
        );
    }

    #[test]
    fn rejects_values_outside_protocol_bounds() {
        assert_invalid(
            Http2Config::new().initial_stream_window(0),
            "http2.initial_stream_window",
        );
        assert_invalid(
            Http2Config::new().initial_connection_window(MAX_HTTP2_WINDOW.saturating_add(1)),
            "http2.initial_connection_window",
        );
        assert_invalid(
            Http2Config::new().max_frame_size(MIN_HTTP2_FRAME - 1),
            "http2.max_frame_size",
        );
        assert_invalid(
            Http2Config::new().max_frame_size(MAX_HTTP2_FRAME.saturating_add(1)),
            "http2.max_frame_size",
        );
        assert_invalid(
            Http2Config::new().max_header_list_size(0),
            "http2.max_header_list_size",
        );
        assert_invalid(
            Http2Config::new().keep_alive(Duration::ZERO, Duration::from_secs(1), false),
            "http2.keep_alive",
        );
    }

    #[test]
    fn maps_http_versions_without_transport_types() {
        assert_eq!(
            HttpProtocol::from_http_version(Version::HTTP_10),
            HttpProtocol::Http10
        );
        assert_eq!(
            HttpProtocol::from_http_version(Version::HTTP_11),
            HttpProtocol::Http11
        );
        assert_eq!(
            HttpProtocol::from_http_version(Version::HTTP_2),
            HttpProtocol::Http2
        );
        assert_eq!(
            HttpProtocol::from_http_version(Version::HTTP_09),
            HttpProtocol::Unknown
        );
    }
}