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

dimitribouniol · dimitribouniol · commit affa03fd7544 · 2020-06-09T13:51:07.000-07:00
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.
diff --git a/README.md b/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")
+```
diff --git a/Sources/AsyncHTTPClient/HTTPClient.swift b/Sources/AsyncHTTPClient/HTTPClient.swift
@@ -194,12 +194,27 @@ public class HTTPClient {
     ///     - url: Remote URL.
     ///     - deadline: Point in time by which the request must complete.
     public func get(url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
-        do {
-            let request = try Request(url: url, method: .GET)
-            return self.execute(request: request, deadline: deadline)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .GET, deadline: deadline)
+    }
+
+    /// 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.
+    public func get(socketPath: String, url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .GET, deadline: deadline)
+    }
+
+    /// 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.
+    public func get(secureSocketPath: String, url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .GET, deadline: deadline)
     }
 
     /// Execute `POST` request using specified URL.
@@ -209,12 +224,29 @@ public class HTTPClient {
     ///     - body: Request body.
     ///     - deadline: Point in time by which the request must complete.
     public func post(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
-        do {
-            let request = try HTTPClient.Request(url: url, method: .POST, body: body)
-            return self.execute(request: request, deadline: deadline)
-        } catch {
-            return self.eventLoopGroup.next().makeFailedFuture(error)
-        }
+        return self.execute(url: url, method: .POST, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func post(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .POST, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func post(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .POST, body: body, deadline: deadline)
     }
 
     /// Execute `PATCH` request using specified URL.
@@ -224,37 +256,142 @@ public class HTTPClient {
     ///     - body: Request body.
     ///     - deadline: Point in time by which the request must complete.
     public func patch(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(url: url, method: .PATCH, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func patch(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .PATCH, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func patch(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .PATCH, body: body, deadline: deadline)
+    }
+
+    /// Execute `PUT` request using specified URL.
+    ///
+    /// - parameters:
+    ///     - url: Remote URL.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    public func put(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(url: url, method: .PUT, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func put(socketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .PUT, body: body, deadline: deadline)
+    }
+
+    /// 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.
+    public func put(secureSocketPath: String, url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .PUT, body: body, deadline: deadline)
+    }
+
+    /// Execute `DELETE` request using specified URL.
+    ///
+    /// - parameters:
+    ///     - url: Remote URL.
+    ///     - deadline: The time when the request must have been completed by.
+    public func delete(url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(url: url, method: .DELETE, deadline: deadline)
+    }
+
+    /// 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.
+    public func delete(socketPath: String, url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(socketPath: socketPath, url: url, method: .DELETE, deadline: deadline)
+    }
+
+    /// 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.
+    public func delete(secureSocketPath: String, url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+        return self.execute(secureSocketPath: secureSocketPath, url: url, method: .DELETE, deadline: deadline)
+    }
+
+    /// 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.
+    public func execute(url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
         do {
-            let request = try HTTPClient.Request(url: url, method: .PATCH, body: body)
+            let request = try Request(url: url, method: method, body: body)
             return self.execute(request: request, deadline: deadline)
         } catch {
             return self.eventLoopGroup.next().makeFailedFuture(error)
         }
     }
 
-    /// Execute `PUT` request using specified URL.
+    /// Execute arbitrary HTTP+UNIX request to a unix domain socket path, using the specified URL as the request to send to the server.
     ///
     /// - parameters:
-    ///     - url: Remote URL.
+    ///     - 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.
-    public func put(url: String, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+    public func execute(socketPath: String, url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
         do {
-            let request = try HTTPClient.Request(url: url, method: .PUT, body: body)
+            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)
         } catch {
             return self.eventLoopGroup.next().makeFailedFuture(error)
         }
     }
 
-    /// Execute `DELETE` request using specified URL.
+    /// 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:
-    ///     - url: Remote URL.
-    ///     - deadline: The time when the request must have been completed by.
-    public func delete(url: String, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
+    ///     - 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.
+    public func execute(secureSocketPath: String, url: String, method: HTTPMethod, body: Body? = nil, deadline: NIODeadline? = nil) -> EventLoopFuture<Response> {
         do {
-            let request = try Request(url: url, method: .DELETE)
+            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)
         } catch {
             return self.eventLoopGroup.next().makeFailedFuture(error)
diff --git a/Sources/AsyncHTTPClient/HTTPHandler.swift b/Sources/AsyncHTTPClient/HTTPHandler.swift
@@ -519,6 +519,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 {
diff --git a/Tests/AsyncHTTPClientTests/HTTPClientTestUtils.swift b/Tests/AsyncHTTPClientTests/HTTPClientTestUtils.swift
@@ -437,6 +437,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
diff --git a/Tests/AsyncHTTPClientTests/HTTPClientTests+XCTest.swift b/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),
diff --git a/Tests/AsyncHTTPClientTests/HTTPClientTests.swift b/Tests/AsyncHTTPClientTests/HTTPClientTests.swift
