reqx 0.1.35

Rust HTTP transport client for API SDK libraries with retry, timeout, idempotency, proxy, and pluggable TLS backends
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

use http::{HeaderMap, Method, StatusCode};

use crate::error::Error;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Redirect handling policy.
pub struct RedirectPolicy {
    enabled: bool,
    max_redirects: usize,
}

impl RedirectPolicy {
    /// Disables automatic redirect following.
    pub const fn none() -> Self {
        Self {
            enabled: false,
            max_redirects: 0,
        }
    }

    /// Follows redirects up to `max_redirects`.
    pub const fn limited(max_redirects: usize) -> Self {
        if max_redirects == 0 {
            Self::none()
        } else {
            Self {
                enabled: true,
                max_redirects,
            }
        }
    }

    /// Follows redirects with the default limit of 10 hops.
    pub const fn follow() -> Self {
        Self::limited(10)
    }

    /// Returns whether redirect following is enabled.
    pub const fn enabled(self) -> bool {
        self.enabled
    }

    /// Returns the configured redirect limit.
    pub const fn max_redirects(self) -> usize {
        if self.enabled { self.max_redirects } else { 0 }
    }
}

impl Default for RedirectPolicy {
    fn default() -> Self {
        Self::none()
    }
}

#[cfg(test)]
mod tests {
    use super::RedirectPolicy;

    #[test]
    fn redirect_policy_limited_zero_is_equivalent_to_none() {
        let policy = RedirectPolicy::limited(0);
        assert!(!policy.enabled());
        assert_eq!(policy.max_redirects(), 0);
        assert_eq!(policy, RedirectPolicy::none());
    }
}

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
/// How HTTP statuses should be surfaced to the caller.
pub enum StatusPolicy {
    #[default]
    /// Treat non-success statuses as [`Error::HttpStatus`](crate::Error::HttpStatus).
    Error,
    /// Return HTTP status responses without converting them into errors.
    Response,
}

impl StatusPolicy {
    /// Returns [`Self::Error`].
    pub const fn error() -> Self {
        Self::Error
    }

    /// Returns [`Self::Response`].
    pub const fn response() -> Self {
        Self::Response
    }

    /// Returns `true` when non-success statuses are converted into errors.
    pub const fn is_error(self) -> bool {
        matches!(self, Self::Error)
    }
}

#[derive(Clone, Debug)]
/// Immutable request metadata passed to interceptors and observers.
pub struct RequestContext {
    method: Method,
    uri: String,
    attempt: usize,
    max_attempts: usize,
    redirect_count: usize,
}

impl RequestContext {
    pub(crate) fn new(
        method: Method,
        uri: String,
        attempt: usize,
        max_attempts: usize,
        redirect_count: usize,
    ) -> Self {
        Self {
            method,
            uri,
            attempt,
            max_attempts,
            redirect_count,
        }
    }

    /// Returns the request method.
    pub fn method(&self) -> &Method {
        &self.method
    }

    /// Returns the request URI with the crate's redaction rules applied.
    pub fn uri(&self) -> &str {
        &self.uri
    }

    /// Returns the current attempt number, starting at `1`.
    pub fn attempt(&self) -> usize {
        self.attempt
    }

    /// Returns the maximum number of attempts allowed for this request.
    pub fn max_attempts(&self) -> usize {
        self.max_attempts
    }

    /// Returns how many redirects have already been followed.
    pub fn redirect_count(&self) -> usize {
        self.redirect_count
    }
}

/// Active hook for mutating or observing request execution.
pub trait Interceptor: Send + Sync {
    /// Called before a request is sent. Interceptors may mutate headers.
    fn on_request(&self, _context: &RequestContext, _headers: &mut HeaderMap) {}

    /// Called after a response status and headers are received.
    fn on_response(&self, _context: &RequestContext, _status: StatusCode, _headers: &HeaderMap) {}

    /// Called when request execution ends in an error.
    fn on_error(&self, _context: &RequestContext, _error: &Error) {}
}