Trait gotham::router::builder::DefineSingleRoute

source · 
pub trait DefineSingleRoute {
    // Required methods
    fn to<H>(self, handler: H)
       where H: Handler + RefUnwindSafe + Copy + Send + Sync + 'static;
    fn to_async<H, Fut>(self, handler: H)
       where Self: Sized,
             H: FnOnce(State) -> Fut + RefUnwindSafe + Copy + Send + Sync + 'static,
             Fut: Future<Output = HandlerResult> + Send + 'static;
    fn to_async_borrowing<F>(self, handler: F)
       where Self: Sized,
             F: HandlerMarker + Copy + Send + Sync + RefUnwindSafe + 'static;
    fn to_new_handler<NH>(self, new_handler: NH)
       where NH: NewHandler + 'static;
    fn with_path_extractor<NPE>(
        self
    ) -> <Self as ReplacePathExtractor<NPE>>::Output
       where NPE: PathExtractor<Body> + Send + Sync + 'static,
             Self: ReplacePathExtractor<NPE>,
             Self::Output: DefineSingleRoute;
    fn with_query_string_extractor<NQSE>(
        self
    ) -> <Self as ReplaceQueryStringExtractor<NQSE>>::Output
       where NQSE: QueryStringExtractor<Body> + Send + Sync + 'static,
             Self: ReplaceQueryStringExtractor<NQSE>,
             Self::Output: DefineSingleRoute;
    fn add_route_matcher<NRM>(
        self,
        matcher: NRM
    ) -> <Self as ExtendRouteMatcher<NRM>>::Output
       where NRM: RouteMatcher + Send + Sync + 'static,
             Self: ExtendRouteMatcher<NRM>,
             Self::Output: DefineSingleRoute;

    // Provided methods
    fn to_dir<P>(self, options: P)
       where Self: ReplacePathExtractor<FilePathExtractor> + Sized,
             Self::Output: DefineSingleRoute,
             FileOptions: From<P> { ... }
    fn to_file<P>(self, options: P)
       where Self: Sized,
             FileOptions: From<P> { ... }
}
Expand description

Describes the API for defining a single route, after determining which request paths will be dispatched here. The API here uses chained function calls to build and add the route into the RouterBuilder which created it.

Examples

fn my_handler(state: State) -> (State, Response<Body>) {
    // Handler implementation elided.
}
build_router(chain, pipelines, |route| {
    route.get("/request/path") // <- This value implements `DefineSingleRoute`
         .to(my_handler);
})

Required Methods§

source

fn to<H>(self, handler: H)where H: Handler + RefUnwindSafe + Copy + Send + Sync + 'static,

Directs the route to the given Handler, automatically creating a NewHandler which copies the Handler. This is the easiest option for code which is using bare functions as Handler functions.

Examples
fn my_handler(state: State) -> (State, Response<Body>) {
    // Handler implementation elided.
}

build_router(chain, pipelines, |route| {
    route.get("/request/path").to(my_handler);
})
source

fn to_async<H, Fut>(self, handler: H)where Self: Sized, H: FnOnce(State) -> Fut + RefUnwindSafe + Copy + Send + Sync + 'static, Fut: Future<Output = HandlerResult> + Send + 'static,

Similar to to, but accepts an async fn

Examples
async fn my_handler(state: State) -> HandlerResult {
    // Handler implementation elided.
}

build_router(chain, pipelines, |route| {
    route.get("/request/path").to_async(my_handler);
})
source

fn to_async_borrowing<F>(self, handler: F)where Self: Sized, F: HandlerMarker + Copy + Send + Sync + RefUnwindSafe + 'static,

Directs the route to the given async fn, passing State to it by mutable reference.

Note that, as of Rust 1.46.0, this does not work for closures due to rust-lang/rust#70263.

On the other hand, one can easily use the ? operator for error handling in these async functions.

Examples
async fn my_handler(_state: &mut State) -> Result<impl IntoResponse, HandlerError> {
    let flavors =
        std::fs::read("coffee-flavors.txt").map_err_with_status(StatusCode::IM_A_TEAPOT)?;
    Ok(flavors)
}

build_router(chain, pipelines, |route| {
    route.get("/request/path").to_async_borrowing(my_handler);
})
source

