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: tweaks to the request and response chapter.

Browse Source
This commit is contained in:
memoryruins 2018-04-06 17:31:18 -04:00
parent 5d8cbccfe9
commit 0fbd05009d
1 changed files with 32 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
guide/src/qs_7.md
View File

@ -5,8 +5,11 @@
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 that helps building responses.
Check [documentation](../actix_web/dev/struct.HttpResponseBuilder.html)
for type descriptions. The methods `.body`, `.finish`, `.json` finalize response creation and > Check the [documentation](../actix_web/dev/struct.HttpResponseBuilder.html)
> for type descriptions.
The methods `.body`, `.finish`, `.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 for the same
builder instance multiple times, the builder will panic. builder instance multiple times, the builder will panic.
@ -28,19 +31,19 @@ fn index(req: HttpRequest) -> HttpResponse {
Actix automatically *compresses*/*decompresses* payloads. Following codecs are supported: Actix automatically *compresses*/*decompresses* payloads. Following codecs are supported:
* Brotli * Brotli
* Gzip * Gzip
* Deflate * Deflate
* Identity * Identity
If request headers contain a `Content-Encoding` header, the request payload is decompressed If request headers contain a `Content-Encoding` header, the request payload is decompressed
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 compression depends on the request's `Accept-Encoding` header.
`ContentEncoding::Identity` can be used to disable compression. `ContentEncoding::Identity` can be used to disable compression.
If another content encoding is selected the compression is enforced for this codec. For example, If another content encoding is selected, the compression is enforced for this codec. For example,
to enable `brotli` use `ContentEncoding::Br`: to enable `brotli` use `ContentEncoding::Br`:
```rust ```rust
@ -55,13 +58,12 @@ fn index(req: HttpRequest) -> HttpResponse {
# fn main() {} # fn main() {}
``` ```
## JSON Request ## JSON Request
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 handler function The first option is to use *Json* extractor. You define a handler function
that accepts `Json<T>` as a parameter and use `.with()` method for registering that accepts `Json<T>` as a parameter and 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`
@ -116,8 +118,9 @@ fn index(mut req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
# fn main() {} # fn main() {}
``` ```
Or you can manually load the payload into memory and then deserialize it. Alternatively, you can manually load the payload into memory and then deserialize it.
Here is a simple 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.
```rust ```rust
@ -149,9 +152,8 @@ fn index(req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
# fn main() {} # fn main() {}
``` ```
A complete example for both options is available in > A complete example for both options is available in
[examples directory](https://github.com/actix/actix-web/tree/master/examples/json/). > [examples directory](https://github.com/actix/actix-web/tree/master/examples/json/).
## JSON Response ## JSON Response
@ -186,12 +188,12 @@ Actix automatically decodes *chunked* encoding. `HttpRequest::payload()` already
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) the byte stream is decompressed.
Chunked encoding on response can be enabled with `HttpResponseBuilder::chunked()`. Chunked encoding on response can be enabled with `HttpResponseBuilder::chunked()`,
But this takes effect only for `Body::Streaming(BodyStream)` or `Body::StreamingContext` bodies. but this takes effect only for `Body::Streaming(BodyStream)` or `Body::StreamingContext` bodies.
Also if response payload compression is enabled and streaming body is used, chunked encoding Also, 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.
```rust ```rust
# extern crate bytes; # extern crate bytes;
@ -218,7 +220,7 @@ 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.
In simple form multipart stream handling can be implemented similar to this example Simple form multipart stream handling could be implemented like the following:
```rust,ignore ```rust,ignore
# extern crate actix_web; # extern crate actix_web;
@ -248,17 +250,18 @@ fn index(req: HttpRequest) -> Box<Future<...>> {
} }
``` ```
A full example is available in the > A full example is available in the
[examples directory](https://github.com/actix/actix-web/tree/master/examples/multipart/). > [examples directory](https://github.com/actix/actix-web/tree/master/examples/multipart/).
## Urlencoded body ## Urlencoded body
Actix provides support for *application/x-www-form-urlencoded* encoded bodies. Actix provides support for *application/x-www-form-urlencoded* encoded bodies.
`HttpResponse::urlencoded()` returns a `HttpResponse::urlencoded()` returns a
[*UrlEncoded*](../actix_web/dev/struct.UrlEncoded.html) future, which resolves [*UrlEncoded*](../actix_web/dev/struct.UrlEncoded.html) future, which resolves
to the deserialized instance, the type of the instance must implement the to the deserialized instance. The type of the instance must implement the
`Deserialize` trait from *serde*. The *UrlEncoded* future can resolve into `Deserialize` trait from *serde*.
a error in several cases:
The *UrlEncoded* future can resolve into an error in several cases:
* content type is not `application/x-www-form-urlencoded` * content type is not `application/x-www-form-urlencoded`
* transfer encoding is `chunked`. * transfer encoding is `chunked`.
@ -294,7 +297,7 @@ fn index(mut req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>> {
*HttpRequest* is a stream of `Bytes` objects. It can be used to read the request *HttpRequest* is a stream of `Bytes` objects. It can be used to read the request
body payload. body payload.
In this example handle reads the request payload chunk by chunk and prints every chunk. In the following example, we read and print the request payload chunk by chunk:
```rust ```rust
# extern crate actix_web; # extern crate actix_web;