📚 ♻️ ✨ Adds response to retriers. General documentation.

- Passes a response, if any, to retriers.
- Improves documentation of various HTTPNetworking types.
- Converts `HTTPMethod` to a struct for external extensibility purposes.

Author: connor-ricks

Sources/HTTPNetworking/HTTPClient.swift

@@ -2,7 +2,7 @@ import Foundation
 
 /// `HTTPClient` creates and manages requests over the network.
 ///
-/// The client also provides common functionality for all  ``HTTPRequest`` objects, including encoding and decoding strategies,
+/// The client provides common functionality for all  ``HTTPRequest`` objects, including encoding and decoding strategies,
 /// request adaptation, response validation and retry stratagies.
 ///
 /// Generally an ``HTTPClient`` is used to manage the interaction with a single API service. Most APIs
@@ -12,20 +12,37 @@ import Foundation
 /// If your API requires a custom encoder or decoder, you can provide your own custom ones to the client. These encoder and decoders
 /// will then be used for all requests made using the client.
 ///
+/// ## Adaptors
+///
 /// If your API requires some sort of repetitive task applied to each request, rather than manipulating it at each call, you can make use of an
 /// ``HTTPRequestAdaptor``. The adaptors that you provide to the client will all be run on a request before it is sent to your API.
 /// This provides you with an opportunity to insert various headers or perform asyncrounous tasks before sending the outbound request.
 ///
+/// > Important: All adaptors will always run for every request.
+///
+/// ## Validators
+///
 /// Different APIs require different forms of validation that help you determine if a request was successful or not.
 /// The default ``HTTPClient`` makes no assumptions about the format and/or success of an API's response. Instead, you can make use of an
 /// ``HTTPResponseValidator``. The validators that you provide the client will all be run on the response received by your API.
 /// This provides you with an opportunity to determine wether or not the response was a success and failure, and consolidate potentially repeated logic in one place.
 ///
+/// > Important: Validators will be run one by one on a request's response. If any validators determines that the response is invalid,
+/// the request will fail and throw the error returned by that validator. No other subsequent validators will be run for that run of a request.
+///
+/// ## Retriers
+///
 /// Sometimes you may want to implement logic for handling retries of failed requests. An ``HTTPClient`` can make use of an
 /// ``HTTPRequestRetriers``. The retriers that you provide the client will be run when a request fails.
 /// This provides you with an opportunity to observe the error and determine wether or not the request should be sent again. You can implement complex retry
 /// logic across your entire client without having to repeat yourself.
 ///
+/// > Important: Retriers will be run one by one in the event of a failed request. If any retrier concedes that the request should not be retried,
+/// the request will ask the next retrier if the request should be retried. If any retrier determines that a request should be retired, the request will
+/// immedietly be retired, without asking any subsequent retriers.
+///
+/// ## Request Manipulation
+///
 /// In addition to providing adaptors, validators and retriers to your entire client, you can provide additional configuration to each
 /// request using a chaining style syntax. This allows you to add additional configuration to endpoints that you may want to provide further
 /// customization to beyond the standard configuration at the client level.
@@ -44,17 +61,7 @@ import Foundation
 /// let response = try await request.run()
 /// ```
 ///
