diff --git a/axum-extra/CHANGELOG.md b/axum-extra/CHANGELOG.md index 3eac0ab9..a745c52e 100644 --- a/axum-extra/CHANGELOG.md +++ b/axum-extra/CHANGELOG.md @@ -7,11 +7,14 @@ and this project adheres to [Semantic Versioning]. # Unreleased -- **added:** Re-export `SameSite` and `Expiration` from the `cookie` crate. +- **added:** Re-export `SameSite` and `Expiration` from the `cookie` crate ([#898]) - **fixed:** Fix `SignedCookieJar` when using custom key types ([#899]) -- **added:** `PrivateCookieJar` for managing private cookies +- **added:** Add `PrivateCookieJar` for managing private cookies ([#900]) +- **added:** Add `SpaRouter` for routing setups commonly used for single page applications +[#898]: https://github.com/tokio-rs/axum/pull/898 [#899]: https://github.com/tokio-rs/axum/pull/899 +[#900]: https://github.com/tokio-rs/axum/pull/900 # 0.2.0 (31. March, 2022) diff --git a/axum-extra/Cargo.toml b/axum-extra/Cargo.toml index 63b2f2ec..57990d92 100644 --- a/axum-extra/Cargo.toml +++ b/axum-extra/Cargo.toml @@ -15,6 +15,7 @@ default = [] erased-json = ["serde_json", "serde"] typed-routing = ["axum-macros", "serde", "percent-encoding"] cookie = ["cookie-lib"] +spa = ["tower-http/fs"] [dependencies] axum = { path = "../axum", version = "0.5" } @@ -37,6 +38,7 @@ cookie-lib = { package = "cookie", version = "0.16", features = ["percent-encode [dev-dependencies] axum = { path = "../axum", version = "0.5", features = ["headers"] } hyper = "0.14" +reqwest = { version = "0.11", default-features = false, features = ["json", "stream", "multipart"] } 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 index 144c137c..705bed73 100644 --- a/axum-extra/src/lib.rs +++ b/axum-extra/src/lib.rs @@ -61,3 +61,19 @@ pub mod __private { const PATH: &AsciiSet = &FRAGMENT.add(b'#').add(b'?').add(b'{').add(b'}'); pub const PATH_SEGMENT: &AsciiSet = &PATH.add(b'/').add(b'%'); } + +#[cfg(test)] +pub(crate) mod test_helpers { + #![allow(unused_imports)] + + use axum::{body::HttpBody, BoxError}; + + mod test_client { + #![allow(dead_code)] + include!(concat!( + env!("CARGO_MANIFEST_DIR"), + "/../axum/src/test_helpers/test_client.rs" + )); + } + pub(crate) use self::test_client::*; +} diff --git a/axum-extra/src/routing/mod.rs b/axum-extra/src/routing/mod.rs index 51fd60c5..8e693e2b 100644 --- a/axum-extra/src/routing/mod.rs +++ b/axum-extra/src/routing/mod.rs @@ -4,6 +4,9 @@ use axum::{handler::Handler, Router}; mod resource; +#[cfg(feature = "spa")] +mod spa; + #[cfg(feature = "typed-routing")] mod typed; @@ -15,6 +18,9 @@ pub use axum_macros::TypedPath; #[cfg(feature = "typed-routing")] pub use self::typed::{FirstElementIs, TypedPath}; +#[cfg(feature = "spa")] +pub use self::spa::SpaRouter; + /// Extension trait that adds additional methods to [`Router`]. pub trait RouterExt: sealed::Sealed { /// Add a typed `GET` route to the router. diff --git a/axum-extra/src/routing/spa.rs b/axum-extra/src/routing/spa.rs new file mode 100644 index 00000000..594b15c2 --- /dev/null +++ b/axum-extra/src/routing/spa.rs @@ -0,0 +1,269 @@ +use axum::{ + body::{Body, HttpBody}, + error_handling::HandleError, + response::Response, + routing::{get_service, Route}, + Router, +}; +use http::{Request, StatusCode}; +use std::{ + any::type_name, + convert::Infallible, + fmt, + future::{ready, Ready}, + io, + marker::PhantomData, + path::{Path, PathBuf}, + sync::Arc, +}; +use tower_http::services::{ServeDir, ServeFile}; +use tower_service::Service; + +/// Router for single page applications. +/// +/// `SpaRouter` gives a routing setup commonly used for single page applications. +/// +/// # Example +/// +/// ``` +/// use axum_extra::routing::SpaRouter; +/// use axum::{Router, routing::get}; +/// +/// let spa = SpaRouter::new("/assets", "dist"); +/// +/// let app = Router::new() +/// // `SpaRouter` implements `Into` so it works with `merge` +/// .merge(spa) +/// // we can still add other routes +/// .route("/api/foo", get(api_foo)); +/// # let _: Router = app; +/// +/// async fn api_foo() {} +/// ``` +/// +/// With this setup we get this behavior: +/// +/// - `GET /` will serve `index.html` +/// - `GET /assets/app.js` will serve `dist/app.js` assuming that file exists +/// - `GET /assets/doesnt_exist` will respond with `404 Not Found` assuming no +/// such file exists +/// - `GET /some/other/path` will serve `index.html` since there isn't another +/// route for it +/// - `GET /api/foo` will serve the `api_foo` handler function +pub struct SpaRouter Ready> { + paths: Arc, + handle_error: F, + _marker: PhantomData (B, T)>, +} + +#[derive(Debug)] +struct Paths { + assets_path: String, + assets_dir: PathBuf, + index_file: PathBuf, +} + +impl SpaRouter Ready> { + /// Create a new `SpaRouter`. + /// + /// Assets will be served at `GET /{serve_assets_at}` from the directory at `assets_dir`. + /// + /// The index file defaults to `assets_dir.join("index.html")`. + pub fn new

