diff --git a/src/app.rs b/src/app.rs index 2b15933da..da33ebc4b 100644 --- a/src/app.rs +++ b/src/app.rs @@ -320,36 +320,42 @@ where self } - /// Registers middleware, in the form of a middleware component (type), - /// that runs during inbound and/or outbound processing in the request - /// life-cycle (request -> response), modifying request/response as - /// necessary, across all requests managed by the *Application*. + /// Registers an app-wide middleware. /// - /// Use middleware when you need to read or modify *every* request or - /// response in some way. + /// Registers middleware, in the form of a middleware compo nen t (type), that runs during + /// inbound and/or outbound processing in the request life-cycle (request -> response), + /// modifying request/response as necessary, across all requests managed by the `App`. /// - /// Notice that the keyword for registering middleware is `wrap`. As you - /// register middleware using `wrap` in the App builder, imagine wrapping - /// layers around an inner App. The first middleware layer exposed to a - /// Request is the outermost layer-- the *last* registered in - /// the builder chain. Consequently, the *first* middleware registered - /// in the builder chain is the *last* to execute during request processing. + /// Use middleware when you need to read or modify *every* request or response in some way. /// + /// Middleware can be applied similarly to individual `Scope`s and `Resource`s. + /// See [`Scope::wrap`](crate::Scope::wrap) and [`Resource::wrap`]. + /// + /// # Middleware Order + /// Notice that the keyword for registering middleware is `wrap`. As you register middleware + /// using `wrap` in the App builder, imagine wrapping layers around an inner App. The first + /// middleware layer exposed to a Request is the outermost layer (i.e., the *last* registered in + /// the builder chain). Consequently, the *first* middleware registered in the builder chain is + /// the *last* to start executing during request processing. + /// + /// Ordering is less obvious when wrapped services also have middleware applied. In this case, + /// middlewares are run in reverse order for `App` _and then_ in reverse order for the + /// wrapped service. + /// + /// # Examples /// ``` - /// use actix_service::Service; /// use actix_web::{middleware, web, App}; - /// use actix_web::http::header::{CONTENT_TYPE, HeaderValue}; /// /// async fn index() -> &'static str { /// "Welcome!" /// } /// - /// fn main() { - /// let app = App::new() - /// .wrap(middleware::Logger::default()) - /// .route("/index.html", web::get().to(index)); - /// } + /// let app = App::new() + /// .wrap(middleware::Logger::default()) + /// .route("/index.html", web::get().to(index)); /// ``` + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap( self, mw: M, @@ -383,40 +389,41 @@ where } } - /// Registers middleware, in the form of a closure, that runs during inbound - /// and/or outbound processing in the request life-cycle (request -> response), - /// modifying request/response as necessary, across all requests managed by - /// the *Application*. + /// Registers an app-wide function middleware. + /// + /// `mw` is a closure that runs during inbound and/or outbound processing in the request + /// life-cycle (request -> response), modifying request/response as necessary, across all + /// requests handled by the `App`. /// /// Use middleware when you need to read or modify *every* request or response in some way. /// + /// Middleware can also be applied to individual `Scope`s and `Resource`s. + /// /// See [`App::wrap`] for details on how middlewares compose with each other. /// /// # Examples /// ``` - /// use actix_service::Service; - /// use actix_web::{web, App}; + /// use actix_web::{dev::Service as _, middleware, web, App}; /// use actix_web::http::header::{CONTENT_TYPE, HeaderValue}; /// /// async fn index() -> &'static str { /// "Welcome!" /// } /// - /// fn main() { - /// let app = App::new() - /// .wrap_fn(|req, srv| { - /// let fut = srv.call(req); - /// async { - /// let mut res = fut.await?; - /// res.headers_mut().insert( - /// CONTENT_TYPE, HeaderValue::from_static("text/plain"), - /// ); - /// Ok(res) - /// } - /// }) - /// .route("/index.html", web::get().to(index)); - /// } + /// let app = App::new() + /// .wrap_fn(|req, srv| { + /// let fut = srv.call(req); + /// async { + /// let mut res = fut.await?; + /// res.headers_mut() + /// .insert(CONTENT_TYPE, HeaderValue::from_static("text/plain")); + /// Ok(res) + /// } + /// }) + /// .route("/index.html", web::get().to(index)); /// ``` + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap_fn( self, mw: F, diff --git a/src/middleware/compat.rs b/src/middleware/compat.rs index 18c9ff6a7..ee8b8a498 100644 --- a/src/middleware/compat.rs +++ b/src/middleware/compat.rs @@ -150,11 +150,13 @@ mod tests { use actix_service::IntoService; - use crate::dev::ServiceRequest; - use crate::http::StatusCode; - use crate::middleware::{self, Condition, Logger}; - use crate::test::{call_service, init_service, TestRequest}; - use crate::{web, App, HttpResponse}; + use crate::{ + dev::ServiceRequest, + http::StatusCode, + middleware::{self, Condition, Logger}, + test::{self, call_service, init_service, TestRequest}, + web, App, HttpResponse, + }; #[actix_rt::test] #[cfg(all(feature = "cookies", feature = "__compress"))] @@ -219,4 +221,17 @@ mod tests { let resp = call_service(&mw, TestRequest::default().to_srv_request()).await; assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR); } + + #[actix_rt::test] + async fn compat_noop_is_noop() { + let srv = test::ok_service(); + + let mw = Compat::noop() + .new_transform(srv.into_service()) + .await + .unwrap(); + + let resp = call_service(&mw, TestRequest::default().to_srv_request()).await; + assert_eq!(resp.status(), StatusCode::OK); + } } diff --git a/src/middleware/mod.rs b/src/middleware/mod.rs index a781052a6..0a61ad6cb 100644 --- a/src/middleware/mod.rs +++ b/src/middleware/mod.rs @@ -1,4 +1,4 @@ -//! Commonly used middleware. +//! A collection of common middleware. mod compat; mod condition; diff --git a/src/resource.rs b/src/resource.rs index b06f744ca..193757eaa 100644 --- a/src/resource.rs +++ b/src/resource.rs @@ -232,10 +232,14 @@ where self } - /// Registers middleware, in the form of a middleware component (type), - /// that can modify the request and response across all routes managed by this `Resource`. + /// Registers a resource middleware. /// - /// See [`App::wrap`](crate::App::wrap) for details. + /// `mw` is a middleware component (type), that can modify the request and response across all + /// routes managed by this `Resource`. + /// + /// See [`App::wrap`](crate::App::wrap) for more details. + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap( self, mw: M, @@ -270,37 +274,15 @@ where } } - /// Registers middleware, in the form of a closure, - /// that can modify the request and response across all routes managed by this `Resource`. + /// Registers a resource function middleware. /// - /// See [`App::wrap_fn`](crate::App::wrap_fn) for details. + /// `mw` is a closure that runs during inbound and/or outbound processing in the request + /// life-cycle (request -> response), modifying request/response as necessary, across all + /// requests handled by the `Resource`. /// - /// # Examples - /// ``` - /// use actix_service::Service; - /// use actix_web::{web, App}; - /// use actix_web::http::header::{CONTENT_TYPE, HeaderValue}; - /// - /// async fn index() -> &'static str { - /// "Welcome!" - /// } - /// - /// fn main() { - /// let app = App::new().service( - /// web::resource("/index.html") - /// .wrap_fn(|req, srv| { - /// let fut = srv.call(req); - /// async { - /// let mut res = fut.await?; - /// res.headers_mut().insert( - /// CONTENT_TYPE, HeaderValue::from_static("text/plain"), - /// ); - /// Ok(res) - /// } - /// }) - /// .route(web::get().to(index))); - /// } - /// ``` + /// See [`App::wrap_fn`](crate::App::wrap_fn) for examples and more details. + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap_fn( self, mw: F, @@ -498,7 +480,7 @@ mod tests { header::{self, HeaderValue}, Method, StatusCode, }, - middleware::{Compat, DefaultHeaders}, + middleware::DefaultHeaders, service::{ServiceRequest, ServiceResponse}, test::{call_service, init_service, TestRequest}, web, App, Error, HttpMessage, HttpResponse, @@ -506,11 +488,11 @@ mod tests { #[test] fn can_be_returned_from_fn() { - fn my_resource() -> Resource { - web::resource("/test").route(web::get().to(|| async { "hello" })) + fn my_resource_1() -> Resource { + web::resource("/test1").route(web::get().to(|| async { "hello" })) } - fn my_compat_resource() -> Resource< + fn my_resource_2() -> Resource< impl ServiceFactory< ServiceRequest, Config = (), @@ -519,18 +501,22 @@ mod tests { InitError = (), >, > { - web::resource("/test-compat") + web::resource("/test2") .wrap_fn(|req, srv| { let fut = srv.call(req); async { Ok(fut.await?.map_into_right_body::<()>()) } }) - .wrap(Compat::noop()) .route(web::get().to(|| async { "hello" })) } + fn my_resource_3() -> impl HttpServiceFactory { + web::resource("/test2").route(web::get().to(|| async { "hello" })) + } + App::new() - .service(my_resource()) - .service(my_compat_resource()); + .service(my_resource_1()) + .service(my_resource_2()) + .service(my_resource_3()); } #[actix_rt::test] diff --git a/src/scope.rs b/src/scope.rs index 83286440a..c05ce054d 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -284,10 +284,14 @@ where self } - /// Registers middleware, in the form of a middleware component (type), - /// that can modify the request and response across all routes managed by this `Scope`. + /// Registers a scope-wide middleware. /// - /// See [`App::wrap`](crate::App::wrap) for details. + /// `mw` is a middleware component (type), that can modify the request and response across all + /// sub-resources managed by this `Scope`. + /// + /// See [`App::wrap`](crate::App::wrap) for more details. + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap( self, mw: M, @@ -322,35 +326,15 @@ where } } - /// Registers middleware, in the form of a closure, - /// that can modify the request and response across all routes managed by this `Scope`. + /// Registers a scope-wide function middleware. /// - /// See [`App::wrap_fn`](crate::App::wrap_fn) for details. + /// `mw` is a closure that runs during inbound and/or outbound processing in the request + /// life-cycle (request -> response), modifying request/response as necessary, across all + /// requests handled by the `Scope`. /// - /// # Examples - /// ``` - /// use actix_service::Service; - /// use actix_web::{web, App}; - /// use actix_web::http::header::{CONTENT_TYPE, HeaderValue}; - /// - /// async fn index() -> &'static str { - /// "Welcome!" - /// } - /// - /// let app = App::new().service( - /// web::scope("/app") - /// .wrap_fn(|req, srv| { - /// let fut = srv.call(req); - /// async { - /// let mut res = fut.await?; - /// res.headers_mut().insert( - /// CONTENT_TYPE, HeaderValue::from_static("text/plain"), - /// ); - /// Ok(res) - /// } - /// }) - /// .route("/index.html", web::get().to(index))); - /// ``` + /// See [`App::wrap_fn`](crate::App::wrap_fn) for examples and more details. + #[doc(alias = "middleware")] + #[doc(alias = "use")] // nodejs terminology pub fn wrap_fn( self, mw: F,