This is currently not to be merged, but while reviewing another PR, I was
considering "this test could be an integration test", and then recalled
why I didn't do this in the past.

The TL;DR is that client.ImagePull (as well as other functions that use
a streaming endpoint) is very hard to consume. To use these functions,
a great amount of boiler-plating code, as well as custom logic is needed,
and the utilities to help with this (`pkg/jsonmessage` and/or `pkg/progress`,
which both seem to be serving similar functionality), are poorly written;

Looking at this (client.ImagePull) example:

- The error returned is only for the initial request (which is "reasonable",
  and makes sense for some situations, but is definitely not intuitive).
- A result of that is that _not_ handling the stream means "cancelling" the
  pull.
- To get errors that occur during the pull, it's required to process the
  stream using the `jsonmessage` package. And the utilities in this package
  are tightly integrated with _presenting_ the stream (i.e., error-handling
  is part of "presenting" the stream).
- Because of this coupling, it also expects things like "do we have a terminal
  attached"? (and if so: its file-descriptor), which is irrelevant for many
  scenarios where the pull is to be used for purposes other than a pull on
  the command-line.
- _if_ we get an error, it's a `JSONError`, which _does_ have a status-code
  (although it appears to not be used) and cannot be handled by the `errdefs`
  package.

We should make this better. Some options to consider:

- (lower hanging fruit): add an "synchronous" option, and move the stream-
  handling logic into the `ImagePull` function. This makes the function
  handle the pull from start to finish, printing the output (if `io.writers`
  are passed for this), and returns any error that occurs while pulling,
  which could be either the initial error (making the request), or errors
  during the pull.
- It would also make sure to return errors with a correct `errdefs` type
  for further processing.
- For the longer term, we must rewrite the `pkg/jsonmessage`, as well as
  the `pkg/progress` packages: remove the duplication, and make sure we
  have a canonical implementation where needed.
- But also separate _handling_ the stream from _presenting_ the stream;
  presentation should be separate, and something the consumer should be
  able to have full control over.
- This would be smilar to the `auxCallback` which was added at some point,
  but instead, any presentation function / callback should be optional
  (possibly some default with printing to a vanilla io.writer: TBD).

Signed-off-by: Sebastiaan van Stijn <[email protected]>