Support writable streams (process STDIN)

[clue]

Quite a few of the API endpoints take advantage of readable streaming APIs.

In the future, we should also look into streaming outgoing data even after having received the HTTP response header. This is relevant for attaching to read/write streams, such as writing to the STDIN of attached streams.

[clue]

This also refs the command streaming APIs in #13 and #14 (but not #12), see also #36.

[clue]

Implementation depends on clue/reactphp-buzz#135. That issue is nontrivial giving the current APIs, but otherwise this should be fairly straight-forward in this library once the underlying support is there.

[clue]

Implementation now depends on reactphp/http#376.

[bosunski]

@clue how can I help on this? I personally will like to see a writable stream available for execStartStream.

[clue]

@bosunski This currently depends on reactphp/http#376 first in order to support the Upgrade: tcp request header used for https://docs.docker.com/engine/api/v1.24/#42-hijacking. Once that is resolved, implementing this here shouldn't be a lot of work.

We've recently made some major changes to the underlying HTTP client and are currently working on some major new features. This will also allow us to expose the required APIs for this feature, so this really only a matter of time at the moment.

PRs to help with this are always very much appreciated! 👍

[clue]

I've just toyed around with this some more an came up with a working prototype! 🎉

It turns out the Upgrade: tcp request header is entirely optional, so this features doesn't necessarily depend on reactphp/http#376. If we don't use this request header, we can pass in the STDIN as a request body. Here's the gist as a bash script:

$ docker run -id --rm --name foo busybox sh
$ (echo -en "POST /containers/foo/attach?stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1\r\nHost: localhost\r\n\r\n";sleep 0.1;echo -en "whoami\n"; sleep 0.1) | nc -N -U /var/run/docker.sock && echo

I've also created a working prototype for this with ReactPHP. It boils down to using the existing containerAttachStream() API, but passing a ThroughStream for the request body and then combining this with the request stream in a CompositeStream. Known limitations include requiring a (pointless) Content-Length request header to avoid the Transfer-Encoding: chunked request header at the moment and writes to this resulting DuplexStreamInterface are currently discarded before the response headers have been received (see sleep 0.1 in above example).

I don't currently have an immediate use case for this feature, so I'll have to postpone this for now. As much as I'd like to commit to specific date, I can only say that we will get to this feature as soon as time permits.

If you need this for a commercial project and you want to help sponsor this feature, feel free to reach out and I'm happy to take a look.