Skip to main content

ntex_util/services/
retry.rs

1use ntex_service::{Ctx, Middleware, Service};
2
3/// Determines whether and how a failed service call is retried.
4pub trait Policy<S: Service<St, Req>, St, Req>: Sized + Clone {
5    /// Returns whether the call should be retried.
6    async fn retry(&mut self, req: &Req, res: &Result<S::Res, S::Error>) -> bool;
7
8    /// Clones or reconstructs a request for a possible retry.
9    ///
10    /// Returning `None` prevents retries for this request.
11    fn clone_request(&self, req: &Req) -> Option<Req>;
12}
13
14#[derive(Clone, Debug)]
15/// Middleware that retries service calls according to a [`Policy`].
16///
17/// The policy is cloned for each request.
18pub struct Retry<P> {
19    policy: P,
20}
21
22#[derive(Clone, Debug)]
23/// A service that retries calls according to a [`Policy`].
24pub struct RetryService<P, S> {
25    policy: P,
26    service: S,
27}
28
29impl<P> Retry<P> {
30    /// Creates retry middleware with the specified policy.
31    pub fn new(policy: P) -> Self {
32        Retry { policy }
33    }
34}
35
36impl<P: Clone, S, St> Middleware<S, St> for Retry<P> {
37    type Service = RetryService<P, S>;
38
39    fn create(&self, _: &St, service: S) -> Self::Service {
40        RetryService {
41            service,
42            policy: self.policy.clone(),
43        }
44    }
45}
46
47impl<P, S> RetryService<P, S> {
48    /// Wraps a service with the specified retry policy.
49    pub fn new(policy: P, service: S) -> Self {
50        RetryService { policy, service }
51    }
52}
53
54impl<P, S, St, Req> Service<St, Req> for RetryService<P, S>
55where
56    P: Policy<S, St, Req>,
57    S: Service<St, Req>,
58{
59    type Res = S::Res;
60    type Error = S::Error;
61
62    #[allow(
63        deprecated,
64        reason = "preserve the validated first-attempt bypass; retries use Ctx::call"
65    )]
66    async fn call(&self, req: Req, ctx: Ctx<'_, Self, St>) -> Result<S::Res, S::Error> {
67        let mut policy = self.policy.clone();
68        let mut cloned = policy.clone_request(&req);
69        // the first call is covered by the outer readiness check
70        let mut result = ctx.call_nowait(&self.service, req).await;
71
72        while let Some(r) = cloned.take() {
73            if !policy.retry(&r, &result).await {
74                break;
75            }
76            cloned = policy.clone_request(&r);
77            result = ctx.call(&self.service, r).await;
78        }
79        result
80    }
81
82    ntex_service::forward_bind!(St, service);
83    ntex_service::forward_ready!(St, service);
84    ntex_service::forward_shutdown!(St, service);
85}
86
87#[derive(Copy, Clone, Debug)]
88/// A retry policy that retries every service error.
89///
90/// The default policy permits up to three retries after the initial call.
91pub struct DefaultRetryPolicy(u16);
92
93impl DefaultRetryPolicy {
94    /// Creates a policy that permits up to `retry` retries.
95    pub fn new(retry: u16) -> Self {
96        DefaultRetryPolicy(retry)
97    }
98}
99
100impl Default for DefaultRetryPolicy {
101    fn default() -> Self {
102        DefaultRetryPolicy::new(3)
103    }
104}
105
106impl<S, St, Req> Policy<S, St, Req> for DefaultRetryPolicy
107where
108    S: Service<St, Req>,
109    Req: Clone,
110{
111    async fn retry(&mut self, _: &Req, res: &Result<S::Res, S::Error>) -> bool {
112        if res.is_err() {
113            if self.0 == 0 {
114                false
115            } else {
116                self.0 -= 1;
117                true
118            }
119        } else {
120            false
121        }
122    }
123
124    fn clone_request(&self, req: &Req) -> Option<Req> {
125        Some(req.clone())
126    }
127}
128
129#[cfg(test)]
130mod tests {
131    #![allow(clippy::unused_async_trait_impl)]
132    use std::{cell::Cell, rc::Rc};
133
134    use ntex_service::{Pipeline, apply, fn_factory};
135
136    use super::*;
137
138    #[derive(Clone, Debug, PartialEq)]
139    struct TestService(Rc<Cell<usize>>);
140
141    impl Service<(), ()> for TestService {
142        type Res = ();
143        type Error = ();
144
145        async fn call(&self, _r: (), _: Ctx<'_, Self>) -> Result<(), ()> {
146            let cnt = self.0.get();
147            if cnt == 0 {
148                Ok(())
149            } else {
150                self.0.set(cnt - 1);
151                Err(())
152            }
153        }
154    }
155
156    /// STATEMENT: Retries stop at the configured budget or return an earlier success.
157    ///
158    /// HOW:
159    /// - Exhaust the default policy against a counted failing service and check remaining failures.
160    /// - Create middleware services that succeed within the retry budget and verify success.
161    #[ntex::test]
162    async fn test_retry() {
163        let cnt = Rc::new(Cell::new(5));
164        let svc = Pipeline::new(
165            (),
166            RetryService::new(DefaultRetryPolicy::default(), TestService(cnt.clone())).clone(),
167        );
168        assert_eq!(svc.call(()).await, Err(()));
169        assert_eq!(svc.ready().await, Ok(()));
170        svc.shutdown().await;
171        assert_eq!(cnt.get(), 1);
172
173        let factory = apply(
174            Retry::new(DefaultRetryPolicy::new(3)).clone(),
175            fn_factory(|(): &()| async { Ok::<_, ()>(TestService(Rc::new(Cell::new(2)))) }),
176        );
177        let srv = factory.pipeline(()).await.unwrap();
178        assert_eq!(srv.call(()).await, Ok(()));
179
180        let factory = apply(
181            Retry::new(DefaultRetryPolicy::new(3)).clone(),
182            fn_factory(|(): &()| async { Ok::<_, ()>(TestService(Rc::new(Cell::new(2)))) }),
183        );
184        let srv = factory.pipeline(()).await.unwrap();
185        assert_eq!(srv.call(()).await, Ok(()));
186    }
187
188    #[derive(Clone)]
189    struct CloneOnce(Rc<Cell<usize>>);
190
191    impl Policy<TestService, (), ()> for CloneOnce {
192        async fn retry(&mut self, (): &(), res: &Result<(), ()>) -> bool {
193            res.is_err()
194        }
195
196        fn clone_request(&self, (): &()) -> Option<()> {
197            let n = self.0.get();
198            self.0.set(n + 1);
199            if n == 0 { Some(()) } else { None }
200        }
201    }
202
203    /// STATEMENT: A retry returns its result when the request cannot be cloned again.
204    ///
205    /// HOW:
206    /// - Use a policy that permits only one request clone against a failing service.
207    /// - Verify the error, two service calls, and two clone attempts.
208    #[ntex::test]
209    async fn test_retry_without_clone() {
210        // the retried request cannot be cloned again, its result is returned
211        let cnt = Rc::new(Cell::new(5));
212        let clones = Rc::new(Cell::new(0));
213        let svc = Pipeline::new(
214            (),
215            RetryService::new(CloneOnce(clones.clone()), TestService(cnt.clone())),
216        );
217        assert_eq!(svc.call(()).await, Err(()));
218        assert_eq!(cnt.get(), 3);
219        assert_eq!(clones.get(), 2);
220    }
221}