libcurl: add UNIX domain sockets support

The ability to do HTTP requests over a UNIX domain socket has been
requested before, in Apr 2008 [0][1] and Sep 2010 [2]. While a
discussion happened, no patch seems to get through. I decided to give it
a go since I need to test a nginx HTTP server which listens on a UNIX
domain socket.

One patch [3] seems to make it possible to use the
CURLOPT_OPENSOCKETFUNCTION function to gain a UNIX domain socket.
Another person wrote a Go program which can do HTTP over a UNIX socket
for Docker[4] which uses a special URL scheme (though the name contains
cURL, it has no relation to the cURL library).

This patch considers support for UNIX domain sockets at the same level
as HTTP proxies / IPv6, it acts as an intermediate socket provider and
not as a separate protocol. Since this feature affects network
operations, a new feature flag was added ("unix-sockets") with a
corresponding CURL_VERSION_UNIX_SOCKETS macro.

A new CURLOPT_UNIX_SOCKET_PATH option is added and documented. This
option enables UNIX domain sockets support for all requests on the
handle (replacing IP sockets and skipping proxies).

A new configure option (--enable-unix-sockets) and CMake option
(ENABLE_UNIX_SOCKETS) can disable this optional feature. Note that I
deliberately did not mark this feature as advanced, this is a
feature/component that should easily be available.

 [0]: http://curl.haxx.se/mail/lib-2008-04/0279.html
 [1]: http://daniel.haxx.se/blog/2008/04/14/http-over-unix-domain-sockets/
 [2]: http://sourceforge.net/p/curl/feature-requests/53/
 [3]: http://curl.haxx.se/mail/lib-2008-04/0361.html
 [4]: https://github.com/Soulou/curl-unix-socket

Signed-off-by: Peter Wu <peter@lekensteyn.nl>

1 files changed, 76 insertions, 0 deletions

diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3
new file mode 100644
index 000000000..880c2f71f
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3
@@ -0,0 +1,76 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_UNIX_SOCKET_PATH 3 "09 Oct 2014" "libcurl 7.40.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_UNIX_SOCKET_PATH \- set UNIX domain socket
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path);
+.SH DESCRIPTION
+Enables the use of UNIX domain sockets as connection end point and sets the path
+to \fIpath\fP. If \fIpath\fP is NULL, then UNIX domain sockets are disabled. An
+empty string will result in an error at some point.
+
+When enabled, cURL will connect to the UNIX domain socket instead of
+establishing a TCP connection to a host. Since no TCP connection is established,
+cURL does not need to resolve the DNS hostname in the URL.
+
+The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms
+might be even less.
+
+Proxy and TCP options such as
+.BR CURLOPT_TCP_NODELAY "(3)
+are not supported. Proxy options such as
+.BR CURLOPT_PROXY "(3)
+have no effect either as these are TCP-oriented, and asking a proxy server to
+connect to a certain UNIX domain socket is not possible.
+.SH DEFAULT
+Default is NULL, meaning that no UNIX domain sockets are used.
+.SH PROTOCOLS
+All protocols except for file:// and FTP are supported in theory. HTTP, IMAP,
+POP3 and SMTP should in particular work (including their SSL/TLS variants).
+.SH EXAMPLE
+Given that you have an nginx server running, listening on /tmp/nginx.sock, you
+can request a HTTP resource with:
+
+    curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
+    curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
+
+If you are on Linux and somehow have a need for paths larger than 107 bytes, you
+could use the proc filesystem to bypass the limitation:
+
+    int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
+    char path[108];
+    snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
+    curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
+    /* Be sure to keep dirfd valid until you discard the handle */
+
+.SH AVAILABILITY
+Since 7.40.0.
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLOPT_OPENSOCKETFUNCTION "(3)
+,
+.BR unix "(7)