Akka HTTP, docs: Explain toStrict in more detail

Issue by ktoso
Tuesday Sep 29, 2015 at 18:00 GMT
Originally opened as https://github.com/akka/akka/issues/18599

Based on gitter feedback, we mention toStrict a bit in the model's page, however people are looking for "how do I get a string out". We should answer that question AND explain why it may not be the best idea, then we can ease them into thinking about streaming.

Is this (https://gist.github.com/hakuch/1cd0bdc051bf9d7e8e41) the easiest way to get the body of an HTTP response in a human-readable format? We are using the host-level client, so all responses should be strictly populated.
It seems awfully involved to convert the byte stream to a strict Stream. Surely there must be an easier way?
*strict String

ktoso 19:54
okey, here we go then 😄

1. being host level does not mean that the response is immediatly available
2. Sink.head only takes the first chunk, if the content is very long that's not what you wanted - you want all the chunks together into the string
3. try to avoid Await, instead just .map{ data => } on the future
4. there's a helper 😄 wait...

Docs would be more or less so:

koso 19:56
you want to make the entity "strict", read about the data model here: http://doc.akka.io/docs/akka-stream-and-http-experimental/1.0/scala/http/common/http-model.html#HttpEntity
Streaming entity types (i.e. all but Strict) cannot be shared or serialized. To create a strict, sharable copy of an entity or message use HttpEntity.toStrict or HttpMessage.toStrict which returns a Future of the object with the body data collected into a ByteString.
right, but the server may respond with the data in multiple chunks
by using streaming, we win - we can process them as soon as parts arrive
if you really want to strict it, see above quote
it's a good question though, people will be asking this so I'll open a ticket and improve docs about the specific use case

Start with the linked HTTP model page, especially the HttpEntity section and the references to HttpEntity.toStrict and HttpMessage.toStrict. Update the documentation to explain how to obtain a human-readable string, why streaming responses may be preferable, and why Sink.head and Await can be problematic; done means the use case and tradeoffs are clear.