actix_service/
lib.rs

1//! See [`Service`] docs for information on this crate's foundational trait.
2
3#![no_std]
4#![allow(clippy::type_complexity)]
5#![doc(html_logo_url = "https://actix.rs/img/logo.png")]
6#![doc(html_favicon_url = "https://actix.rs/favicon.ico")]
7
8extern crate alloc;
9
10use alloc::{boxed::Box, rc::Rc, sync::Arc};
11use core::{
12    cell::RefCell,
13    future::Future,
14    task::{self, Context, Poll},
15};
16
17mod and_then;
18mod apply;
19mod apply_cfg;
20pub mod boxed;
21mod ext;
22mod fn_service;
23mod macros;
24mod map;
25mod map_config;
26mod map_err;
27mod map_init_err;
28mod pipeline;
29mod ready;
30mod then;
31mod transform;
32mod transform_err;
33
34#[allow(unused_imports)]
35use self::ready::{err, ok, ready, Ready};
36pub use self::{
37    apply::{apply_fn, apply_fn_factory},
38    apply_cfg::{apply_cfg, apply_cfg_factory},
39    ext::{ServiceExt, ServiceFactoryExt, TransformExt},
40    fn_service::{fn_factory, fn_factory_with_config, fn_service},
41    map_config::{map_config, unit_config},
42    transform::{apply, ApplyTransform, Transform},
43};
44
45/// An asynchronous operation from `Request` to a `Response`.
46///
47/// The `Service` trait models a request/response interaction, receiving requests and returning
48/// replies. You can think about a service as a function with one argument that returns some result
49/// asynchronously. Conceptually, the operation looks like this:
50///
51/// ```ignore
52/// async fn(Request) -> Result<Response, Err>
53/// ```
54///
55/// The `Service` trait just generalizes this form. Requests are defined as a generic type parameter
56/// and responses and other details are defined as associated types on the trait impl. Notice that
57/// this design means that services can receive many request types and converge them to a single
58/// response type.
59///
60/// Services can also have mutable state that influence computation by using a `Cell`, `RefCell`
61/// or `Mutex`. Services intentionally do not take `&mut self` to reduce overhead in the
62/// common cases.
63///
64/// `Service` provides a symmetric and uniform API; the same abstractions can be used to represent
65/// both clients and servers. Services describe only _transformation_ operations which encourage
66/// simple API surfaces. This leads to simpler design of each service, improves test-ability and
67/// makes composition easier.
68///
69/// ```ignore
70/// struct MyService;
71///
72/// impl Service<u8> for MyService {
73///      type Response = u64;
74///      type Error = MyError;
75///      type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>>>>;
76///
77///      fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
78///
79///      fn call(&self, req: u8) -> Self::Future { ... }
80/// }
81/// ```
82///
83/// Sometimes it is not necessary to implement the Service trait. For example, the above service
84/// could be rewritten as a simple function and passed to [`fn_service`](fn_service()).
85///
86/// ```ignore
87/// async fn my_service(req: u8) -> Result<u64, MyError>;
88///
89/// let svc = fn_service(my_service)
90/// svc.call(123)
91/// ```
92pub trait Service<Req> {
93    /// Responses given by the service.
94    type Response;
95
96    /// Errors produced by the service when polling readiness or executing call.
97    type Error;
98
99    /// The future response value.
100    type Future: Future<Output = Result<Self::Response, Self::Error>>;
101
102    /// Returns `Ready` when the service is able to process requests.
103    ///
104    /// If the service is at capacity, then `Pending` is returned and the task is notified when the
105    /// service becomes ready again. This function is expected to be called while on a task.
106    ///
107    /// This is a best effort implementation. False positives are permitted. It is permitted for
108    /// the service to return `Ready` from a `poll_ready` call and the next invocation of `call`
109    /// results in an error.
110    ///
111    /// # Notes
112    /// 1. `poll_ready` might be called on a different task to `call`.
113    /// 1. In cases of chained services, `.poll_ready()` is called for all services at once.
114    fn poll_ready(&self, ctx: &mut task::Context<'_>) -> Poll<Result<(), Self::Error>>;
115
116    /// Process the request and return the response asynchronously.
117    ///
118    /// This function is expected to be callable off-task. As such, implementations of `call` should
119    /// take care to not call `poll_ready`. If the service is at capacity and the request is unable
120    /// to be handled, the returned `Future` should resolve to an error.
121    ///
122    /// Invoking `call` without first invoking `poll_ready` is permitted. Implementations must be
123    /// resilient to this fact.
124    fn call(&self, req: Req) -> Self::Future;
125}
126
127/// Factory for creating `Service`s.
128///
129/// This is useful for cases where new `Service`s must be produced. One case is a TCP
130/// server listener: a listener accepts new connections, constructs a new `Service` for each using
131/// the `ServiceFactory` trait, and uses the new `Service` to process inbound requests on that new
132/// connection.
133///
134/// `Config` is a service factory configuration type.
135///
136/// Simple factories may be able to use [`fn_factory`] or [`fn_factory_with_config`] to
137/// reduce boilerplate.
138pub trait ServiceFactory<Req> {
139    /// Responses given by the created services.
140    type Response;
141
142    /// Errors produced by the created services.
143    type Error;
144
145    /// Service factory configuration.
146    type Config;
147
148    /// The kind of `Service` created by this factory.
149    type Service: Service<Req, Response = Self::Response, Error = Self::Error>;
150
151    /// Errors potentially raised while building a service.
152    type InitError;
153
154    /// The future of the `Service` instance.g
155    type Future: Future<Output = Result<Self::Service, Self::InitError>>;
156
157    /// Create and return a new service asynchronously.
158    fn new_service(&self, cfg: Self::Config) -> Self::Future;
159}
160
161// TODO: remove implement on mut reference.
162impl<'a, S, Req> Service<Req> for &'a mut S
163where
164    S: Service<Req> + 'a,
165{
166    type Response = S::Response;
167    type Error = S::Error;
168    type Future = S::Future;
169
170    fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
171        (**self).poll_ready(ctx)
172    }
173
174    fn call(&self, request: Req) -> S::Future {
175        (**self).call(request)
176    }
177}
178
179impl<'a, S, Req> Service<Req> for &'a S
180where
181    S: Service<Req> + 'a,
182{
183    type Response = S::Response;
184    type Error = S::Error;
185    type Future = S::Future;
186
187    fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
188        (**self).poll_ready(ctx)
189    }
190
191    fn call(&self, request: Req) -> S::Future {
192        (**self).call(request)
193    }
194}
195
196impl<S, Req> Service<Req> for Box<S>
197where
198    S: Service<Req> + ?Sized,
199{
200    type Response = S::Response;
201    type Error = S::Error;
202    type Future = S::Future;
203
204    fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
205        (**self).poll_ready(ctx)
206    }
207
208    fn call(&self, request: Req) -> S::Future {
209        (**self).call(request)
210    }
211}
212
213impl<S, Req> Service<Req> for Rc<S>
214where
215    S: Service<Req> + ?Sized,
216{
217    type Response = S::Response;
218    type Error = S::Error;
219    type Future = S::Future;
220
221    fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
222        (**self).poll_ready(ctx)
223    }
224
225    fn call(&self, request: Req) -> S::Future {
226        (**self).call(request)
227    }
228}
229
230/// This impl is deprecated since v2 because the `Service` trait now receives shared reference.
231impl<S, Req> Service<Req> for RefCell<S>
232where
233    S: Service<Req>,
234{
235    type Response = S::Response;
236    type Error = S::Error;
237    type Future = S::Future;
238
239    fn poll_ready(&self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
240        self.borrow().poll_ready(ctx)
241    }
242
243    fn call(&self, request: Req) -> S::Future {
244        self.borrow().call(request)
245    }
246}
247
248impl<S, Req> ServiceFactory<Req> for Rc<S>
249where
250    S: ServiceFactory<Req>,
251{
252    type Response = S::Response;
253    type Error = S::Error;
254    type Config = S::Config;
255    type Service = S::Service;
256    type InitError = S::InitError;
257    type Future = S::Future;
258
259    fn new_service(&self, cfg: S::Config) -> S::Future {
260        self.as_ref().new_service(cfg)
261    }
262}
263
264impl<S, Req> ServiceFactory<Req> for Arc<S>
265where
266    S: ServiceFactory<Req>,
267{
268    type Response = S::Response;
269    type Error = S::Error;
270    type Config = S::Config;
271    type Service = S::Service;
272    type InitError = S::InitError;
273    type Future = S::Future;
274
275    fn new_service(&self, cfg: S::Config) -> S::Future {
276        self.as_ref().new_service(cfg)
277    }
278}
279
280/// Trait for types that can be converted to a `Service`
281pub trait IntoService<S, Req>
282where
283    S: Service<Req>,
284{
285    /// Convert to a `Service`
286    fn into_service(self) -> S;
287}
288
289/// Trait for types that can be converted to a `ServiceFactory`
290pub trait IntoServiceFactory<SF, Req>
291where
292    SF: ServiceFactory<Req>,
293{
294    /// Convert `Self` to a `ServiceFactory`
295    fn into_factory(self) -> SF;
296}
297
298impl<S, Req> IntoService<S, Req> for S
299where
300    S: Service<Req>,
301{
302    fn into_service(self) -> S {
303        self
304    }
305}
306
307impl<SF, Req> IntoServiceFactory<SF, Req> for SF
308where
309    SF: ServiceFactory<Req>,
310{
311    fn into_factory(self) -> SF {
312        self
313    }
314}
315
316/// Convert object of type `U` to a service `S`
317pub fn into_service<I, S, Req>(tp: I) -> S
318where
319    I: IntoService<S, Req>,
320    S: Service<Req>,
321{
322    tp.into_service()
323}
actix_service/lib.rs

actix_service/
lib.rs
