Struct xitca_web::App

pub struct App<R = (), CF = ()> { /* private fields */ }

composed application type with router, stateful context and default middlewares.

Implementations

impl App

pub fn new<Obj>() -> App<AppRouter<Obj>>

Construct a new application instance.

impl<Obj, CF> App<AppRouter<Obj>, CF>

pub fn at<F, C, B>(self, path: &'static str, builder: F) -> Self

where F: RouterGen + Service + Send + Sync, F::Response: for<'r> Service<WebContext<'r, C, B>>, for<'r> WebContext<'r, C, B>: IntoObject<F::Route<F>, (), Object = Obj>,

insert routed service with given path to application.

pub fn at_typed<T, C>(self, typed: T) -> Self

where T: TypedRoute<C, Route = Obj>,

insert typed route service with given path to application.

impl<R, CF> App<R, CF>

pub fn with_state<C>( self, state: C ) -> App<R, Box<dyn Fn() -> Pin<Box<dyn Future<Output = Result<C, Box<dyn Debug>>>>> + Send + Sync>>

where C: Send + Sync + Clone + 'static,

Construct App with a thread safe state that will be shared among all tasks and worker threads.

State accessing is based on generic type approach where the State type and it’s typed fields are generally opaque to middleware and routing services of the application. In order to cast concrete type from generic state type std::borrow::Borrow trait is utilized. See example below for explanation.

Example

// our typed state.
#[derive(Clone, Default)]
struct State {
    string: String,
    usize: usize
}

// implement Borrow trait to enable borrowing &String type from State.
impl Borrow<String> for State {
    fn borrow(&self) -> &String {
        &self.string
    }
}

App::new()
    .with_state(State::default())// construct app with state type.
    .at("/", handler_service(index)) // a function service that have access to state.
    .enclosed_fn(middleware_fn); // a function middleware that have access to state

// the function service don't know what the real type of application state is.
// it only needs to know &String can be borrowed from it.
async fn index(_: StateRef<'_, String>) -> &'static str {
    ""
}

// similar to function service. the middleware does not need to know the real type of C.
// it only needs to know it implement according trait.
async fn middleware_fn<S, C, Res>(service: &S, ctx: WebContext<'_, C>) -> Result<Res, Error<C>>
where
    S: for<'r> Service<WebContext<'r, C>, Response = Res, Error = Error<C>>,
    C: Borrow<String> // annotate we want to borrow &String from generic C state type.
{
    // WebContext::state would return &C then we can call Borrow::borrow on it to get &String
    let _string = ctx.state().borrow();
    // or use extractor manually like in function service.
    let _string = StateRef::<'_, String>::from_request(&ctx).await?;
    service.call(ctx).await
}

pub fn with_async_state<CF1, Fut, C, E>( self, builder: CF1 ) -> App<R, Box<dyn Fn() -> Pin<Box<dyn Future<Output = Result<C, Box<dyn Debug>>>>> + Send + Sync>>

where CF1: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<C, E>> + 'static, E: Debug + 'static,

Construct App with async closure which it’s output would be used as state. async state is used to produce thread per core and/or non thread safe state copies. The output state is not bound to Send and Sync auto traits.

impl<R, CF> App<R, CF>

where R: Service + Send + Sync, R::Error: Debug + 'static,

pub fn enclosed<T>(self, transform: T) -> App<EnclosedBuilder<R, T>, CF>

where T: Service<Result<R::Response, R::Error>>,

Enclose App with middleware type. Middleware must impl Service trait.

pub fn enclosed_fn<Req, T>( self, transform: T ) -> App<EnclosedFnBuilder<R, T>, CF>

where T: for<'s> AsyncClosure<(&'s R::Response, Req)> + Clone,

Enclose App with function as middleware type.

pub fn map<T, Res, ResMap>(self, mapper: T) -> App<MapBuilder<R, T>, CF>

where T: Fn(Res) -> ResMap + Clone, Self: Sized,

Mutate <<Self::Response as Service<Req>>::Future as Future>::Output type with given closure.

impl<R, CF> App<R, CF>

where R: Service + Send + Sync, R::Error: Debug + 'static,

pub fn finish<C, ResB, SE>( self ) -> impl Service<Response = impl ReadyService + Service<WebRequest, Response = WebResponse<Either<ResB, ResponseBody>>, Error = Infallible>, Error = impl Debug>

where R::Response: ReadyService + for<'r> Service<WebContext<'r, C>, Response = WebResponse<ResB>, Error = SE>, SE: for<'r> Service<WebContext<'r, C>, Response = WebResponse, Error = Infallible>, CF: IntoCtx<C>, C: 'static,

Finish App build. No other App method can be called afterwards.

pub fn finish_boxed<C, ResB, SE, BE>( self ) -> AppObject<impl ReadyService + Service<WebRequest, Response = WebResponse, Error = Infallible>>

where R: 'static, R::Response: ReadyService + for<'r> Service<WebContext<'r, C>, Response = WebResponse<ResB>, Error = SE> + 'static, SE: for<'r> Service<WebContext<'r, C>, Response = WebResponse, Error = Infallible> + 'static, ResB: Stream<Item = Result<Bytes, BE>> + 'static, BE: Error + Send + Sync + 'static, CF: IntoCtx<C> + 'static, C: 'static,

Finish App build. No other App method can be called afterwards.

pub fn serve<C, ResB, SE>( self ) -> HttpServer<impl Service<Response = impl ReadyService + Service<WebRequest, Response = WebResponse<Either<ResB, ResponseBody>>, Error = Infallible>, Error = impl Debug>>

where R: 'static, R::Response: ReadyService + for<'r> Service<WebContext<'r, C>, Response = WebResponse<ResB>, Error = SE>, SE: for<'r> Service<WebContext<'r, C>, Response = WebResponse, Error = Infallible> + 'static, ResB: 'static, CF: IntoCtx<C> + 'static, C: 'static,

Finish App build and serve is with HttpServer. No other App method can be called afterwards.

Trait Implementations

impl<R, F> RouterGen for App<R, F>

where R: RouterGen,

type Route<R1> = <R as RouterGen>::Route<R1>

service builder type for generating the final route service.

fn path_gen(&mut self, prefix: &'static str) -> Cow<'static, str>

path generator.

fn route_gen<R1>(route: R1) -> Self::Route<R1>

route service generator.

impl<R, Arg, F> Service<Arg> for App<R, F>

where R: Service<Arg>,

type Response = <R as Service<Arg>>::Response

The Ok part of output future.

type Error = <R as Service<Arg>>::Error

The Err part of output future.

async fn call(&self, req: Arg) -> Result<Self::Response, Self::Error>