berkus
/
actix-web
mirror of https://github.com/fafhrd91/actix-web
1
0
Fork 0
Code Issues Releases Wiki Activity

tweak middleware docs

This commit is contained in:
Rob Ede 2022-01-05 14:43:24 +00:00
parent e14261e6ee
commit 675cbd0813
No known key found for this signature in database
GPG Key ID: 97C636207D3EF933
5 changed files with 107 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
src/app.rs
View File

@ -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<M, B>(
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<F, R, B>(
self,
mw: F,

25
src/middleware/compat.rs
View File

@ -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);
}
}

2
src/middleware/mod.rs
View File

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

66
src/resource.rs
View File

@ -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<M, B>(
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<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 {
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]

44
src/scope.rs
View File

@ -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<M, B>(
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<F, R, B>(
self,
mw: F,