Convenience methods for socket paths (#235)

* Added additional tests for socketPath-based requests

Motivation:

While going through the existing tests, I identified a few more instances where we could add some testing.

Modifications:

Added one test that verifies Requests are being decoded correctly, and improved three others to check for path parsing, error throwing, and schema casing respectively.

Result:

Tests that continue to pass, but that will also catch any incompatible changes in the future.

* 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.

* Removed some of the new public methods added for creating a socket-path based request

Motivation:

I previously added too much new public API that will most likely not be necessary, and can be better accessed using a generic execute method.

Modifications:

Removed the get/post/patch/put/delete methods that were specific to socket paths.

Result:

Less new public API.

* Renamed execute(url:) methods such that the HTTP method is the first argument in the parameter list

Motivation:

If these are intended to be general methods for building simple requests, then it makes sense to have the method be the first parameter in the list.

Modifications:

Moved the `method: HTTPMethod` parameter to the front of the list for all `execute([...] url: [...])` methods, and made it default to .GET. I also changed the url parameter to be `urlPath` for the two socketPath based execute methods.

Result:

A cleaner public interface for users of the API.

* Fixed some minor issues introduces with logging

Motivation:

Some of the convenience request methods weren't properly adapted for logging.

Modifications:

- Removed a doc comment from patch() that incorrectly referenced a logger.
- Fixed an issue where patch() would call into post().
- Added a doc comment to delete() that references the logger.
- Tests for the above come in the next commit...

Result:

Correct documentation and functionality for the patch() and delete() methods.

* Updated logging tests to also check the new execute methods

Motivation:

The logging tests previously didn't check for socket path-based requests.

Modifications:

Updated the `testAllMethodsLog()` and `testAllMethodsLog()` tests to include checks for each of the new `execute()` methods.

Result:

Two more tests that pass.

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.execute(.GET, socketPath: "/tmp/myServer.socket", urlPath: "/path/to/resource").whenComplete (...)
+```
+
+Connecting over TLS to a unix domain socket path is possible as well:
+```swift
+let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+httpClient.execute(.POST, secureSocketPath: "/tmp/myServer.socket", urlPath: "/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,7 @@ 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(.GET, url: url, deadline: deadline, logger: logger)
     }
 
     /// Execute `POST` request using specified URL.
@@ -263,12 +258,7 @@ 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(.POST, url: url, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `PATCH` request using specified URL.
@@ -277,9 +267,8 @@ public class HTTPClient {
     ///     - url: Remote URL.
     ///     - body: Request body.
     ///     - 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) -> EventLoopFuture<Response> {
-        return self.post(url: url, body: body, deadline: deadline, logger: HTTPClient.loggingDisabled)
+        return self.patch(url: url, body: body, deadline: deadline, logger: HTTPClient.loggingDisabled)
     }
 
     /// Execute `PATCH` request using specified URL.
@@ -290,12 +279,7 @@ 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(.PATCH, url: url, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `PUT` request using specified URL.
@@ -316,12 +300,7 @@ 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(.PUT, url: url, body: body, deadline: deadline, logger: logger)
     }
 
     /// Execute `DELETE` request using specified URL.
@@ -338,10 +317,65 @@ public class HTTPClient {
     /// - parameters:
     ///     - url: Remote URL.
     ///     - 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(.DELETE, url: url, deadline: deadline, logger: logger)
+    }
+
+    /// Execute arbitrary HTTP request using specified URL.
+    ///
+    /// - parameters:
+    ///     - method: Request method.
+    ///     - url: Request url.
+    ///     - body: Request body.
+    ///     - deadline: Point in time by which the request must complete.
+    ///     - logger: The logger to use for this request.
+    public func execute(_ method: HTTPMethod = .GET, url: String, 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)
+            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:
+    ///     - method: Request method.
+    ///     - socketPath: The path to the unix domain socket to connect to.
+    ///     - urlPath: 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 execute(_ method: HTTPMethod = .GET, socketPath: String, urlPath: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        do {
+            guard let url = URL(httpURLWithSocketPath: socketPath, uri: urlPath) 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:
+    ///     - method: Request method.
+    ///     - secureSocketPath: The path to the unix domain socket to connect to.
+    ///     - urlPath: 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 execute(_ method: HTTPMethod = .GET, secureSocketPath: String, urlPath: String, body: Body? = nil, deadline: NIODeadline? = nil, logger: Logger? = nil) -> EventLoopFuture<Response> {
+        do {
+            guard let url = URL(httpsURLWithSocketPath: secureSocketPath, uri: urlPath) 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

@@ -95,8 +95,8 @@ extension HTTPClient {
     /// Represent HTTP request.
     public struct Request {
         /// Represent kind of Request
-        enum Kind {
-            enum UnixScheme {
+        enum Kind: Equatable {
+            enum UnixScheme: Equatable {
                 case baseURL
                 case http_unix
                 case https_unix
@@ -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/HTTPClientInternalTests+XCTest.swift

@@ -43,6 +43,7 @@ extension HTTPClientInternalTests {
             ("testUploadStreamingIsCalledOnTaskEL", testUploadStreamingIsCalledOnTaskEL),
             ("testWeCanActuallyExactlySetTheEventLoops", testWeCanActuallyExactlySetTheEventLoops),
             ("testTaskPromiseBoundToEL", testTaskPromiseBoundToEL),
+            ("testInternalRequestURI", testInternalRequestURI),
         ]
     }
 }

Tests/AsyncHTTPClientTests/HTTPClientInternalTests.swift

@@ -959,4 +959,31 @@ class HTTPClientInternalTests: XCTestCase {
         XCTAssertTrue(task.futureResult.eventLoop === el2)
         XCTAssertNoThrow(try task.wait())
     }
+
+    func testInternalRequestURI() throws {
+        let request1 = try Request(url: "https://someserver.com:8888/some/path?foo=bar")
+        XCTAssertEqual(request1.kind, .host)
+        XCTAssertEqual(request1.socketPath, "")
+        XCTAssertEqual(request1.uri, "/some/path?foo=bar")
+
+        let request2 = try Request(url: "https://someserver.com")
+        XCTAssertEqual(request2.kind, .host)
+        XCTAssertEqual(request2.socketPath, "")
+        XCTAssertEqual(request2.uri, "/")
+
+        let request3 = try Request(url: "unix:///tmp/file")
+        XCTAssertEqual(request3.kind, .unixSocket(.baseURL))
+        XCTAssertEqual(request3.socketPath, "/tmp/file")
+        XCTAssertEqual(request3.uri, "/")
+
+        let request4 = try Request(url: "http+unix://%2Ftmp%2Ffile/file/path")
+        XCTAssertEqual(request4.kind, .unixSocket(.http_unix))
+        XCTAssertEqual(request4.socketPath, "/tmp/file")
+        XCTAssertEqual(request4.uri, "/file/path")
+
+        let request5 = try Request(url: "https+unix://%2Ftmp%2Ffile/file/path")
+        XCTAssertEqual(request5.kind, .unixSocket(.https_unix))
+        XCTAssertEqual(request5.socketPath, "/tmp/file")
+        XCTAssertEqual(request5.uri, "/file/path")
+    }
 }

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),