Skip to main content

ntex_util/services/
onerequest.rs

1//! Middleware that permits one service call at a time.
2use std::{cell::Cell, future::poll_fn, task::Poll};
3
4use ntex_service::{BindCtx, Ctx, Middleware, ReadyBinding, ReadyNotifier, Service};
5
6use crate::{channel::condition::Condition, future::OnDropFn};
7
8/// Middleware that serializes calls to its wrapped service.
9#[derive(Copy, Clone, Default, Debug)]
10pub struct OneRequest;
11
12impl<S, St> Middleware<S, St> for OneRequest {
13    type Service = OneRequestService<S>;
14
15    fn create(&self, _: &St, service: S) -> Self::Service {
16        OneRequestService {
17            service: ReadyBinding::new(service),
18            ready: Cell::new(true),
19            waiters: Condition::new(),
20            changed: ReadyNotifier::new(),
21        }
22    }
23}
24
25/// Service wrapper that allows only one call to run at a time.
26///
27/// This type is intentionally not cloneable. Cloning its readiness state would
28/// create another independent gate and allow calls to overlap.
29///
30/// Acquiring or releasing the call slot invalidates this service's readiness.
31/// The wrapped service has an independent readiness cache and must notify when
32/// its readiness changes.
33#[derive(Debug)]
34pub struct OneRequestService<S> {
35    waiters: Condition,
36    service: ReadyBinding<S>,
37    ready: Cell<bool>,
38    changed: ReadyNotifier,
39}
40
41impl<S> OneRequestService<S> {
42    /// Wraps a service so that concurrent callers wait for the active call.
43    pub fn new<St, Req>(service: S) -> Self
44    where
45        S: Service<St, Req>,
46    {
47        Self {
48            service: ReadyBinding::new(service),
49            ready: Cell::new(true),
50            waiters: Condition::new(),
51            changed: ReadyNotifier::new(),
52        }
53    }
54}
55
56impl<S> OneRequestService<S> {
57    /// Waits until no call is active.
58    async fn acquire(&self) {
59        if self.ready.get() {
60            return;
61        }
62
63        let waiter = self.waiters.wait();
64        poll_fn(|cx| {
65            // the waiter stays registered after a notification, another task
66            // may have started a call before this one was polled
67            let _ = waiter.poll_ready(cx);
68            if self.ready.get() {
69                Poll::Ready(())
70            } else {
71                Poll::Pending
72            }
73        })
74        .await;
75    }
76}
77
78/// Releases the call slot even if the call future is dropped or panics.
79struct Release<'a, S>(&'a OneRequestService<S>);
80
81impl<S> Drop for Release<'_, S> {
82    fn drop(&mut self) {
83        self.0.ready.set(true);
84        let _wake = OnDropFn::new(|| self.0.waiters.notify(()));
85        self.0.changed.notify();
86    }
87}
88
89impl<S: Service<St, Req>, St, Req> Service<St, Req> for OneRequestService<S> {
90    type Res = S::Res;
91    type Error = S::Error;
92
93    fn bind(&self, ctx: BindCtx<'_>) {
94        ctx.subscribe(&self.changed);
95        ctx.bind::<_, St, Req>(&self.service);
96    }
97
98    #[inline]
99    async fn ready(&self, ctx: Ctx<'_, Self, St>) -> Result<(), S::Error> {
100        self.acquire().await;
101        ctx.ready(&self.service).await
102    }
103
104    #[inline]
105    async fn call(&self, req: Req, ctx: Ctx<'_, Self, St>) -> Result<S::Res, S::Error> {
106        // several callers can observe readiness before any of them calls
107        self.acquire().await;
108        self.ready.set(false);
109        let _release = Release(self);
110        self.changed.notify();
111
112        ctx.call(&self.service, req).await
113    }
114
115    ntex_service::forward_shutdown!(St, service);
116}
117
118#[cfg(test)]
119mod tests {
120    use ntex_service::{Pipeline, apply, fn_factory};
121    use std::{cell::RefCell, rc::Rc, time::Duration};
122
123    use super::*;
124    use crate::{channel::oneshot, future::lazy};
125
126    struct SleepService(oneshot::Receiver<()>);
127
128    impl Service<(), ()> for SleepService {
129        type Res = ();
130        type Error = ();
131
132        async fn call(&self, _r: (), _: Ctx<'_, Self>) -> Result<(), ()> {
133            let _ = self.0.recv().await;
134            Ok::<_, ()>(())
135        }
136    }
137
138    /// STATEMENT: An active request blocks readiness until it completes.
139    ///
140    /// HOW:
141    /// - Start a channel-blocked request after checking initial readiness.
142    /// - Observe pending readiness, release the request, and verify readiness returns.
143    #[ntex::test]
144    async fn test_oneshot() {
145        let (tx, rx) = oneshot::channel();
146
147        let srv = Pipeline::new((), OneRequestService::new(SleepService(rx)));
148        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
149
150        let srv2 = srv.bind();
151        ntex::rt::spawn(async move {
152            let _ = srv2.call(()).await;
153        });
154        crate::time::sleep(Duration::from_millis(25)).await;
155        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Pending);
156
157        let _ = tx.send(());
158        crate::time::sleep(Duration::from_millis(25)).await;
159        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
160        srv.shutdown().await;
161    }
162
163    /// STATEMENT: Factory-applied `OneRequest` blocks readiness during an active call.
164    ///
165    /// HOW:
166    /// - Create middleware around a channel-blocked service and check its debug name.
167    /// - Verify readiness before, during, and after releasing a spawned request.
168    #[ntex::test]
169    async fn test_middleware() {
170        assert_eq!(format!("{OneRequest:?}"), "OneRequest");
171
172        let (tx, rx) = oneshot::channel();
173        let rx = RefCell::new(Some(rx));
174        let sf = apply(
175            OneRequest,
176            fn_factory(move |(): &()| {
177                let rx = rx.borrow_mut().take().unwrap();
178                async move { Ok::<_, ()>(SleepService(rx)) }
179            }),
180        );
181
182        let srv = sf.pipeline(()).await.unwrap();
183        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
184
185        let srv1 = srv.bind();
186        ntex::rt::spawn(async move {
187            let _ = srv1.call(()).await;
188        });
189        crate::time::sleep(Duration::from_millis(25)).await;
190        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Pending);
191
192        let _ = tx.send(());
193        crate::time::sleep(Duration::from_millis(25)).await;
194        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
195    }
196
197    /// STATEMENT: A `OneRequest` middleware pipeline becomes ready again after completion.
198    ///
199    /// HOW:
200    /// - Build the middleware through a factory and start a channel-blocked request.
201    /// - Check readiness becomes pending, then send completion and check readiness recovers.
202    #[ntex::test]
203    async fn test_middleware2() {
204        assert_eq!(format!("{OneRequest:?}"), "OneRequest");
205
206        let (tx, rx) = oneshot::channel();
207        let rx = RefCell::new(Some(rx));
208        let sf = apply(
209            OneRequest,
210            fn_factory(move |(): &()| {
211                let rx = rx.borrow_mut().take().unwrap();
212                async move { Ok::<_, ()>(SleepService(rx)) }
213            }),
214        );
215
216        let srv = sf.pipeline(()).await.unwrap();
217        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
218
219        let srv1 = srv.bind();
220        ntex::rt::spawn(async move {
221            let _ = srv1.call(()).await;
222        });
223        crate::time::sleep(Duration::from_millis(25)).await;
224        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Pending);
225
226        let _ = tx.send(());
227        crate::time::sleep(Duration::from_millis(25)).await;
228        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
229    }
230
231    /// STATEMENT: Canceling a request releases the single-request readiness gate.
232    ///
233    /// HOW:
234    /// - Time out a call whose inner service is waiting on a channel.
235    /// - Verify the timeout and immediately poll the pipeline as ready.
236    #[ntex::test]
237    async fn test_cancelled_call_releases() {
238        let (_tx, rx) = oneshot::channel();
239        let srv = Pipeline::new((), OneRequestService::new(SleepService(rx)));
240
241        let res = crate::time::timeout(Duration::from_millis(25), srv.call(())).await;
242        assert!(res.is_err());
243        assert_eq!(lazy(|cx| srv.poll_ready(cx)).await, Poll::Ready(Ok(())));
244    }
245
246    struct CountService {
247        active: Rc<Cell<usize>>,
248        max: Rc<Cell<usize>>,
249    }
250
251    impl Service<(), ()> for CountService {
252        type Res = ();
253        type Error = ();
254
255        async fn call(&self, _r: (), _: Ctx<'_, Self>) -> Result<(), ()> {
256            self.active.set(self.active.get() + 1);
257            self.max.set(self.max.get().max(self.active.get()));
258            crate::time::sleep(Duration::from_millis(10)).await;
259            self.active.set(self.active.get() - 1);
260            Ok(())
261        }
262    }
263
264    fn count_srv() -> (Pipeline<(), (), ()>, Rc<Cell<usize>>) {
265        let max = Rc::new(Cell::new(0));
266        let srv = Pipeline::new(
267            (),
268            OneRequestService::new(CountService {
269                active: Rc::new(Cell::new(0)),
270                max: max.clone(),
271            }),
272        );
273        (srv, max)
274    }
275
276    /// STATEMENT: Multiple waiting requests complete without overlapping inner calls.
277    ///
278    /// HOW:
279    /// - Spawn four requests against a service that counts active calls.
280    /// - Wait for all completions and verify the maximum concurrency is one.
281    #[ntex::test]
282    async fn test_many_waiters() {
283        let (srv, max) = count_srv();
284        let done = Rc::new(Cell::new(0));
285        for _ in 0..4 {
286            let (srv, done) = (srv.bind(), done.clone());
287            ntex::rt::spawn(async move {
288                srv.call(()).await.unwrap();
289                done.set(done.get() + 1);
290            });
291        }
292
293        // calls run one after another, wait for all of them with a generous
294        // deadline, timers on loaded CI runners overshoot a lot
295        for _ in 0..100 {
296            if done.get() == 4 {
297                break;
298            }
299            crate::time::sleep(Duration::from_millis(50)).await;
300        }
301        assert_eq!(done.get(), 4);
302        assert_eq!(max.get(), 1);
303    }
304
305    /// STATEMENT: Repeated readiness checks do not permit overlapping requests.
306    ///
307    /// HOW:
308    /// - Check readiness twice, then join two concurrent calls.
309    /// - Verify both succeed while the inner service's maximum concurrency stays at one.
310    #[ntex::test]
311    async fn test_no_overlap_after_ready() {
312        let (srv, max) = count_srv();
313
314        srv.ready().await.unwrap();
315        srv.ready().await.unwrap();
316        let (r1, r2) = crate::future::join(srv.call_static(()), srv.call_static(())).await;
317        assert!(r1.is_ok() && r2.is_ok());
318        assert_eq!(max.get(), 1);
319    }
320}