Implement communication via Unix domain sockets (UDS)

[clue]

Depends on reactphp-legacy/socket-client#41

[clue]

This is actually ready, this very likely only requires some tests and documentation 👍

[clue]

Functionally, this has been ready for years, for example I've been using with via https://github.com/clue/php-buzz-react#unix-domain-sockets for https://github.com/clue/php-docker-react, but I've never been quite happy with this API.

The question remains: How (whether?) should this be exposed to the API of this project. This project is designed around the concept of URLs for sending HTTP requests either via plaintext TCP/IP or secure TLS sockets. For UDS, we essentially need to do the same thing, but only over UDS sockets.

Docker for example has a single listening socket under unix:///var/run/docker.sock by default. You can send normal HTTP requests to this socket and request information by sending a request such as this:

GET /info HTTP/1.1
Host: localhost

If we were to expose this functionality through our API, what URL should be passed here? Also, do we really want any outside location to be able to redirect to such an URL? Hint: We probably do not want this. Also, should we assume localhost for the Host header here?

As such, it's my understanding that UDS should probably not be enabled by default unless explicitly configured. Instead of breaking the existing API I would suggest using some kind of hostname-to-UDS-mapping so that the HTTP API does not really notice this at all. For example, this would allow the consumer of this package to explicitly map docker.localhost:8888 to unix:///var/run/docker.sock so that the URL http://docker.localhost:8888/info would send the above request with a Host: docker.localhost:8888 header in this case.

What do you think? Any input would be much appreciated! 👍

[clue]

• libcurl now has a CURLOPT_UNIX_SOCKET_PATH option that can be used to explicitly use a Unix domain socket (UDS) path: https://curl.haxx.se/libcurl/c/CURLOPT_UNIX_SOCKET_PATH.html
• Similarly, the curl binary now accepts a --unix-socket option: https://superuser.com/questions/834307/can-curl-send-requests-to-sockets
• The php-http/socket-client package a remote_socket option which allows to set a UDS path: http://docs.php-http.org/en/latest/clients/socket-client.html#usage

They all share that UDS support has to be configured explicitly and is not enabled by default. The all also only support a single path, which means that once configured, every request will be sent to the given UDS path.

I think a similar approach would work fine here. As such, I've just filed reactphp/socket#117 which would allow creating an explicit connector instance which can be passed to the Client so that the existing API remains entirely unchanged. Once this PR is in, we only need to update the dependency and add some documentation here