qubit-http 0.5.0

General-purpose HTTP infrastructure for Rust with unified client semantics, secure logging, and built-in SSE decoding
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

/*******************************************************************************
 *
 *    Copyright (c) 2025 - 2026 Haixing Hu.
 *
 *    SPDX-License-Identifier: Apache-2.0
 *
 *    Licensed under the Apache License, Version 2.0.
 *
 ******************************************************************************/
//! Request-level retry override options.

use crate::HttpRetryMethodPolicy;

/// Per-request overrides for the client retry strategy.
///
/// This type allows callers to:
/// - force-enable retry even when client-level retry is disabled;
/// - force-disable retry for one request;
/// - override the retryable-method policy for one request;
/// - optionally honor `Retry-After` on retryable status responses (`429` and
///   `5xx`).
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct HttpRequestRetryOverride {
    /// Force retry on for this request (unless explicitly force-disabled).
    force_enable: bool,
    /// Force retry off for this request.
    force_disable: bool,
    /// Optional method-policy override for this request.
    method_policy: Option<HttpRetryMethodPolicy>,
    /// Whether to honor `Retry-After` on retryable status responses.
    honor_retry_after: bool,
}

impl HttpRequestRetryOverride {
    /// Creates an empty override that follows client-level retry settings.
    ///
    /// # Returns
    /// New [`HttpRequestRetryOverride`] with all per-request overrides disabled.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enables force-retry for this request and clears force-disable.
    ///
    /// # Returns
    /// Updated override for chaining.
    pub fn force_enable(mut self) -> Self {
        self.force_enable = true;
        self.force_disable = false;
        self
    }

    /// Enables force-disable for this request and clears force-enable.
    ///
    /// # Returns
    /// Updated override for chaining.
    pub fn force_disable(mut self) -> Self {
        self.force_disable = true;
        self.force_enable = false;
        self
    }

    /// Sets the per-request retryable-method policy override.
    ///
    /// # Parameters
    /// - `policy`: Method policy to use for this request.
    ///
    /// # Returns
    /// Updated override for chaining.
    pub fn with_method_policy(mut self, policy: HttpRetryMethodPolicy) -> Self {
        self.method_policy = Some(policy);
        self
    }

    /// Enables or disables honoring `Retry-After` for this request.
    ///
    /// # Parameters
    /// - `enabled`: `true` to honor `Retry-After` on retryable status
    ///   responses (`429` and `5xx`).
    ///
    /// # Returns
    /// Updated override for chaining.
    pub fn with_honor_retry_after(mut self, enabled: bool) -> Self {
        self.honor_retry_after = enabled;
        self
    }

    /// Returns whether force-enable is active for this request.
    ///
    /// # Returns
    /// `true` when retry is force-enabled at request level.
    pub fn is_force_enable(&self) -> bool {
        self.force_enable
    }

    /// Returns whether force-disable is active for this request.
    ///
    /// # Returns
    /// `true` when retry is force-disabled at request level.
    pub fn is_force_disable(&self) -> bool {
        self.force_disable
    }

    /// Returns the per-request method-policy override, if present.
    ///
    /// # Returns
    /// Optional override for [`HttpRetryMethodPolicy`].
    pub fn method_policy(&self) -> Option<HttpRetryMethodPolicy> {
        self.method_policy
    }

    /// Returns whether `Retry-After` should be honored for this request.
    ///
    /// # Returns
    /// `true` when this request should honor `Retry-After` on retryable status
    /// responses (`429` and `5xx`).
    pub fn should_honor_retry_after(&self) -> bool {
        self.honor_retry_after
    }

    /// Resolves request-level force-enable/force-disable against client defaults.
    ///
    /// # Parameters
    /// - `client_enabled`: Client-level retry enabled flag.
    ///
    /// # Returns
    /// Effective retry-enabled flag for this request.
    pub(crate) fn resolve_enabled(&self, client_enabled: bool) -> bool {
        if self.force_disable {
            false
        } else if self.force_enable {
            true
        } else {
            client_enabled
        }
    }

    /// Resolves effective method policy from request-level override + client policy.
    ///
    /// # Parameters
    /// - `client_policy`: Client-level method policy.
    ///
    /// # Returns
    /// Effective method policy for this request.
    pub(crate) fn resolve_method_policy(
        &self,
        client_policy: HttpRetryMethodPolicy,
    ) -> HttpRetryMethodPolicy {
        self.method_policy.unwrap_or(client_policy)
    }
}