Trait gotham::router::builder::DefineSingleRoute

source · [−]
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 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;

    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

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

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

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

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

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

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

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

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

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