(serve_assets_at: &str, assets_dir: P) -> Self + where + P: AsRef, + { + let path = assets_dir.as_ref(); + Self { + paths: Arc::new(Paths { + assets_path: serve_assets_at.to_owned(), + assets_dir: path.to_owned(), + index_file: path.join("index.html"), + }), + handle_error: |_| ready(StatusCode::INTERNAL_SERVER_ERROR), + _marker: PhantomData, + } + } +} + +impl SpaRouter { + /// Set the path to the index file. + /// + /// `path` must be relative to `assets_dir` passed to [`SpaRouter::new`]. + /// + /// # Example + /// + /// ``` + /// use axum_extra::routing::SpaRouter; + /// use axum::Router; + /// + /// let spa = SpaRouter::new("/assets", "dist") + /// .index_file("another_file.html"); + /// + /// let app = Router::new().merge(spa); + /// # let _: Router = app; + /// ``` + pub fn index_file

(mut self, path: P) -> Self + where + P: AsRef, + { + self.paths = Arc::new(Paths { + assets_path: self.paths.assets_path.clone(), + assets_dir: self.paths.assets_dir.clone(), + index_file: self.paths.assets_dir.join(path), + }); + self + } + + /// Change the function used to handle unknown IO errors. + /// + /// `SpaRouter` automatically maps missing files and permission denied to + /// `404 Not Found`. The callback given here will be used for other IO errors. + /// + /// See [`axum::error_handling::HandleErrorLayer`] for more details. + /// + /// # Example + /// + /// ``` + /// use std::io; + /// use axum_extra::routing::SpaRouter; + /// use axum::{Router, http::{Method, Uri}}; + /// + /// let spa = SpaRouter::new("/assets", "dist").handle_error(handle_error); + /// + /// async fn handle_error(method: Method, uri: Uri, err: io::Error) -> String { + /// format!("{} {} failed with {}", method, uri, err) + /// } + /// + /// let app = Router::new().merge(spa); + /// # let _: Router = app; + /// ``` + pub fn handle_error(self, f: F2) -> SpaRouter { + SpaRouter { + paths: self.paths, + handle_error: f, + _marker: PhantomData, + } + } +} + +impl From> for Router +where + F: Clone + Send + 'static, + HandleError, F, T>: + Service, Response = Response, Error = Infallible>, + , F, T> as Service>>::Future: Send, + B: HttpBody + Send + 'static, + T: 'static, +{ + fn from(spa: SpaRouter) -> Self { + let assets_service = get_service(ServeDir::new(&spa.paths.assets_dir)) + .handle_error(spa.handle_error.clone()); + + Router::new() + .nest(&spa.paths.assets_path, assets_service) + .fallback( + get_service(ServeFile::new(&spa.paths.index_file)).handle_error(spa.handle_error), + ) + } +} + +impl fmt::Debug for SpaRouter { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + let Self { + paths, + handle_error: _, + _marker, + } = self; + + f.debug_struct("SpaRouter") + .field("paths", &paths) + .field("handle_error", &format_args!("{}", type_name::())) + .field("request_body_type", &format_args!("{}", type_name::())) + .field( + "extractor_input_type", + &format_args!("{}", type_name::()), + ) + .finish() + } +} + +impl Clone for SpaRouter +where + F: Clone, +{ + fn clone(&self) -> Self { + Self { + paths: self.paths.clone(), + handle_error: self.handle_error.clone(), + _marker: self._marker, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_helpers::*; + use axum::{ + http::{Method, Uri}, + routing::get, + }; + + #[tokio::test] + async fn basic() { + let app = Router::new() + .route("/foo", get(|| async { "GET /foo" })) + .merge(SpaRouter::new("/assets", "test_files")); + let client = TestClient::new(app); + + let res = client.get("/").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "

Hello, World!

\n"); + + let res = client.get("/some/random/path").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "

Hello, World!

\n"); + + let res = client.get("/assets/script.js").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "console.log('hi')\n"); + + let res = client.get("/foo").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "GET /foo"); + + let res = client.get("/assets/doesnt_exist").send().await; + assert_eq!(res.status(), StatusCode::NOT_FOUND); + } + + #[tokio::test] + async fn setting_index_file() { + let app = + Router::new().merge(SpaRouter::new("/assets", "test_files").index_file("index_2.html")); + let client = TestClient::new(app); + + let res = client.get("/").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "Hello, World!\n"); + + let res = client.get("/some/random/path").send().await; + assert_eq!(res.status(), StatusCode::OK); + assert_eq!(res.text().await, "Hello, World!\n"); + } + + // this should just compile + #[allow(dead_code)] + fn setting_error_handler() { + async fn handle_error(method: Method, uri: Uri, err: io::Error) -> (StatusCode, String) { + ( + StatusCode::INTERNAL_SERVER_ERROR, + format!("{} {} failed. Error: {}", method, uri, err), + ) + } + + let spa = SpaRouter::new("/assets", "test_files").handle_error(handle_error); + + Router::::new().merge(spa); + } +} diff --git a/axum-extra/test_files/index.html b/axum-extra/test_files/index.html new file mode 100644 index 00000000..f76d8e92 --- /dev/null +++ b/axum-extra/test_files/index.html @@ -0,0 +1 @@ +

Hello, World!

diff --git a/axum-extra/test_files/index_2.html b/axum-extra/test_files/index_2.html new file mode 100644 index 00000000..82082e07 --- /dev/null +++ b/axum-extra/test_files/index_2.html @@ -0,0 +1 @@ +Hello, World! diff --git a/axum-extra/test_files/script.js b/axum-extra/test_files/script.js new file mode 100644 index 00000000..6687898e --- /dev/null +++ b/axum-extra/test_files/script.js @@ -0,0 +1 @@ +console.log('hi') diff --git a/axum/src/test_helpers/mod.rs b/axum/src/test_helpers/mod.rs new file mode 100644 index 00000000..60ff6575 --- /dev/null +++ b/axum/src/test_helpers/mod.rs @@ -0,0 +1,12 @@ +#![allow(clippy::blacklisted_name)] + +use crate::{body::HttpBody, BoxError}; + +mod test_client; +pub(crate) use self::test_client::*; + +pub(crate) fn assert_send() {} +pub(crate) fn assert_sync() {} +pub(crate) fn assert_unpin() {} + +pub(crate) struct NotSendSync(*const ()); diff --git a/axum/src/test_helpers.rs b/axum/src/test_helpers/test_client.rs similarity index 94% rename from axum/src/test_helpers.rs rename to axum/src/test_helpers/test_client.rs index 43ae5c1e..27f4be4a 100644 --- a/axum/src/test_helpers.rs +++ b/axum/src/test_helpers/test_client.rs @@ -1,7 +1,4 @@ -#![allow(clippy::blacklisted_name)] - -use crate::body::HttpBody; -use crate::BoxError; +use super::{BoxError, HttpBody}; use bytes::Bytes; use http::{ header::{HeaderName, HeaderValue}, @@ -15,12 +12,6 @@ use std::{ use tower::make::Shared; use tower_service::Service; -pub(crate) fn assert_send() {} -pub(crate) fn assert_sync() {} -pub(crate) fn assert_unpin() {} - -pub(crate) struct NotSendSync(*const ()); - pub(crate) struct TestClient { client: reqwest::Client, addr: SocketAddr,