-/// > Note: All adaptors, validators and retriers at the client level will be run first, after which the
-/// request configurations at the request level will be run.
-///
-/// > Important: All adaptors will always run for every request.
-///
-/// > Important: Validators will be run one by one on a request's response. If any validators determines that the response is invalid,
-/// the request will fail and throw the error returned by that validator. No other subsequent validators will be run for that run of a request.
-///
-/// > Important: Retriers will be run one by one in the event of a failred request. If any retrier concedes that the request should not be retried,
-/// the request will ask the next retrier if the request should be retried. If any retrier determines that a request should be retired, the request will
-/// immedietly be retired, without asking any subsequent retriers.
+/// > Note: For all adaptors, validators and retriers, the client level plugins will run before the request level plugins
 public struct HTTPClient {
 
     // MARK: Properties

Sources/HTTPNetworking/HTTPDispatcher.swift

@@ -18,7 +18,7 @@ public struct HTTPDispatcher {
     }
 
     /// Fetches data using the provided request.
-    func data(for request: URLRequest) async throws -> (Data, HTTPURLResponse) {
+    func data(for request: URLRequest) async throws -> (data: Data, response: HTTPURLResponse) {
         let (data, response) = try await session.data(for: request)
         guard let response = response as? HTTPURLResponse else {
             throw URLError(.cannotParseResponse)
@@ -46,7 +46,7 @@ extension HTTPDispatcher {
     /// A mock implementation of an ``HTTPDispatcher`` that will return the provided
     /// response to the corresponding request.
     ///
-    /// - Parameter responses: A dictionary of responses keyed by the requests for which they should respond to.
+    /// - Parameter responses: A dictionary of responses keyed by the urls for which they should respond to.
     /// - Returns: An ``HTTPDispatcher``
     public static func mock(
         responses: [URL: MockResponse]

Sources/HTTPNetworking/HTTPMethod.swift

@@ -1,23 +1,39 @@
 import Foundation
 
-/// An HTTP method for an HTTP request.
-public enum HTTPMethod: String {
-    /// The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.
-    case get
-    /// The HEAD method asks for a response identical to that of a GET request, but without the response body.
-    case head
-    /// The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
-    case post
-    /// The PUT method replaces all current representations of the target resource with the request payload.
-    case put
-    /// The DELETE method deletes the specified resource.
-    case delete
-    /// The CONNECT method establishes a tunnel to the server identified by the target resource.
-    case connect
-    /// The OPTIONS method is used to describe the communication options for the target resource.
-    case options
-    /// The TRACE method performs a message loop-back test along the path to the target resource.
-    case trace
-    /// The PATCH method is used to apply partial modifications to a resource.
-    case patch
+/// A type representing HTTP methods.
+///
+/// See [RFC 9110 - Section 9](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) for more information.
+public struct HTTPMethod: RawRepresentable, Equatable, Hashable {
+    /// The `GET` method requests a representation of the specified resource. Requests using GET should only retrieve data.
+    public static let get = HTTPMethod(rawValue: "GET")
+    
+    /// The `HEAD` method asks for a response identical to that of a GET request, but without the response body.
+    public static let head = HTTPMethod(rawValue: "HEAD")
+    
+    /// The `POST` method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
+    public static let post = HTTPMethod(rawValue: "POST")
+    
+    /// The `PUT` method replaces all current representations of the target resource with the request payload.
+    public static let put = HTTPMethod(rawValue: "PUT")
+    
+    /// The `DELETE` method deletes the specified resource.
+    public static let delete = HTTPMethod(rawValue: "DELETE")
+    
+    /// The `CONNECT` method establishes a tunnel to the server identified by the target resource.
+    public static let connect = HTTPMethod(rawValue: "CONNECT")
+    
+    /// The `OPTIONS` method is used to describe the communication options for the target resource.
+    public static let options = HTTPMethod(rawValue: "OPTIONS")
+    
+    /// The `TRACE` method performs a message loop-back test along the path to the target resource.
+    public static let trace = HTTPMethod(rawValue: "TRACE")
+    
+    /// The `PATCH` method is used to apply partial modifications to a resource.
+    public static let patch = HTTPMethod(rawValue: "PATCH")
+    
+    public let rawValue: String
+    
+    public init(rawValue: String) {
+        self.rawValue = rawValue.uppercased()
+    }
 }

Sources/HTTPNetworking/HTTPRequest.swift

@@ -8,16 +8,19 @@ import Foundation
 ///
 /// To send an ``HTTPRequest`` call ``run()``. This will perform the network request ant return the expected response type.
 ///
-/// You can adapt the `URLRequest`, before it gets sent out, by calling ``adapt(_:)`` or ``adapt(with:)``.
-/// By providing an ``AdaptationHandler`` or ``HTTPRequestAdaptor``, you can perform various asyncronous logic before a request gets sent
+/// Each ``HTTPRequest`` is setup with concurrency in mind. In-flight requests are periodically checked for `Task` cancellation and will approprietly stop
+/// when their parent task is cancelled.
+///
+/// > Tip: You can adapt the `URLRequest`, before it gets sent out, by calling methods like ``adapt(_:)`` or ``adapt(with:)``.
+/// By providing an ``AdaptationHandler`` or any ``HTTPRequestAdaptor``, you can perform various asyncronous logic before a request gets sent
 /// Typical use cases include things like adding headers to requests, or managing the lifecycle of a client's authorization status.
 ///
-/// You can validate the `HTTPURLResponse`, before it gets deocded, by calling ``validate(_:)`` or ``validate(with:)``.
-/// By providing a ``ValidationHandler`` or ``HTTPResponseValidator``, you can perform various validations before a response is decoded.
+/// > Tip: You can validate the `HTTPURLResponse`, before it gets deocded, by calling  methods like ``validate(_:)`` or ``validate(with:)``.
+/// By providing a ``ValidationHandler`` or any ``HTTPResponseValidator``, you can perform various validations before a response is decoded.
 /// Typical use cases include things like validating the status code or headers of a request.
 ///
-/// You can retry the ``HTTPRequest`` if it fails by calling ``retry(_:)`` or ``retry(with:)``.
-/// By providing a ``RetryHandler`` or ``HTTPRequestRetrier``, you can determine if a request should be retried if it fails.
+/// > Tip: You can retry the ``HTTPRequest`` if it fails by calling retry methods like ``retry(_:)`` or ``retry(with:)``.
+/// By providing a ``RetryHandler`` or any ``HTTPRequestRetrier``, you can determine if a request should be retried if it fails.
 /// Typical use cases include retrying requests a given number of times in the event of poor network connectivity.
 public class HTTPRequest<Value: Decodable> {
 
@@ -69,6 +72,8 @@ public class HTTPRequest<Value: Decodable> {
     /// Executes the request to the dispatcher.
     private func execute(previousAttempts: Int) async throws -> Value {
         var request = self.request
+        var response: HTTPURLResponse?
+        
         do {
 
             try Task.checkCancellation()
@@ -79,24 +84,26 @@ public class HTTPRequest<Value: Decodable> {
             try Task.checkCancellation()
 
             // Dispatch the request and wait for a response.
-            let (data, response) = try await dispatcher.data(for: request)
+            let reply = try await dispatcher.data(for: request)
+            response = reply.response
 
             try Task.checkCancellation()
 
             // Validate the response.
             try await ZipValidator(validators)
-                .validate(response, for: request, with: data)
+                .validate(reply.response, for: request, with: reply.data)
                 .get()
 
             try Task.checkCancellation()
 
             // Convert data to the expected type
-            return try decoder.decode(Value.self, from: data)
+            return try decoder.decode(Value.self, from: reply.data)
         } catch {
             let previousAttempts = previousAttempts + 1
             let strategy = try await ZipRetrier(retriers).retry(
                 request,
                 for: dispatcher.session,
+                with: response,
                 dueTo: error,
                 previousAttempts: previousAttempts
             )

Sources/HTTPNetworking/Plugins/Adaptors/Adaptor.swift

@@ -1,6 +1,9 @@
 import Foundation
 
-public typealias AdaptationHandler = (URLRequest, URLSession) async throws -> URLRequest
+public typealias AdaptationHandler = (
+    _ request: URLRequest,
+    _ session: URLSession
+) async throws -> URLRequest
 
 /// An ``HTTPRequestAdaptor`` that can be used to manipulate a `URLRequest` before it is sent out over the network.
 public struct Adaptor: HTTPRequestAdaptor {

Sources/HTTPNetworking/Plugins/HTTPRequestRetrier.swift

@@ -7,7 +7,13 @@ import Foundation
 /// By conforming to ``HTTPRequestRetrier`` you can implement both simple and complex logic for retrying an ``HTTPRequest`` when
 /// it fails. Common uses cases include retrying a given amount of times due to a specific error such as poor network connectivity.
 public protocol HTTPRequestRetrier {
-    func retry(_ request: URLRequest, for session: URLSession, dueTo error: Error, previousAttempts: Int) async throws -> RetryStrategy
+    func retry(
+        _ request: URLRequest,
+        for session: URLSession,
+        with response: HTTPURLResponse?,
+        dueTo error: Error,
+        previousAttempts: Int
+    ) async throws -> RetryStrategy
 }
 
 // MARK: - RetryStrategy

Sources/HTTPNetworking/Plugins/Retriers/Retrier.swift

@@ -1,6 +1,12 @@
 import Foundation
 
-public typealias RetryHandler = (URLRequest, URLSession, Error, Int) async throws -> RetryStrategy
+public typealias RetryHandler = (
+    _ request: URLRequest,
+    _ session: URLSession,
+    _ response: HTTPURLResponse?,
+    _ error: Error,
+    _ previousAttempts: Int
+) async throws -> RetryStrategy
 
 /// An ``HTTPRequestRetrier`` that can be used to retry an ``HTTPRequest`` upon failure.
 public struct Retrier: HTTPRequestRetrier {
@@ -24,10 +30,11 @@ public struct Retrier: HTTPRequestRetrier {
     public func retry(
         _ request: URLRequest,
         for session: URLSession,
+        with response: HTTPURLResponse?,
         dueTo error: Error,
         previousAttempts: Int
     ) async throws -> RetryStrategy {
-        try await handler(request, session, error, previousAttempts)
+        try await handler(request, session, response, error, previousAttempts)
     }
 }
 

Sources/HTTPNetworking/Plugins/Retriers/ZipRetrier.swift

@@ -29,6 +29,7 @@ public struct ZipRetrier: HTTPRequestRetrier {
     public func retry(
         _ request: URLRequest,
         for session: URLSession,
+        with response: HTTPURLResponse?,
         dueTo error: Error,
         previousAttempts: Int
     ) async throws -> RetryStrategy {
@@ -38,6 +39,7 @@ public struct ZipRetrier: HTTPRequestRetrier {
             let strategy = try await retrier.retry(
                 request,
                 for: session,
+                with: response,
                 dueTo: error,
                 previousAttempts: previousAttempts
             )

Sources/HTTPNetworking/Plugins/Validators/Validator.swift

@@ -1,6 +1,10 @@
 import Foundation
 
-public typealias ValidationHandler = (HTTPURLResponse, URLRequest, Data) async throws -> ValidationResult
+public typealias ValidationHandler = (
+    _ response: HTTPURLResponse,
+    _ request: URLRequest,
+    _ data: Data
+) async throws -> ValidationResult
 
 /// An ``HTTPResponseValidator`` that can be used to validate a response from an ``HTTPRequest``.
 public struct Validator: HTTPResponseValidator {