Skip to main content

ntex_service/
lib.rs

1//! Asynchronous services, factories, middleware, and execution pipelines.
2//!
3//! The [`Service`] trait is the crate's central abstraction. A service
4//! asynchronously transforms a request into a response, while
5//! [`ServiceFactory`] constructs services and [`Pipeline`] manages readiness,
6//! calls, and shutdown.
7#![deny(clippy::pedantic)]
8#![allow(
9    clippy::cast_possible_truncation,
10    clippy::missing_fields_in_debug,
11    clippy::missing_errors_doc,
12    clippy::missing_panics_doc,
13    clippy::must_use_candidate,
14    clippy::type_complexity,
15    clippy::unused_async,
16    clippy::unused_async_trait_impl
17)]
18use std::rc::Rc;
19
20mod and_then;
21mod apply;
22mod bind;
23mod binding;
24pub mod boxed;
25pub mod cfg;
26mod chain;
27mod ctx;
28mod fn_ready;
29mod fn_service;
30mod fn_shutdown;
31mod inline;
32mod macros;
33mod map;
34mod map_err;
35mod map_init_err;
36mod map_state;
37mod middleware;
38mod readiness;
39mod ready;
40mod ready_call;
41pub mod state;
42mod then;
43mod util;
44
45pub mod pipeline;
46mod pl_factory;
47mod pl_inner;
48mod pl_state;
49
50pub use crate::apply::{apply_fn, apply_fn_factory};
51pub use crate::bind::BindCtx;
52pub use crate::binding::{ReadyBinding, ReadyBindingMiddleware};
53pub use crate::chain::{ServiceChain, ServiceChainFactory, factory, service};
54pub use crate::ctx::Ctx;
55pub use crate::fn_service::{fn_factory, fn_service, fn_service_st};
56pub use crate::map_state::{map_state, map_state_factory};
57pub use crate::middleware::{Identity, Middleware, Stack, apply, fn_layer};
58pub use crate::pipeline::Pipeline;
59pub use crate::readiness::{ReadyCallback, ReadyLink, ReadyNotifier};
60pub use crate::ready::{ready, ready_factory};
61pub use crate::state::{RequestState, State};
62
63#[allow(unused_variables)]
64/// An asynchronous operation from a request to a response.
65///
66/// A service receives requests and asynchronously produces responses.
67/// Conceptually, it is similar to:
68///
69/// ```rust,ignore
70/// async fn(Request) -> Result<Response, Error>
71/// ```
72///
73/// The request and pipeline-state types are generic parameters. The response
74/// and error types are associated types, allowing one service type to implement
75/// `Service` for multiple request types.
76///
77/// Methods take `&self`, so implementations that mutate internal state must use
78/// interior mutability such as `Cell`, `RefCell`, or a synchronization
79/// primitive when appropriate.
80///
81/// The same abstraction can represent client- and server-side operations.
82/// Services focus on transformation, making them straightforward to test and
83/// compose.
84///
85/// A service call requires a [`Ctx`] and therefore runs through a [`Pipeline`]
86/// or from another service. The pipeline coordinates readiness across a
87/// composed service chain before dispatching a request.
88///
89/// ```rust
90/// # use std::convert::Infallible;
91/// #
92/// # use ntex_service::{Service, Ctx};
93///
94/// struct MyService;
95///
96/// impl Service<(), u8> for MyService {
97///     type Res = u64;
98///     type Error = Infallible;
99///
100///     async fn call(&self, req: u8, ctx: Ctx<'_, Self>) -> Result<Self::Res, Self::Error> {
101///         Ok(req as u64)
102///     }
103/// }
104/// ```
105///
106/// Simple services do not need a manual trait implementation. The example
107/// above can be expressed with [`fn_service`]:
108///
109/// ```rust
110/// # use std::convert::Infallible;
111/// # use ntex_service::{Pipeline, fn_service};
112/// #
113/// # async fn run() -> Result<(), Infallible> {
114/// let service = fn_service(|req: u8| async move {
115///     Ok::<_, Infallible>(u64::from(req))
116/// });
117/// let pipeline = Pipeline::new((), service);
118///
119/// assert_eq!(pipeline.call(10).await?, 10);
120/// # Ok(())
121/// # }
122/// ```
123///
124/// # Wrapping services
125///
126/// The default [`Self::bind`], [`Self::ready`], and [`Self::shutdown`] bodies
127/// are only suitable for leaf services. A wrapper that owns another service and
128/// implements only [`Self::call`] still compiles, but its child is never bound,
129/// child readiness errors and capacity limits are bypassed, child readiness
130/// notifications never invalidate the wrapper's cached readiness, and the child
131/// is never shut down.
132///
133/// Prefer helpers that forward the whole lifecycle:
134///
135/// - [`fn_layer`] or [`apply_fn`] for wrappers that only adapt calls;
136///   `ntex::web::middleware::from_fn` is the equivalent for web middleware.
137/// - [`forward!`] for manual implementations with one or several service fields.
138/// - [`Pipeline::bind_to`] in [`Self::bind`] for [`Pipeline`] fields.
139///
140/// Otherwise implement all three methods: bind every child with
141/// [`BindCtx::bind`], check each child with [`Ctx::ready`], and shut each child
142/// down with [`Ctx::shutdown`]. A wrapper that adds its own readiness, such as a
143/// capacity limit, must also subscribe a [`ReadyNotifier`] in [`Self::bind`] and
144/// notify it on every change; waking a task does not invalidate cached success.
145///
146/// # Framework guide
147///
148/// - [Service Model](https://docs.ntex.rs/1-service.html)
149/// - [Service Pipelines](https://docs.ntex.rs/2-pipeline.html)
150/// - [Service State](https://docs.ntex.rs/3-state.html)
151#[diagnostic::on_unimplemented(
152    message = "`{Self}` is not a `Service<{St}, {Req}>`",
153    label = "expected a service for `{Req}` requests with `{St}` state",
154    note = "the state type comes first: `impl Service<St, Req> for T`; use `()` for no state",
155    note = "check that `St` and `Req` match the pipeline or parent service exactly",
156    note = "wrap async functions with `fn_service` (`async |req| ..`) or `fn_service_st` (`async |st, req| ..`)"
157)]
158pub trait Service<St, Req> {
159    /// Response produced by the service.
160    type Res;
161
162    /// Error produced while checking readiness or processing a request.
163    type Error;
164
165    /// Processes a request and asynchronously returns the response.
166    ///
167    /// The enclosing pipeline checks readiness before invoking this method.
168    /// Implementations should not call their own `ready` method. A composed
169    /// service can use [`Ctx::call`] to call an inner service using the closest
170    /// upstream readiness cache. A service wrapped with [`ready()`] can be
171    /// called directly to check its own cache instead.
172    async fn call(&self, req: Req, ctx: Ctx<'_, Self, St>) -> Result<Self::Res, Self::Error>;
173
174    #[inline]
175    /// Initializes the service within a [`Pipeline`].
176    ///
177    /// Called during pipeline construction or [`Ctx::create`], before runtime
178    /// operations on the new service.
179    ///
180    /// The default is suitable for leaves without notification sources.
181    /// Composites must bind every existing child, and services with changing
182    /// readiness must subscribe to all their sources here. Lazily created
183    /// children must be initialized through [`Ctx::create`], which binds them
184    /// explicitly before use.
185    /// Register reusable [`ReadyCallback`] handles with [`BindCtx::on_notify`]
186    /// to observe notifications reaching the service's scope.
187    ///
188    /// Binding is synchronous. Shared services can be bound to multiple parents;
189    /// implementations must support repeated binding.
190    /// [`forward!`] forwards to one or several service fields. Register [`Pipeline`] fields with [`Pipeline::bind_to`].
191    /// Ordinary readiness checks, calls, and shutdown do not add dependencies.
192    fn bind(&self, ctx: BindCtx<'_>) {}
193
194    #[inline]
195    /// Waits until the service is ready to process a request.
196    ///
197    /// If the service is at capacity, the returned future remains pending until
198    /// capacity becomes available.
199    ///
200    /// Pipeline readiness is coordinated across all services in a composed
201    /// chain. A request is dispatched only when the chain is ready.
202    ///
203    /// A [`Pipeline`] or [`ReadyBinding`] caches success until a subscribed
204    /// [`ReadyNotifier`] invalidates it; calls do not consume that success.
205    /// Subscribe in [`Self::bind`] and notify on every readiness-changing
206    /// transition, including consuming or releasing capacity and external
207    /// failures, before another caller can use stale cached readiness.
208    /// A task wake schedules a pending check but does not invalidate a cached
209    /// success. Services must not rely on this method being polled on every
210    /// call to drive background progress.
211    ///
212    /// Readiness checks and their wake sources run on the pipeline's thread.
213    /// This local-only requirement does not apply to task wakers supplied to
214    /// [`Self::call`] or [`Self::shutdown`].
215    ///
216    /// Readiness may inspect [`Ctx::st`], but it describes the shared gate, not
217    /// a reservation for one request or state value. State-taking pipeline
218    /// handles share the same cache; independent gates need separate pipelines
219    /// or service bindings.
220    async fn ready(&self, ctx: Ctx<'_, Self, St>) -> Result<(), Self::Error> {
221        Ok(())
222    }
223
224    #[inline]
225    /// Shuts down the service.
226    ///
227    /// Returns when the service has been properly shut down.
228    async fn shutdown(&self, ctx: Ctx<'_, Self, St>) {}
229
230    #[inline]
231    /// Maps this service's output to a different type, returning a new service.
232    ///
233    /// This is similar to `Option::map` or `Iterator::map`, changing the
234    /// output type of the underlying service.
235    ///
236    /// This function consumes the original service and returns a wrapped version,
237    /// following the pattern of standard library `map` methods.
238    fn map<F, Res>(self, f: F) -> ServiceChain<dev::Map<F, Self, Res>, St, Req>
239    where
240        Self: Sized,
241        F: Fn(Self::Res) -> Res,
242    {
243        service(dev::Map::new(f, self))
244    }
245
246    #[inline]
247    /// Maps this service's error to a different type, returning a new service.
248    ///
249    /// This is similar to `Result::map_err`, changing the error type of the
250    /// underlying service. It is useful, for example, to ensure multiple
251    /// services have the same error type.
252    ///
253    /// This function consumes the original service and returns a wrapped version.
254    fn map_err<F, E>(self, f: F) -> ServiceChain<dev::MapErr<F, Self, E>, St, Req>
255    where
256        Self: Sized,
257        F: Fn(Self::Error) -> E,
258    {
259        service(dev::MapErr::new(f, self))
260    }
261
262    #[inline]
263    /// Calls another service after this service completes successfully.
264    ///
265    /// The first service's response becomes the second service's request. If
266    /// the first service returns an error, the second service is not called.
267    fn and_then<Next, F>(self, f: F) -> ServiceChain<dev::AndThen<Self, Next>, St, Req>
268    where
269        Self: Sized,
270        Next: Service<St, Self::Res, Error = Self::Error>,
271        F: IntoService<Next, St, Self::Res>,
272    {
273        service(dev::AndThen::new(self, f.into_service()))
274    }
275
276    #[inline]
277    /// Wraps this service and its state in a [`Pipeline`].
278    fn pipeline(self, st: St) -> Pipeline<Req, Self::Res, Self::Error>
279    where
280        Self: Sized + 'static,
281        St: 'static,
282        Req: 'static,
283    {
284        Pipeline::new(st, self)
285    }
286}
287
288/// A factory for asynchronously creating [`Service`] values.
289///
290/// This is useful when new `Service`s must be produced dynamically. For example,
291/// a TCP server listener accepts new connections, constructs a new `Service` for
292/// each connection using the `ServiceFactory` trait, and uses that service to
293/// handle inbound requests.
294///
295/// `St` is the state type shared by the factory and its services.
296///
297/// Simple factories can often use [`fn_factory`] to reduce boilerplate.
298#[diagnostic::on_unimplemented(
299    message = "`{Self}` is not a `ServiceFactory<{St}, {Req}>`",
300    label = "expected a factory of services for `{Req}` requests with `{St}` state",
301    note = "the state type comes first: `impl ServiceFactory<St, Req> for T`; use `()` for no state",
302    note = "a `Service` is not a factory; use `fn_factory(async |st| Ok(service))` to create it per pipeline",
303    note = "async functions `async |req| ..` and `async |st, req| ..` convert into factories automatically"
304)]
305pub trait ServiceFactory<St, Req> {
306    /// Response produced by the created services.
307    type Res;
308
309    /// Error produced by the created services.
310    type Error;
311
312    /// The type of `Service` produced by this factory.
313    type Service: Service<St, Req, Res = Self::Res, Error = Self::Error>;
314
315    /// Error that can occur while constructing a service.
316    type InitError;
317
318    /// Asynchronously creates a service using the supplied state.
319    async fn create(&self, st: &St) -> Result<Self::Service, Self::InitError>;
320
321    #[inline]
322    /// Creates a service and wraps it with its state in a [`Pipeline`].
323    async fn pipeline(
324        &self,
325        st: St,
326    ) -> Result<Pipeline<Req, Self::Res, Self::Error>, Self::InitError>
327    where
328        Self: 'static,
329        St: 'static,
330        Req: 'static,
331    {
332        let svc = self.create(&st).await?;
333        Ok(Pipeline::new(st, svc))
334    }
335
336    #[inline]
337    /// Returns a factory whose services map responses to a different type.
338    fn map<F, Res>(self, f: F) -> ServiceChainFactory<dev::MapFactory<F, Self, Res>, St, Req>
339    where
340        Self: Sized,
341        F: Fn(Self::Res) -> Res + Clone,
342    {
343        factory(dev::MapFactory::new(f, self))
344    }
345
346    #[inline]
347    /// Returns a factory whose services map errors to a different type.
348    fn map_err<F, E>(self, f: F) -> ServiceChainFactory<dev::MapErrFactory<F, Self, E>, St, Req>
349    where
350        Self: Sized,
351        F: Fn(Self::Error) -> E + Clone,
352    {
353        factory(dev::MapErrFactory::new(f, self))
354    }
355
356    #[inline]
357    /// Maps this factory's initialization error to a different error,
358    /// returning a new service factory.
359    fn map_init_err<F, E>(self, f: F) -> ServiceChainFactory<dev::MapInitErr<F, Self, E>, St, Req>
360    where
361        Self: Sized,
362        F: Fn(Self::InitError) -> E + Clone,
363    {
364        factory(dev::MapInitErr::new(f, self))
365    }
366
367    /// Chains another factory after this factory's services.
368    ///
369    /// Each response from the first service becomes a request to the second
370    /// service. The second service is not called when the first returns an
371    /// error.
372    fn and_then<U, F>(self, f: F) -> ServiceChainFactory<dev::AndThenFactory<Self, U>, St, Req>
373    where
374        Self: Sized,
375        U: ServiceFactory<St, Self::Res, Error = Self::Error, InitError = Self::InitError>,
376        F: IntoServiceFactory<U, St, Self::Res>,
377    {
378        factory(dev::AndThenFactory::new(self, f.into_factory()))
379    }
380
381    /// Creates a boxed service factory.
382    fn boxed(self) -> boxed::BoxServiceFactory<St, Req, Self::Res, Self::Error, Self::InitError>
383    where
384        St: 'static,
385        Req: 'static,
386        Self: Sized + 'static,
387    {
388        boxed::factory(self)
389    }
390}
391
392impl<S, St, Req> Service<St, Req> for &S
393where
394    S: Service<St, Req>,
395{
396    type Res = S::Res;
397    type Error = S::Error;
398
399    fn bind(&self, ctx: BindCtx<'_>) {
400        ctx.bind(&**self);
401    }
402
403    #[inline]
404    fn ready(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = Result<(), S::Error>> {
405        Service::ready(&**self, ctx.cast())
406    }
407
408    #[inline]
409    fn call(
410        &self,
411        req: Req,
412        ctx: Ctx<'_, Self, St>,
413    ) -> impl Future<Output = Result<S::Res, S::Error>> {
414        Service::call(&**self, req, ctx.cast())
415    }
416
417    #[inline]
418    fn shutdown(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = ()> {
419        Service::shutdown(&**self, ctx.cast())
420    }
421}
422
423impl<S, St, Req> Service<St, Req> for Box<S>
424where
425    S: Service<St, Req>,
426{
427    type Res = S::Res;
428    type Error = S::Error;
429
430    fn bind(&self, ctx: BindCtx<'_>) {
431        ctx.bind(&**self);
432    }
433
434    #[inline]
435    fn ready(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = Result<(), S::Error>> {
436        Service::ready(&**self, ctx.cast())
437    }
438
439    #[inline]
440    fn call(
441        &self,
442        req: Req,
443        ctx: Ctx<'_, Self, St>,
444    ) -> impl Future<Output = Result<S::Res, S::Error>> {
445        Service::call(&**self, req, ctx.cast())
446    }
447
448    #[inline]
449    fn shutdown(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = ()> {
450        Service::shutdown(&**self, ctx.cast())
451    }
452}
453
454impl<S, St, Req> Service<St, Req> for Rc<S>
455where
456    S: Service<St, Req>,
457{
458    type Res = S::Res;
459    type Error = S::Error;
460
461    fn bind(&self, ctx: BindCtx<'_>) {
462        ctx.bind(&**self);
463    }
464
465    #[inline]
466    fn ready(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = Result<(), S::Error>> {
467        Service::ready(&**self, ctx.cast())
468    }
469
470    #[inline]
471    fn call(
472        &self,
473        req: Req,
474        ctx: Ctx<'_, Self, St>,
475    ) -> impl Future<Output = Result<S::Res, S::Error>> {
476        Service::call(&**self, req, ctx.cast())
477    }
478
479    #[inline]
480    fn shutdown(&self, ctx: Ctx<'_, Self, St>) -> impl Future<Output = ()> {
481        Service::shutdown(&**self, ctx.cast())
482    }
483}
484
485impl<Sf, St, Req> ServiceFactory<St, Req> for Rc<Sf>
486where
487    Sf: ServiceFactory<St, Req>,
488{
489    type Res = Sf::Res;
490    type Error = Sf::Error;
491    type Service = Sf::Service;
492    type InitError = Sf::InitError;
493
494    async fn create(&self, st: &St) -> Result<Self::Service, Self::InitError> {
495        self.as_ref().create(st).await
496    }
497}
498
499/// A common interface for values that can call a service.
500pub trait ServiceCaller<Req, Res, Err> {
501    /// Waits for readiness, then calls the service.
502    async fn call_service(&self, req: Req) -> Result<Res, Err>;
503}
504
505/// Conversion into a [`Service`].
506#[diagnostic::on_unimplemented(
507    message = "`{Self}` cannot be converted into a `Service<{St}, {Req}>`",
508    label = "expected a service or an async function for `{Req}` requests",
509    note = "accepted values: a `Service<{St}, {Req}>`, `async |req: {Req}| -> Result<Res, Err>`, or `async |st: &{St}, req: {Req}| -> Result<Res, Err>`",
510    note = "async functions must return `Result`"
511)]
512pub trait IntoService<S, St, Req>
513where
514    S: Service<St, Req>,
515{
516    /// Converts this value into a service.
517    fn into_service(self) -> S;
518}
519
520/// Conversion into a [`ServiceFactory`].
521#[diagnostic::on_unimplemented(
522    message = "`{Self}` cannot be converted into a `ServiceFactory<{St}, {Req}>`",
523    label = "expected a service factory or an async function for `{Req}` requests",
524    note = "accepted values: a `ServiceFactory<{St}, {Req}>`, a `Clone` async function `async |req: {Req}| -> Result<Res, Err>` or `async |st: &{St}, req: {Req}| -> Result<Res, Err>`, or `async |st: &{St}| -> Result<impl Service, Err>`",
525    note = "a `Service` value is not a factory; wrap its construction with `fn_factory`"
526)]
527pub trait IntoServiceFactory<Sf, St, Req>
528where
529    Sf: ServiceFactory<St, Req>,
530{
531    /// Converts this value into a service factory.
532    fn into_factory(self) -> Sf;
533}
534
535impl<S, St, Req> IntoService<S, St, Req> for S
536where
537    S: Service<St, Req>,
538{
539    #[inline]
540    fn into_service(self) -> S {
541        self
542    }
543}
544
545impl<Sf, St, Req> IntoServiceFactory<Sf, St, Req> for Sf
546where
547    Sf: ServiceFactory<St, Req>,
548{
549    #[inline]
550    fn into_factory(self) -> Sf {
551        self
552    }
553}
554
555/// Combinator and helper types used by the public API.
556///
557/// Most services can be built through the crate-level functions and the
558/// [`Service`] and [`ServiceFactory`] methods without naming these types.
559/// This module exposes their concrete return types for type annotations,
560/// reusable wrappers, and custom composition.
561///
562/// - [`ServiceChain`] and [`ServiceChainFactory`] are builders returned by
563///   [`service()`] and [`factory()`].
564/// - [`dev::FnService`], [`dev::FnServiceSt`], and [`dev::FnFactory`] adapt
565///   functions into services and factories.
566/// - [`dev::AndThen`], [`dev::Then`], [`dev::Map`], and [`dev::MapErr`] compose
567///   or transform service results, with corresponding factory adapters.
568/// - [`dev::ApplyCtx`] provides state and inner-service calls to
569///   [`apply_fn`] middleware; [`dev::MapState`] substitutes the inner state.
570/// - [`dev::Ready`] and [`dev::ReadyFactory`] are the wrappers produced by
571///   [`ready()`] and [`ready_factory()`] for independent cached readiness.
572///
573/// # Framework guide
574///
575/// - [Service Pipelines](https://docs.ntex.rs/2-pipeline.html)
576/// - [Service State](https://docs.ntex.rs/3-state.html)
577#[doc(hidden)]
578pub mod __private {
579    pub use crate::readiness::Generation;
580    pub use crate::util::{join, map_output, ready_field, ready_join};
581}
582
583pub mod dev {
584    pub use crate::and_then::{AndThen, AndThenFactory};
585    pub use crate::apply::{Apply, ApplyCtx, ApplyFactory};
586    pub use crate::chain::{ServiceChain, ServiceChainFactory};
587    pub use crate::fn_ready::FnReadiness;
588    pub use crate::fn_service::{FnFactory, FnService, FnServiceSt, FnServiceStFactory};
589    pub use crate::fn_shutdown::FnShutdown;
590    pub use crate::inline::InlineFuture;
591    pub use crate::map::{Map, MapFactory};
592    pub use crate::map_err::{MapErr, MapErrFactory};
593    pub use crate::map_init_err::MapInitErr;
594    pub use crate::map_state::{MapState, MapStateFactory};
595    pub use crate::middleware::{ApplyMiddleware, FnMiddleware};
596    pub use crate::ready::{Ready, ReadyFactory};
597    pub use crate::then::{Then, ThenFactory};
598}
599
600#[cfg(test)]
601#[path = "../tests/unit/lib.rs"]
602mod tests;