actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2024-11-24 16:02:59 +01:00
Code Issues Releases Wiki Activity

Guide: updates to Middleware chapter.

Browse Source
This commit is contained in:
memoryruins 2018-04-06 18:29:18 -04:00
parent 1f08100f6f
commit a88e97edba
1 changed files with 41 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
guide/src/qs_10.md
View File

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