Code review updates

Author: jmarek41

.swiftlint.yml

@@ -17,7 +17,6 @@ opt_in_rules:
   - contains_over_first_not_nil
   - contains_over_range_nil_comparison
   - convenience_type
-  - discouraged_object_literal
   - discouraged_optional_boolean
   - empty_collection_literal
   - empty_count
@@ -45,22 +44,17 @@ opt_in_rules:
   - multiline_literal_brackets
   - multiline_parameters
   - multiline_parameters_brackets
-  - nimble_operator
   - number_separator
-  - object_literal
   - operator_usage_whitespace
   - optional_enum_case_matching
   - overridden_super_call
   - override_in_extension
   - pattern_matching_keywords
   - prefer_self_type_over_type_of_self
-  - private_action
-  - private_outlet
   - prohibited_super_call
   - reduce_into
   - redundant_nil_coalescing
   - required_enum_case
-  - single_test_class
   - sorted_first_last
   - sorted_imports
   - static_operator
@@ -73,10 +67,6 @@ opt_in_rules:
   - vertical_parameter_alignment_on_call
   - vertical_whitespace_closing_braces
   - yoda_condition
-analyzer_rules:
-  - unused_declaration
-  - unused_import
-
 # Rule configurations
 identifier_name:
   excluded:

CLAUDE.md

@@ -88,7 +88,7 @@ The framework is built around two core protocols:
 **Source Structure** (`Sources/FTAPIKit/`):
 - Core protocols: `URLServer.swift`, `Endpoint.swift`
 - Request building: `URLRequestBuilder.swift`, `RequestConfiguring.swift`
-- Async execution: `URLServer+Async.swift`, `URLServer+Download.swift`
+- Async execution: `URLServer+Async.swift` (includes download)
 - Observers: `NetworkObserver.swift`
 - Utilities: `Coding.swift`, `URLQuery.swift`, `MultipartFormData.swift`, etc.
 - Error handling: `APIError.swift`, `APIError+Standard.swift`

Sources/FTAPIKit/MultipartFormData.swift

@@ -11,6 +11,10 @@ struct MultipartFormData {
         self.boundary = boundary
     }
 
+    /// Returns the size of the temporary file containing the multipart body.
+    ///
+    /// - Important: Must be called after ``inputStream()`` which writes the file.
+    ///   Returns `nil` if the file does not exist yet.
     var contentLength: Int64? {
         (try? FileManager.default.attributesOfItem(atPath: temporaryUrl.path)[.size] as? Int64)?.flatMap { $0 }
     }

Sources/FTAPIKit/NetworkObserver.swift

@@ -12,7 +12,8 @@ import Foundation
 /// 3. `didFail` is called additionally if the request processing fails (network, HTTP status, or decoding error)
 ///
 /// - Note: Observers are strongly retained for the duration of a request to ensure lifecycle callbacks