fn to_new_handler<NH>(self, new_handler: NH)where NH: NewHandler + 'static,

Directs the route to the given NewHandler. This gives more control over how Handler values are constructed.

Examples
struct MyNewHandler;
struct MyHandler;

impl NewHandler for MyNewHandler {
    type Instance = MyHandler;

    fn new_handler(&self) -> anyhow::Result<Self::Instance> {
        Ok(MyHandler)
    }
}

impl Handler for MyHandler {
    fn handle(self, state: State) -> Pin<Box<HandlerFuture>> {
        // Handler implementation elided.
    }
}

build_router(chain, pipelines, |route| {
    route.get("/request/path").to_new_handler(MyNewHandler);
})
source

fn with_path_extractor<NPE>(self) -> <Self as ReplacePathExtractor<NPE>>::Outputwhere NPE: PathExtractor<Body> + Send + Sync + 'static, Self: ReplacePathExtractor<NPE>, Self::Output: DefineSingleRoute,

Applies a PathExtractor type to the current route, to extract path parameters into State with the given type.

Examples
#[derive(Deserialize, StateData, StaticResponseExtender)]
struct MyPathParams {
    name: String,
}

fn my_handler(state: State) -> (State, Response<Body>) {
    let params = MyPathParams::borrow_from(&state);

    // Handler implementation elided.
}

build_router(default_pipeline_chain, pipelines, |route| {
    route.get("/hello/:name")
         .with_path_extractor::<MyPathParams>()
         .to(my_handler);
})
source

fn with_query_string_extractor<NQSE>( self ) -> <Self as ReplaceQueryStringExtractor<NQSE>>::Outputwhere NQSE: QueryStringExtractor<Body> + Send + Sync + 'static, Self: ReplaceQueryStringExtractor<NQSE>, Self::Output: DefineSingleRoute,

Applies a QueryStringExtractor type to the current route, to extract query parameters into State with the given type.

Examples
#[derive(StateData, Deserialize, StaticResponseExtender)]
struct MyQueryParams {
    id: u64,
}

fn my_handler(state: State) -> (State, Response<Body>) {
    let id = MyQueryParams::borrow_from(&state).id;

    // Handler implementation elided.
}

build_router(default_pipeline_chain, pipelines, |route| {
    route.get("/request/path")
         .with_query_string_extractor::<MyQueryParams>()
         .to(my_handler);
})
source

fn add_route_matcher<NRM>( self, matcher: NRM ) -> <Self as ExtendRouteMatcher<NRM>>::Outputwhere NRM: RouteMatcher + Send + Sync + 'static, Self: ExtendRouteMatcher<NRM>, Self::Output: DefineSingleRoute,

Adds additional RouteMatcher requirements to the current route.

build_simple_router(|route| {
    let matcher = AcceptHeaderRouteMatcher::new(vec![mime::APPLICATION_JSON]);
    route.get("/request/path")
         .add_route_matcher(matcher)
         .to(my_handler);
})

Provided Methods§

source

fn to_dir<P>(self, options: P)where Self: ReplacePathExtractor<FilePathExtractor> + Sized, Self::Output: DefineSingleRoute, FileOptions: From<P>,

Directs the route to serve static files from the given root directory. The route must contain a trailing glob segment, which will be used to serve any matching names under the given path.

Examples

build_router(chain, pipelines, |route| {
    route.get("/*").to_dir("resources/test/assets");
})
source

fn to_file<P>(self, options: P)where Self: Sized, FileOptions: From<P>,

Directs the route to serve a single static file from the given path.

Examples

build_router(chain, pipelines, |route| {
    route.get("/").to_file("resources/test/assets/doc.html");
})

Implementors§

source§

impl<'a, M, C, P, PE, QSE> DefineSingleRoute for SingleRouteBuilder<'a, M, C, P, PE, QSE>where M: RouteMatcher + Send + Sync + 'static, C: PipelineHandleChain<P> + Send + Sync + 'static, P: RefUnwindSafe + Send + Sync + 'static, PE: PathExtractor<Body> + Send + Sync + 'static, QSE: QueryStringExtractor<Body> + Send + Sync + 'static,