refactor(networkobserver): Clarify callback lifecycle

Explicitly document that `didReceiveResponse` is always invoked with raw data, and `didFail` is an additional callback for errors occurring after the response is received. Update tests to assert this behavior.

Author: Šimon Šesták

Sources/FTAPIKit/NetworkObserver.swift

@@ -7,17 +7,27 @@ import FoundationNetworking
 /// Protocol for observing network request lifecycle events.
 ///
 /// Implement this protocol to add logging, analytics, or request tracking.
-/// The `context` parameter allows passing correlation data (request ID, start time, etc.)
-/// between `willSendRequest` and the completion callbacks.
+///
+/// ## Context Lifecycle
+/// The `Context` associated type allows passing correlation data (request ID, start time, etc.)
+/// through the request lifecycle:
+/// 1. `willSendRequest` is called before the request starts and returns a `Context` value
+/// 2. `didReceiveResponse` is always called with the raw response data (useful for debugging)
+/// 3. `didFail` is called additionally if the request processing fails (network, HTTP status, or decoding error)
+/// 4. If the observer is deallocated before the request completes, the context is discarded
+///    and no completion callback is invoked
 public protocol NetworkObserver: AnyObject, Sendable {
     associatedtype Context: Sendable
 
     /// Called immediately before a request is sent.
     /// - Parameter request: The URLRequest about to be sent
-    /// - Returns: Context to be passed to `didReceiveResponse` or `didFail`
+    /// - Returns: Context to be passed to `didReceiveResponse` and optionally `didFail`
     func willSendRequest(_ request: URLRequest) -> Context
 
-    /// Called when a response is received.
+    /// Called when a response is received from the server.
+    ///
+    /// This is always called with the raw response data, even if processing subsequently fails.
+    /// This allows observers to inspect the actual response for debugging purposes.
     /// - Parameters:
     ///   - request: The original request
     ///   - response: The URL response (may be HTTPURLResponse)
@@ -26,9 +36,11 @@ public protocol NetworkObserver: AnyObject, Sendable {
     func didReceiveResponse(for request: URLRequest, response: URLResponse?, data: Data?, context: Context)
 
     /// Called when a request fails with an error.
+    ///
+    /// Called after `didReceiveResponse` if processing determines the request failed.
     /// - Parameters:
     ///   - request: The original request
-    ///   - error: The error that occurred
+    ///   - error: The error that occurred (may be network, HTTP status, or decoding error)
     ///   - context: Value returned from `willSendRequest`
     func didFail(request: URLRequest, error: Error, context: Context)
 }

Tests/FTAPIKitTests/NetworkObserverTests.swift

@@ -50,11 +50,8 @@ final class NetworkObserverTests: XCTestCase {
         wait(for: [expectation], timeout: timeout)
 
         XCTAssertEqual(mockObserver.willSendCount, 1, "willSendRequest should be called once")
-        XCTAssertGreaterThanOrEqual(
-            mockObserver.didReceiveCount + mockObserver.didFailCount,
-            1,
-            "Either didReceive or didFail should be called"
-        )
+        // didReceiveResponse is always called; didFail is called additionally on failure
+        XCTAssertEqual(mockObserver.didReceiveCount, 1, "didReceiveResponse should always be called")
     }
 
     func testObserverLogsFailedRequest() {
@@ -69,13 +66,10 @@ final class NetworkObserverTests: XCTestCase {
 
         wait(for: [expectation], timeout: timeout)
 
-        // Verify observer was called (request is always logged, even on failure)
-        XCTAssertEqual(mockObserver.willSendCount, 1, "Request should be logged once")
-        XCTAssertGreaterThanOrEqual(
-            mockObserver.didReceiveCount + mockObserver.didFailCount,
-            1,
-            "Either response or error should be logged"
-        )
+        // didReceiveResponse is always called with raw data; didFail is called additionally on failure
+        XCTAssertEqual(mockObserver.willSendCount, 1, "willSendRequest should be called once")
+        XCTAssertEqual(mockObserver.didReceiveCount, 1, "didReceiveResponse should always be called")
+        XCTAssertEqual(mockObserver.didFailCount, 1, "didFail should be called on failure")
     }
 
     func testMultipleObserversAllReceiveCallbacks() {
@@ -94,7 +88,7 @@ final class NetworkObserverTests: XCTestCase {
         // Both observers should receive callbacks
         XCTAssertEqual(observer1.willSendCount, 1, "Observer 1 willSendRequest should be called")
         XCTAssertEqual(observer2.willSendCount, 1, "Observer 2 willSendRequest should be called")
-        XCTAssertGreaterThanOrEqual(observer1.didReceiveCount + observer1.didFailCount, 1)
-        XCTAssertGreaterThanOrEqual(observer2.didReceiveCount + observer2.didFailCount, 1)
+        XCTAssertEqual(observer1.didReceiveCount, 1, "Observer 1 didReceiveResponse should be called")
+        XCTAssertEqual(observer2.didReceiveCount, 1, "Observer 2 didReceiveResponse should be called")
     }
 }