Skip to main content

ServiceChain

Struct ServiceChain 

Source
pub struct ServiceChain<S, St, Req> { /* private fields */ }
Expand description

A builder for composing services and combinators into one service.

Created by service() and service combinators. Each builder method consumes the chain and returns a new chain containing the added adapter. Use Self::and_then to process successful responses, Self::then to handle the complete result, or Self::apply_fn to wrap a call with asynchronous middleware.

The chain implements Service when its enclosed composition does. It owns the enclosed service but does not store pipeline state; supply state through Service::pipeline.

Binding, calls, readiness, and shutdown are forwarded to the enclosed service. The builder adds no independent readiness cache. Raw children share the enclosing readiness scope; use crate::ready() around a child that needs its own cache and call-time readiness check.

Cloning clones the enclosed service. Shared state and readiness depend on that service’s clone implementation.

See the framework guide’s Service Pipelines chapter for composition and readiness semantics.

Implementations§

Source§

impl<S, St, Req> ServiceChain<S, St, Req>
where S: Service<St, Req>,

Source

pub fn and_then<Next, F>( self, service: F, ) -> ServiceChain<AndThen<S, Next>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: IntoService<Next, St, <S as Service<St, Req>>::Res>, Next: Service<St, <S as Service<St, Req>>::Res>,

Calls another service after this service completes successfully.

The current service’s response becomes the next service’s request. If the current service returns an error, the next service is not called. Otherwise, the next service’s result becomes the chain’s result.

Both services must use the same state and error types for the resulting chain to implement Service. Binding, readiness, and shutdown cover both children. See AndThen for readiness behavior between calls.

Source

pub fn then<Next, F>(self, service: F) -> ServiceChain<Then<S, Next>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: IntoService<Next, St, Result<<S as Service<St, Req>>::Res, <S as Service<St, Req>>::Error>>, Next: Service<St, Result<<S as Service<St, Req>>::Res, <S as Service<St, Req>>::Error>>,

Calls another service after this service completes.

The next service receives the current service’s complete Result, so it can handle either a response or an error.

Both services must use the same state and error types for the resulting chain to implement Service. The next service determines the final response or error. Errors from the chain’s readiness check are returned directly, not passed to the next service as a request.

See Then for an error-recovery example and lifecycle behavior.

Source

pub fn map<F, Res>(self, f: F) -> ServiceChain<Map<F, S, Res>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: Fn(<S as Service<St, Req>>::Res) -> Res,

Maps this service’s response to a different type.

Like Result::map, this invokes the synchronous function only for successful responses. Errors, requests, state, and lifecycle behavior are unchanged. Use Self::and_then for asynchronous processing.

Source

pub fn map_err<F, Err>(self, f: F) -> ServiceChain<MapErr<F, S, Err>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: Fn(<S as Service<St, Req>>::Error) -> Err,

Maps this service’s error to a different type.

The synchronous function transforms errors from both calls and readiness checks, making this useful for normalizing error types before composing services. Successful responses, requests, and state are unchanged. Binding and shutdown are forwarded without modification.

Source

pub fn readiness<F>( self, ready: F, ) -> ServiceChain<AndThen<S, FnReadiness<F, <S as Service<St, Req>>::Error>>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: AsyncFn(&St) -> Result<(), <S as Service<St, Req>>::Error>,

Adds a custom readiness check to the service chain.

The callback and the wrapped service’s readiness futures are polled together; the callback does not wait for the service to become ready. The chain is ready only when both succeed. Requests and responses pass through unchanged.

The callback must implement Clone for the resulting chain to implement Service. A successful check can be cached by the enclosing pipeline, so this is not a per-request callback.

The callback receives only pipeline state. For scoped readiness and change notifications, implement Service directly.

Source

pub fn shutdown<F>( self, sh: F, ) -> ServiceChain<AndThen<S, FnShutdown<F, <S as Service<St, Req>>::Error>>, St, Req>
where ServiceChain<S, St, Req>: Sized, F: AsyncFnOnce(&St),

Adds a callback invoked at most once when the service shuts down.

The callback receives pipeline state and is polled alongside the wrapped service’s shutdown future, not after it completes. Shutdown waits for both. Requests and responses are unchanged.

