actix/actix-extras
1
0
Fork 0
mirror of https://github.com/actix/actix-extras.git synced 2024-11-28 09:42:40 +01:00
Code Issues Releases Wiki Activity

Guide: additional tweaks to request and response chapter.

Browse Source
This commit is contained in:
memoryruins 2018-04-06 19:17:03 -04:00
parent c04e0fdec4
commit 7cff5d9ade
1 changed files with 24 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
guide/src/qs_7.md
View File

@ -4,13 +4,13 @@
A builder-like pattern is used to construct an instance of `HttpResponse`. A builder-like pattern is used to construct an instance of `HttpResponse`.
`HttpResponse` provides several methods that return a `HttpResponseBuilder` instance, `HttpResponse` provides several methods that return a `HttpResponseBuilder` instance,
which implements various convenience methods that helps building responses. which implements various convenience methods for building responses.
> Check the [documentation](../actix_web/dev/struct.HttpResponseBuilder.html) > Check the [documentation](../actix_web/dev/struct.HttpResponseBuilder.html)
> for type descriptions. > for type descriptions.
The methods `.body`, `.finish`, `.json` finalize response creation and The methods `.body`, `.finish`, and `.json` finalize response creation and
return a constructed *HttpResponse* instance. If this methods is called for the same return a constructed *HttpResponse* instance. If this methods is called on the same
builder instance multiple times, the builder will panic. builder instance multiple times, the builder will panic.
```rust ```rust
@ -29,7 +29,7 @@ fn index(req: HttpRequest) -> HttpResponse {
## Content encoding ## Content encoding
Actix automatically *compresses*/*decompresses* payloads. Following codecs are supported: Actix automatically *compresses*/*decompresses* payloads. The following codecs are supported:
* Brotli * Brotli
* Gzip * Gzip
@ -40,11 +40,13 @@ If request headers contain a `Content-Encoding` header, the request payload is d
according to the header value. Multiple codecs are not supported, i.e: `Content-Encoding: br, gzip`. according to the header value. Multiple codecs are not supported, i.e: `Content-Encoding: br, gzip`.
Response payload is compressed based on the *content_encoding* parameter. Response payload is compressed based on the *content_encoding* parameter.
By default `ContentEncoding::Auto` is used. If `ContentEncoding::Auto` is selected, By default, `ContentEncoding::Auto` is used. If `ContentEncoding::Auto` is selected,
then compression depends on the request's `Accept-Encoding` header. then the compression depends on the request's `Accept-Encoding` header.
`ContentEncoding::Identity` can be used to disable compression.
If another content encoding is selected, the compression is enforced for this codec. For example, > `ContentEncoding::Identity` can be used to disable compression.
to enable `brotli` use `ContentEncoding::Br`: > If another content encoding is selected, the compression is enforced for that codec.
For example, to enable `brotli` use `ContentEncoding::Br`:
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
@ -62,10 +64,10 @@ fn index(req: HttpRequest) -> HttpResponse {
There are several options for json body deserialization. There are several options for json body deserialization.
The first option is to use *Json* extractor. You define a handler function The first option is to use *Json* extractor. First, you define a handler function
that accepts `Json<T>` as a parameter and use the `.with()` method for registering that accepts `Json<T>` as a parameter, then, you use the `.with()` method for registering
this handler. It is also possible to accept arbitrary valid json object by this handler. It is also possible to accept arbitrary valid json object by
using `serde_json::Value` as a type `T` using `serde_json::Value` as a type `T`.
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
@ -89,7 +91,7 @@ fn main() {
} }
``` ```
The second option is to use *HttpResponse::json()*. This method returns a Another option is to use *HttpResponse::json()*. This method returns a
[*JsonBody*](../actix_web/dev/struct.JsonBody.html) object which resolves into [*JsonBody*](../actix_web/dev/struct.JsonBody.html) object which resolves into
the deserialized value. the deserialized value.
@ -118,7 +120,7 @@ fn index(mut req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
# fn main() {} # fn main() {}
``` ```
Alternatively, you can manually load the payload into memory and then deserialize it. You may also manually load the payload into memory and then deserialize it.
In the following example, we will deserialize a *MyObj* struct. We need to load the request In the following example, we will deserialize a *MyObj* struct. We need to load the request
body first and then deserialize the json into an object. body first and then deserialize the json into an object.
@ -158,8 +160,8 @@ fn index(req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
## JSON Response ## JSON Response
The `Json` type allows to respond with well-formed JSON data: simply return a value of The `Json` type allows to respond with well-formed JSON data: simply return a value of
type Json<T> where T is the type of a structure to serialize into *JSON*. The type Json<T> where `T` is the type of a structure to serialize into *JSON*.
type `T` must implement the `Serialize` trait from *serde*. The type `T` must implement the `Serialize` trait from *serde*.
```rust ```rust
# extern crate actix_web; # extern crate actix_web;
@ -186,11 +188,11 @@ fn main() {
Actix automatically decodes *chunked* encoding. `HttpRequest::payload()` already contains Actix automatically decodes *chunked* encoding. `HttpRequest::payload()` already contains
the decoded byte stream. If the request payload is compressed with one of the supported the decoded byte stream. If the request payload is compressed with one of the supported
compression codecs (br, gzip, deflate) the byte stream is decompressed. compression codecs (br, gzip, deflate), then the byte stream is decompressed.
Chunked encoding on response can be enabled with `HttpResponseBuilder::chunked()`, Chunked encoding on a response can be enabled with `HttpResponseBuilder::chunked()`.
but this takes effect only for `Body::Streaming(BodyStream)` or `Body::StreamingContext` bodies. This takes effect only for `Body::Streaming(BodyStream)` or `Body::StreamingContext` bodies.
Also, if the response payload compression is enabled and a streaming body is used, chunked encoding If the response payload compression is enabled and a streaming body is used, chunked encoding
is enabled automatically. is enabled automatically.
> Enabling chunked encoding for *HTTP/2.0* responses is forbidden. > Enabling chunked encoding for *HTTP/2.0* responses is forbidden.
@ -216,11 +218,11 @@ fn index(req: HttpRequest) -> HttpResponse {
Actix provides multipart stream support. Actix provides multipart stream support.
[*Multipart*](../actix_web/multipart/struct.Multipart.html) is implemented as [*Multipart*](../actix_web/multipart/struct.Multipart.html) is implemented as
a stream of multipart items, each item can be a a stream of multipart items. Each item can be a
[*Field*](../actix_web/multipart/struct.Field.html) or a nested *Multipart* stream. [*Field*](../actix_web/multipart/struct.Field.html) or a nested *Multipart* stream.
`HttpResponse::multipart()` returns the *Multipart* stream for the current request. `HttpResponse::multipart()` returns the *Multipart* stream for the current request.
Simple form multipart stream handling could be implemented like the following: The following demonstrates multipart stream handling for a simple form:
```rust,ignore ```rust,ignore
# extern crate actix_web; # extern crate actix_web;