From a88e97edba030bde272e8739bf0b6d34d0aabc9b Mon Sep 17 00:00:00 2001 From: memoryruins Date: Fri, 6 Apr 2018 18:29:18 -0400 Subject: [PATCH] Guide: updates to Middleware chapter. --- guide/src/qs_10.md | 78 ++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/guide/src/qs_10.md b/guide/src/qs_10.md index ce1ed4a7e..0594c04bf 100644 --- a/guide/src/qs_10.md +++ b/guide/src/qs_10.md @@ -1,23 +1,25 @@ # Middleware -Actix' middleware system allows to add additional behavior to request/response processing. -Middleware can hook into incoming request process and modify request or halt request -processing and return response early. Also it can hook into response processing. +Actix's middleware system allows us to add additional behavior to request/response processing. +Middleware can hook into an incoming request process, enabling the ability to modify requests +as well as the ability to halt request processing and return response early. -Typically middlewares are involved in the following actions: +Middleware can also hook into response processing. + +Typically, middleware is involved in the following actions: * Pre-process the Request * Post-process a Response * Modify application state * Access external services (redis, logging, sessions) -Middlewares are registered for each application and are executed in same order as -registration order. In general, a *middleware* is a type that implements the +Middleware is registered for each application and executed in same order as +registration. In general, a *middleware* is a type that implements the [*Middleware trait*](../actix_web/middlewares/trait.Middleware.html). Each method in this trait has a default implementation. Each method can return a result immediately or a *future* object. -Here is an example of a simple middleware that adds request and response headers: +The following is an example of a simple middleware that adds request and response headers: ```rust # extern crate http; @@ -57,16 +59,17 @@ fn main() { } ``` -Actix provides several useful middlewares, like *logging*, *user sessions*, etc. - +> Actix provides several useful middlewares, such as *logging*, *user sessions*, etc. ## Logging Logging is implemented as a middleware. It is common to register a logging middleware as the first middleware for the application. -Logging middleware has to be registered for each application. *Logger* middleware -uses the standard log crate to log information. You should enable logger for *actix_web* -package to see access log ([env_logger](https://docs.rs/env_logger/*/env_logger/) or similar). +Logging middleware must be registered for each application. + +The `Logger` middleware uses the standard log crate to log information. You should enable logger +for *actix_web* package to see access log +([env_logger](https://docs.rs/env_logger/*/env_logger/) or similar). ### Usage @@ -76,6 +79,7 @@ Default `Logger` can be created with `default` method, it uses the default forma ```ignore %a %t "%r" %s %b "%{Referer}i" "%{User-Agent}i" %T ``` + ```rust # extern crate actix_web; extern crate env_logger; @@ -93,7 +97,7 @@ fn main() { } ``` -Here is an example of the default logging format: +The following is an example of the default logging format: ``` INFO:actix_web::middleware::logger: 127.0.0.1:59934 [02/Dec/2017:00:21:43 -0800] "GET / HTTP/1.1" 302 0 "-" "curl/7.54.0" 0.000397 @@ -126,12 +130,11 @@ INFO:actix_web::middleware::logger: 127.0.0.1:59947 [02/Dec/2017:00:22:40 -0800] `%{FOO}e` os.environ['FOO'] - ## Default headers -To set default response headers the `DefaultHeaders` middleware can be used. The +To set default response headers, the `DefaultHeaders` middleware can be used. The *DefaultHeaders* middleware does not set the header if response headers already contain -the specified header. +a specified header. ```rust # extern crate actix_web; @@ -153,27 +156,28 @@ fn main() { ## User sessions Actix provides a general solution for session management. The -[*Session storage*](../actix_web/middleware/struct.SessionStorage.html) middleware can be +[**SessionStorage**](../actix_web/middleware/struct.SessionStorage.html) middleware can be used with different backend types to store session data in different backends. -By default only cookie session backend is implemented. Other backend implementations -could be added later. -[*Cookie session backend*](../actix_web/middleware/struct.CookieSessionBackend.html) -uses signed cookies as session storage. *Cookie session backend* creates sessions which -are limited to storing fewer than 4000 bytes of data (as the payload must fit into a -single cookie). Internal server error is generated if session contains more than 4000 bytes. +> By default, only cookie session backend is implemented. Other backend implementations +> can be added. -You need to pass a random value to the constructor of *CookieSessionBackend*. -This is private key for cookie session. When this value is changed, all session data is lost. -Note that whatever you write into your session is visible by the user (but not modifiable). +[**CookieSessionBackend**](../actix_web/middleware/struct.CookieSessionBackend.html) +uses signed cookies as session storage. `CookieSessionBackend` creates sessions which +are limited to storing fewer than 4000 bytes of data, as the payload must fit into a +single cookie. An internal server error is generated if a session contains more than 4000 bytes. -In general case, you create -[*Session storage*](../actix_web/middleware/struct.SessionStorage.html) middleware -and initializes it with specific backend implementation, like *CookieSessionBackend*. -To access session data +You need to pass a random value to the constructor of `CookieSessionBackend`. +This is a private key for cookie session. When this value is changed, all session data is lost. + +> **Note**: anything you write into the session is visible by the user, but it is not modifiable. + +In general, you create a +`SessionStorage` middleware and initialize it with specific backend implementation, +such as a `CookieSessionBackend`. To access session data, [*HttpRequest::session()*](../actix_web/middleware/trait.RequestSession.html#tymethod.session) - has to be used. This method returns a -[*Session*](../actix_web/middleware/struct.Session.html) object, which allows to get or set + must be used. This method returns a +[*Session*](../actix_web/middleware/struct.Session.html) object, which allows us to get or set session data. ```rust @@ -212,12 +216,12 @@ fn main() { ## Error handlers -`ErrorHandlers` middleware allows to provide custom handlers for responses. +`ErrorHandlers` middleware allows us to provide custom handlers for responses. -You can use `ErrorHandlers::handler()` method to register a custom error handler -for specific status code. You can modify existing response or create completly new -one. Error handler can return response immediately or return future that resolves -to a response. +You can use the `ErrorHandlers::handler()` method to register a custom error handler +for specific status code. You can modify an existing response or create completly new +one. The error handler can return a response immediately or return a future that resolves +into a response. ```rust # extern crate actix_web;