From 220c04b7b38ef39beb8cba0ef977d6c4f9e50aa4 Mon Sep 17 00:00:00 2001 From: dowwie Date: Mon, 1 Apr 2019 09:30:11 -0400 Subject: [PATCH 1/4] added docs for wrap and wrap_fn --- src/app.rs | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/src/app.rs b/src/app.rs index 9cdfc436a..0c5671f7b 100644 --- a/src/app.rs +++ b/src/app.rs @@ -112,7 +112,26 @@ where self } - /// Register a middleware. + /// Registers heavyweight Application-level middleware, in the form of a + /// middleware type, that runs during inbound and/or outbound processing in the + /// request lifecycle (request -> response). + /// + /// ```rust + /// use actix_service::Service; + /// # use futures::Future; + /// use actix_web::{middleware, web, App}; + /// use actix_web::http::{header::CONTENT_TYPE, HeaderValue}; + /// + /// fn index() -> &'static str { + /// "Welcome!" + /// } + /// + /// fn main() { + /// let app = App::new() + /// .wrap(middleware::Logger::default()) + /// .route("/index.html", web::get().to(index)); + /// } + /// ``` pub fn wrap( self, mw: F, @@ -152,7 +171,9 @@ where } } - /// Register a middleware function. + /// Registers lightweight Application-level middleware, in the form of a + /// closure, that runs during inbound and/or outbound processing in the + /// request lifecycle (request -> response). /// /// ```rust /// use actix_service::Service; @@ -400,7 +421,9 @@ where self } - /// Register a middleware. + /// Registers heavyweight Route-level middleware, in the form of a + /// middleware type, that runs during inbound and/or outbound processing in the + /// request lifecycle (request -> response). pub fn wrap( self, mw: F, @@ -440,7 +463,9 @@ where } } - /// Register a middleware function. + /// Registers lightweight Route-level middleware, in the form of a + /// closure, that runs during inbound and/or outbound processing in the + /// request lifecycle (request -> response). pub fn wrap_fn( self, mw: F, From 8800b8ef13d8b52d78a2125ffbb8951156638bca Mon Sep 17 00:00:00 2001 From: dowwie Date: Mon, 1 Apr 2019 09:59:21 -0400 Subject: [PATCH 2/4] mentioned re-use in wrap doc --- src/app.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/app.rs b/src/app.rs index 0c5671f7b..cfa6c98e3 100644 --- a/src/app.rs +++ b/src/app.rs @@ -113,8 +113,8 @@ where } /// Registers heavyweight Application-level middleware, in the form of a - /// middleware type, that runs during inbound and/or outbound processing in the - /// request lifecycle (request -> response). + /// re-usable middleware type, that runs during inbound and/or outbound + /// processing in the request lifecycle (request -> response). /// /// ```rust /// use actix_service::Service; @@ -422,8 +422,8 @@ where } /// Registers heavyweight Route-level middleware, in the form of a - /// middleware type, that runs during inbound and/or outbound processing in the - /// request lifecycle (request -> response). + /// re-usable middleware type, that runs during inbound and/or outbound + /// processing in the request lifecycle (request -> response). pub fn wrap( self, mw: F, From 03dfbdfcdd16ea7e863d76e59c742af802f2f513 Mon Sep 17 00:00:00 2001 From: dowwie Date: Mon, 1 Apr 2019 14:52:05 -0400 Subject: [PATCH 3/4] updated wrap and wrap fn descriptions, still requiring viable examples --- src/app.rs | 38 ++++++++++++++++++++++++++------------ src/scope.rs | 20 ++++++++++++-------- 2 files changed, 38 insertions(+), 20 deletions(-) diff --git a/src/app.rs b/src/app.rs index cfa6c98e3..9535dac21 100644 --- a/src/app.rs +++ b/src/app.rs @@ -112,9 +112,12 @@ where self } - /// Registers heavyweight Application-level middleware, in the form of a - /// re-usable middleware type, that runs during inbound and/or outbound - /// processing in the request lifecycle (request -> response). + /// Registers middleware, in the form of a middleware component (type), + /// that runs during inbound and/or outbound processing in the request + /// lifecycle (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 response in some way. /// /// ```rust /// use actix_service::Service; @@ -171,9 +174,12 @@ where } } - /// Registers lightweight Application-level middleware, in the form of a - /// closure, that runs during inbound and/or outbound processing in the - /// request lifecycle (request -> response). + /// Registers middleware, in the form of a closure, that runs during inbound + /// and/or outbound processing in the request lifecycle (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 response in some way. /// /// ```rust /// use actix_service::Service; @@ -421,9 +427,13 @@ where self } - /// Registers heavyweight Route-level middleware, in the form of a - /// re-usable middleware type, that runs during inbound and/or outbound - /// processing in the request lifecycle (request -> response). + /// Registers middleware, in the form of a middleware component (type), + /// that runs during inbound and/or outbound processing in the request + /// lifecycle (request -> response), modifying request/response as + /// necessary, across all requests managed by the *Route*. + /// + /// Use middleware when you need to read or modify *every* request or response in some way. + /// pub fn wrap( self, mw: F, @@ -463,9 +473,13 @@ where } } - /// Registers lightweight Route-level middleware, in the form of a - /// closure, that runs during inbound and/or outbound processing in the - /// request lifecycle (request -> response). + /// Registers middleware, in the form of a closure, that runs during inbound + /// and/or outbound processing in the request lifecycle (request -> response), + /// modifying request/response as necessary, across all requests managed by + /// the *Route*. + /// + /// Use middleware when you need to read or modify *every* request or response in some way. + /// pub fn wrap_fn( self, mw: F, diff --git a/src/scope.rs b/src/scope.rs index d45609c5e..3fdc4ccb5 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -200,11 +200,14 @@ where self } - /// Register a scope level middleware. + /// Registers middleware, in the form of a middleware component (type), + /// that runs during inbound processing in the request + /// lifecycle (request -> response), modifying request as + /// necessary, across all requests managed by the *Scope*. Note that + /// Scope-level middleware is only used for inbound requests, not outbound + /// responses. /// - /// This is similar to `App's` middlewares, but middleware get invoked on scope level. - /// Scope level middlewares are not allowed to change response - /// type (i.e modify response's body). + /// Use middleware when you need to read or modify *every* request in some way. pub fn wrap( self, mw: F, @@ -238,10 +241,11 @@ where } } - /// Register a scope level middleware function. - /// - /// This function accepts instance of `ServiceRequest` type and - /// mutable reference to the next middleware in chain. + /// Registers middleware, in the form of a closure, that runs during inbound + /// processing in the request lifecycle (request -> response), modifying + /// request as necessary, across all requests managed by the *Scope*. + /// Note that Scope-level middleware is only used for inbound requests, + /// not outbound responses. /// /// ```rust /// use actix_service::Service; From 3dd3f7bc92aa25ef700d05ddf23ff346d8318204 Mon Sep 17 00:00:00 2001 From: dowwie Date: Mon, 1 Apr 2019 15:10:28 -0400 Subject: [PATCH 4/4] updated scope wrap doc --- src/scope.rs | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/scope.rs b/src/scope.rs index 3fdc4ccb5..0dfaaf066 100644 --- a/src/scope.rs +++ b/src/scope.rs @@ -203,9 +203,10 @@ where /// Registers middleware, in the form of a middleware component (type), /// that runs during inbound processing in the request /// lifecycle (request -> response), modifying request as - /// necessary, across all requests managed by the *Scope*. Note that - /// Scope-level middleware is only used for inbound requests, not outbound - /// responses. + /// necessary, across all requests managed by the *Scope*. Scope-level + /// middleware is more limited in what it can modify, relative to Route or + /// Application level middleware, in that Scope-level middleware can not modify + /// ServiceResponse. /// /// Use middleware when you need to read or modify *every* request in some way. pub fn wrap( @@ -244,8 +245,9 @@ where /// Registers middleware, in the form of a closure, that runs during inbound /// processing in the request lifecycle (request -> response), modifying /// request as necessary, across all requests managed by the *Scope*. - /// Note that Scope-level middleware is only used for inbound requests, - /// not outbound responses. + /// Scope-level middleware is more limited in what it can modify, relative + /// to Route or Application level middleware, in that Scope-level middleware + /// can not modify ServiceResponse. /// /// ```rust /// use actix_service::Service;