[−][src]Trait gotham::router::builder::DefineSingleRoute

pub trait DefineSingleRoute {
    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::Output
    where
        NPE: PathExtractor<Body> + Send + Sync + 'static,
        Self: ReplacePathExtractor<NPE>,
        Self::Output: DefineSingleRoute;

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

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

    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>,
    { ... }
}

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

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);
})

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);
})

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);
})

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);
})

fn with_path_extractor<NPE>(self) -> Self::Output where
    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);
})

fn with_query_string_extractor<NQSE>(self) -> Self::Output where
    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);
})

fn add_route_matcher<NRM>(self, matcher: NRM) -> Self::Output where
    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);
})
Loading content...

Provided methods

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");
})

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");
})
Loading content...

Implementors

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, [src]

Loading content...