Docs

docs/requests/body.md

@@ -106,3 +106,13 @@ basicRequest.body(serializePerson(Person("mary", "smith", 67)))
 ```
 
 See the implementations of the `BasicBody` trait for more options.
+
+## Compressing bodies
+
+Request bodies can be compressed, using an algorithm that's supported by the backend. By default, all backends support the `gzip` and `deflate` compression algorithms.
+
+To compress a request body, use the `request.compressBody(encoding)` method. This will set the the `Content-Encoding` header on the request, as well as compress the body when the request is sent. If the given encoding is not supported by the backend, an exception will be thrown / a failed effect will be returned.
+
+Support for custom compression algorithms can be added at backend creation time, by customising the `compressionHandlers` parameter, and adding a `Compressor` implementation. Such an implementation has to specify the encoding, which it handles, as well as appropriate body transformation (which is backend-specific).
+
+Note that clients often don't know upfront which compression algorithms (if at all) the server supports, and that's why requests are often sent uncompressed. Sending an encoded (compressed) body, when the server doesn't support decompression, might lead to 4xx or 5xx errors.

docs/responses/body.md

@@ -245,3 +245,14 @@ val response: Future[Response[Either[String, Source[ByteString, Any]]]] =
 ```
 
 It's also possible to parse the received stream as server-sent events (SSE), using an implementation-specific mapping function. Refer to the documentation for particular backends for more details.
+
+## Decompressing bodies (handling the Conent-Encoding header)
+
+If the response body is compressed using `gzip` or `deflate` algorithms, it will be decompressed if the `decompressResponseBody` request option is set. By default this is set to `true`, and can be disabled using the `request.disableAutoDecompression` method.
+
+The encoding of the response body is determined by the encodings that are accepted by the client. That's why `basicRequest` and `quickRequest` both have the `Accept-Encoding` header set to `gzip, deflate`. That's in contrast to `emptyRequest`, which has no headers set by default.
+
+If you'd like to use additional decompression algorithms, you'll need to:
+
+* amend the `Accept-Encoding` header that's set on the request
+* add a decompression algorithm to the backend; that can be done on backend creation time, by customising the `compressionHandlers` parameter, and adding a `Decompressor` implementation. Such an implementation has to specify the encoding, which it handles, as well as appropriate body transformation (which is backend-specific).