nyquest_interface/blocking/
backend.rs

1//! Core blocking client interface traits.
2//!
3//! This module provides the core trait definitions that backend implementations
4//! must implement to provide blocking HTTP functionality.
5//!
6//! Backend developers need to implement the `BlockingBackend` and `BlockingClient` traits,
7//! along with a custom `BlockingResponse` type.
8
9use std::{fmt, io};
10
11use super::Request;
12use crate::client::{BuildClientResult, ClientOptions};
13
14/// Trait for blocking HTTP clients.
15///
16/// Backend implementations must provide a concrete type that implements this trait
17/// to handle blocking HTTP requests.
18pub trait BlockingClient: Clone + Send + Sync + 'static {
19    /// The type of response returned by this client.
20    type Response: BlockingResponse;
21
22    /// Provides a textual description of this client.
23    fn describe(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
24        write!(f, "BlockingClient")
25    }
26
27    /// Sends an HTTP request and returns the response.
28    fn request(&self, req: Request) -> crate::Result<Self::Response>;
29}
30
31/// Trait for blocking HTTP backend implementations.
32///
33/// This trait represents a backend implementation that can create blocking HTTP clients.
34pub trait BlockingBackend: Send + Sync + 'static {
35    /// The type of client this backend creates.
36    type BlockingClient: BlockingClient;
37
38    /// Creates a new blocking client with the given options.
39    fn create_blocking_client(
40        &self,
41        options: ClientOptions,
42    ) -> BuildClientResult<Self::BlockingClient>;
43}
44
45/// Trait for blocking HTTP responses.
46///
47/// This trait provides methods for accessing the data in an HTTP response
48/// and extends io::Read to allow streaming the response body.
49///
50/// ## Response Method Receivers
51///
52/// Note that the `BlockingResponse` trait uses `&mut self` receivers for content reading methods
53/// (`text()`, `bytes()`, etc.) to ensure object safety and dyn compatibility.
54/// This differs from the main nyquest crate which uses consuming `self` receivers.
55///
56/// Backend implementors should design their implementations with the understanding that
57/// these methods may be called only once per response instance, even though the signature allows
58/// multiple calls. The nyquest facade enforces this by consuming the response.
59pub trait BlockingResponse: io::Read + Send + Sync + 'static {
60    /// Provides a textual description of this response.
61    fn describe(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
62        write!(f, "BlockingResponse")
63    }
64
65    /// Returns the HTTP status code of this response.
66    fn status(&self) -> u16;
67
68    /// Returns the content-length of the response body, if known.
69    fn content_length(&self) -> Option<u64>;
70
71    /// Gets all values for the specified header.
72    fn get_header(&self, header: &str) -> crate::Result<Vec<String>>;
73
74    /// Reads the response body as text.
75    fn text(&mut self) -> crate::Result<String>;
76
77    /// Reads the response body as bytes.
78    fn bytes(&mut self) -> crate::Result<Vec<u8>>;
79}
nyquest_interface/blocking/backend.rs

nyquest_interface/blocking/
backend.rs
