Added some convenience initializers to URL and methods to Request for making requests to socket paths

Motivation:

Creating URLs for connecting to servers bound to socket paths currently requires some additional code to get exactly right. It would be nice to have convenience methods on both URL and Request to assist here.

Modifications:

- Refactored the get/post/patch/put/delete methods so they all call into a one line execute() method.
- Added variations on the above methods so they can be called with socket paths (both over HTTP and HTTPS).
- Added public convenience initializers to URL to support the above, and so socket path URLs can be easily created in other situations.
- Added unit tests for creating socket path URLs, and testing the new suite of convenience execute methods (that, er, test `HTTPMETHOD`s). (patch, put, and delete are now also tested as a result of these tests)
- Updated the read me with basic usage instructions.

Result:

New methods that allow for easily creating requests to socket paths, and passing tests to go with them.

Author: dimitribouniol

README.md

@@ -157,3 +157,22 @@ httpClient.execute(request: request, delegate: delegate).futureResult.whenSucces
     print(count)
 }
 ```
+
+### Unix Domain Socket Paths
+Connecting to servers bound to socket paths is easy:
+```swift
+let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+httpClient.get(socketPath: "/tmp/myServer.socket", url: "/path/to/resource").whenComplete (...)
+```
+
+Connecting over TLS to a unix domain socket path is possible as well:
+```swift
+let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+httpClient.post(secureSocketPath: "/tmp/myServer.socket", url: "/path/to/resource", body: .string("hello")).whenComplete (...)
+```
+
+Direct URLs can easily be contructed to be executed in other scenarios:
+```swift
+let socketPathBasedURL = URL(httpURLWithSocketPath: "/tmp/myServer.socket", uri: "/path/to/resource")
+let secureSocketPathBasedURL = URL(httpsURLWithSocketPath: "/tmp/myServer.socket", uri: "/path/to/resource")
+```

Sources/AsyncHTTPClient/HTTPClient.swift

@@ -237,12 +237,29 @@ public class HTTPClient {
     ///     - deadline: Point in time by which the request must complete.
     ///     - logger: The logger to use for this request.
     public func get(url: String, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response> {
-        do {
-            let request = try Request(url: url, method: .GET)
-            return self.execute(request: request, deadline: deadline, logger: logger)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .GET, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `GET` request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func get(socketPath: String, url: String, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .GET, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `GET` request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func get(secureSocketPath: String, url: String, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .GET, deadline: deadline, logger: logger)
     }
 
     /// Execute `POST` request using specified URL.
@@ -263,12 +280,31 @@ public class HTTPClient {
     ///     - deadline: Point in time by which the request must complete.
     ///     - logger: The logger to use for this request.
     public func post(url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response> {
-        do {
-            let request = try HTTPClient.Request(url: url, method: .POST, body: body)
-            return self.execute(request: request, deadline: deadline, logger: logger)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .POST, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `POST` request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func post(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .POST, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `POST` request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func post(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .POST, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `PATCH` request using specified URL.
@@ -289,12 +325,31 @@ public class HTTPClient {
     ///     - deadline: Point in time by which the request must complete.
     ///     - logger: The logger to use for this request.
     public func patch(url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response> {
-        do {
-            let request = try HTTPClient.Request(url: url, method: .PATCH, body: body)
-            return self.execute(request: request, deadline: deadline, logger: logger)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .PATCH, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `PATCH` request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func patch(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .PATCH, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `PATCH` request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func patch(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .PATCH, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `PUT` request using specified URL.
@@ -315,12 +370,31 @@ public class HTTPClient {
     ///     - deadline: Point in time by which the request must complete.
     ///     - logger: The logger to use for this request.
     public func put(url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response> {
-        do {
-            let request = try HTTPClient.Request(url: url, method: .PUT, body: body)
-            return self.execute(request: request, deadline: deadline, logger: logger)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .PUT, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `PUT` request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func put(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .PUT, body: body, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `PUT` request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func put(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .PUT, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `DELETE` request using specified URL.
@@ -339,9 +413,85 @@ public class HTTPClient {
     ///     - deadline: The time when the request must have been completed by.
     ///     - logger: The logger to use for this request.
     public func delete(url: String, deadline: NIODeadline? = nil, logger: Logger) -> EventLoopFuture<Response> {
+        return self.execute(url: url, method: .DELETE, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `DELETE` request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - deadline: The time when the request must have been completed by.
+    ///     - logger: The logger to use for this request.
+    public func delete(socketPath: String, url: String, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .DELETE, deadline: deadline, logger: logger)
+    }
+
+    /// Execute `DELETE` request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - deadline: The time when the request must have been completed by.
+    ///     - logger: The logger to use for this request.
+    public func delete(secureSocketPath: String, url: String, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .DELETE, deadline: deadline, logger: logger)
+    }
+
+    /// Execute arbitrary HTTP request using specified URL.
+    ///
+    /// - parameters:
+    ///     - url: Request url.
+    ///     - method: Request method.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func execute(url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        do {
+            let request = try Request(url: url, method: method, body: body)
+            return self.execute(request: request, deadline: deadline, logger: logger ?? HTTPClient.loggingDisabled)
+        } catch {
+            return self.eventLoopGroup.next().makeFailedFuture(error)
+        }
+    }
+
+    /// Execute arbitrary HTTP+UNIX request to a unix domain socket path, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - method: Request method.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func execute(socketPath: String, url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        do {
+            guard let url = URL(httpURLWithSocketPath: socketPath, uri: url) else {
+                throw HTTPClientError.invalidURL
+            }
+            let request = try Request(url: url, method: method, body: body)
+            return self.execute(request: request, deadline: deadline, logger: logger ?? HTTPClient.loggingDisabled)
+        } catch {
+            return self.eventLoopGroup.next().makeFailedFuture(error)
+        }
+    }
+
+    /// Execute arbitrary HTTPS+UNIX request to a unix domain socket path over TLS, using the specified URL as the request to send to the server.
+    ///
+    /// - parameters:
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - url: The URL path and query that will be sent to the server.
+    ///     - method: Request method.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func execute(secureSocketPath: String, url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
         do {
-            let request = try Request(url: url, method: .DELETE)
-            return self.execute(request: request, deadline: deadline, logger: logger)
+            guard let url = URL(httpsURLWithSocketPath: secureSocketPath, uri: url) else {
+                throw HTTPClientError.invalidURL
+            }
+            let request = try Request(url: url, method: method, body: body)
+            return self.execute(request: request, deadline: deadline, logger: logger ?? HTTPClient.loggingDisabled)
         } catch {
             return self.eventLoopGroup.next().makeFailedFuture(error)
         }

Sources/AsyncHTTPClient/HTTPHandler.swift

@@ -516,6 +516,36 @@ extension URL {
     func hasTheSameOrigin(as other: URL) -> Bool {
         return self.host == other.host && self.scheme == other.scheme && self.port == other.port
     }
+
+    /// Initializes a newly created HTTP URL connecting to a unix domain socket path. The socket path is encoded as the URL's host, replacing percent encoding invalid path characters, and will use the "http+unix" scheme.
+    /// - Parameters:
+    ///   - socketPath: The path to the unix domain socket to connect to.
+    ///   - uri: The URI path and query that will be sent to the server.
+    public init?(httpURLWithSocketPath socketPath: String, uri: String = "/") {
+        guard let host = socketPath.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed) else { return nil }
+        var urlString: String
+        if uri.hasPrefix("/") {
+            urlString = "http+unix://\(host)\(uri)"
+        } else {
+            urlString = "http+unix://\(host)/\(uri)"
+        }
+        self.init(string: urlString)
+    }
+
+    /// Initializes a newly created HTTPS URL connecting to a unix domain socket path over TLS. The socket path is encoded as the URL's host, replacing percent encoding invalid path characters, and will use the "https+unix" scheme.
+    /// - Parameters:
+    ///   - socketPath: The path to the unix domain socket to connect to.
+    ///   - uri: The URI path and query that will be sent to the server.
+    public init?(httpsURLWithSocketPath socketPath: String, uri: String = "/") {
+        guard let host = socketPath.addingPercentEncoding(withAllowedCharacters: .urlHostAllowed) else { return nil }
+        var urlString: String
+        if uri.hasPrefix("/") {
+            urlString = "https+unix://\(host)\(uri)"
+        } else {
+            urlString = "https+unix://\(host)/\(uri)"
+        }
+        self.init(string: urlString)
+    }
 }
 
 extension HTTPClient {

Tests/AsyncHTTPClientTests/HTTPClientTestUtils.swift

@@ -439,6 +439,11 @@ internal final class HttpBinHandler: ChannelInboundHandler {
                 headers.add(name: "X-Calling-URI", value: req.uri)
                 self.resps.append(HTTPResponseBuilder(status: .ok, headers: headers))
                 return
+            case "/echo-method":
+                var headers = self.responseHeaders
+                headers.add(name: "X-Method-Used", value: req.method.rawValue)
+                self.resps.append(HTTPResponseBuilder(status: .ok, headers: headers))
+                return
             case "/ok":
                 self.resps.append(HTTPResponseBuilder(status: .ok))
                 return

Tests/AsyncHTTPClientTests/HTTPClientTests+XCTest.swift

@@ -28,6 +28,10 @@ extension HTTPClientTests {
             ("testRequestURI", testRequestURI),
             ("testBadRequestURI", testBadRequestURI),
             ("testSchemaCasing", testSchemaCasing),
+            ("testURLSocketPathInitializers", testURLSocketPathInitializers),
+            ("testConvenienceExecuteMethods", testConvenienceExecuteMethods),
+            ("testConvenienceExecuteMethodsOverSocket", testConvenienceExecuteMethodsOverSocket),
+            ("testConvenienceExecuteMethodsOverSecureSocket", testConvenienceExecuteMethodsOverSecureSocket),
             ("testGet", testGet),
             ("testGetWithDifferentEventLoopBackpressure", testGetWithDifferentEventLoopBackpressure),
             ("testPost", testPost),