OpenSource/axum
OpenSource/axum
1
0
Fork 0
mirror of https://github.com/tokio-rs/axum.git synced 2024-11-22 15:17:18 +01:00
Code Issues Projects Releases Packages Wiki Activity

Write some more docs

Browse source
This commit is contained in:
David Pedersen 2021-06-07 15:45:19 +02:00
parent 21c96e0aa1
commit d8b0153939
7 changed files with 358 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
examples/static_file_server.rs
View file

@ -11,12 +11,12 @@ async fn main() {
let app = tower_web::routing::nest(
"/static",
ServeDir::new(".").handle_error(|error: std::io::Error| {
tower_web::service::get(ServeDir::new(".").handle_error(|error: std::io::Error| {
(
StatusCode::INTERNAL_SERVER_ERROR,
format!("Unhandled interal error: {}", error),
)
}),
})),
)
.layer(TraceLayer::new_for_http());

2
src/body.rs
View file

@ -1,3 +1,5 @@
//! HTTP body utilities.
use bytes::Bytes;
use http_body::{Empty, Full};
use std::{

247
src/handler.rs
View file

@ -11,12 +11,26 @@ use futures_util::future;
use http::{Request, Response};
use std::{
convert::Infallible,
fmt,
future::Future,
marker::PhantomData,
task::{Context, Poll},
};
use tower::{BoxError, Layer, Service, ServiceExt};
/// Route requests to the given handler regardless of the HTTP method of the
/// request.
///
/// # Example
///
/// ```rust
/// use tower_web::prelude::*;
///
/// async fn handler(request: Request<Body>) {}
///
/// // All requests to `/` will go to `handler` regardless of the HTTP method.
/// let app = route("/", any(handler));
/// ```
pub fn any<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -24,6 +38,9 @@ where
on(MethodFilter::Any, handler)
}
/// Route `CONNECT` requests to the given handler.
///
/// See [`get`] for an example.
pub fn connect<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -31,6 +48,9 @@ where
on(MethodFilter::Connect, handler)
}
/// Route `DELETE` requests to the given handler.
///
/// See [`get`] for an example.
pub fn delete<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -38,6 +58,18 @@ where
on(MethodFilter::Delete, handler)
}
/// Route `GET` requests to the given handler.
///
/// # Example
///
/// ```rust
/// use tower_web::prelude::*;
///
/// async fn handler(request: Request<Body>) {}
///
/// // Requests to `GET /` will go to `handler`.
/// let app = route("/", get(handler));
/// ```
pub fn get<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -45,6 +77,9 @@ where
on(MethodFilter::Get, handler)
}
/// Route `HEAD` requests to the given handler.
///
/// See [`get`] for an example.
pub fn head<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -52,6 +87,9 @@ where
on(MethodFilter::Head, handler)
}
/// Route `OPTIONS` requests to the given handler.
///
/// See [`get`] for an example.
pub fn options<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -59,6 +97,9 @@ where
on(MethodFilter::Options, handler)
}
/// Route `PATCH` requests to the given handler.
///
/// See [`get`] for an example.
pub fn patch<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -66,6 +107,9 @@ where
on(MethodFilter::Patch, handler)
}
/// Route `POST` requests to the given handler.
///
/// See [`get`] for an example.
pub fn post<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -73,6 +117,9 @@ where
on(MethodFilter::Post, handler)
}
/// Route `PUT` requests to the given handler.
///
/// See [`get`] for an example.
pub fn put<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -80,6 +127,9 @@ where
on(MethodFilter::Put, handler)
}
/// Route `TRACE` requests to the given handler.
///
/// See [`get`] for an example.
pub fn trace<H, T>(handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -87,6 +137,18 @@ where
on(MethodFilter::Trace, handler)
}
/// Route requests with the given method to the handler.
///
/// # Example
///
/// ```rust
/// use tower_web::{handler::on, routing::MethodFilter, prelude::*};
///
/// async fn handler(request: Request<Body>) {}
///
/// // Requests to `POST /` will go to `handler`.
/// let app = route("/", on(MethodFilter::Post, handler));
/// ```
pub fn on<H, T>(method: MethodFilter, handler: H) -> OnMethod<IntoService<H, T>, EmptyRouter>
where
H: Handler<T>,
@ -99,13 +161,49 @@ where
}
mod sealed {
#![allow(unreachable_pub)]
#![allow(unreachable_pub, missing_docs, missing_debug_implementations)]
pub trait HiddentTrait {}
pub struct Hidden;
impl HiddentTrait for Hidden {}
}
/// Trait for async functions that can be used to handle requests.
///
/// You shouldn't need to depend on this trait directly. It is automatically
/// implemented to closures of the right types.
///
/// # Example
///
/// Some examples of handlers:
///
/// ```rust
/// use tower_web::prelude::*;
/// use bytes::Bytes;
/// use http::StatusCode;
///
/// // Handlers must take `Request<Body>` as the first argument and must return
/// // something that implements `IntoResponse`, which `()` does
/// async fn unit_handler(request: Request<Body>) {}
///
/// // `String` also implements `IntoResponse`
/// async fn string_handler(request: Request<Body>) -> String {
/// "Hello, World!".to_string()
/// }
///
/// // Handler the buffers the request body and returns it if it is valid UTF-8
/// async fn buffer_body(request: Request<Body>, body: Bytes) -> Result<String, StatusCode> {
/// if let Ok(string) = String::from_utf8(body.to_vec()) {
/// Ok(string)
/// } else {
/// Err(StatusCode::BAD_REQUEST)
/// }
/// }
/// ```
///
/// For more details on generating responses see the
/// [`response`](crate::response) module and for more details on extractors see
/// the [`extract`](crate::extract) module.
#[async_trait]
pub trait Handler<In>: Sized {
// This seals the trait. We cannot use the regular "sealed super trait" approach
@ -113,8 +211,27 @@ pub trait Handler<In>: Sized {
#[doc(hidden)]
type Sealed: sealed::HiddentTrait;
/// Call the handler with the given request.
async fn call(self, req: Request<Body>) -> Response<BoxBody>;
/// Apply a [`tower::Layer`] to the handler.
///
/// # Example
///
/// Adding the [`tower::limit::ConcurrencyLimit`] middleware to a handler
/// can be done with [`tower::limit::ConcurrencyLimitLayer`]:
///
/// ```rust
/// use tower_web::prelude::*;
/// use tower::limit::{ConcurrencyLimitLayer, ConcurrencyLimit};
///
/// async fn handler(request: Request<Body>) { /* ... */ }
///
/// let layered_handler = handler.layer(ConcurrencyLimitLayer::new(64));
/// ```
///
/// When adding middleware that might fail its required to handle those
/// errors. See [`Layered::handle_error`] for more details.
fn layer<L>(self, layer: L) -> Layered<L::Service, In>
where
L: Layer<IntoService<Self, In>>,
@ -122,6 +239,7 @@ pub trait Handler<In>: Sized {
Layered::new(layer.layer(IntoService::new(self)))
}
/// Convert the handler into a [`Service`].
fn into_service(self) -> IntoService<Self, In> {
IntoService::new(self)
}
@ -182,11 +300,23 @@ macro_rules! impl_handler {
impl_handler!(T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11, T12, T13, T14, T15, T16);
/// A [`Service`] created from a [`Handler`] by applying a Tower middleware.
///
/// Created with [`Handler::layer`].
pub struct Layered<S, T> {
svc: S,
_input: PhantomData<fn() -> T>,
}
impl<S, T> fmt::Debug for Layered<S, T>
where
S: fmt::Debug,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Layered").field("svc", &self.svc).finish()
}
}
impl<S, T> Clone for Layered<S, T>
where
S: Clone,
@ -229,6 +359,44 @@ impl<S, T> Layered<S, T> {
}
}
/// Create a new [`Layered`] handler where errors will be handled using the
/// given closure.
///
/// tower-web requires that services gracefully handles all errors. That
/// means when you apply a Tower middleware that adds a new failure
/// condition you have to handle that as well.
///
/// That can be done using `handle_error` like so:
///
/// ```rust
/// use tower_web::prelude::*;
/// use http::StatusCode;
/// use tower::{BoxError, timeout::TimeoutLayer};
/// use std::time::Duration;
///
/// async fn handler(request: Request<Body>) { /* ... */ }
///
/// // `Timeout` will fail with `BoxError` if the timeout elapses...
/// let layered_handler = handler
/// .layer(TimeoutLayer::new(Duration::from_secs(30)));
///
/// // ...so we must handle that error
/// let layered_handler = layered_handler.handle_error(|error: BoxError| {
/// if error.is::<tower::timeout::error::Elapsed>() {
/// (
/// StatusCode::REQUEST_TIMEOUT,
/// "request took too long".to_string(),
/// )
/// } else {
/// (
/// StatusCode::INTERNAL_SERVER_ERROR,
/// format!("Unhandled internal error: {}", error),
/// )
/// }
/// });
/// ```
///
/// The closure can return any type that implements [`IntoResponse`].
pub fn handle_error<F, B, Res>(self, f: F) -> Layered<HandleError<S, F>, T>
where
S: Service<Request<Body>, Response = Response<B>>,
@ -240,6 +408,9 @@ impl<S, T> Layered<S, T> {
}
}
/// An adapter that makes a [`Handler`] into a [`Service`].
///
/// Created with [`Handler::into_service`].
pub struct IntoService<H, T> {
handler: H,
_marker: PhantomData<fn() -> T>,
@ -254,6 +425,17 @@ impl<H, T> IntoService<H, T> {
}
}
impl<H, T> fmt::Debug for IntoService<H, T>
where
H: fmt::Debug,
{
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("IntoService")
.field("handler", &self.handler)
.finish()
}
}
impl<H, T> Clone for IntoService<H, T>
where
H: Clone,
@ -292,11 +474,13 @@ where
}
opaque_future! {
/// The response future for [`IntoService`].
pub type IntoServiceFuture =
future::BoxFuture<'static, Result<Response<BoxBody>, Infallible>>;
}
#[derive(Clone)]
/// A handler [`Service`] that accepts requests based on a [`MethodFilter`].
#[derive(Debug, Clone, Copy)]
pub struct OnMethod<S, F> {
pub(crate) method: MethodFilter,
pub(crate) svc: S,
@ -304,6 +488,10 @@ pub struct OnMethod<S, F> {
}
impl<S, F> OnMethod<S, F> {
/// Chain an additional handler that will accept all requests regardless of
/// its HTTP method.
///
/// See [`OnMethod::get`] for an example.
pub fn any<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -311,6 +499,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Any, handler)
}
/// Chain an additional handler that will only accept `CONNECT` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn connect<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -318,6 +509,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Connect, handler)
}
/// Chain an additional handler that will only accept `DELETE` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn delete<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -325,6 +519,21 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Delete, handler)
}
/// Chain an additional handler that will only accept `GET` requests.
///
/// # Example
///
/// ```rust
/// use tower_web::prelude::*;
///
/// async fn handler(request: Request<Body>) {}
///
/// async fn other_handler(request: Request<Body>) {}
///
/// // Requests to `GET /` will go to `handler` and `POST /` will go to
/// // `other_handler`.
/// let app = route("/", post(handler).get(other_handler));
/// ```
pub fn get<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -332,6 +541,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Get, handler)
}
/// Chain an additional handler that will only accept `HEAD` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn head<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -339,6 +551,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Head, handler)
}
/// Chain an additional handler that will only accept `OPTIONS` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn options<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -346,6 +561,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Options, handler)
}
/// Chain an additional handler that will only accept `PATCH` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn patch<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -353,6 +571,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Patch, handler)
}
/// Chain an additional handler that will only accept `POST` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn post<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -360,6 +581,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Post, handler)
}
/// Chain an additional handler that will only accept `PUT` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn put<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -367,6 +591,9 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Put, handler)
}
/// Chain an additional handler that will only accept `TRACE` requests.
///
/// See [`OnMethod::get`] for an example.
pub fn trace<H, T>(self, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,
@ -374,6 +601,22 @@ impl<S, F> OnMethod<S, F> {
self.on(MethodFilter::Trace, handler)
}
/// Chain an additional handler that will accept requests matching the given
/// `MethodFilter`.
///
/// # Example
///
/// ```rust
/// use tower_web::{routing::MethodFilter, prelude::*};
///
/// async fn handler(request: Request<Body>) {}
///
/// async fn other_handler(request: Request<Body>) {}
///
/// // Requests to `GET /` will go to `handler` and `DELETE /` will go to
/// // `other_handler`
/// let app = route("/", get(handler).on(MethodFilter::Delete, other_handler));
/// ```
pub fn on<H, T>(self, method: MethodFilter, handler: H) -> OnMethod<IntoService<H, T>, Self>
where
H: Handler<T>,

3
src/lib.rs
View file

@ -570,6 +570,7 @@
rust_2018_idioms,
future_incompatible,
nonstandard_style,
missing_debug_implementations,
missing_docs
)]
#![deny(unreachable_pub, broken_intra_doc_links, private_in_public)]
@ -629,7 +630,7 @@ pub mod prelude {
///
/// - `/foo/bar/baz` will only match requests where the path is `/foo/bar/bar`.
/// - `/:foo` will match any route with exactly one segment _and_ it will
/// capture the first segment and store it only the key `foo`.
/// capture the first segment and store it at the key `foo`.
///
/// `service` is the [`Service`] that should receive the request if the path
/// matches `description`.

2
src/response.rs
View file

@ -160,6 +160,7 @@ where
/// An HTML response.
///
/// Will automatically get `Content-Type: text/html`.
#[derive(Clone, Copy, Debug)]
pub struct Html<T>(pub T);
impl<T> IntoResponse for Html<T>
@ -198,6 +199,7 @@ where
/// "application/json",
/// );
/// ```
#[derive(Clone, Copy, Debug)]
pub struct Json<T>(pub T);
impl<T> IntoResponse for Json<T>

114
src/routing.rs
View file

@ -21,19 +21,28 @@ use tower::{
BoxError, Layer, Service, ServiceBuilder,
};
// ===== DSL =====
/// A filter that matches one or more HTTP method.
#[derive(Debug, Copy, Clone)]
pub enum MethodFilter {
/// Match any method.
Any,
/// Match `CONNECT` requests.
Connect,
/// Match `DELETE` requests.
Delete,
/// Match `GET` requests.
Get,
/// Match `HEAD` requests.
Head,
/// Match `OPTIONS` requests.
Options,
/// Match `PATCH` requests.
Patch,
/// Match `POST` requests.
Post,
/// Match `PUT` requests.
Put,
/// Match `TRACE` requests.
Trace,
}
@ -56,7 +65,11 @@ impl MethodFilter {
}
}
#[derive(Clone)]
/// A route that sends requests to one of two [`Service`]s depending on the
/// path.
///
/// Created with [`route`](crate::route). See that function for more details.
#[derive(Debug, Clone)]
pub struct Route<S, F> {
pub(crate) pattern: PathPattern,
pub(crate) svc: S,
@ -111,8 +124,6 @@ pub trait RoutingDsl: Sized {
impl<S, F> RoutingDsl for Route<S, F> {}
// ===== Routing service impls =====
impl<S, F, SB, FB> Service<Request<Body>> for Route<S, F>
where
S: Service<Request<Body>, Response = Response<SB>, Error = Infallible> + Clone,
@ -144,7 +155,9 @@ where
}
}
/// The response future for [`Route`].
#[pin_project]
#[derive(Debug)]
pub struct RouteFuture<S, F>(
#[pin]
pub(crate) future::Either<
@ -185,7 +198,9 @@ fn insert_url_params<B>(req: &mut Request<B>, params: Vec<(String, String)>) {
}
}
/// A response future that boxes the response body with [`BoxBody`].
#[pin_project]
#[derive(Debug)]
pub struct BoxResponseBody<F>(#[pin] pub(crate) F);
impl<F, B> Future for BoxResponseBody<F>
@ -206,7 +221,11 @@ where
}
}
#[derive(Clone, Copy)]
/// A [`Service`] that responds with `404 Not Found` to all requests.
///
/// This is used as the bottom service in a router stack. You shouldn't have to
/// use to manually.
#[derive(Debug, Clone, Copy)]
pub struct EmptyRouter;
impl RoutingDsl for EmptyRouter {}
@ -228,12 +247,11 @@ impl Service<Request<Body>> for EmptyRouter {
}
opaque_future! {
/// Response future for [`EmptyRouter`].
pub type EmptyRouterFuture =
future::Ready<Result<Response<Body>, Infallible>>;
}
// ===== PathPattern =====
#[derive(Debug, Clone)]
pub(crate) struct PathPattern(Arc<Inner>);
@ -324,8 +342,6 @@ struct Match<'a> {
type Captures = Vec<(String, String)>;
// ===== BoxRoute =====
pub struct BoxRoute<B>(Buffer<BoxService<Request<Body>, Response<B>, Infallible>, Request<Body>>);
impl<B> Clone for BoxRoute<B> {
@ -356,6 +372,7 @@ where
}
}
/// The response future for [`BoxRoute`].
#[pin_project]
pub struct BoxRouteFuture<B>(#[pin] InnerFuture<B>);
@ -411,8 +428,6 @@ fn handle_buffer_error(error: BoxError) -> Response<BoxBody> {
.unwrap()
}
// ===== Layered =====
#[derive(Clone, Debug)]
pub struct Layered<S>(S);
@ -450,8 +465,76 @@ where
}
}
// ===== nesting =====
/// Nest a group of routes (or [`Service`]) at some path.
///
/// This allows you to break your application into smaller pieces and compose
/// them together. This will strip the matching prefix from the URL so the
/// nested route will only see the part of URL:
///
/// ```
/// use tower_web::{routing::nest, prelude::*};
///
/// async fn users_get(request: Request<Body>) {
/// // `users_get` doesn't see the whole URL. `nest` will strip the matching
/// // `/api` prefix.
/// assert_eq!(request.uri().path(), "/users");
/// }
///
/// async fn users_post(request: Request<Body>) {}
///
/// async fn careers(request: Request<Body>) {}
///
/// let users_api = route("/users", get(users_get).post(users_post));
///
/// let app = nest("/api", users_api).route("/careers", get(careers));
/// # async {
/// # hyper::Server::bind(&"".parse().unwrap()).serve(tower::make::Shared::new(app)).await;
/// # };
/// ```
///
/// Take care when using `nest` together with dynamic routes as nesting also
/// captures from the outer routes:
///
/// ```
/// use tower_web::{routing::nest, prelude::*};
///
/// async fn users_get(request: Request<Body>, params: extract::UrlParamsMap) {
/// // Both `version` and `id` were captured even though `users_api` only
/// // explicitly captures `id`.
/// let version = params.get("version");
/// let id = params.get("id");
/// }
///
/// let users_api = route("/users/:id", get(users_get));
///
/// let app = nest("/:version/api", users_api);
/// # async {
/// # hyper::Server::bind(&"".parse().unwrap()).serve(tower::make::Shared::new(app)).await;
/// # };
/// ```
///
/// `nest` also accepts any [`Service`]. This can for example be used with
/// [`tower_http::services::ServeDir`] to serve static files from a directory:
///
/// ```
/// use tower_web::{
/// routing::nest, service::get, ServiceExt, prelude::*,
/// };
/// use tower_http::services::ServeDir;
///
/// // Serves files inside the `public` directory at `GET /public/*`
/// let serve_dir_service = ServeDir::new("public")
/// .handle_error(|error: std::io::Error| { /* ... */ });
///
/// let app = nest("/public", get(serve_dir_service));
/// # async {
/// # hyper::Server::bind(&"".parse().unwrap()).serve(tower::make::Shared::new(app)).await;
/// # };
/// ```
///
/// If necessary you can use [`RoutingDsl::boxed`] to box a group of routes
/// making the type easier to name. This is sometimes useful when working with
/// `nest`.
pub fn nest<S>(description: &str, svc: S) -> Nested<S, EmptyRouter>
where
S: Service<Request<Body>, Error = Infallible> + Clone,
@ -463,6 +546,9 @@ where
}
}
/// A [`Service`] that has been nested inside a router at some path.
///
/// Created with [`nest`] or [`RoutingDsl::nest`].
#[derive(Debug, Clone)]
pub struct Nested<S, F> {
pattern: PathPattern,

5
src/service.rs
View file

@ -187,6 +187,11 @@ where
}
}
/// A [`Service`] adapter that handles errors with a closure.
///
/// Create with [`handler::Layered::handle_error`](crate::handler::Layered::handle_error) or
/// [`routing::Layered::handle_error`](crate::routing::Layered::handle_error). See those methods
/// for more details.
#[derive(Clone)]
pub struct HandleError<S, F> {
pub(crate) inner: S,