client: make streaming functions easier to consume #46528
Labels
area/api
area/cli
kind/enhancement
Enhancements are not bugs or new features but can improve usability or performance.
kind/refactor
PR's that refactor, or clean-up code
Description
This is just a quick draft, related to #46527, but there's been other discussions in this area that I may add here. This ticket should also be added to an epic (to be created) about improving the client (or providing a better sdk / better tools for functionality that's currently living in docker/cli, but should be more easy to consume).
The client.ImagePull (as well as other functions that use a streaming endpoint)
function 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/orpkg/progress
, which both seem to beserving similar functionality), are poorly written;
Looking at this (client.ImagePull) example:
and makes sense for some situations, but is definitely not intuitive).
pull.
stream using the
jsonmessage
package. And the utilities in this packageare tightly integrated with presenting the stream (i.e., error-handling
is part of "presenting" the stream).
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.
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:
handling logic into the
ImagePull
function. This makes the functionhandle 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.
errdefs
typefor further processing.
pkg/jsonmessage
, as well asthe
pkg/progress
packages: remove the duplication, and make sure wehave a canonical implementation where needed.
presentation should be separate, and something the consumer should be
able to have full control over.
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).
The text was updated successfully, but these errors were encountered: