Skip to main content

open_net/api/ws/
retry.rs

1//! WebSocket replay permissions and protocol-specific retry classifiers.
2use super::Response;
3use crate::api::retry::{
4    RetryConfigError, RetryContext, RetryDecision, RetryObserver, RetryObserverHandle,
5    RetrySchedule,
6};
7use crate::error::{ErrorKind, ErrorStage};
8use crate::{NetError, Result};
9use std::fmt;
10use std::sync::Arc;
11
12/// SDK budget that expired. Admission and Total are always terminal.
13#[non_exhaustive]
14#[derive(Clone, Copy, Debug, Eq, PartialEq)]
15pub enum WsTimeoutPhase {
16    Admission,
17    Write,
18    Response,
19    Attempt,
20    Total,
21}
22
23/// Application guarantee permitting a second delivery of the same business operation.
24#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
25pub enum WsReplaySafety {
26    /// Never repeat a delivery that may have reached the peer.
27    #[default]
28    Never,
29    /// The application protocol guarantees that repeating this operation is idempotent.
30    IdempotentByContract,
31    /// The peer deduplicates the stable key encoded by the application's message factory.
32    /// This declaration does not insert a key into an opaque message or verify the peer.
33    IdempotencyKey,
34}
35
36/// Error categories selected for retrying an untracked message write.
37#[derive(Clone, Debug, Default, Eq, PartialEq)]
38pub struct WsSendRetryOn {
39    errors: Vec<ErrorKind>,
40    write_timeout: bool,
41}
42
43impl WsSendRetryOn {
44    pub fn none() -> Self {
45        Self::default()
46    }
47    /// Select the common transient transport-write errors.
48    pub fn with_write_errors(mut self, enabled: bool) -> Self {
49        self.errors = if enabled {
50            vec![
51                ErrorKind::Io,
52                ErrorKind::DeliveryUnknown,
53                ErrorKind::NotConnected,
54            ]
55        } else {
56            Vec::new()
57        };
58        self
59    }
60    /// Replace error kinds. Cancellation, shutdown, configuration and admission errors remain terminal.
61    pub fn with_errors(mut self, errors: impl IntoIterator<Item = ErrorKind>) -> Self {
62        self.errors = errors.into_iter().collect();
63        self
64    }
65    pub fn with_write_timeout(mut self, enabled: bool) -> Self {
66        self.write_timeout = enabled;
67        self
68    }
69    pub fn errors(&self) -> &[ErrorKind] {
70        &self.errors
71    }
72    pub(crate) fn allows(&self, error: &NetError) -> bool {
73        if terminal_error(error) {
74            return false;
75        }
76        match timeout_phase(error) {
77            Some(WsTimeoutPhase::Write) => self.write_timeout,
78            Some(_) => false,
79            None => self.errors.contains(&error.kind()),
80        }
81    }
82}
83
84/// Error categories selected for a logical request, in addition to its business classifier.
85#[derive(Clone, Debug, Default, Eq, PartialEq)]
86pub struct WsRequestRetryOn {
87    write: WsSendRetryOn,
88    response_timeout: bool,
89    attempt_timeout: bool,
90}
91
92impl WsRequestRetryOn {
93    pub fn none() -> Self {
94        Self::default()
95    }
96    pub fn with_write_errors(mut self, enabled: bool) -> Self {
97        self.write = self.write.with_write_errors(enabled);
98        self
99    }
100    pub fn with_errors(mut self, errors: impl IntoIterator<Item = ErrorKind>) -> Self {
101        self.write = self.write.with_errors(errors);
102        self
103    }
104    pub fn with_write_timeout(mut self, enabled: bool) -> Self {
105        self.write = self.write.with_write_timeout(enabled);
106        self
107    }
108    pub fn with_response_timeout(mut self, enabled: bool) -> Self {
109        self.response_timeout = enabled;
110        self
111    }
112    /// Enable retry only for the whole-attempt budget, independently of write/response timeouts.
113    pub fn with_attempt_timeout(mut self, enabled: bool) -> Self {
114        self.attempt_timeout = enabled;
115        self
116    }
117    pub(crate) fn allows(&self, error: &NetError) -> bool {
118        if terminal_error(error) {
119            return false;
120        }
121        match timeout_phase(error) {
122            Some(WsTimeoutPhase::Attempt) => self.attempt_timeout,
123            Some(WsTimeoutPhase::Response) => self.response_timeout,
124            Some(WsTimeoutPhase::Admission | WsTimeoutPhase::Total) => false,
125            _ => self.write.allows(error),
126        }
127    }
128}
129
130/// Immutable information for an untracked write classifier.
131pub struct WsSendRetryContext<'a> {
132    pub error: &'a NetError,
133    pub retry: &'a RetryContext,
134}
135/// Immutable response or failure of one logical request attempt.
136pub struct WsRequestRetryContext<'a> {
137    pub outcome: std::result::Result<&'a Response, &'a NetError>,
138    pub retry: &'a RetryContext,
139}
140type SendClassifier = dyn for<'a> Fn(&WsSendRetryContext<'a>) -> RetryDecision + Send + Sync;
141type RequestClassifier = dyn for<'a> Fn(&WsRequestRetryContext<'a>) -> RetryDecision + Send + Sync;
142
143/// Cloneable policy for message writes. It owns no mutable attempt state.
144#[derive(Clone)]
145pub struct WsSendRetryPolicy {
146    schedule: RetrySchedule,
147    retry_on: WsSendRetryOn,
148    safety: WsReplaySafety,
149    classifier: Option<Arc<SendClassifier>>,
150    observer: Option<RetryObserverHandle>,
151}
152
153impl WsSendRetryPolicy {
154    pub fn no_retry() -> Self {
155        Self {
156            schedule: RetrySchedule::no_retry(),
157            retry_on: WsSendRetryOn::none(),
158            safety: WsReplaySafety::Never,
159            classifier: None,
160            observer: None,
161        }
162    }
163    pub fn builder() -> WsSendRetryPolicyBuilder {
164        WsSendRetryPolicyBuilder {
165            policy: Self::no_retry(),
166        }
167    }
168    pub fn schedule(&self) -> &RetrySchedule {
169        &self.schedule
170    }
171    pub fn retry_on(&self) -> &WsSendRetryOn {
172        &self.retry_on
173    }
174    pub fn safety(&self) -> WsReplaySafety {
175        self.safety
176    }
177    pub fn observer(&self) -> Option<RetryObserverHandle> {
178        self.observer.clone()
179    }
180    pub(crate) fn allows_replay(&self) -> bool {
181        self.safety != WsReplaySafety::Never
182    }
183    pub(crate) fn should_retry_error(&self, error: &NetError) -> bool {
184        self.retry_on.allows(error)
185    }
186    pub(crate) fn classify(&self, error: &NetError, retry: &RetryContext) -> Result<RetryDecision> {
187        match &self.classifier {
188            None => Ok(RetryDecision::Default),
189            Some(classifier) => {
190                isolate_classifier(|| classifier(&WsSendRetryContext { error, retry }))
191            }
192        }
193    }
194}
195impl Default for WsSendRetryPolicy {
196    fn default() -> Self {
197        Self::no_retry()
198    }
199}
200impl fmt::Debug for WsSendRetryPolicy {
201    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
202        f.debug_struct("WsSendRetryPolicy")
203            .field("schedule", &self.schedule)
204            .field("retry_on", &self.retry_on)
205            .field("safety", &self.safety)
206            .field("has_classifier", &self.classifier.is_some())
207            .field("observer", &self.observer)
208            .finish()
209    }
210}
211
212pub struct WsSendRetryPolicyBuilder {
213    policy: WsSendRetryPolicy,
214}
215impl WsSendRetryPolicyBuilder {
216    pub fn schedule(mut self, schedule: RetrySchedule) -> Self {
217        self.policy.schedule = schedule;
218        self
219    }
220    pub fn retry_on(mut self, retry_on: WsSendRetryOn) -> Self {
221        self.policy.retry_on = retry_on;
222        self
223    }
224    pub fn safety(mut self, safety: WsReplaySafety) -> Self {
225        self.policy.safety = safety;
226        self
227    }
228    pub fn observer(mut self, observer: impl RetryObserver) -> Self {
229        self.policy.observer = Some(RetryObserverHandle::new(observer));
230        self
231    }
232    pub fn classifier<F>(mut self, classifier: F) -> Self
233    where
234        F: for<'a> Fn(&WsSendRetryContext<'a>) -> RetryDecision + Send + Sync + 'static,
235    {
236        self.policy.classifier = Some(Arc::new(classifier));
237        self
238    }
239    pub fn build(self) -> std::result::Result<WsSendRetryPolicy, RetryConfigError> {
240        Ok(self.policy)
241    }
242}
243
244/// One schedule and replay permission for write, response-timeout and business retries.
245#[derive(Clone)]
246pub struct WsRequestRetryPolicy {
247    schedule: RetrySchedule,
248    retry_on: WsRequestRetryOn,
249    safety: WsReplaySafety,
250    classifier: Option<Arc<RequestClassifier>>,
251    observer: Option<RetryObserverHandle>,
252}
253impl WsRequestRetryPolicy {
254    pub fn no_retry() -> Self {
255        Self {
256            schedule: RetrySchedule::no_retry(),
257            retry_on: WsRequestRetryOn::none(),
258            safety: WsReplaySafety::Never,
259            classifier: None,
260            observer: None,
261        }
262    }
263    pub fn builder() -> WsRequestRetryPolicyBuilder {
264        WsRequestRetryPolicyBuilder {
265            policy: Self::no_retry(),
266        }
267    }
268    pub fn schedule(&self) -> &RetrySchedule {
269        &self.schedule
270    }
271    pub fn retry_on(&self) -> &WsRequestRetryOn {
272        &self.retry_on
273    }
274    pub fn safety(&self) -> WsReplaySafety {
275        self.safety
276    }
277    pub fn observer(&self) -> Option<RetryObserverHandle> {
278        self.observer.clone()
279    }
280    pub(crate) fn allows_replay(&self) -> bool {
281        self.safety != WsReplaySafety::Never
282    }
283    pub(crate) fn should_retry_error(&self, error: &NetError) -> bool {
284        self.retry_on.allows(error)
285    }
286    pub(crate) fn classify(&self, context: &WsRequestRetryContext<'_>) -> Result<RetryDecision> {
287        match &self.classifier {
288            None => Ok(RetryDecision::Default),
289            Some(classifier) => isolate_classifier(|| classifier(context)),
290        }
291    }
292}
293impl Default for WsRequestRetryPolicy {
294    fn default() -> Self {
295        Self::no_retry()
296    }
297}
298impl fmt::Debug for WsRequestRetryPolicy {
299    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
300        f.debug_struct("WsRequestRetryPolicy")
301            .field("schedule", &self.schedule)
302            .field("retry_on", &self.retry_on)
303            .field("safety", &self.safety)
304            .field("has_classifier", &self.classifier.is_some())
305            .field("observer", &self.observer)
306            .finish()
307    }
308}
309pub struct WsRequestRetryPolicyBuilder {
310    policy: WsRequestRetryPolicy,
311}
312impl WsRequestRetryPolicyBuilder {
313    pub fn schedule(mut self, schedule: RetrySchedule) -> Self {
314        self.policy.schedule = schedule;
315        self
316    }
317    pub fn retry_on(mut self, retry_on: WsRequestRetryOn) -> Self {
318        self.policy.retry_on = retry_on;
319        self
320    }
321    pub fn safety(mut self, safety: WsReplaySafety) -> Self {
322        self.policy.safety = safety;
323        self
324    }
325    pub fn observer(mut self, observer: impl RetryObserver) -> Self {
326        self.policy.observer = Some(RetryObserverHandle::new(observer));
327        self
328    }
329    pub fn classifier<F>(mut self, classifier: F) -> Self
330    where
331        F: for<'a> Fn(&WsRequestRetryContext<'a>) -> RetryDecision + Send + Sync + 'static,
332    {
333        self.policy.classifier = Some(Arc::new(classifier));
334        self
335    }
336    pub fn build(self) -> std::result::Result<WsRequestRetryPolicy, RetryConfigError> {
337        Ok(self.policy)
338    }
339}
340
341pub(crate) fn terminal_error(error: &NetError) -> bool {
342    matches!(
343        timeout_phase(error),
344        Some(WsTimeoutPhase::Admission | WsTimeoutPhase::Total)
345    ) || matches!(
346        error.kind(),
347        ErrorKind::Cancelled
348            | ErrorKind::Closed
349            | ErrorKind::EngineDropped
350            | ErrorKind::InvalidConfig
351            | ErrorKind::InvalidInput
352            | ErrorKind::InvalidPolicy
353            | ErrorKind::CallbackPanicked
354            | ErrorKind::RuntimeUnavailable
355            | ErrorKind::Internal
356    ) || matches!(
357        error.context().stage,
358        Some(ErrorStage::RequestBuild | ErrorStage::Configuration)
359    ) || (error.context().stage == Some(ErrorStage::Admission)
360        && timeout_phase(error) != Some(WsTimeoutPhase::Attempt))
361}
362
363pub(crate) fn isolate_classifier<T>(callback: impl FnOnce() -> T) -> Result<T> {
364    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(callback)) {
365        Ok(value) => Ok(value),
366        Err(payload) => {
367            if let Err(second) =
368                std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| drop(payload)))
369            {
370                std::mem::forget(second);
371            }
372            Err(NetError::from(ErrorKind::CallbackPanicked).with_stage(ErrorStage::Provider))
373        }
374    }
375}
376
377/// Bounded traversal preserves timeout identity through DeliveryUnknown while
378/// remaining safe for arbitrary caller-owned error-source chains.
379pub(crate) fn timeout_phase(error: &NetError) -> Option<WsTimeoutPhase> {
380    let mut current: Option<&(dyn std::error::Error + 'static)> = Some(error);
381    for _ in 0..32 {
382        let source = current?;
383        if let Some(error) = source.downcast_ref::<NetError>() {
384            if let Some(phase) = error.ws_timeout_phase() {
385                return Some(phase);
386            }
387            if error.kind() == ErrorKind::TimedOut {
388                match error.context().stage {
389                    Some(ErrorStage::Write) => return Some(WsTimeoutPhase::Write),
390                    Some(ErrorStage::Response) => return Some(WsTimeoutPhase::Response),
391                    Some(ErrorStage::Admission) => return Some(WsTimeoutPhase::Admission),
392                    _ => {}
393                }
394            }
395        }
396        current = source.source();
397    }
398    None
399}