-///   are always delivered.
+///   are always delivered. Observers must not hold strong references back to the server to avoid
+///   retain cycles.
 public protocol NetworkObserver: AnyObject, Sendable {
     associatedtype Context: Sendable
 

Sources/FTAPIKit/RequestConfiguring.swift

@@ -23,3 +23,28 @@ public protocol RequestConfiguring: Sendable {
     /// - Throws: Any error that occurs during configuration (e.g., token refresh failure)
     func configure(_ request: inout URLRequest) async throws
 }
+
+/// Composes multiple ``RequestConfiguring`` instances into a single configuration.
+///
+/// Configurations are applied in order, so later configurations can override
+/// headers set by earlier ones.
+///
+/// ```swift
+/// let config = CompositeRequestConfiguring([authConfig, tracingConfig])
+/// let data = try await server.call(data: endpoint, configuring: config)
+/// ```
+public struct CompositeRequestConfiguring: RequestConfiguring {
+    private let configurations: [any RequestConfiguring]
+
+    /// Creates a composite configuration from multiple configurations.
+    /// - Parameter configurations: Configurations to apply in order.
+    public init(_ configurations: [any RequestConfiguring]) {
+        self.configurations = configurations
+    }
+
+    public func configure(_ request: inout URLRequest) async throws {
+        for configuration in configurations {
+            try await configuration.configure(&request)
+        }
+    }
+}

Sources/FTAPIKit/URLQuery.swift

@@ -14,11 +14,12 @@ import Foundation
 ///     "child[]": "Maggie"
 /// ]
 /// ```
-public struct URLQuery: ExpressibleByDictionaryLiteral {
+public struct URLQuery: ExpressibleByDictionaryLiteral, Sendable {
     /// Array of URL query items.
     public let items: [URLQueryItem]
 
-    init() {
+    /// Creates an empty URL query.
+    public init() {
         self.items = []
     }
 

Sources/FTAPIKit/URLRequestBuilder.swift

@@ -27,6 +27,10 @@ struct URLRequestBuilder<S: URLServer> {
         return request
     }
 
+    /// Populates the request body based on the endpoint's protocol conformance.
+    ///
+    /// - Important: Case ordering matters. If an endpoint conforms to multiple body-providing
+    ///   protocols (e.g., both `DataEndpoint` and `EncodableEndpoint`), the first match wins.
     private func buildBody(to request: inout URLRequest) throws {
         switch endpoint {
         case let endpoint as DataEndpoint:

Sources/FTAPIKit/URLServer+Async.swift

@@ -6,7 +6,8 @@ public extension URLServer {
     /// - Parameters:
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
-    /// - Throws: Throws an APIError if the request fails or server returns an error
+    /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
+    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
     func call(endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws {
         _ = try await execute(endpoint: endpoint, configuring: configuring)
     }
@@ -15,7 +16,8 @@ public extension URLServer {
     /// - Parameters:
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
-    /// - Throws: Throws an APIError if the request fails or server returns an error
+    /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
+    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
     /// - Returns: Plain data returned with the HTTP Response
     func call(data endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws -> Data {
         try await execute(endpoint: endpoint, configuring: configuring).data
@@ -25,7 +27,9 @@ public extension URLServer {
     /// - Parameters:
     ///   - endpoint: The endpoint
     ///   - configuring: Optional request configuration to apply before sending
-    /// - Throws: Throws an APIError if the request fails, server returns an error, or decoding fails
+    /// - Throws: Throws an ``APIError`` if the request fails or server returns an error.
+    ///   Throws a `DecodingError` directly if response decoding fails (decoding errors are not
+    ///   routed through ``URLServer/ErrorType``).
     /// - Returns: Instance of the required type
     func call<EP: ResponseEndpoint>(response endpoint: EP, configuring: RequestConfiguring? = nil) async throws -> EP.Response {
         let result = try await execute(endpoint: endpoint, configuring: configuring)
@@ -36,22 +40,48 @@ public extension URLServer {
             throw error
         }
     }
+
+    /// Downloads a file from the specified endpoint to a temporary location.
+    /// - Parameters:
+    ///   - endpoint: The endpoint
+    ///   - configuring: Optional request configuration to apply before sending
+    /// - Throws: Throws an ``APIError`` if the request fails or server returns an error,
+    ///   or an error from ``RequestConfiguring/configure(_:)`` if configuration fails.
+    /// - Returns: The location of a temporary file where the server's response is stored.
+    ///   You must move this file or open it for reading before the async function returns. Otherwise, the file
+    ///   is deleted, and the data is lost.
+    func download(endpoint: Endpoint, configuring: RequestConfiguring? = nil) async throws -> URL {
+        let (urlRequest, observers) = try await prepareObservers(endpoint: endpoint, configuring: configuring)
+
+        let (localURL, response): (URL, URLResponse)
+        do {
+            (localURL, response) = try await urlSession.download(for: urlRequest)
+        } catch {
+            observers.forEach { $0.didFail(request: urlRequest, error: error) }
+            throw error
+        }
+
+        observers.forEach { $0.didReceiveResponse(for: urlRequest, response: response, data: nil) }
+        try checkForError(data: nil, response: response, request: urlRequest, observers: observers)
+
+        return localURL
+    }
 }
 
 // MARK: - Private helpers
 
 private struct ExecuteResult {
     let data: Data
     let request: URLRequest
-    let observers: [AnyObserverToken]
+    let observers: [BoundObserverContext]
 }
 
 private extension URLServer {
 
     /// Core execution method that builds the request, notifies observers, performs the network call,
     /// and handles errors.
     func execute(endpoint: Endpoint, configuring: RequestConfiguring?) async throws -> ExecuteResult {
-        let (urlRequest, observers) = try await prepareRequest(endpoint: endpoint, configuring: configuring)
+        let (urlRequest, observers) = try await prepareObservers(endpoint: endpoint, configuring: configuring)
 
         let file = (endpoint as? UploadEndpoint)?.file
 
@@ -72,20 +102,15 @@ private extension URLServer {
 
         return ExecuteResult(data: data, request: urlRequest, observers: observers)
     }
-}
-
-// MARK: - Shared helpers
-
-extension URLServer {
 
-    /// Builds the URLRequest for the endpoint, applies optional configuration, and creates observer tokens.
-    func prepareRequest(
+    /// Builds the URLRequest for the endpoint, applies optional configuration, and creates observer contexts.
+    func prepareObservers(
         endpoint: Endpoint,
         configuring: RequestConfiguring?
-    ) async throws -> (URLRequest, [AnyObserverToken]) {
+    ) async throws -> (URLRequest, [BoundObserverContext]) {
         var urlRequest = try await buildRequest(endpoint: endpoint)
         try await configuring?.configure(&urlRequest)
-        let observers = networkObservers.map { AnyObserverToken(observer: $0, request: urlRequest) }
+        let observers = networkObservers.map { BoundObserverContext(observer: $0, request: urlRequest) }
         return (urlRequest, observers)
     }
 
@@ -94,7 +119,7 @@ extension URLServer {
         data: Data?,
         response: URLResponse,
         request: URLRequest,
-        observers: [AnyObserverToken]
+        observers: [BoundObserverContext]
     ) throws {
         if let error = ErrorType(data: data, response: response, error: nil, decoding: decoding) {
             observers.forEach { $0.didFail(request: request, error: error) }
@@ -103,8 +128,13 @@ extension URLServer {
     }
 }
 
-/// Type-erasing wrapper that captures an observer and its context from `willSendRequest`.
-final class AnyObserverToken: @unchecked Sendable {
+/// Captures an observer and its context from `willSendRequest`, binding the lifecycle callbacks
+/// for a single request. Created at request start and consumed before the call returns.
+///
+/// Marked `@unchecked Sendable` because the stored closures capture a `Sendable` observer
+/// and its `Sendable` context. Instances are created and consumed within a single async call
+/// and never shared across task boundaries.
+private final class BoundObserverContext: @unchecked Sendable {
     private let _didReceiveResponse: (URLRequest, URLResponse?, Data?) -> Void
     private let _didFail: (URLRequest, Error) -> Void
 

Sources/FTAPIKit/URLServer+Download.swift

@@ -1,8 +1,7 @@
 import Foundation
+import FTAPIKit
 import Testing
 
-@testable import FTAPIKit
-
 /// Tests demonstrating async buildRequest functionality addressing GitHub issue #105
 @Suite
 struct AsyncBuildRequestTests {
@@ -11,7 +10,7 @@ struct AsyncBuildRequestTests {
     func asyncBuildRequestWithDynamicHeaders() async throws {
         let server = DynamicHeaderServer()
         let data = try await server.call(data: GetEndpoint())
-        let response = try JSONDecoder().decode(HTTPBinResponse.self, from: data)
+        let response = try JSONDecoder().decode(HTTPBinHeadersResponse.self, from: data)
         #expect(response.headers["X-App-Version"] == "2.0.0")
         #expect(response.headers["X-Device-Id"] == "test-device-123")
     }
@@ -22,7 +21,7 @@ struct AsyncBuildRequestTests {
         let server = TokenRefreshServer(tokenManager: tokenManager)
         tokenManager.currentToken = "expired-token"
         let data = try await server.call(data: GetEndpoint())
-        let response = try JSONDecoder().decode(HTTPBinResponse.self, from: data)
+        let response = try JSONDecoder().decode(HTTPBinHeadersResponse.self, from: data)
         #expect(response.headers["Authorization"] == "Bearer refreshed-token-456")
         #expect(tokenManager.refreshCalled)
     }
@@ -67,40 +66,3 @@ private struct AppConfiguration {
     let appVersion: String
     let deviceId: String
 }
-
-private final class MockTokenManager: @unchecked Sendable {
-    private let lock = NSLock()
-    private var _currentToken: String = "initial-token"
-    private var _refreshCalled = false
-
-    var currentToken: String {
-        get { lock.withLock { _currentToken } }
-        set { lock.withLock { _currentToken = newValue } }
-    }
-
-    var refreshCalled: Bool {
-        lock.withLock { _refreshCalled }
-    }
-
-    func refreshIfNeeded() async {
-        try? await Task.sleep(nanoseconds: 10_000_000)
-        lock.withLock {
-            _refreshCalled = true
-            _currentToken = "refreshed-token-456"
-        }
-    }
-}
-
-private struct HTTPBinResponse: Decodable, Sendable {
-    let headers: [String: String]
-
-    private enum CodingKeys: String, CodingKey {
-        case headers
-    }
-
-    init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        let rawHeaders = try container.decode([String: String].self, forKey: .headers)
-        self.headers = rawHeaders
-    }
-}