Implement Chainable Request Interceptors (#15)

Author: otaviocc

README.md

@@ -215,41 +215,75 @@ let configuration = NetworkConfiguration(
 
 ### Request Interceptors
 
-Modify requests before they're sent using synchronous or asynchronous interceptors.
+Modify requests before they are sent by creating a chain of objects that conform to the `NetworkRequestInterceptor` protocol. This is useful for cross-cutting concerns like adding authentication tokens, logging, or caching headers.
 
-#### Synchronous Interceptor
+#### 1. Create an Interceptor
 
-A synchronous interceptor is useful for quick modifications, like adding a static header.
+First, define a struct or class that conforms to `NetworkRequestInterceptor` and implement the `intercept` method.
 
 ```swift
-let configuration = NetworkConfiguration(
-    baseURL: URL(string: "https://api.example.com")!,
-    interceptor: { request in
+// An interceptor for adding a static API key to every request.
+struct APIKeyInterceptor: NetworkRequestInterceptor {
+    let apiKey: String
+
+    func intercept(_ request: URLRequest) async throws -> URLRequest {
         var mutableRequest = request
-        mutableRequest.setValue("Bearer <STATIC_TOKEN>", forHTTPHeaderField: "Authorization")
+        mutableRequest.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
         return mutableRequest
     }
-)
+}
+
+// An interceptor that asynchronously refreshes an auth token.
+struct AuthTokenInterceptor: NetworkRequestInterceptor {
+    let tokenProvider: TokenProviding
+
+    func intercept(_ request: URLRequest) async throws -> URLRequest {
+        // Asynchronously get a fresh token.
+        let token = await tokenProvider.getFreshToken()
+        
+        var mutableRequest = request
+        mutableRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        return mutableRequest
+    }
+}
 ```
 
-#### Asynchronous Interceptor
+#### 2. Configure the Client
 
-An asynchronous interceptor is ideal for operations that require waiting, such as refreshing an authentication token.
+Add instances of your interceptors to the `NetworkConfiguration`. They will be executed in the order they appear in the array.
 
 ```swift
 let configuration = NetworkConfiguration(
     baseURL: URL(string: "https://api.example.com")!,
-    asyncInterceptor: { request in
+    interceptors: [
+        APIKeyInterceptor(apiKey: "my-secret-key"),
+        AuthTokenInterceptor(tokenProvider: myTokenProvider)
+    ]
+)
+
+let client = NetworkClient(configuration: configuration)
+```
+
+#### 3. Per-Request Override (Optional)
+
+You can also provide a specific set of interceptors for an individual request. This will override the interceptors set in the global configuration.
+
+```swift
+struct OneTimeHeaderInterceptor: NetworkRequestInterceptor {
+    func intercept(_ request: URLRequest) async throws -> URLRequest {
         var mutableRequest = request
-        let token = await tokenProvider.refreshToken()
-        mutableRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+        mutableRequest.setValue("true", forHTTPHeaderField: "X-Special-Request")
         return mutableRequest
     }
+}
+
+let request = NetworkRequest<VoidRequest, User>(
+    path: "/users/123",
+    method: .get,
+    interceptors: [OneTimeHeaderInterceptor()] // This interceptor runs instead of the global ones.
 )
 ```
 
-The synchronous interceptor runs first, followed by the asynchronous one.
-
 ### Custom Encoders/Decoders
 
 Override global configuration per request:

Sources/MicroClient/Logger/NetworkLogLevel.swift

@@ -20,7 +20,10 @@ public enum NetworkLogLevel: Int, Sendable {
 
 extension NetworkLogLevel: Comparable {
 
-    public static func < (lhs: NetworkLogLevel, rhs: NetworkLogLevel) -> Bool {
+    public static func < (
+        lhs: NetworkLogLevel,
+        rhs: NetworkLogLevel
+    ) -> Bool {
         lhs.rawValue < rhs.rawValue
     }
 }

Sources/MicroClient/Logger/NetworkLogger.swift

@@ -7,5 +7,8 @@ public protocol NetworkLogger: Sendable {
     /// - Parameters:
     ///   - level: The log level.
     ///   - message: The message to log.
-    func log(level: NetworkLogLevel, message: String)
+    func log(
+        level: NetworkLogLevel,
+        message: String
+    )
 }

Sources/MicroClient/NetworkClient.swift

@@ -54,6 +54,7 @@ public actor NetworkClient: NetworkClientProtocol {
 
     // MARK: - Private
 
+    // swiftlint:disable function_body_length
     private func performRequest<RequestModel, ResponseModel>(
         _ networkRequest: NetworkRequest<RequestModel, ResponseModel>,
         attempt: Int
@@ -76,12 +77,15 @@ public actor NetworkClient: NetworkClientProtocol {
             throw NetworkClientError.malformedURL
         }
 
-        if let interceptor = configuration.interceptor {
-            urlRequest = interceptor(urlRequest)
-        }
+        let interceptors = networkRequest.interceptors ?? configuration.interceptors
 
-        if let asyncInterceptor = configuration.asyncInterceptor {
-            urlRequest = await asyncInterceptor(urlRequest)
+        do {
+            for interceptor in interceptors {
+                urlRequest = try await interceptor.intercept(urlRequest)
+            }
+        } catch {
+            log(.error, "Interceptor error: \(error.localizedDescription)")
+            throw NetworkClientError.interceptorError(error)
         }
 
         log(.info, "Request: \(urlRequest.httpMethod ?? "") \(urlRequest.url?.absoluteString ?? "")")
@@ -132,8 +136,12 @@ public actor NetworkClient: NetworkClientProtocol {
             throw NetworkClientError.unknown(error)
         }
     }
+    // swiftlint:enable function_body_length
 
-    private func log(_ level: NetworkLogLevel, _ message: String) {
+    private func log(
+        _ level: NetworkLogLevel,
+        _ message: String
+    ) {
         guard let logger = configuration.logger,
               level >= configuration.logLevel else { return }
 

Sources/MicroClient/NetworkClientError.swift

@@ -23,6 +23,9 @@ public enum NetworkClientError: Error {
     /// The associated `Error` value contains the original decoding error.
     case encodingError(Error)
 
+    /// An error occurred during the execution of a request interceptor.
+    case interceptorError(Error)
+
     /// An unexpected or unknown error occurred.
     case unknown(Error?)
 }

Sources/MicroClient/NetworkConfiguration.swift

@@ -1,11 +1,5 @@
 import Foundation
 
-/// Type alias for synchronous request interceptors
-public typealias NetworkRequestsInterceptor = @Sendable (URLRequest) -> URLRequest
-
-/// Type alias for asynchronous request interceptors
-public typealias NetworkAsyncRequestInterceptor = @Sendable (URLRequest) async -> URLRequest
-
 /// The network client configuration.
 public struct NetworkConfiguration: Sendable {
 
@@ -35,15 +29,9 @@ public struct NetworkConfiguration: Sendable {
     /// The log level for the logger. The default value is `.info`.
     public let logLevel: NetworkLogLevel
 
-    /// The interceptor called right before performing the
-    /// network request. Can be used to modify the `URLRequest`
-    /// if necessary.
-    public let interceptor: NetworkRequestsInterceptor?
-
-    /// The async interceptor called after the synchronous interceptor
-    /// and right before performing the network request. Can be used to
-    /// modify the `URLRequest` with async operations if necessary.
-    public let asyncInterceptor: NetworkAsyncRequestInterceptor?
+    /// A chain of interceptors that can inspect and modify requests before they are sent.
+    /// Interceptors are applied in the order they appear in this array.
+    public let interceptors: [NetworkRequestInterceptor]
 
     /// Initializes the network client configuration.
     /// - Parameters:
@@ -54,8 +42,7 @@ public struct NetworkConfiguration: Sendable {
     ///   - retryStrategy: The retry strategy for network requests.
     ///   - logger: The logger for network requests and responses.
     ///   - logLevel: The log level for the logger.
-    ///   - interceptor: The synchronous interceptor function (optional).
-    ///   - asyncInterceptor: The asynchronous interceptor function (optional).
+    ///   - interceptors: A chain of interceptors to apply to requests. Defaults to an empty array.
     public init(
         session: URLSessionProtocol,
         defaultDecoder: JSONDecoder,
@@ -64,8 +51,7 @@ public struct NetworkConfiguration: Sendable {
         retryStrategy: RetryStrategy = .none,
         logger: NetworkLogger? = nil,
         logLevel: NetworkLogLevel = .info,
-        interceptor: NetworkRequestsInterceptor? = nil,
-        asyncInterceptor: NetworkAsyncRequestInterceptor? = nil
+        interceptors: [NetworkRequestInterceptor] = []
     ) {
         self.session = session
         self.defaultDecoder = defaultDecoder
@@ -74,7 +60,6 @@ public struct NetworkConfiguration: Sendable {
         self.retryStrategy = retryStrategy
         self.logger = logger
         self.logLevel = logLevel
-        self.interceptor = interceptor
-        self.asyncInterceptor = asyncInterceptor
+        self.interceptors = interceptors
     }
 }

Sources/MicroClient/NetworkRequest.swift

@@ -52,6 +52,10 @@ public struct NetworkRequest<
     /// `NetworkConfiguration.retryStrategy`.
     public let retryStrategy: RetryStrategy?
 
+    /// A chain of interceptors to apply to this specific request. If provided,
+    /// this overrides the default interceptors from the `NetworkConfiguration`.
+    public let interceptors: [NetworkRequestInterceptor]?
+
     // MARK: - Life cycle
 
     /// Initializes the request model.
@@ -66,6 +70,7 @@ public struct NetworkRequest<
     ///   - encoder: The encoder used to encode the `RequestModel`.
     ///   - retryStrategy: The retry strategy for the request.
     ///   - additionalHeaders: A dictionary containing additional header fields.
+    ///   - interceptors: A chain of interceptors to apply to this specific request.
     public init(
         path: String? = nil,
         method: HTTPMethod,
@@ -76,7 +81,8 @@ public struct NetworkRequest<
         decoder: JSONDecoder? = nil,
         encoder: JSONEncoder? = nil,
         retryStrategy: RetryStrategy? = nil,
-        additionalHeaders: [String: String]? = nil
+        additionalHeaders: [String: String]? = nil,
+        interceptors: [NetworkRequestInterceptor]? = nil
     ) {
         self.path = path
         self.method = method
@@ -88,6 +94,7 @@ public struct NetworkRequest<
         self.encoder = encoder
         self.retryStrategy = retryStrategy
         self.additionalHeaders = additionalHeaders
+        self.interceptors = interceptors
     }
 }
 

Sources/MicroClient/NetworkRequestInterceptor.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// A protocol for intercepting and modifying network requests before they are sent.
+public protocol NetworkRequestInterceptor: Sendable {
+
+    /// Intercepts and potentially modifies a URLRequest.
+    ///
+    /// This method is called for each interceptor in the chain. It can be used to add headers,
+    /// modify the request body, or even perform asynchronous tasks like refreshing an authentication token.
+    ///
+    /// - Parameter request: The `URLRequest` to be processed.
+    /// - Returns: A potentially modified `URLRequest`.
+    /// - Throws: An error if the interception process fails. Throwing an error will cancel the entire request.
+    func intercept(_ request: URLRequest) async throws -> URLRequest
+}

Tests/MicroClientTests/Doubles/HeaderInterceptor.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+@testable import MicroClient
+
+struct HeaderInterceptor: NetworkRequestInterceptor {
+
+    // MARK: - Properties
+
+    let headerName: String
+    let headerValue: String
+    let storage: MockInterceptorStorage
+
+    // MARK: - Public
+
+    func intercept(_ request: URLRequest) async throws -> URLRequest {
+        await storage.recordCall(id: headerName)
+
+        var mutableRequest = request
+        mutableRequest.setValue(
+            headerValue,
+            forHTTPHeaderField: headerName
+        )
+        return mutableRequest
+    }
+}

Tests/MicroClientTests/Doubles/InterceptorMock.swift

@@ -0,0 +1,16 @@
+import Foundation
+
+@testable import MicroClient
+
+struct InterceptorMock: NetworkRequestInterceptor {
+
+    // MARK: - Properties
+
+    let id = UUID()
+
+    // MARK: - Public
+
+    func intercept(_ request: URLRequest) async throws -> URLRequest {
+        request
+    }
+}