Type safe routing (#756)

* wip * wip * make macro implement trait * checkpoint * checkpoint * Simplify things quite a bit * re-export `axum_macros::TypedPath` from `axum_extra` * docs * add missing feature * fix docs link * fix features * fix missing imports * make serde an optional dep again * ui tests * Break things up a bit * Update span for `FromRequest` impls to point to callsite * make docs feature labels show up automatically * Apply suggestions from code review Co-authored-by: Jonas Platte <jplatte@users.noreply.github.com> * add note about Display/Serialize being compatible * Update axum-extra/src/routing/typed.rs Co-authored-by: Jonas Platte <jplatte@users.noreply.github.com> * fix missing docs link * what about typed methods? * Revert "what about typed methods?" This reverts commit cc1f989. * don't allow wildcards for now * percent encode params * Update axum-extra/src/routing/typed.rs Co-authored-by: Jonas Platte <jplatte@users.noreply.github.com> * rephrase args * changelog Co-authored-by: Jonas Platte <jplatte@users.noreply.github.com>
tokio-rs · Feb 22, 2022 · c298c36 · c298c36
1 parent 00553a3
commit c298c36
Show file tree

Hide file tree

Showing 24 changed files with 929 additions and 6 deletions.
diff --git a/axum-extra/CHANGELOG.md b/axum-extra/CHANGELOG.md
@@ -7,12 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
+- **added:** Add type safe routing. See `axum_extra::routing::typed` for more details ([#756])
 - **fix:** Depend on tower with `default_features = false` ([#666])
 - **change:** `middleware::from_fn` has been deprecated and moved into the main
   axum crate ([#719])
 
 [#666]: https://github.com/tokio-rs/axum/pull/666
 [#719]: https://github.com/tokio-rs/axum/pull/719
+[#756]: https://github.com/tokio-rs/axum/pull/756
 
 # 0.1.2 (13. January, 2021)
 

diff --git a/axum-extra/Cargo.toml b/axum-extra/Cargo.toml
@@ -11,7 +11,9 @@ repository = "https://github.com/tokio-rs/axum"
 version = "0.1.1"
 
 [features]
-erased-json = ["serde", "serde_json"]
+default = []
+erased-json = ["serde_json", "serde"]
+typed-routing = ["axum-macros", "serde", "percent-encoding"]
 
 [dependencies]
 axum = { path = "../axum", version = "0.4" }
@@ -25,11 +27,14 @@ tower-layer = "0.3"
 tower-service = "0.3"
 
 # optional dependencies
-serde = { version = "1.0.130", optional = true }
+axum-macros = { path = "../axum-macros", version = "0.1", optional = true }
+serde = { version = "1.0", optional = true }
 serde_json = { version = "1.0.71", optional = true }
+percent-encoding = { version = "2.1", optional = true }
 
 [dev-dependencies]
 hyper = "0.14"
+serde = { version = "1.0", features = ["derive"] }
 tokio = { version = "1.14", features = ["full"] }
 tower = { version = "0.4", features = ["util"] }
 

diff --git a/axum-extra/src/lib.rs b/axum-extra/src/lib.rs
@@ -40,7 +40,7 @@
 #![deny(unreachable_pub, private_in_public)]
 #![allow(elided_lifetimes_in_paths, clippy::type_complexity)]
 #![forbid(unsafe_code)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 #![cfg_attr(test, allow(clippy::float_cmp))]
 
 pub mod extract;
@@ -61,3 +61,18 @@ pub mod middleware {
         };
     }
 }
+
+#[cfg(feature = "typed-routing")]
+#[doc(hidden)]
+pub mod __private {
+    //! _not_ public API
+
+    use percent_encoding::{AsciiSet, CONTROLS};
+
+    pub use percent_encoding::utf8_percent_encode;
+
+    // from https://github.com/servo/rust-url/blob/master/url/src/parser.rs
+    const FRAGMENT: &AsciiSet = &CONTROLS.add(b' ').add(b'"').add(b'<').add(b'>').add(b'`');
+    const PATH: &AsciiSet = &FRAGMENT.add(b'#').add(b'?').add(b'{').add(b'}');
+    pub const PATH_SEGMENT: &AsciiSet = &PATH.add(b'/').add(b'%');
+}
diff --git a/axum-extra/src/routing/mod.rs b/axum-extra/src/routing/mod.rs
@@ -1,11 +1,20 @@
 //! Additional types for defining routes.
 
-use axum::{body::Body, Router};
+use axum::{body::Body, handler::Handler, Router};
 
 mod resource;
 
+#[cfg(feature = "typed-routing")]
+mod typed;
+
 pub use self::resource::Resource;
 
+#[cfg(feature = "typed-routing")]
+pub use axum_macros::TypedPath;
+
+#[cfg(feature = "typed-routing")]
+pub use self::typed::{FirstElementIs, TypedPath};
+
 /// Extension trait that adds additional methods to [`Router`].
 pub trait RouterExt<B>: sealed::Sealed {
     /// Add the routes from `T`'s [`HasRoutes::routes`] to this router.
@@ -32,6 +41,110 @@ pub trait RouterExt<B>: sealed::Sealed {
     fn with<T>(self, routes: T) -> Self
     where
         T: HasRoutes<B>;
+
+    /// Add a typed `GET` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_get<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `DELETE` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_delete<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `HEAD` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_head<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `OPTIONS` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_options<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `PATCH` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_patch<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `POST` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_post<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `PUT` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_put<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
+
+    /// Add a typed `TRACE` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    ///
+    /// See [`TypedPath`] for more details and examples.
+    #[cfg(feature = "typed-routing")]
+    fn typed_trace<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath;
 }
 
 impl<B> RouterExt<B> for Router<B>
@@ -44,6 +157,86 @@ where
     {
         self.merge(routes.routes())
     }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_get<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::get(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_delete<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::delete(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_head<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::head(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_options<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::options(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_patch<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::patch(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_post<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::post(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_put<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::put(handler))
+    }
+
+    #[cfg(feature = "typed-routing")]
+    fn typed_trace<H, T, P>(self, handler: H) -> Self
+    where
+        H: Handler<T, B>,
+        T: FirstElementIs<P> + 'static,
+        P: TypedPath,
+    {
+        self.route(P::PATH, axum::routing::trace(handler))
+    }
 }
 
 /// Trait for things that can provide routes.