+Doc #20192 update http example to always consume response (#21241)

The single-request-in-actor-example does not consume the response
in where the status code is not OK.  Although this is unlikely
to cause backpressure issues as the response is likely to have
a HttpEntity.Strict entity, the example is confusing as it
does not follow the warning about always consuming the response.

akka-docs/rst/java/http/client-side/request-level.rst

@@ -58,13 +58,13 @@ to the Actor as a message:
 
 .. warning::
   Be sure to consume the response entities ``dataBytes:Source[ByteString,Unit]`` by for example connecting it
-  to a ``Sink`` (for example ``response.entity.dataBytes.runWith(Sink.ignore)`` if you don't care about the
+  to a ``Sink`` (for example ``response.discardEntityBytes(Materializer)`` if you don't care about the
   response entity), since otherwise Akka HTTP (and the underlying Streams infrastructure) will understand the
   lack of entity consumption as a back-pressure signal and stop reading from the underlying TCP connection!
 
   This is a feature of Akka HTTP that allows consuming entities (and pulling them through the network) in
   a streaming fashion, and only *on demand* when the client is ready to consume the bytes -
-  it may be a bit suprising at first though.
+  it may be a bit surprising at first though.
 
   There are tickets open about automatically dropping entities if not consumed (`#18716`_ and `#18540`_),
   so these may be implemented in the near future.

akka-docs/rst/java/http/implications-of-streaming-http-entity.rst

@@ -7,7 +7,7 @@ Akka HTTP is streaming *all the way through*, which means that the back-pressure
 are exposed through all layers–from the TCP layer, through the HTTP server, all the way up to the user-facing ``HttpRequest``
 and ``HttpResponse`` and their ``HttpEntity`` APIs.
 
-This has suprising implications if you are used to non-streaming / not-reactive HTTP clients.
+This has surprising implications if you are used to non-streaming / not-reactive HTTP clients.
 Specifically it means that: "*lack of consumption of the HTTP Entity, is signaled as back-pressure to the other
 side of the connection*". This is a feature, as it allows one only to consume the entity, and back-pressure servers/clients
 from overwhelming our application, possibly causing un-necessary buffering of the entity in memory.
@@ -15,7 +15,8 @@ from overwhelming our application, possibly causing un-necessary buffering of th
 .. warning::
   Consuming (or discarding) the Entity of a request is mandatory!
   If *accidentally* left neither consumed or discarded Akka HTTP will
-  asume the incoming data should remain back-pressured, and will stall the incoming data via TCP back-pressure mechanisms.
+  assume the incoming data should remain back-pressured, and will stall the incoming data via TCP back-pressure mechanisms.
+  A client should consume the Entity regardless of the status of the ``HttpResponse``.
 
 Client-Side handling of streaming HTTP Entities
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -25,7 +26,7 @@ Consuming the HTTP Response Entity (Client)
 
 The most common use-case of course is consuming the response entity, which can be done via
 running the underlying ``dataBytes`` Source. This is as simple as running the dataBytes source,
-(or on the server-side using directives such as 
+(or on the server-side using directives such as ``BasicDirectives.extractDataBytes``).
 
 It is encouraged to use various streaming techniques to utilise the underlying infrastructure to its fullest,
 for example by framing the incoming chunks, parsing them line-by-line and then connecting the flow into another

akka-docs/rst/scala/code/docs/http/scaladsl/HttpClientExampleSpec.scala

@@ -207,8 +207,9 @@ class HttpClientExampleSpec extends WordSpec with Matchers with CompileOnlySpec
       def receive = {
         case HttpResponse(StatusCodes.OK, headers, entity, _) =>
           log.info("Got response, body: " + entity.dataBytes.runFold(ByteString(""))(_ ++ _))
-        case HttpResponse(code, _, _, _) =>
+        case resp @ HttpResponse(code, _, _, _) =>
           log.info("Request failed, response code: " + code)
+          resp.discardEntityBytes()
       }
 
     }

akka-docs/rst/scala/http/client-side/request-level.rst

@@ -68,13 +68,13 @@ Example
 
 .. warning::
   Be sure to consume the response entities ``dataBytes:Source[ByteString,Unit]`` by for example connecting it
-  to a ``Sink`` (for example ``response.entity.dataBytes.runWith(Sink.ignore)`` if you don't care about the
+  to a ``Sink`` (for example ``response.discardEntityBytes()`` if you don't care about the
   response entity), since otherwise Akka HTTP (and the underlying Streams infrastructure) will understand the
   lack of entity consumption as a back-pressure signal and stop reading from the underlying TCP connection!
 
   This is a feature of Akka HTTP that allows consuming entities (and pulling them through the network) in
   a streaming fashion, and only *on demand* when the client is ready to consume the bytes -
-  it may be a bit suprising at first though.
+  it may be a bit surprising at first though.
 
   There are tickets open about automatically dropping entities if not consumed (`#18716`_ and `#18540`_),
   so these may be implemented in the near future.

akka-docs/rst/scala/http/implications-of-streaming-http-entity.rst

@@ -7,7 +7,7 @@ Akka HTTP is streaming *all the way through*, which means that the back-pressure
 are exposed through all layers–from the TCP layer, through the HTTP server, all the way up to the user-facing ``HttpRequest``
 and ``HttpResponse`` and their ``HttpEntity`` APIs.
 
-This has suprising implications if you are used to non-streaming / not-reactive HTTP clients.
+This has surprising implications if you are used to non-streaming / not-reactive HTTP clients.
 Specifically it means that: "*lack of consumption of the HTTP Entity, is signaled as back-pressure to the other
 side of the connection*". This is a feature, as it allows one only to consume the entity, and back-pressure servers/clients
 from overwhelming our application, possibly causing un-necessary buffering of the entity in memory.
@@ -15,7 +15,8 @@ from overwhelming our application, possibly causing un-necessary buffering of th
 .. warning::
   Consuming (or discarding) the Entity of a request is mandatory!
   If *accidentally* left neither consumed or discarded Akka HTTP will
-  asume the incoming data should remain back-pressured, and will stall the incoming data via TCP back-pressure mechanisms.
+  assume the incoming data should remain back-pressured, and will stall the incoming data via TCP back-pressure mechanisms.
+  A client should consume the Entity regardless of the status of the ``HttpResponse``.
 
 Client-Side handling of streaming HTTP Entities
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -25,7 +26,7 @@ Consuming the HTTP Response Entity (Client)
 
 The most common use-case of course is consuming the response entity, which can be done via
 running the underlying ``dataBytes`` Source. This is as simple as running the dataBytes source,
-(or on the server-side using directives such as 
+(or on the server-side using directives such as ``BasicDirectives.extractDataBytes``).
 
 It is encouraged to use various streaming techniques to utilise the underlying infrastructure to its fullest,
 for example by framing the incoming chunks, parsing them line-by-line and then connecting the flow into another