The callback is consumed when first polled; cancellation does not make it available for a later shutdown attempt. Dropping the chain alone does not invoke it.

Source

pub fn apply_fn<F, In, Out, Err>( self, f: F, ) -> ServiceChain<Apply<S, St, Req, F, In, Out, Err>, St, In>
where F: AsyncFn(In, &ApplyCtx<'_, S, St, Req>) -> Result<Out, Err>, Err: From<<S as Service<St, Req>>::Error>,

Applies an asynchronous function as middleware to this service.

This is shorthand for calling crate::apply_fn on the chained service. The function receives an input request and an ApplyCtx for state access and inner calls. It may change request, response, and error types, or decide not to call the inner service.

State is unchanged. Inner readiness errors are converted with From; errors from ApplyCtx::call retain their inner type. See crate::apply_fn for call-time readiness behavior.

Trait Implementations§

Source§

impl<S, St, Req> Clone for ServiceChain<S, St, Req>
where S: Service<St, Req> + Clone,

Source§

fn clone(&self) -> ServiceChain<S, St, Req>

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<S, St, Req> Debug for ServiceChain<S, St, Req>
where S: Service<St, Req> + Debug,

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl<S, St, Req> Service<St, Req> for ServiceChain<S, St, Req>
where S: Service<St, Req>,

Source§

type Res = <S as Service<St, Req>>::Res

Response produced by the service.
Source§

type Error = <S as Service<St, Req>>::Error

Error produced while checking readiness or processing a request.
Source§

fn bind(&self, ctx: BindCtx<'_>)

Initializes the service within a Pipeline. Read more
Source§

async fn call( &self, req: Req, ctx: Ctx<'_, ServiceChain<S, St, Req>, St>, ) -> Result<<ServiceChain<S, St, Req> as Service<St, Req>>::Res, <ServiceChain<S, St, Req> as Service<St, Req>>::Error>

Processes a request and asynchronously returns the response. Read more
Source§

async fn ready( &self, ctx: Ctx<'_, ServiceChain<S, St, Req>, St>, ) -> Result<(), <ServiceChain<S, St, Req> as Service<St, Req>>::Error>

Waits until the service is ready to process a request. Read more
Source§

async fn shutdown(&self, ctx: Ctx<'_, ServiceChain<S, St, Req>, St>)

Shuts down the service. Read more
Source§

fn map<F, Res>(self, f: F) -> ServiceChain<Map<F, Self, Res>, St, Req>
where Self: Sized, F: Fn(Self::Res) -> Res,

Maps this service’s output to a different type, returning a new service. Read more
Source§

fn map_err<F, E>(self, f: F) -> ServiceChain<MapErr<F, Self, E>, St, Req>
where Self: Sized, F: Fn(Self::Error) -> E,

Maps this service’s error to a different type, returning a new service. Read more
Source§

fn and_then<Next, F>(self, f: F) -> ServiceChain<AndThen<Self, Next>, St, Req>
where Self: Sized, Next: Service<St, Self::Res, Error = Self::Error>, F: IntoService<Next, St, Self::Res>,

Calls another service after this service completes successfully. Read more
Source§

fn pipeline(self, st: St) -> Pipeline<Req, Self::Res, Self::Error>
where Self: Sized + 'static, St: 'static, Req: 'static,

Wraps this service and its state in a Pipeline.

Auto Trait Implementations§

§

impl<S, St, Req> Freeze for ServiceChain<S, St, Req>

§

impl<S, St, Req> RefUnwindSafe for ServiceChain<S, St, Req>

§

impl<S, St, Req> Send for ServiceChain<S, St, Req>

§

impl<S, St, Req> Sync for ServiceChain<S, St, Req>

§

impl<S, St, Req> Unpin for ServiceChain<S, St, Req>

§

impl<S, St, Req> UnsafeUnpin for ServiceChain<S, St, Req>

§

impl<S, St, Req> UnwindSafe for ServiceChain<S, St, Req>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<S, St, Req> IntoService<S, St, Req> for S
where S: Service<St, Req>,

Source§

fn into_service(self) -> S

Converts this value into a service.
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.