feat: CompositeInterceptor allows separate adapters and retriers

+ documentation

Author: plajdo

Sources/GoodNetworking/Interception/Interceptor.swift

@@ -9,10 +9,16 @@ import Foundation
 
 // MARK: - Interceptor
 
+/// Interceptor merges request adaptation and retry behavior.
 public protocol Interceptor: Adapter, Retrier {}
 
 // MARK: - Default interceptor
 
+/// Default interceptor does not adapt (modify) requests in any way.
+/// Default retrying behaviour is applied as per RFC9110 specification.
+///
+/// - warning: Retrying is currently not implemented and all requests
+/// are resolved as `.doNotRetry`.
 public final class DefaultInterceptor: Interceptor {
 
     public init() {}
@@ -28,22 +34,42 @@ public final class DefaultInterceptor: Interceptor {
 
 // MARK: - Composite interceptor
 
+/// Merges multiple interceptors, adapters and retriers into single interceptor instance.
+///
+/// Adapters have priority over general interceptors and are executed first when adapting
+/// requests. All adapters execute in order they are passed in at initialization.
+///
+/// Retriers have priority over general interceptors and are executed first when retrying
+/// requests. The first retrier to allow retrying the request is used, rest are not executed.
+///
+/// This behaviour effectively accomplishes that request authentication is executed
+/// last, and requests are retried if a specific retrier allows it.
 public final class CompositeInterceptor: Interceptor {
 
     private let interceptors: [Interceptor]
-
-    public init(interceptors: [Interceptor]) {
+    private let adapters: [Adapter]
+    private let retriers: [Retrier]
+
+    public init(
+        interceptors: [Interceptor],
+        adapters: [Adapter] = [],
+        retriers: [Retrier] = []
+    ) {
         self.interceptors = interceptors
+        self.adapters = adapters
+        self.retriers = retriers
     }
 
     public func adapt(urlRequest: inout URLRequest) async throws(NetworkError) {
-        for adapter in interceptors {
+        let allAdapters: [Adapter] = adapters + interceptors
+        for adapter in allAdapters {
             try await adapter.adapt(urlRequest: &urlRequest)
         }
     }
 
     public func retry(urlRequest: inout URLRequest, for session: NetworkSession, dueTo error: NetworkError) async throws(NetworkError) -> RetryResult {
-        for retrier in interceptors {
+        let allRetriers: [Retrier] = retriers + interceptors
+        for retrier in allRetriers {
             let retryResult = try await retrier.retry(urlRequest: &urlRequest, for: session, dueTo: error)
             switch retryResult {
             case .doNotRetry:

Sources/GoodNetworking/Interception/Retrier.swift

@@ -17,10 +17,18 @@ public protocol Retrier: Sendable {
 
 // MARK: - Retry result
 
+/// Result of a retry operation.
+///
+/// See ``Retrier``.
 public enum RetryResult: Sendable {
 
+    /// Request will not be retried
     case doNotRetry
+    
+    /// Request will be retried only after the specified time interval has passed
     case retryAfter(TimeInterval)
+    
+    /// Request will be retried immediately
     case retry
 
 }