Support fallbacks for nested routers

axum-extra/CHANGELOG.md

@@ -9,7 +9,10 @@ and this project adheres to [Semantic Versioning].
 
 - **added:** Add `RouterExt::route_with_tsr` for adding routes with an
   additional "trailing slash redirect" route ([#1119])
+- **breaking:** `Resource::nest` and `Resource::nest_collection` now only
+  accepts `Router`s ([#1086])
 
+[#1086]: https://github.com/tokio-rs/axum/pull/1086
 [#1119]: https://github.com/tokio-rs/axum/pull/1119
 
 # 0.3.5 (27. June, 2022)

axum-extra/src/routing/resource.rs

@@ -137,29 +137,21 @@ where
         self.route(&path, delete(handler))
     }
 
-    /// Nest another route at the "member level".
+    /// Nest another router at the "member level".
     ///
     /// The routes will be nested at `/{resource_name}/:{resource_name}_id`.
-    pub fn nest<T>(mut self, svc: T) -> Self
-    where
-        T: Service<Request<B>, Response = Response, Error = Infallible> + Clone + Send + 'static,
-        T::Future: Send + 'static,
-    {
+    pub fn nest(mut self, router: Router<B>) -> Self {
         let path = self.show_update_destroy_path();
-        self.router = self.router.nest(&path, svc);
+        self.router = self.router.nest(&path, router);
         self
     }
 
-    /// Nest another route at the "collection level".
+    /// Nest another router at the "collection level".
     ///
     /// The routes will be nested at `/{resource_name}`.
-    pub fn nest_collection<T>(mut self, svc: T) -> Self
-    where
-        T: Service<Request<B>, Response = Response, Error = Infallible> + Clone + Send + 'static,
-        T::Future: Send + 'static,
-    {
+    pub fn nest_collection(mut self, router: Router<B>) -> Self {
         let path = self.index_create_path();
-        self.router = self.router.nest(&path, svc);
+        self.router = self.router.nest(&path, router);
         self
     }
 

axum-extra/src/routing/spa.rs

@@ -161,7 +161,7 @@ where
             .handle_error(spa.handle_error.clone());
 
         Router::new()
-            .nest(&spa.paths.assets_path, assets_service)
+            .nest_service(&spa.paths.assets_path, assets_service)
             .fallback(
                 get_service(ServeFile::new(&spa.paths.index_file)).handle_error(spa.handle_error),
             )

axum/CHANGELOG.md

@@ -11,6 +11,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Use `axum::middleware::from_extractor` instead ([#1077])
 - **breaking:** Allow `Error: Into<Infallible>` for `Route::{layer, route_layer}` ([#924])
 - **breaking:** `MethodRouter` now panics on overlapping routes ([#1102])
+- **breaking:** `Router::nest` now only accepts `Router`s. Use
+  `Router::nest_service` to nest opaque services ([#1086])
+- **added:** Add `Router::nest_service` for nesting opaque services. Use this to
+  nest services like `tower::services::ServeDir` ([#1086])
+- **breaking:** The request `/foo/` no longer matches `/foo/*rest`. If you want
+  to match `/foo/` you have to add a route specifically for that ([#1086])
+- **breaking:** Path params for wildcard routes no longer include the prefix
+  `/`. e.g. `/foo.js` will match `/*filepath` with a value of `foo.js`, _not_
+  `/foo.js` ([#1086])
+- **fixed:** Routes like `/foo` and `/*rest` are no longer considered
+  overlapping. `/foo` will take priority ([#1086])
 - **breaking:** Remove trailing slash redirects. Previously if you added a route
   for `/foo`, axum would redirect calls to `/foo/` to `/foo` (or vice versa for
   `/foo/`). That is no longer supported and such requests will now be sent to
@@ -20,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **added:** Support running extractors from `middleware::from_fn` functions ([#1088])
 
 [#1077]: https://github.com/tokio-rs/axum/pull/1077
+[#1086]: https://github.com/tokio-rs/axum/pull/1086
 [#1088]: https://github.com/tokio-rs/axum/pull/1088
 [#1102]: https://github.com/tokio-rs/axum/pull/1102
 [#1119]: https://github.com/tokio-rs/axum/pull/1119

axum/Cargo.toml

@@ -33,7 +33,7 @@ http = "0.2.5"
 http-body = "0.4.4"
 hyper = { version = "0.14.14", features = ["server", "tcp", "stream"] }
 itoa = "1.0.1"
-matchit = "0.5.0"
+matchit = "0.6"
 memchr = "2.4.1"
 mime = "0.3.16"
 percent-encoding = "2.1"

axum/src/docs/routing/nest.md

@@ -1,4 +1,4 @@
-Nest a group of routes (or a [`Service`]) at some path.
+Nest a router at some path.
 
 This allows you to break your application into smaller pieces and compose
 them together.
@@ -64,36 +64,6 @@ let app = Router::new().nest("/:version/api", users_api);
 # };
 ```
 
-# Nesting services
-
-`nest` also accepts any [`Service`]. This can for example be used with
-[`tower_http::services::ServeDir`] to serve static files from a directory:
-
-```rust
-use axum::{
-    Router,
-    routing::get_service,
-    http::StatusCode,
-    error_handling::HandleErrorLayer,
-};
-use std::{io, convert::Infallible};
-use tower_http::services::ServeDir;
-
-// Serves files inside the `public` directory at `GET /public/*`
-let serve_dir_service = get_service(ServeDir::new("public"))
-    .handle_error(|error: io::Error| async move {
-        (
-            StatusCode::INTERNAL_SERVER_ERROR,
-            format!("Unhandled internal error: {}", error),
-        )
-    });
-
-let app = Router::new().nest("/public", serve_dir_service);
-# async {
-# axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
-# };
-```
-
 # Differences to wildcard routes
 
 Nested routes are similar to wildcard routes. The difference is that
@@ -103,18 +73,79 @@ the prefix stripped:
 ```rust
 use axum::{routing::get, http::Uri, Router};
 
+let nested_router = Router::new()
+    .route("/", get(|uri: Uri| async {
+        // `uri` will _not_ contain `/bar`
+    }));
+
 let app = Router::new()
     .route("/foo/*rest", get(|uri: Uri| async {
         // `uri` will contain `/foo`
     }))
-    .nest("/bar", get(|uri: Uri| async {
-        // `uri` will _not_ contain `/bar`
-    }));
+    .nest("/bar", nested_router);
 # async {
 # axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
 # };
 ```
 
+# Differences between `nest` and `nest_service`
+
+When [fallbacks] are called differs between `nest` and `nested_service`. Routers
+nested with `nest` will delegate to the outer router's fallback if they don't
+have a matching route, whereas `nested_service` will not.
+
+```rust
+use axum::{
+    Router,
+    routing::get,
+    handler::Handler,
+};
+
+let nested_router = Router::new().route("/users", get(|| async {}));
+
+let nested_service = Router::new().route("/app.js", get(|| async {}));
+
+let app = Router::new()
+    .nest("/api", nested_router)
+    .nest_service("/assets", nested_service)
+    // the fallback is not called for request starting with `/assets` but will be
+    // called for requests starting with `/api` if `nested_router` doesn't have
+    // a matching route
+    .fallback(fallback.into_service());
+# let _: Router = app;
+
+async fn fallback() {}
+```
+
+You can still add fallbacks explicitly to the inner router:
+
+```rust
+use axum::{
+    Router,
+    routing::get,
+    handler::Handler,
+};
+
+let nested_service = Router::new()
+    .route("/app.js", get(|| async {}))
+    .fallback(nested_service_fallback.into_service());
+
+let app = Router::new()
+    .nest_service("/assets", nested_service)
+    .fallback(outer_router_fallback.into_service());
+# let _: Router = app;
+
+// this handler is used for `nested_service`
+async fn nested_service_fallback() {
+    // ..
+}
+
+// this handler is used for the outer router
+async fn outer_router_fallback() {
+    // ...
+}
+```
+
 # Panics
 
 - If the route overlaps with another route. See [`Router::route`]
@@ -125,3 +156,4 @@ for more details.
   `Router` only allows a single fallback.
 
 [`OriginalUri`]: crate::extract::OriginalUri
+[fallbacks]: Router::fallback

axum/src/docs/routing/nest_service.md

@@ -0,0 +1,40 @@
+Nest a [`Service`] at some path.
+
+`nest_service` behaves in the same way as `nest` in terms of
+
+- [How the URI changes](#how-the-uri-changes)
+- [Captures from outer routes](#captures-from-outer-routes)
+- [Differences to wildcard routes](#differences-to-wildcard-routes)
+
+But differs with regards to [fallbacks]. See ["Differences between `nest` and
+`nest_service`"](#differences-between-nest-and-nest_service) for more details.
+
+# Example
+
+`nest_service` can for example be used with [`tower_http::services::ServeDir`]
+to serve static files from a directory:
+
+```rust
+use axum::{
+    Router,
+    routing::get_service,
+    http::StatusCode,
+    error_handling::HandleErrorLayer,
+};
+use std::{io, convert::Infallible};
+use tower_http::services::ServeDir;
+
+// Serves files inside the `public` directory at `GET /assets/*`
+let serve_dir_service = get_service(ServeDir::new("public"))
+    .handle_error(|error: io::Error| async move {
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("Unhandled internal error: {}", error),
+        )
+    });
+
+let app = Router::new().nest_service("/assets", serve_dir_service);
+# let _: Router = app;
+```
+
+[fallbacks]: Router::fallback

axum/src/docs/routing/route.md

@@ -51,6 +51,8 @@ Examples:
 - `/:id/:repo/*tree`
 
 Wildcard captures can also be extracted using [`Path`](crate::extract::Path).
+Note that the leading slash is not included, i.e. for the route `/foo/*rest` and
+the path `/foo/bar/baz` the value of `rest` will be `bar/baz`.
 
 # Accepting multiple methods
 
@@ -184,22 +186,6 @@ let app = Router::new()
 The static route `/foo` and the dynamic route `/:key` are not considered to
 overlap and `/foo` will take precedence.
 
-Take care when using [`Router::nest`] as it behaves like a wildcard route.
-Therefore this setup panics:
-
-```rust,should_panic
-use axum::{routing::get, Router};
-
-let app = Router::new()
-    // this is similar to `/api/*`
-    .nest("/api", get(|| async {}))
-    // which overlaps with this route
-    .route("/api/users", get(|| async {}));
-# async {
-# axum::Server::bind(&"".parse().unwrap()).serve(app.into_make_service()).await.unwrap();
-# };
-```
-
 Also panics if `path` is empty.
 
 ## Nesting

axum/src/extract/matched_path.rs

@@ -1,5 +1,8 @@
+use crate::routing::NEST_TAIL_PARAM_CAPTURE;
+
 use super::{rejection::*, FromRequest, RequestParts};
 use async_trait::async_trait;
+use http::Request;
 use std::sync::Arc;
 
 /// Access the path in the router that matches the request.
@@ -81,6 +84,25 @@ where
     }
 }
 
+pub(crate) fn insert_matched_path<B>(matched_path: &Arc<str>, req: &mut Request<B>) {
+    let matched_path = if let Some(previous) = req.extensions_mut().get::<MatchedPath>() {
+        // a previous `MatchedPath` might exist if we're inside a nested Router
+        let previous =
+            if let Some(previous) = previous.as_str().strip_suffix(NEST_TAIL_PARAM_CAPTURE) {
+                previous
+            } else {
+                previous.as_str()
+            };
+
+        let matched_path = format!("{}{}", previous, matched_path);
+        matched_path.into()
+    } else {
+        Arc::clone(matched_path)
+    };
+
+    req.extensions_mut().insert(MatchedPath(matched_path));
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -149,12 +171,14 @@ mod tests {
                 "/public",
                 Router::new().route("/assets/*path", get(handler)),
             )
-            .nest("/foo", handler.into_service())
+            .nest_service("/foo", handler.into_service())
             .layer(tower::layer::layer_fn(SetMatchedPathExtension));
 
         let client = TestClient::new(app);
 
-        let res = client.get("/foo").send().await;
+        // we cannot call `/foo` because `nest_service("/foo", _)` registers routes
+        // for `/foo/*rest` and `/foo`
+        let res = client.get("/public").send().await;
         assert_eq!(res.text().await, "/:key");
 
         let res = client.get("/api/users/123").send().await;
@@ -176,4 +200,20 @@ mod tests {
             ),
         );
     }
+
+    #[tokio::test]
+    async fn nested_opaque_routers_append_to_matched_path() {
+        let app = Router::new().nest_service(
+            "/:a",
+            Router::new().route(
+                "/:b",
+                get(|path: MatchedPath| async move { path.as_str().to_owned() }),
+            ),
+        );
+
+        let client = TestClient::new(app);
+
+        let res = client.get("/foo/bar").send().await;
+        assert_eq!(res.text().await, "/:a/:b");
+    }
 }

axum/src/extract/mod.rs

@@ -13,7 +13,7 @@ pub mod ws;
 mod content_length_limit;
 mod host;
 mod raw_query;
-mod request_parts;
+pub(crate) mod request_parts;
 
 #[doc(inline)]
 pub use axum_core::extract::{FromRequest, RequestParts};
@@ -41,7 +41,7 @@ pub use crate::Extension;
 pub use crate::form::Form;
 
 #[cfg(feature = "matched-path")]
-mod matched_path;
+pub(crate) mod matched_path;
 
 #[cfg(feature = "matched-path")]
 #[doc(inline)]

axum/src/extract/path/mod.rs

@@ -499,10 +499,10 @@ mod tests {
         let client = TestClient::new(app);
 
         let res = client.get("/foo/bar/baz").send().await;
-        assert_eq!(res.text().await, "/bar/baz");
+        assert_eq!(res.text().await, "bar/baz");
 
         let res = client.get("/bar/baz/qux").send().await;
-        assert_eq!(res.text().await, "/baz/qux");
+        assert_eq!(res.text().await, "baz/qux");
     }
 
     #[tokio::test]