tweak middleware docs

src/app.rs

@@ -320,36 +320,42 @@ where
         self
     }
 
-    /// Registers middleware, in the form of a middleware component (type),
+    /// Registers an app-wide middleware.
-    /// 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*.
     ///
-    /// Use middleware when you need to read or modify *every* request or
+    /// Registers middleware, in the form of a middleware compo nen t (type), that runs during
-    /// response in some way.
+    /// 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
+    /// Use middleware when you need to read or modify *every* request or response in some way.
-    /// 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.
     ///
+    /// 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));
-    /// }
     /// ```
+    #[doc(alias = "middleware")]
+    #[doc(alias = "use")] // nodejs terminology
     pub fn wrap<M, B>(
         self,
         mw: M,
@@ -383,40 +389,41 @@ where
         }
     }
 
-    /// Registers middleware, in the form of a closure, that runs during inbound
+    /// Registers an app-wide function middleware.
-    /// and/or outbound processing in the request life-cycle (request -> response),
+    ///
-    /// modifying request/response as necessary, across all requests managed by
+    /// `mw` is a closure that runs during inbound and/or outbound processing in the request
-    /// the *Application*.
+    /// 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::{dev::Service as _, middleware, web, App};
-    /// 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()
     ///     .wrap_fn(|req, srv| {
     ///         let fut = srv.call(req);
     ///         async {
     ///             let mut res = fut.await?;
-    ///                 res.headers_mut().insert(
+    ///             res.headers_mut()
-    ///                    CONTENT_TYPE, HeaderValue::from_static("text/plain"),
+    ///                 .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<F, R, B>(
         self,
         mw: F,

src/middleware/compat.rs

@@ -150,11 +150,13 @@ mod tests {
 
     use actix_service::IntoService;
 
-    use crate::dev::ServiceRequest;
+    use crate::{
-    use crate::http::StatusCode;
+        dev::ServiceRequest,
-    use crate::middleware::{self, Condition, Logger};
+        http::StatusCode,
-    use crate::test::{call_service, init_service, TestRequest};
+        middleware::{self, Condition, Logger},
-    use crate::{web, App, HttpResponse};
+        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);
+    }
 }

src/middleware/mod.rs

@@ -1,4 +1,4 @@
-//! Commonly used middleware.
+//! A collection of common middleware.
 
 mod compat;
 mod condition;

src/resource.rs

@@ -232,10 +232,14 @@ where
         self
     }
 
-    /// Registers middleware, in the form of a middleware component (type),
+    /// Registers a resource middleware.
-    /// that can modify the request and response across all routes managed by this `Resource`.
     ///
-    /// 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<M, B>(
         self,
         mw: M,
@@ -270,37 +274,15 @@ where
         }
     }
 
-    /// Registers middleware, in the form of a closure,
+    /// Registers a resource function middleware.
-    /// that can modify the request and response across all routes managed by this `Resource`.
     ///
-    /// 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
+    /// See [`App::wrap_fn`](crate::App::wrap_fn) for examples and more details.
-    /// ```
+    #[doc(alias = "middleware")]
-    /// use actix_service::Service;
+    #[doc(alias = "use")] // nodejs terminology
-    /// 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)));
-    /// }
-    /// ```
     pub fn wrap_fn<F, R, B>(
         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 {
+        fn my_resource_1() -> Resource {
-            web::resource("/test").route(web::get().to(|| async { "hello" }))
+            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_resource_1())
-            .service(my_compat_resource());
+            .service(my_resource_2())
+            .service(my_resource_3());
     }
 
     #[actix_rt::test]

src/scope.rs

@@ -284,10 +284,14 @@ where
         self
     }
 
-    /// Registers middleware, in the form of a middleware component (type),
+    /// Registers a scope-wide middleware.
-    /// that can modify the request and response across all routes managed by this `Scope`.
     ///
-    /// 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<M, B>(
         self,
         mw: M,
@@ -322,35 +326,15 @@ where
         }
     }
 
-    /// Registers middleware, in the form of a closure,
+    /// Registers a scope-wide function middleware.
-    /// that can modify the request and response across all routes managed by this `Scope`.
     ///
-    /// 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
+    /// See [`App::wrap_fn`](crate::App::wrap_fn) for examples and more details.
-    /// ```
+    #[doc(alias = "middleware")]
-    /// use actix_service::Service;
+    #[doc(alias = "use")] // nodejs terminology
-    /// 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)));
-    /// ```
     pub fn wrap_fn<F, R, B>(
         self,
         mw: F,