product-os-request 0.0.55

//! HTTP client trait and implementations
//!
//! This module provides the `ProductOSClient` trait and its implementations.

use alloc::string::String;

#[cfg(any(feature = "request", feature = "request_std"))]
use crate::method::Method;

#[cfg(any(feature = "request", feature = "request_std"))]
use crate::error::ProductOSRequestError;

#[cfg(any(feature = "request", feature = "request_std"))]
use crate::request::ProductOSRequest;

#[cfg(any(feature = "request", feature = "request_std"))]
use crate::response::ProductOSResponse;

#[cfg(any(feature = "request", feature = "request_std"))]
use crate::requester::ProductOSRequester;

#[cfg(any(feature = "request", feature = "request_std"))]
pub use product_os_http::Request;

/// HTTP client trait
///
/// Defines the interface for HTTP clients that can execute requests.
///
/// Note: Async methods in this trait do not automatically bound the returned futures
/// as `Send`. If you need `Send` bounds, ensure the concrete implementation is `Send`.
#[cfg(any(feature = "request", feature = "request_std"))]
#[allow(async_fn_in_trait)]
pub trait ProductOSClient<DReq: product_os_http_body::Body, DRes: product_os_http_body::Body> {
    /// Build/configure the client from a requester
    fn build(&mut self, requester: &ProductOSRequester);

    /// Create a new request
    fn new_request(&self, method: Method, url: &str) -> ProductOSRequest<DReq>;

    /// Execute a request
    async fn request(
        &self,
        r: ProductOSRequest<DReq>,
    ) -> Result<ProductOSResponse<DRes>, ProductOSRequestError>;

    /// Execute a streaming request
    #[cfg(any(feature = "stream_reqwest", feature = "stream_hyper"))]
    async fn request_stream(
        &self,
        r: ProductOSRequest<DReq>,
    ) -> Result<ProductOSResponse<DRes>, ProductOSRequestError>;

    /// Execute a simple request with just method and URL
    async fn request_simple(
        &self,
        method: Method,
        url: &str,
    ) -> Result<ProductOSResponse<DRes>, ProductOSRequestError>;

    /// Execute a raw HTTP request
    async fn request_raw(
        &self,
        r: Request<DReq>,
    ) -> Result<ProductOSResponse<DRes>, ProductOSRequestError>;

    /// Execute a raw streaming request
    #[cfg(any(feature = "stream_reqwest", feature = "stream_hyper"))]
    async fn request_stream_raw(
        &self,
        r: Request<DReq>,
    ) -> Result<ProductOSResponse<DRes>, ProductOSRequestError>;

    /// Set JSON body on a request
    #[cfg(feature = "json")]
    async fn set_body_json(&self, r: &mut ProductOSRequest<DReq>, json: serde_json::Value);

    /// Set form body on a request
    #[cfg(feature = "form")]
    async fn set_body_form(&self, r: &mut ProductOSRequest<DReq>, form: &str);

    /// Extract text from response
    async fn text(&self, r: ProductOSResponse<DRes>) -> Result<String, ProductOSRequestError>;

    /// Extract JSON from response
    #[cfg(feature = "json")]
    async fn json(
        &self,
        r: ProductOSResponse<DRes>,
    ) -> Result<serde_json::Value, ProductOSRequestError>;

    /// Extract bytes from response
    async fn bytes(
        &self,
        r: ProductOSResponse<DRes>,
    ) -> Result<bytes::Bytes, ProductOSRequestError>;

    /// Get next chunk of bytes from streaming response
    async fn next_bytes(
        &self,
        r: &mut ProductOSResponse<DRes>,
    ) -> Result<Option<bytes::Bytes>, ProductOSRequestError>;

    /// Convert the response body into a [`product_os_http_body::BodyDataStream`].
    ///
    /// The stream owns the body and does **not** borrow the client, so it can be held across
    /// awaits or sent into tasks without keeping a reference to `self`.
    fn to_stream(
        &self,
        r: ProductOSResponse<product_os_http_body::BodyBytes>,
    ) -> Result<
        product_os_http_body::BodyDataStream<product_os_http_body::BodyBytes>,
        ProductOSRequestError,
    >;
}

#[cfg(all(feature = "request_std", any(feature = "std", feature = "std_reqwest")))]
mod reqwest_impl;

#[cfg(all(feature = "request_std", feature = "std_hyper"))]
mod hyper_impl;

// Concrete client exports
#[cfg(all(feature = "request_std", any(feature = "std", feature = "std_reqwest")))]
pub use reqwest_impl::ProductOSReqwestClient;

#[cfg(all(feature = "request_std", feature = "std_hyper"))]
pub use hyper_impl::ProductOSHyperClient;

/// Unified HTTP client type alias
///
/// Provides a portable client type that resolves to either `ProductOSReqwestClient`
/// or `ProductOSHyperClient` depending on enabled features.
/// Priority: reqwest if both enabled (for backward compatibility), otherwise use whichever is enabled.
#[cfg(all(
    feature = "request_std",
    any(feature = "std", feature = "std_reqwest"),
    not(feature = "std_hyper")
))]
pub type ProductOSRequestClient = ProductOSReqwestClient;

/// Unified HTTP client type alias
///
/// See [`ProductOSReqwestClient`] or [`ProductOSHyperClient`] for details.
#[cfg(all(
    feature = "request_std",
    feature = "std_hyper",
    not(feature = "std"),
    not(feature = "std_reqwest")
))]
pub type ProductOSRequestClient = ProductOSHyperClient;

/// Unified HTTP client type alias
///
/// See [`ProductOSReqwestClient`] or [`ProductOSHyperClient`] for details.
#[cfg(all(
    feature = "request_std",
    any(feature = "std", feature = "std_reqwest"),
    feature = "std_hyper"
))]
pub type ProductOSRequestClient = ProductOSReqwestClient;