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;