scrappy_service/
lib.rs

1#![deny(rust_2018_idioms, warnings)]
2#![allow(clippy::type_complexity)]
3
4use std::cell::RefCell;
5use std::future::Future;
6use std::rc::Rc;
7use std::sync::Arc;
8use std::task::{self, Context, Poll};
9
10mod and_then;
11mod and_then_apply_fn;
12mod apply;
13mod apply_cfg;
14pub mod boxed;
15mod cell;
16mod fn_service;
17mod map;
18mod map_config;
19mod map_err;
20mod map_init_err;
21mod pipeline;
22mod then;
23mod transform;
24mod transform_err;
25
26pub use self::apply::{apply_fn, apply_fn_factory};
27pub use self::apply_cfg::{apply_cfg, apply_cfg_factory};
28pub use self::fn_service::{fn_factory, fn_factory_with_config, fn_service};
29pub use self::map_config::{map_config, unit_config};
30pub use self::pipeline::{pipeline, pipeline_factory, Pipeline, PipelineFactory};
31pub use self::transform::{apply, Transform};
32
33/// An asynchronous function from `Request` to a `Response`.
34///
35/// `Service` represents a service that represanting interation, taking requests and giving back
36/// replies. You can think about service as a function with one argument and result as a return
37/// type. In general form it looks like `async fn(Req) -> Result<Res, Err>`. `Service`
38/// trait just generalizing form of this function. Each parameter described as an assotiated type.
39///
40/// Services provides a symmetric and uniform API, same abstractions represents
41/// clients and servers. Services describe only `transforamtion` operation
42/// which encorouge to simplify api surface and phrases `value transformation`.
43/// That leads to simplier design of each service. That also allows better testability
44/// and better composition.
45///
46/// Services could be represented in several different forms. In general,
47/// Service is a type that implements `Service` trait.
48///
49/// ```rust,ignore
50/// struct MyService;
51///
52/// impl Service for MyService {
53///      type Request = u8;
54///      type Response = u64;
55///      type Error = MyError;
56///      type Future = Pin<Box<Future<Output=Result<Self::Response, Self::Error>>>;
57///
58///      fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> { ... }
59///
60///      fn call(&mut self, req: Self::Request) -> Self::Future { ... }
61/// }
62/// ```
63///
64/// Service can have mutable state that influence computation.
65/// This service could be rewritten as a simple function:
66///
67/// ```rust,ignore
68/// async fn my_service(req: u8) -> Result<u64, MyError>;
69/// ```
70pub trait Service {
71    /// Requests handled by the service.
72    type Request;
73
74    /// Responses given by the service.
75    type Response;
76
77    /// Errors produced by the service.
78    type Error;
79
80    /// The future response value.
81    type Future: Future<Output = Result<Self::Response, Self::Error>>;
82
83    /// Returns `Ready` when the service is able to process requests.
84    ///
85    /// If the service is at capacity, then `Pending` is returned and the task
86    /// is notified when the service becomes ready again. This function is
87    /// expected to be called while on a task.
88    ///
89    /// This is a **best effort** implementation. False positives are permitted.
90    /// It is permitted for the service to return `Ready` from a `poll_ready`
91    /// call and the next invocation of `call` results in an error.
92    ///
93    /// There are several notes to consider:
94    ///
95    /// 1. `.poll_ready()` might be called on different task from actual service call.
96    ///
97    /// 2. In case of chained services, `.poll_ready()` get called for all services at once.
98    fn poll_ready(&mut self, ctx: &mut task::Context<'_>) -> Poll<Result<(), Self::Error>>;
99
100    /// Process the request and return the response asynchronously.
101    ///
102    /// This function is expected to be callable off task. As such,
103    /// implementations should take care to not call `poll_ready`. If the
104    /// service is at capacity and the request is unable to be handled, the
105    /// returned `Future` should resolve to an error.
106    ///
107    /// Calling `call` without calling `poll_ready` is permitted. The
108    /// implementation must be resilient to this fact.
109    fn call(&mut self, req: Self::Request) -> Self::Future;
110
111    /// Map this service's output to a different type, returning a new service
112    /// of the resulting type.
113    ///
114    /// This function is similar to the `Option::map` or `Iterator::map` where
115    /// it will change the type of the underlying service.
116    ///
117    /// Note that this function consumes the receiving service and returns a
118    /// wrapped version of it, similar to the existing `map` methods in the
119    /// standard library.
120    fn map<F, R>(self, f: F) -> crate::dev::Map<Self, F, R>
121    where
122        Self: Sized,
123        F: FnMut(Self::Response) -> R,
124    {
125        crate::dev::Map::new(self, f)
126    }
127
128    /// Map this service's error to a different error, returning a new service.
129    ///
130    /// This function is similar to the `Result::map_err` where it will change
131    /// the error type of the underlying service. This is useful for example to
132    /// ensure that services have the same error type.
133    ///
134    /// Note that this function consumes the receiving service and returns a
135    /// wrapped version of it.
136    fn map_err<F, E>(self, f: F) -> crate::dev::MapErr<Self, F, E>
137    where
138        Self: Sized,
139        F: Fn(Self::Error) -> E,
140    {
141        crate::dev::MapErr::new(self, f)
142    }
143}
144
145/// Creates new `Service` values.
146///
147/// Acts as a service factory. This is useful for cases where new `Service`
148/// values must be produced. One case is a TCP server listener. The listener
149/// accepts new TCP streams, obtains a new `Service` value using the
150/// `ServiceFactory` trait, and uses that new `Service` value to process inbound
151/// requests on that new TCP stream.
152///
153/// `Config` is a service factory configuration type.
154pub trait ServiceFactory {
155    /// Requests handled by the service.
156    type Request;
157
158    /// Responses given by the service
159    type Response;
160
161    /// Errors produced by the service
162    type Error;
163
164    /// Service factory configuration
165    type Config;
166
167    /// The `Service` value created by this factory
168    type Service: Service<
169        Request = Self::Request,
170        Response = Self::Response,
171        Error = Self::Error,
172    >;
173
174    /// Errors produced while building a service.
175    type InitError;
176
177    /// The future of the `Service` instance.
178    type Future: Future<Output = Result<Self::Service, Self::InitError>>;
179
180    /// Create and return a new service value asynchronously.
181    fn new_service(&self, cfg: Self::Config) -> Self::Future;
182
183    /// Map this service's output to a different type, returning a new service
184    /// of the resulting type.
185    fn map<F, R>(self, f: F) -> crate::map::MapServiceFactory<Self, F, R>
186    where
187        Self: Sized,
188        F: FnMut(Self::Response) -> R + Clone,
189    {
190        crate::map::MapServiceFactory::new(self, f)
191    }
192
193    /// Map this service's error to a different error, returning a new service.
194    fn map_err<F, E>(self, f: F) -> crate::map_err::MapErrServiceFactory<Self, F, E>
195    where
196        Self: Sized,
197        F: Fn(Self::Error) -> E + Clone,
198    {
199        crate::map_err::MapErrServiceFactory::new(self, f)
200    }
201
202    /// Map this factory's init error to a different error, returning a new service.
203    fn map_init_err<F, E>(self, f: F) -> crate::map_init_err::MapInitErr<Self, F, E>
204    where
205        Self: Sized,
206        F: Fn(Self::InitError) -> E + Clone,
207    {
208        crate::map_init_err::MapInitErr::new(self, f)
209    }
210}
211
212impl<'a, S> Service for &'a mut S
213where
214    S: Service + 'a,
215{
216    type Request = S::Request;
217    type Response = S::Response;
218    type Error = S::Error;
219    type Future = S::Future;
220
221    fn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
222        (**self).poll_ready(ctx)
223    }
224
225    fn call(&mut self, request: Self::Request) -> S::Future {
226        (**self).call(request)
227    }
228}
229
230impl<S> Service for Box<S>
231where
232    S: Service + ?Sized,
233{
234    type Request = S::Request;
235    type Response = S::Response;
236    type Error = S::Error;
237    type Future = S::Future;
238
239    fn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), S::Error>> {
240        (**self).poll_ready(ctx)
241    }
242
243    fn call(&mut self, request: Self::Request) -> S::Future {
244        (**self).call(request)
245    }
246}
247
248impl<S> Service for RefCell<S>
249where
250    S: Service,
251{
252    type Request = S::Request;
253    type Response = S::Response;
254    type Error = S::Error;
255    type Future = S::Future;
256
257    fn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
258        self.borrow_mut().poll_ready(ctx)
259    }
260
261    fn call(&mut self, request: Self::Request) -> S::Future {
262        self.borrow_mut().call(request)
263    }
264}
265
266impl<S> Service for Rc<RefCell<S>>
267where
268    S: Service,
269{
270    type Request = S::Request;
271    type Response = S::Response;
272    type Error = S::Error;
273    type Future = S::Future;
274
275    fn poll_ready(&mut self, ctx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
276        self.borrow_mut().poll_ready(ctx)
277    }
278
279    fn call(&mut self, request: Self::Request) -> S::Future {
280        (&mut (**self).borrow_mut()).call(request)
281    }
282}
283
284impl<S> ServiceFactory for Rc<S>
285where
286    S: ServiceFactory,
287{
288    type Request = S::Request;
289    type Response = S::Response;
290    type Error = S::Error;
291    type Config = S::Config;
292    type Service = S::Service;
293    type InitError = S::InitError;
294    type Future = S::Future;
295
296    fn new_service(&self, cfg: S::Config) -> S::Future {
297        self.as_ref().new_service(cfg)
298    }
299}
300
301impl<S> ServiceFactory for Arc<S>
302where
303    S: ServiceFactory,
304{
305    type Request = S::Request;
306    type Response = S::Response;
307    type Error = S::Error;
308    type Config = S::Config;
309    type Service = S::Service;
310    type InitError = S::InitError;
311    type Future = S::Future;
312
313    fn new_service(&self, cfg: S::Config) -> S::Future {
314        self.as_ref().new_service(cfg)
315    }
316}
317
318/// Trait for types that can be converted to a `Service`
319pub trait IntoService<T>
320where
321    T: Service,
322{
323    /// Convert to a `Service`
324    fn into_service(self) -> T;
325}
326
327/// Trait for types that can be converted to a `ServiceFactory`
328pub trait IntoServiceFactory<T>
329where
330    T: ServiceFactory,
331{
332    /// Convert `Self` to a `ServiceFactory`
333    fn into_factory(self) -> T;
334}
335
336impl<T> IntoService<T> for T
337where
338    T: Service,
339{
340    fn into_service(self) -> T {
341        self
342    }
343}
344
345impl<T> IntoServiceFactory<T> for T
346where
347    T: ServiceFactory,
348{
349    fn into_factory(self) -> T {
350        self
351    }
352}
353
354/// Convert object of type `T` to a service `S`
355pub fn into_service<T, S>(tp: T) -> S
356where
357    S: Service,
358    T: IntoService<S>,
359{
360    tp.into_service()
361}
362
363pub mod dev {
364    pub use crate::apply::{Apply, ApplyServiceFactory};
365    pub use crate::fn_service::{
366        FnService, FnServiceConfig, FnServiceFactory, FnServiceNoConfig,
367    };
368    pub use crate::map::{Map, MapServiceFactory};
369    pub use crate::map_config::{MapConfig, UnitConfig};
370    pub use crate::map_err::{MapErr, MapErrServiceFactory};
371    pub use crate::map_init_err::MapInitErr;
372    pub use crate::transform::ApplyTransform;
373    pub use crate::transform_err::TransformMapInitErr;
374}
scrappy_service/lib.rs

scrappy_service/
lib.rs
