@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/ios-networking/references/urlsession-patterns.md

@@ -1,207 +1,163 @@
-# URLSession Patterns Reference
+# URLSession Patterns
 
-Complete implementation patterns for URLSession-based networking.
-
----
+Longer implementations behind the summaries in [SKILL.md](../SKILL.md). The
+types here are the same ones SKILL.md names: `APIClientProtocol` with
+`fetch`, `send`, `perform` and `upload`; `Endpoint`; `NetworkError`;
+`RequestMiddleware`. None of the code force-unwraps.
 
 ## Contents
 
-- [Complete API Client with Protocol](#complete-api-client-with-protocol)
-- [Request Middleware](#request-middleware)
-- [Request Builder Pattern](#request-builder-pattern)
-- [Multipart Form Upload](#multipart-form-upload)
-- [Download with Progress Tracking](#download-with-progress-tracking)
-- [Cursor-Based Pagination](#cursor-based-pagination)
-- [Offset-Based Pagination](#offset-based-pagination)
-- [URLProtocol Mock for Testing](#urlprotocol-mock-for-testing)
-- [Retry with Exponential Backoff](#retry-with-exponential-backoff)
-- [Certificate Pinning (URLSessionDelegate)](#certificate-pinning-urlsessiondelegate)
-- [Request Logging / Debugging Middleware](#request-logging-debugging-middleware)
-- [Request Caching Strategies](#request-caching-strategies)
-- [Server-Sent Events (SSE) Parsing](#server-sent-events-sse-parsing)
-- [Configured URLSession for Production](#configured-urlsession-for-production)
-
-## Complete API Client with Protocol
-
-A full-featured client with middleware support, configurable decoding,
-and response validation.
+- [A protocol-backed API client](#a-protocol-backed-api-client)
+- [Building requests step by step](#building-requests-step-by-step)
+- [Uploading multipart form data](#uploading-multipart-form-data)
+- [Downloads that report progress](#downloads-that-report-progress)
+- [Paging by cursor](#paging-by-cursor)
+- [Paging by offset](#paging-by-offset)
+- [Stubbing the network with URLProtocol](#stubbing-the-network-with-urlprotocol)
+- [Retries that back off exponentially](#retries-that-back-off-exponentially)
+- [Pinning certificates in a session delegate](#pinning-certificates-in-a-session-delegate)
+- [Middleware that logs requests](#middleware-that-logs-requests)
+- [Choosing a cache policy](#choosing-a-cache-policy)
+- [Reading a server-sent event stream](#reading-a-server-sent-event-stream)
+- [A production-ready session setup](#a-production-ready-session-setup)
+
+## A protocol-backed API client
 
 ### Protocol
 
 ```swift
 protocol APIClientProtocol: Sendable {
-    func request<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint
-    ) async throws -> T
-
-    func request(endpoint: Endpoint) async throws
-
-    func upload<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint,
-        body: Data
-    ) async throws -> T
+    func fetch<Reply: Decodable & Sendable>(_ endpoint: Endpoint, as kind: Reply.Type) async throws -> Reply
+    func send<Reply: Decodable & Sendable>(_ endpoint: Endpoint, json payload: some Encodable & Sendable,
+                                           as kind: Reply.Type) async throws -> Reply
+    func perform(_ endpoint: Endpoint) async throws
+    func upload<Reply: Decodable & Sendable>(_ endpoint: Endpoint, bytes: Data,
+                                             as kind: Reply.Type) async throws -> Reply
 }
 ```
 
+- `fetch` decodes the response of any request that carries no Swift body.
+- `send` JSON-encodes a body, then decodes the reply.
+- `perform` validates the status and ignores the body (DELETE, fire-and-ack).
+- `upload` sends raw bytes through `upload(for:from:)`.
+
 ### Endpoint Definition
 
+`Endpoint` is exactly the struct shown in SKILL.md: `path`, a nested
+`HTTPMethod` enum (get, post, put, patch, delete, sent upper-cased), query items,
+headers, an optional `body`, a `cachePolicy` defaulting to
+`.useProtocolCachePolicy` and a 30 second `timeoutInterval`. Its
+`urlRequest(relativeTo:)` adds query items only when there are some, copies
+method, body, cache policy, timeout and every header, and throws
+`NetworkError.invalidURL` when components or the final URL cannot be formed.
+
+### Client Implementation
+
 ```swift
-struct Endpoint: Sendable {
-    let path: String
-    var method: HTTPMethod = .get
-    var queryItems: [URLQueryItem] = []
-    var headers: [String: String] = [:]
-    var body: Data? = nil
-    var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
-    var timeoutInterval: TimeInterval = 30
-
-    enum HTTPMethod: String, Sendable {
-        case get = "GET"
-        case post = "POST"
-        case put = "PUT"
-        case patch = "PATCH"
-        case delete = "DELETE"
+final class APIClient: APIClientProtocol {
+    private let root: URL
+    private let transport: URLSession
+    private let pipeline: [any RequestMiddleware]
+    private let decoder = JSONDecoder.snakeCaseISO8601
+    private let encoder = JSONEncoder.snakeCaseISO8601
+
+    init(baseURL: URL, session: URLSession, middleware: [any RequestMiddleware] = []) {
+        root = baseURL
+        transport = session
+        pipeline = middleware
     }
 
-    func urlRequest(relativeTo baseURL: URL) -> URLRequest {
-        var components = URLComponents(
-            url: baseURL.appendingPathComponent(path),
-            resolvingAgainstBaseURL: true
-        )!
-        if !queryItems.isEmpty {
-            components.queryItems = queryItems
-        }
-        var request = URLRequest(url: components.url!)
-        request.httpMethod = method.rawValue
-        request.httpBody = body
-        request.cachePolicy = cachePolicy
-        request.timeoutInterval = timeoutInterval
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-        return request
+    func fetch<Reply: Decodable & Sendable>(_ endpoint: Endpoint, as kind: Reply.Type) async throws -> Reply {
+        let outgoing = try await prepared(endpoint)
+        return try decoded(kind, try await execute { try await self.transport.data(for: outgoing) })
     }
-}
-```
 
-### Client Implementation
+    func send<Reply: Decodable & Sendable>(_ endpoint: Endpoint, json payload: some Encodable & Sendable,
+                                           as kind: Reply.Type) async throws -> Reply {
+        var json = endpoint
+        json.body = try encoder.encode(payload)
+        json.headers["Content-Type"] = "application/json"
+        return try await fetch(json, as: kind)
+    }
 
-```swift
-final class APIClient: APIClientProtocol {
-    private let baseURL: URL
-    private let session: URLSession
-    private let decoder: JSONDecoder
-    private let encoder: JSONEncoder
-    private let middlewares: [any RequestMiddleware]
-
-    init(
-        baseURL: URL,
-        session: URLSession = .shared,
-        decoder: JSONDecoder = {
-            let d = JSONDecoder()
-            d.dateDecodingStrategy = .iso8601
-            d.keyDecodingStrategy = .convertFromSnakeCase
-            return d
-        }(),
-        encoder: JSONEncoder = {
-            let e = JSONEncoder()
-            e.dateEncodingStrategy = .iso8601
-            e.keyEncodingStrategy = .convertToSnakeCase
-            return e
-        }(),
-        middlewares: [any RequestMiddleware] = []
-    ) {
-        self.baseURL = baseURL
-        self.session = session
-        self.decoder = decoder
-        self.encoder = encoder
-        self.middlewares = middlewares
+    func perform(_ endpoint: Endpoint) async throws {
+        let outgoing = try await prepared(endpoint)
+        _ = try await execute { try await self.transport.data(for: outgoing) }
     }
 
-    func request<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint
-    ) async throws -> T {
-        let request = try await prepareRequest(for: endpoint)
-        let (data, response) = try await session.data(for: request)
-        try validateResponse(response, data: data)
-        return try decoder.decode(T.self, from: data)
+    func upload<Reply: Decodable & Sendable>(_ endpoint: Endpoint, bytes: Data,
+                                             as kind: Reply.Type) async throws -> Reply {
+        let outgoing = try await prepared(endpoint)
+        return try decoded(kind, try await execute { try await self.transport.upload(for: outgoing, from: bytes) })
     }
 
-    func request(endpoint: Endpoint) async throws {
-        let request = try await prepareRequest(for: endpoint)
-        let (data, response) = try await session.data(for: request)
-        try validateResponse(response, data: data)
+    private func prepared(_ endpoint: Endpoint) async throws -> URLRequest {
+        var outgoing = try endpoint.urlRequest(relativeTo: root)
+        for step in pipeline { try await step.adapt(&outgoing) }
+        return outgoing
     }
 
-    func upload<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint,
-        body: Data
-    ) async throws -> T {
-        var request = try await prepareRequest(for: endpoint)
-        request.httpBody = body
-        let (data, response) = try await session.upload(for: request, from: body)
-        try validateResponse(response, data: data)
-        return try decoder.decode(T.self, from: data)
+    private func execute(_ call: () async throws -> (Data, URLResponse)) async throws -> Data {
+        let data: Data
+        let response: URLResponse
+        do {
+            (data, response) = try await call()
+        } catch let error as URLError {
+            throw NetworkError.from(error)
+        }
+        guard let status = (response as? HTTPURLResponse)?.statusCode else {
+            throw NetworkError.invalidResponse
+        }
+        if !(200...299).contains(status) {
+            throw NetworkError.httpStatus(code: status, body: data,
+                                          message: APIErrorBody.decode(from: data)?.message)
+        }
+        return data
     }
 
-    // MARK: - Convenience methods
-
-    func get<T: Decodable & Sendable>(
-        _ type: T.Type,
-        path: String,
-        queryItems: [URLQueryItem] = []
-    ) async throws -> T {
-        try await request(type, endpoint: Endpoint(
-            path: path,
-            method: .get,
-            queryItems: queryItems
-        ))
+    private func decoded<Reply: Decodable>(_ kind: Reply.Type, _ payload: Data) throws -> Reply {
+        do { return try decoder.decode(kind, from: payload) }
+        catch { throw NetworkError.decodingFailed(error) }
     }
+}
 
-    func post<T: Decodable & Sendable, B: Encodable & Sendable>(
-        _ type: T.Type,
-        path: String,
-        body: B
-    ) async throws -> T {
-        let bodyData = try encoder.encode(body)
-        return try await request(type, endpoint: Endpoint(
-            path: path,
-            method: .post,
-            headers: ["Content-Type": "application/json"],
-            body: bodyData
-        ))
+extension JSONDecoder {
+    static var snakeCaseISO8601: JSONDecoder {
+        let made = JSONDecoder()
+        made.keyDecodingStrategy = .convertFromSnakeCase
+        made.dateDecodingStrategy = .iso8601
+        return made
     }
+}
 
-    func delete(path: String) async throws {
-        try await request(endpoint: Endpoint(path: path, method: .delete))
+extension JSONEncoder {
+    static var snakeCaseISO8601: JSONEncoder {
+        let made = JSONEncoder()
+        made.keyEncodingStrategy = .convertToSnakeCase
+        made.dateEncodingStrategy = .iso8601
+        return made
     }
+}
+```
 
-    // MARK: - Internal
+Middleware runs in array order, so put authentication before logging if the
+log should show that a header was added. Thin conveniences keep call sites
+short:
 
-    private func prepareRequest(for endpoint: Endpoint) async throws -> URLRequest {
-        var request = endpoint.urlRequest(relativeTo: baseURL)
-        for middleware in middlewares {
-            request = try await middleware.prepare(request)
-        }
-        return request
+```swift
+extension APIClient {
+    func get<Reply: Decodable & Sendable>(_ route: String, query: [URLQueryItem] = [],
+                                          as kind: Reply.Type) async throws -> Reply {
+        try await fetch(Endpoint(path: route, queryItems: query), as: kind)
     }
 
-    private func validateResponse(_ response: URLResponse, data: Data) throws {
-        guard let http = response as? HTTPURLResponse else {
-            throw NetworkError.invalidResponse
-        }
-        guard (200..<300).contains(http.statusCode) else {
-            let apiError = try? decoder.decode(APIErrorBody.self, from: data)
-            throw NetworkError.httpError(
-                statusCode: http.statusCode,
-                data: data,
-                message: apiError?.message
-            )
-        }
+    func post<Reply: Decodable & Sendable>(_ route: String, json payload: some Encodable & Sendable,
+                                           as kind: Reply.Type) async throws -> Reply {
+        try await send(Endpoint(path: route, method: .post), json: payload, as: kind)
+    }
+
+    func delete(_ route: String) async throws {
+        try await perform(Endpoint(path: route, method: .delete))
     }
 }
 ```
@@ -209,502 +165,360 @@ final class APIClient: APIClientProtocol {
 ### Error Types
 
 ```swift
-enum NetworkError: Error, Sendable, LocalizedError {
+enum NetworkError: Error, LocalizedError {
+    case invalidURL
     case invalidResponse
-    case httpError(statusCode: Int, data: Data, message: String? = nil)
+    case httpStatus(code: Int, body: Data, message: String?)
+    case decodingFailed(any Error)
     case noConnection
     case timedOut
     case cancelled
-
-    var errorDescription: String? {
-        switch self {
-        case .invalidResponse:
-            return "Invalid server response"
-        case .httpError(let code, _, let message):
-            return message ?? "HTTP error \(code)"
-        case .noConnection:
-            return "No internet connection"
-        case .timedOut:
-            return "Request timed out"
-        case .cancelled:
-            return nil
+    case transport(URLError)
+
+    static func from(_ error: URLError) -> NetworkError {
+        switch error.code {
+        case .notConnectedToInternet, .networkConnectionLost: .noConnection
+        case .timedOut: .timedOut
+        case .cancelled: .cancelled
+        default: .transport(error)
         }
     }
 
-    static func from(_ urlError: URLError) -> NetworkError {
-        switch urlError.code {
-        case .notConnectedToInternet, .networkConnectionLost:
-            return .noConnection
-        case .timedOut:
-            return .timedOut
-        case .cancelled:
-            return .cancelled
-        default:
-            return .invalidResponse
+    var errorDescription: String? {
+        switch self {
+        case .invalidURL: "The request address is not valid."
+        case .invalidResponse: "The server sent a response that could not be read."
+        case .httpStatus(let status, _, let message): message ?? "The server returned status \(status)."
+        case .decodingFailed: "The server data was in an unexpected format."
+        case .noConnection: "You appear to be offline."
+        case .timedOut: "The server took too long to answer."
+        case .cancelled: nil
+        case .transport(let error): error.localizedDescription
         }
     }
 }
 
 struct APIErrorBody: Decodable, Sendable {
-    let code: String?
     let message: String?
-}
-```
-
-### Request Middleware
-
-```swift
-protocol RequestMiddleware: Sendable {
-    func prepare(_ request: URLRequest) async throws -> URLRequest
-}
-
-struct AuthMiddleware: RequestMiddleware {
-    let tokenProvider: @Sendable () async throws -> String
+    let code: String?
 
-    func prepare(_ request: URLRequest) async throws -> URLRequest {
-        var request = request
-        let token = try await tokenProvider()
-        request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
-        return request
+    static func decode(from data: Data) -> APIErrorBody? {
+        try? JSONDecoder().decode(APIErrorBody.self, from: data)
     }
 }
 ```
 
----
+`.cancelled` has no description on purpose: a cancelled request should not
+produce an alert.
+
+### Request Middleware
+
+`RequestMiddleware` and `BearerTokenMiddleware` are the ones in SKILL.md:
+one `adapt(_:)` method that edits the request in place, and a middleware that asks an async token provider
+for the current token and sets `Authorization: Bearer ...`.
 
-## Request Builder Pattern
+## Building requests step by step
 
-For complex request construction, a builder provides a fluent API that
-reduces errors.
+For requests with many optional parts, a value-type builder keeps call sites
+readable and hard to get wrong. Each modifier returns a changed copy.
 
 ```swift
 struct RequestBuilder: Sendable {
-    private var method: String = "GET"
-    private var path: String
-    private var baseURL: URL
-    private var queryItems: [URLQueryItem] = []
-    private var headers: [String: String] = [:]
-    private var body: Data?
-    private var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
-    private var timeout: TimeInterval = 30
+    private let target: URL
+    private var verb = "GET"
+    private var caching = URLRequest.CachePolicy.useProtocolCachePolicy
+    private var limit: TimeInterval = 30
+    private var items: [URLQueryItem] = []
+    private var fields: [String: String] = [:]
+    private var payload: Data?
 
     init(baseURL: URL, path: String) {
-        self.baseURL = baseURL
-        self.path = path
+        target = baseURL.appending(path: path)
     }
 
-    func method(_ method: String) -> RequestBuilder {
-        var copy = self
-        copy.method = method
-        return copy
+    private func with(_ change: (inout Self) throws -> Void) rethrows -> Self {
+        var next = self
+        try change(&next)
+        return next
     }
 
-    func query(_ name: String, _ value: String?) -> RequestBuilder {
-        guard let value else { return self }
-        var copy = self
-        copy.queryItems.append(URLQueryItem(name: name, value: value))
-        return copy
-    }
-
-    func header(_ name: String, _ value: String) -> RequestBuilder {
-        var copy = self
-        copy.headers[name] = value
-        return copy
-    }
+    func method(_ verb: String) -> Self { with { $0.verb = verb } }
+    func timeout(_ seconds: TimeInterval) -> Self { with { $0.limit = seconds } }
+    func cachePolicy(_ rule: URLRequest.CachePolicy) -> Self { with { $0.caching = rule } }
+    func header(_ field: String, _ text: String) -> Self { with { $0.fields[field] = text } }
 
-    func jsonBody<T: Encodable>(_ value: T) throws -> RequestBuilder {
-        var copy = self
-        copy.body = try JSONEncoder().encode(value)
-        copy.headers["Content-Type"] = "application/json"
-        return copy
+    func query(_ key: String, _ text: String?) -> Self {
+        guard let text else { return self }
+        return with { $0.items.append(URLQueryItem(name: key, value: text)) }
     }
 
-    func timeout(_ interval: TimeInterval) -> RequestBuilder {
-        var copy = self
-        copy.timeout = interval
-        return copy
-    }
-
-    func cachePolicy(_ policy: URLRequest.CachePolicy) -> RequestBuilder {
-        var copy = self
-        copy.cachePolicy = policy
-        return copy
+    func jsonBody(_ model: some Encodable) throws -> Self {
+        let encoded = try JSONEncoder().encode(model)
+        return with {
+            $0.payload = encoded
+            $0.fields["Content-Type"] = "application/json"
+        }
     }
 
-    func build() -> URLRequest {
-        var components = URLComponents(
-            url: baseURL.appendingPathComponent(path),
-            resolvingAgainstBaseURL: true
-        )!
-        if !queryItems.isEmpty {
-            components.queryItems = queryItems
-        }
-        var request = URLRequest(url: components.url!)
-        request.httpMethod = method
-        request.httpBody = body
-        request.cachePolicy = cachePolicy
-        request.timeoutInterval = timeout
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-        return request
+    func build() throws -> URLRequest {
+        var parts = URLComponents(url: target, resolvingAgainstBaseURL: true)
+        if !items.isEmpty { parts?.queryItems = items }
+        guard let url = parts?.url else { throw NetworkError.invalidURL }
+        var built = URLRequest(url: url, cachePolicy: caching, timeoutInterval: limit)
+        built.httpMethod = verb
+        built.httpBody = payload
+        built.allHTTPHeaderFields = fields
+        return built
     }
 }
 
-// Usage
-let request = try RequestBuilder(baseURL: apiURL, path: "users")
+let request = try RequestBuilder(baseURL: apiRoot, path: "tickets")
     .method("POST")
-    .header("X-Request-ID", UUID().uuidString)
-    .jsonBody(CreateUserRequest(name: "Alice", email: "alice@example.com"))
+    .header("X-Correlation-ID", UUID().uuidString)
+    .jsonBody(TicketDraft(subject: "Printer offline"))
     .timeout(15)
     .build()
 ```
 
----
+`query(_:_:)` quietly drops a `nil` value, which keeps optional filters tidy.
 
-## Multipart Form Upload
+## Uploading multipart form data
 
-Multipart/form-data uploads are common for file attachments. Build the
-body manually -- no third-party library needed.
+`multipart/form-data` is plain text framing around each part; you can build
+it without a library.
 
 ```swift
-struct MultipartFormData: Sendable {
-    private let boundary: String
-    private var parts: [Part] = []
+struct MultipartForm: Sendable {
+    private struct Section: Sendable { let lines: [String]; let payload: Data }
 
-    init(boundary: String = UUID().uuidString) {
-        self.boundary = boundary
-    }
+    let separator = "Boundary-\(UUID().uuidString)"
+    private var sections: [Section] = []
 
-    var contentType: String {
-        "multipart/form-data; boundary=\(boundary)"
-    }
+    var headerValue: String { "multipart/form-data; boundary=\(separator)" }
 
-    mutating func addField(name: String, value: String) {
-        parts.append(Part(
-            headers: "Content-Disposition: form-data; name=\"\(name)\"",
-            body: Data(value.utf8)
-        ))
+    mutating func addText(_ value: String, named field: String) {
+        let disposition = #"Content-Disposition: form-data; name="\#(field)""#
+        sections.append(Section(lines: [disposition], payload: Data(value.utf8)))
     }
 
-    mutating func addFile(
-        name: String,
-        filename: String,
-        mimeType: String,
-        data: Data
-    ) {
-        parts.append(Part(
-            headers: """
-            Content-Disposition: form-data; name="\(name)"; filename="\(filename)"\r
-            Content-Type: \(mimeType)
-            """,
-            body: data
-        ))
+    mutating func addFile(_ data: Data, named field: String, filename file: String, type mimeType: String) {
+        let disposition = #"Content-Disposition: form-data; name="\#(field)"; filename="\#(file)""#
+        sections.append(Section(lines: [disposition, "Content-Type: " + mimeType], payload: data))
     }
 
-    func encode() -> Data {
-        var data = Data()
-        let crlf = "\r\n"
-        for part in parts {
-            data.append("--\(boundary)\(crlf)")
-            data.append("\(part.headers)\(crlf)\(crlf)")
-            data.append(part.body)
-            data.append(crlf)
+    func encoded() -> Data {
+        var out = Data()
+        for section in sections {
+            out.append(line: "--\(separator)")
+            section.lines.forEach { out.append(line: $0) }
+            out.append(line: "")
+            out.append(section.payload)
+            out.append(line: "")
         }
-        data.append("--\(boundary)--\(crlf)")
-        return data
-    }
-
-    private struct Part: Sendable {
-        let headers: String
-        let body: Data
+        out.append(line: "--\(separator)--")
+        return out
     }
 }
 
 extension Data {
-    mutating func append(_ string: String) {
-        append(Data(string.utf8))
-    }
+    mutating func append(line: String) { append(Data((line + "\r\n").utf8)) }
 }
 
-// Usage
-var form = MultipartFormData()
-form.addField(name: "title", value: "Profile Photo")
-form.addFile(
-    name: "image",
-    filename: "photo.jpg",
-    mimeType: "image/jpeg",
-    data: imageData
-)
-
-var request = URLRequest(url: uploadURL)
-request.httpMethod = "POST"
-request.setValue(form.contentType, forHTTPHeaderField: "Content-Type")
-request.httpBody = form.encode()
-
-let (data, response) = try await URLSession.shared.upload(
-    for: request,
-    from: form.encode()
-)
+var form = MultipartForm()
+form.addText("Harbor at dusk", named: "caption")
+form.addFile(jpegData, named: "photo", filename: "harbor.jpg", type: "image/jpeg")
+var post = URLRequest(url: uploadURL)
+post.httpMethod = "POST"
+post.allHTTPHeaderFields = ["Content-Type": form.headerValue]
+let (reply, _) = try await session.upload(for: post, from: form.encoded())
 ```
 
----
+`Data(string.utf8)` never fails, so there is no optional to unwrap. For a
+background upload, write `encoded()` to a file and upload the file (see
+[background-websocket.md](background-websocket.md#uploads-from-a-file-on-disk)).
 
-## Download with Progress Tracking
+## Downloads that report progress
 
-Use `bytes(for:)` for real-time progress. The response includes
-`expectedContentLength` for calculating percentage.
+`bytes(for:)` and `bytes(from:)` (iOS 15 and later) expose the body byte by
+byte, and `response.expectedContentLength` gives the total when the server
+sends one:
 
 ```swift
-@available(iOS 15.0, *)
-func downloadWithProgress(
-    from url: URL,
-    progressHandler: @Sendable (Double) -> Void
-) async throws -> Data {
-    let (bytes, response) = try await URLSession.shared.bytes(from: url)
-
-    let expectedLength = response.expectedContentLength
-    var receivedData = Data()
-    if expectedLength > 0 {
-        receivedData.reserveCapacity(Int(expectedLength))
-    }
-
-    var receivedLength: Int64 = 0
-    for try await byte in bytes {
-        receivedData.append(byte)
-        receivedLength += 1
-        if expectedLength > 0 {
-            let progress = Double(receivedLength) / Double(expectedLength)
-            progressHandler(progress)
+func downloadReportingProgress(from url: URL, onFraction: (Double) -> Void) async throws -> Data {
+    let (incoming, response) = try await session.bytes(from: url)
+    let expected = response.expectedContentLength
+    var buffer = Data()
+    if expected > 0 { buffer.reserveCapacity(Int(expected)) }
+    for try await octet in incoming {
+        buffer.append(octet)
+        if expected > 0, buffer.count % 65_536 == 0 {
+            onFraction(Double(buffer.count) / Double(expected))
         }
     }
-
-    return receivedData
+    return buffer
 }
 ```
 
-For large files, prefer `URLSessionDownloadTask` with a delegate for
-better memory efficiency and background support.
+This holds the whole body in memory. For big files use a download task with a
+delegate, which writes to disk and also works in background sessions.
 
-### Download to File with Progress (Delegate-Based)
+### Delegate-Based File Download with Progress
+
+A delegate object can turn callbacks into an `AsyncStream`:
 
 ```swift
-@available(iOS 15.0, *)
-final class DownloadManager: NSObject, URLSessionDownloadDelegate, Sendable {
-    private let continuation: AsyncStream<DownloadEvent>.Continuation
-
-    enum DownloadEvent: Sendable {
-        case progress(Double)
-        case completed(URL)
-        case failed(Error)
-    }
+enum TransferEvent: Sendable {
+    case progress(Double)
+    case finished(URL)
+    case failed(any Error)
+}
 
-    static func download(from url: URL) -> AsyncStream<DownloadEvent> {
-        AsyncStream { continuation in
-            let manager = DownloadManager(continuation: continuation)
-            let session = URLSession(
-                configuration: .default,
-                delegate: manager,
-                delegateQueue: nil
-            )
-            session.downloadTask(with: url).resume()
-        }
-    }
+final class FileDownload: NSObject, URLSessionDownloadDelegate, Sendable {
+    private let continuation: AsyncStream<TransferEvent>.Continuation
 
-    private init(continuation: AsyncStream<DownloadEvent>.Continuation) {
+    private init(continuation: AsyncStream<TransferEvent>.Continuation) {
         self.continuation = continuation
     }
 
-    nonisolated func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didFinishDownloadingTo location: URL
-    ) {
-        // Move file to permanent location before this method returns
-        let destination = FileManager.default.temporaryDirectory
-            .appendingPathComponent(UUID().uuidString)
+    static func start(from url: URL) -> AsyncStream<TransferEvent> {
+        let (stream, continuation) = AsyncStream.makeStream(of: TransferEvent.self)
+        let observer = FileDownload(continuation: continuation)
+        let owner = URLSession(configuration: .default, delegate: observer, delegateQueue: nil)
+        owner.downloadTask(with: url).resume()
+        continuation.onTermination = { _ in owner.invalidateAndCancel() }
+        return stream
+    }
+
+    nonisolated func urlSession(_: URLSession, downloadTask _: URLSessionDownloadTask,
+                                didFinishDownloadingTo location: URL) {
+        let kept = URL.temporaryDirectory.appending(path: UUID().uuidString)
         do {
-            try FileManager.default.moveItem(at: location, to: destination)
-            continuation.yield(.completed(destination))
+            let files = FileManager.default
+            try files.moveItem(at: location, to: kept)
+            continuation.yield(.finished(kept))
         } catch {
             continuation.yield(.failed(error))
         }
         continuation.finish()
     }
 
-    nonisolated func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didWriteData bytesWritten: Int64,
-        totalBytesWritten: Int64,
-        totalBytesExpectedToWrite: Int64
-    ) {
+    nonisolated func urlSession(_: URLSession, downloadTask _: URLSessionDownloadTask,
+                                didWriteData bytesWritten: Int64, totalBytesWritten: Int64,
+                                totalBytesExpectedToWrite: Int64) {
         guard totalBytesExpectedToWrite > 0 else { return }
-        let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
-        continuation.yield(.progress(progress))
+        continuation.yield(.progress(Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)))
     }
 
-    nonisolated func urlSession(
-        _ session: URLSession,
-        task: URLSessionTask,
-        didCompleteWithError error: (any Error)?
-    ) {
-        if let error {
-            continuation.yield(.failed(error))
-            continuation.finish()
-        }
+    nonisolated func urlSession(_: URLSession, task _: URLSessionTask,
+                                didCompleteWithError error: (any Error)?) {
+        guard let error else { return }
+        continuation.yield(.failed(error))
+        continuation.finish()
     }
 }
 ```
 
----
-
-## Cursor-Based Pagination
+The move happens inside `didFinishDownloadingTo` because the system deletes
+`location` as soon as that method returns. A session retains its delegate
+until it is invalidated, so the stream's termination handler invalidates it.
 
-A reusable paginator that conforms to `AsyncSequence`, yielding pages
-of results until the server indicates no more data.
+## Paging by cursor
 
 ```swift
-struct PageResponse<T: Decodable & Sendable>: Decodable, Sendable {
-    let data: [T]
-    let pagination: PaginationInfo
-}
-
-struct PaginationInfo: Decodable, Sendable {
-    let nextCursor: String?
-    let hasMore: Bool
-}
-
-struct CursorPaginator<T: Decodable & Sendable>: AsyncSequence {
-    typealias Element = [T]
-
-    private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
-
-    init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
-        self.fetchPage = fetchPage
-    }
-
-    func makeAsyncIterator() -> Iterator {
-        Iterator(fetchPage: fetchPage)
+struct CursorPage<Item: Decodable & Sendable>: Decodable, Sendable {
+    struct Paging: Decodable, Sendable {
+        let nextCursor: String?
+        let hasMore: Bool
     }
+    let data: [Item]
+    let pagination: Paging
+}
 
-    struct Iterator: AsyncIteratorProtocol {
-        private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
-        private var cursor: String?
-        private var exhausted = false
+struct CursorPager<Item: Decodable & Sendable>: AsyncSequence {
+    typealias Element = [Item]
+    let loadPage: @Sendable (_ cursor: String?) async throws -> CursorPage<Item>
 
-        init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
-            self.fetchPage = fetchPage
-        }
+    struct AsyncIterator: AsyncIteratorProtocol {
+        let loadPage: @Sendable (String?) async throws -> CursorPage<Item>
+        var cursor: String?
+        var finished = false
 
-        mutating func next() async throws -> [T]? {
-            guard !exhausted else { return nil }
+        mutating func next() async throws -> [Item]? {
+            guard !finished else { return nil }
             try Task.checkCancellation()
-
-            let response = try await fetchPage(cursor)
-            cursor = response.pagination.nextCursor
-            exhausted = !response.pagination.hasMore
-
-            return response.data.isEmpty ? nil : response.data
+            let page = try await loadPage(cursor)
+            cursor = page.pagination.nextCursor
+            finished = !page.pagination.hasMore
+            return page.data.isEmpty ? nil : page.data
         }
     }
-}
 
-// Usage
-let paginator = CursorPaginator<User> { cursor in
-    var queryItems = [URLQueryItem(name: "limit", value: "50")]
-    if let cursor {
-        queryItems.append(URLQueryItem(name: "cursor", value: cursor))
-    }
-    return try await client.get(
-        PageResponse<User>.self,
-        path: "users",
-        queryItems: queryItems
-    )
+    func makeAsyncIterator() -> AsyncIterator { AsyncIterator(loadPage: loadPage) }
 }
 
-var allUsers: [User] = []
-for try await batch in paginator {
-    allUsers.append(contentsOf: batch)
+let pager = CursorPager<Comment> { cursor in
+    let query = [URLQueryItem(name: "limit", value: "50")]
+        + (cursor.map { [URLQueryItem(name: "cursor", value: $0)] } ?? [])
+    return try await client.fetch(Endpoint(path: "comments", queryItems: query),
+                                  as: CursorPage<Comment>.self)
 }
+var comments: [Comment] = []
+for try await batch in pager { comments += batch }
 ```
 
----
-
-## Offset-Based Pagination
+## Paging by offset
 
 ```swift
-struct OffsetPaginator<T: Decodable & Sendable>: AsyncSequence {
-    typealias Element = [T]
-
-    private let pageSize: Int
-    private let fetchPage: @Sendable (Int, Int) async throws -> [T]
-
-    init(
-        pageSize: Int = 20,
-        fetchPage: @escaping @Sendable (_ offset: Int, _ limit: Int) async throws -> [T]
-    ) {
-        self.pageSize = pageSize
-        self.fetchPage = fetchPage
-    }
-
-    func makeAsyncIterator() -> Iterator {
-        Iterator(pageSize: pageSize, fetchPage: fetchPage)
-    }
-
-    struct Iterator: AsyncIteratorProtocol {
-        private let pageSize: Int
-        private let fetchPage: @Sendable (Int, Int) async throws -> [T]
-        private var offset = 0
-        private var exhausted = false
-
-        init(
-            pageSize: Int,
-            fetchPage: @escaping @Sendable (Int, Int) async throws -> [T]
-        ) {
-            self.pageSize = pageSize
-            self.fetchPage = fetchPage
-        }
-
-        mutating func next() async throws -> [T]? {
-            guard !exhausted else { return nil }
+struct OffsetPager<Item: Sendable>: AsyncSequence {
+    typealias Element = [Item]
+    var pageSize = 20
+    let loadPage: @Sendable (_ skip: Int, _ take: Int) async throws -> [Item]
+
+    struct AsyncIterator: AsyncIteratorProtocol {
+        let pageSize: Int
+        let loadPage: @Sendable (Int, Int) async throws -> [Item]
+        var offset = 0
+        var finished = false
+
+        mutating func next() async throws -> [Item]? {
+            guard !finished else { return nil }
             try Task.checkCancellation()
-
-            let items = try await fetchPage(offset, pageSize)
+            let items = try await loadPage(offset, pageSize)
             offset += items.count
-            if items.count < pageSize { exhausted = true }
-
+            finished = items.count < pageSize
             return items.isEmpty ? nil : items
         }
     }
+
+    func makeAsyncIterator() -> AsyncIterator { AsyncIterator(pageSize: pageSize, loadPage: loadPage) }
 }
 ```
 
----
+A short page means the server has nothing more, so the next call ends the
+sequence without another request.
 
-## URLProtocol Mock for Testing
+## Stubbing the network with URLProtocol
 
-`URLProtocol` is the correct way to mock network responses at the
-transport level. It works with any URLSession configuration and does
-not require changing production code.
+A `URLProtocol` subclass intercepts requests at the transport layer. It works
+with any session configuration and needs no change to production code, so
+it tests the real client, middleware and validation.
 
 ```swift
-final class MockURLProtocol: URLProtocol {
-    nonisolated(unsafe) static var requestHandler: ((URLRequest) throws -> (HTTPURLResponse, Data))?
+final class StubURLProtocol: URLProtocol {
+    nonisolated(unsafe) static var respond: ((URLRequest) throws -> (HTTPURLResponse, Data))?
 
-    override class func canInit(with request: URLRequest) -> Bool { true }
-
-    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+    override class func canInit(with _: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for original: URLRequest) -> URLRequest { original }
 
     override func startLoading() {
-        guard let handler = Self.requestHandler else {
-            fatalError("MockURLProtocol.requestHandler is not set")
+        guard let respond = Self.respond else {
+            client?.urlProtocol(self, didFailWithError: URLError(.resourceUnavailable))
+            return
         }
-
         do {
-            let (response, data) = try handler(request)
-            client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
-            client?.urlProtocol(self, didLoad: data)
+            let (head, payload) = try respond(request)
+            client?.urlProtocol(self, didReceive: head, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: payload)
             client?.urlProtocolDidFinishLoading(self)
         } catch {
             client?.urlProtocol(self, didFailWithError: error)
@@ -715,321 +529,241 @@ final class MockURLProtocol: URLProtocol {
 }
 ```
 
+A missing stub fails the request instead of crashing the test run.
+
 ### Test Setup
 
 ```swift
 import Testing
+import Foundation
 
-@Suite struct APIClientTests {
-    let client: APIClient
-    let session: URLSession
-
-    init() {
+@Suite(.serialized)
+struct APIClientTests {
+    func makeClient(middleware: [any RequestMiddleware] = []) throws -> APIClient {
         let config = URLSessionConfiguration.ephemeral
-        config.protocolClasses = [MockURLProtocol.self]
-        session = URLSession(configuration: config)
-        client = APIClient(
-            baseURL: URL(string: "https://api.example.com")!,
-            session: session
-        )
+        config.protocolClasses = [StubURLProtocol.self]
+        return APIClient(baseURL: try #require(URL(string: "https://api.test")),
+                         session: URLSession(configuration: config), middleware: middleware)
     }
 
-    @Test func fetchUsersDecodesCorrectly() async throws {
-        let usersJSON = """
-        [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
-        """
-        MockURLProtocol.requestHandler = { request in
-            #expect(request.url?.path == "/users")
-            let response = HTTPURLResponse(
-                url: request.url!,
-                statusCode: 200,
-                httpVersion: nil,
-                headerFields: ["Content-Type": "application/json"]
-            )!
-            return (response, Data(usersJSON.utf8))
-        }
-
-        let users: [User] = try await client.get([User].self, path: "users")
-        #expect(users.count == 2)
-        #expect(users[0].name == "Alice")
+    func reply(_ status: Int, _ json: String, for request: URLRequest) throws -> (HTTPURLResponse, Data) {
+        let url = try #require(request.url)
+        let response = try #require(HTTPURLResponse(url: url, statusCode: status, httpVersion: nil, headerFields: nil))
+        return (response, Data(json.utf8))
     }
 
-    @Test func fetchReturnsHTTPError() async throws {
-        MockURLProtocol.requestHandler = { request in
-            let response = HTTPURLResponse(
-                url: request.url!,
-                statusCode: 404,
-                httpVersion: nil,
-                headerFields: nil
-            )!
-            return (response, Data())
+    @Test func decodesProjects() async throws {
+        StubURLProtocol.respond = { request in
+            #expect(request.url?.path() == "/projects")
+            return try self.reply(200, #"[{"id":7,"title":"Atlas"},{"id":8,"title":"Beacon"}]"#, for: request)
         }
+        let projects = try await makeClient().fetch(Endpoint(path: "projects"), as: [Project].self)
+        #expect(projects.count == 2)
+    }
 
+    @Test func notFoundThrows() async throws {
+        StubURLProtocol.respond = { try self.reply(404, "{}", for: $0) }
+        let client = try makeClient()
         await #expect(throws: NetworkError.self) {
-            let _: [User] = try await client.get([User].self, path: "missing")
+            try await client.perform(Endpoint(path: "projects/99"))
         }
     }
 
-    @Test func requestIncludesAuthHeader() async throws {
-        let authClient = APIClient(
-            baseURL: URL(string: "https://api.example.com")!,
-            session: session,
-            middlewares: [AuthMiddleware { "test-token" }]
-        )
-
-        MockURLProtocol.requestHandler = { request in
-            #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer test-token")
-            let response = HTTPURLResponse(
-                url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil
-            )!
-            return (response, Data("{}".utf8))
+    @Test func middlewareSignsRequests() async throws {
+        StubURLProtocol.respond = { request in
+            #expect(request.allHTTPHeaderFields?["Authorization"] == "Bearer fixture-token")
+            return try self.reply(200, "{}", for: request)
         }
-
-        let _: EmptyResponse = try await authClient.get(EmptyResponse.self, path: "me")
+        let client = try makeClient(middleware: [BearerTokenMiddleware { "fixture-token" }])
+        _ = try await client.fetch(Endpoint(path: "me"), as: Empty.self)
     }
 }
 
-struct EmptyResponse: Decodable, Sendable {}
+struct Project: Decodable, Sendable { let id: Int; let title: String }
+struct Empty: Decodable, Sendable {}
 ```
 
----
+The suite is serialized because the stub is shared static state. `Empty`
+decodes a `{}` body when only the status matters.
 
-## Retry with Exponential Backoff
+## Retries that back off exponentially
 
-Respect cancellation. Do not retry client errors (4xx except 429 rate
-limiting). Include jitter to prevent thundering herd.
+Three rules: stop on cancellation, do not retry a 4xx other than 429, and
+add jitter so that many clients do not retry in lockstep after an outage.
+`withRetry` in SKILL.md implements this with a `maxDelay` cap, a
+`shouldRetry` predicate, `Task.checkCancellation()` before every attempt, and
+up to 10% random jitter on the capped delay. It throws immediately when the
+predicate says no or on the final attempt. The default predicate:
 
 ```swift
-func withRetry<T: Sendable>(
-    maxAttempts: Int = 3,
-    initialDelay: Duration = .seconds(1),
-    maxDelay: Duration = .seconds(30),
-    shouldRetry: @Sendable (Error) -> Bool = { error in
-        if error is CancellationError { return false }
-        if case NetworkError.httpError(let code, _, _) = error {
-            return code >= 500 || code == 429
-        }
-        if let urlError = error as? URLError {
-            return [.timedOut, .networkConnectionLost, .notConnectedToInternet]
-                .contains(urlError.code)
-        }
+func isTransient(_ error: any Error) -> Bool {
+    switch error {
+    case is CancellationError:
         return false
-    },
-    operation: @Sendable () async throws -> T
-) async throws -> T {
-    var lastError: Error?
-
-    for attempt in 0..<maxAttempts {
-        try Task.checkCancellation()
-        do {
-            return try await operation()
-        } catch {
-            lastError = error
-            guard shouldRetry(error), attempt < maxAttempts - 1 else {
-                throw error
-            }
-            // Exponential backoff with jitter
-            let base = Double(initialDelay.components.seconds) * pow(2.0, Double(attempt))
-            let capped = min(base, Double(maxDelay.components.seconds))
-            let jitter = Double.random(in: 0...(capped * 0.1))
-            let delay = Duration.seconds(capped + jitter)
-            try await Task.sleep(for: delay)
+    case let failure as NetworkError:
+        switch failure {
+        case .httpStatus(let status, _, _): return status >= 500 || status == 429
+        case .timedOut, .noConnection: return true
+        case .transport(let urlError): return urlError.code == .networkConnectionLost
+        default: return false
         }
+    case let urlError as URLError:
+        let transient: Set<URLError.Code> = [.timedOut, .networkConnectionLost, .notConnectedToInternet]
+        return transient.contains(urlError.code)
+    default:
+        return false
     }
-
-    throw lastError!
 }
 
-// Usage
-let users = try await withRetry {
-    try await client.get([User].self, path: "users")
+let summary = try await withRetry(maxAttempts: 4) {
+    try await client.fetch(Endpoint(path: "summary"), as: Summary.self)
 }
 ```
 
----
-
-## Certificate Pinning (URLSessionDelegate)
-
-Prefer ATS `NSPinnedDomains` for declarative certificate pinning when the
-pinset can ship in `Info.plist`. For manual `URLSessionDelegate` trust work,
-defer to the `swift-security` skill: correct SPKI pinning requires hashing
-the Subject Public Key Info structure, not just the raw key bytes returned by
-`SecKeyCopyExternalRepresentation`.
+The raw `URLError` branch covers callers that talk to URLSession directly
+instead of through `APIClient`.
 
-**Important considerations:**
-- Pin at least two keys (primary + backup) to avoid lockout during rotation.
-- Have a remote kill switch (feature flag) to disable pinning in emergencies.
-- Test certificate rotation in staging before deploying to production.
-- Always evaluate system trust before applying pins.
-- Keep certificate-trust implementation details in the security boundary.
+## Pinning certificates in a session delegate
 
----
+- When the pins can ship in `Info.plist`, use ATS `NSPinnedDomains` instead
+  of writing trust code.
+- Hand-written trust evaluation in `urlSession(_:didReceive:completionHandler:)`
+  belongs to `swift-security`. SPKI pinning hashes the DER-encoded Subject
+  Public Key Info; the bytes from `SecKeyCopyExternalRepresentation` alone are
+  not that.
+- Always pin at least two keys, the live one and a backup, so a rotation
+  cannot lock users out.
+- Keep a remote switch (a feature flag) that can turn pinning off in an
+  emergency.
+- Try a full key rotation against a staging host first, never first in production.
+- Run the system trust evaluation first; pins only narrow an already trusted
+  chain.
+- Keep the trust implementation inside the security module rather than
+  scattering it through networking code.
 
-## Request Logging / Debugging Middleware
+## Middleware that logs requests
 
-Log outgoing requests and incoming responses for debugging. Disable or
-reduce verbosity in release builds.
+Log traffic while developing, and compile it out or turn it down for
+release.
 
 ```swift
-struct LoggingMiddleware: RequestMiddleware {
-    let logger: Logger
+import OSLog
 
-    func prepare(_ request: URLRequest) async throws -> URLRequest {
+struct DebugLogMiddleware: RequestMiddleware {
+    private let log = Logger(subsystem: "app.networking", category: "http")
+
+    func adapt(_ request: inout URLRequest) async throws {
         #if DEBUG
-        let method = request.httpMethod ?? "GET"
-        let url = request.url?.absoluteString ?? "unknown"
-        logger.debug("[\(method)] \(url)")
-        if let headers = request.allHTTPHeaderFields {
-            for (key, value) in headers where key != "Authorization" {
-                logger.debug("  \(key): \(value)")
-            }
-        }
-        if let body = request.httpBody, body.count < 10_000 {
-            logger.debug("  Body: \(String(data: body, encoding: .utf8) ?? "<binary>")")
+        let verb = request.httpMethod ?? "GET"
+        log.debug("\(verb) \(request.url?.absoluteString ?? "-")")
+        let visible = (request.allHTTPHeaderFields ?? [:]).filter { $0.key != "Authorization" }
+        visible.forEach { log.debug("  \($0.key): \($0.value)") }
+        if let payload = request.httpBody, payload.count < 10_000 {
+            log.debug("  body: \(String(decoding: payload, as: UTF8.self))")
         }
         #endif
-        return request
     }
 }
 ```
 
+The `Authorization` header is never written out, and large bodies are
+skipped.
+
 ### Response Logging
 
-To log responses, wrap the transport call rather than using middleware:
+Middleware sees only the outgoing request. To log outcomes and timing, wrap
+the transport call:
 
 ```swift
-func loggedRequest<T: Decodable & Sendable>(
-    _ type: T.Type,
-    endpoint: Endpoint,
-    logger: Logger
-) async throws -> T {
-    let start = ContinuousClock().now
+func timed(_ outgoing: URLRequest, on session: URLSession, log: Logger) async throws -> (Data, URLResponse) {
+    let clock = ContinuousClock()
+    let start = clock.now
+    let route = outgoing.url?.path() ?? "-"
     do {
-        let result: T = try await request(type, endpoint: endpoint)
-        let elapsed = ContinuousClock().now - start
-        logger.debug("[\(endpoint.method.rawValue)] \(endpoint.path) -> 200 (\(elapsed))")
+        let result = try await session.data(for: outgoing)
+        let status = (result.1 as? HTTPURLResponse)?.statusCode ?? -1
+        log.debug("\(status) \(route) in \(clock.now - start)")
         return result
     } catch {
-        let elapsed = ContinuousClock().now - start
-        logger.error("[\(endpoint.method.rawValue)] \(endpoint.path) -> ERROR (\(elapsed)): \(error)")
+        log.error("failed \(route) after \(clock.now - start): \(error.localizedDescription)")
         throw error
     }
 }
 ```
 
----
-
-## Request Caching Strategies
+## Choosing a cache policy
 
 ### URLCache Configuration
 
 ```swift
-// 50 MB memory / 200 MB disk cache
-let cache = URLCache(
-    memoryCapacity: 50 * 1024 * 1024,
-    diskCapacity: 200 * 1024 * 1024,
-    directory: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)
-        .first?.appendingPathComponent("URLCache")
-)
-
+let cacheFolder = URL.cachesDirectory.appending(path: "HTTPCache")
+let megabyte = 1_048_576
+let cache = URLCache(memoryCapacity: 50 * megabyte, diskCapacity: 200 * megabyte, directory: cacheFolder)
 let config = URLSessionConfiguration.default
 config.urlCache = cache
 config.requestCachePolicy = .returnCacheDataElseLoad
-
-let session = URLSession(configuration: config)
 ```
 
 ### Per-Request Cache Control
 
-```swift
-// Force fresh data
-var request = URLRequest(url: url)
-request.cachePolicy = .reloadIgnoringLocalCacheData
-
-// Use cached if available
-request.cachePolicy = .returnCacheDataElseLoad
-
-// Cache only (offline mode)
-request.cachePolicy = .returnCacheDataDontLoad
-```
+| Policy | Behaviour |
+|---|---|
+| `.reloadIgnoringLocalCacheData` | Always go to the network |
+| `.returnCacheDataElseLoad` | Use a cached response if there is one |
+| `.returnCacheDataDontLoad` | Cache only; an offline mode |
 
 ### ETag / If-None-Match
 
 ```swift
-func fetchWithETag<T: Decodable & Sendable>(
-    _ type: T.Type,
-    url: URL,
-    cachedETag: String?,
-    cachedData: Data?
-) async throws -> (T, String?) {
-    var request = URLRequest(url: url)
-    if let etag = cachedETag {
-        request.setValue(etag, forHTTPHeaderField: "If-None-Match")
-    }
-
-    let (data, response) = try await URLSession.shared.data(for: request)
-    guard let http = response as? HTTPURLResponse else {
-        throw NetworkError.invalidResponse
-    }
-
-    if http.statusCode == 304, let cachedData {
-        // Not modified -- use cached data
-        let decoded = try JSONDecoder().decode(T.self, from: cachedData)
-        return (decoded, cachedETag)
-    }
-
-    let newETag = http.value(forHTTPHeaderField: "ETag")
-    let decoded = try JSONDecoder().decode(T.self, from: data)
-    return (decoded, newETag)
+func fetchRevalidating<Model: Decodable>(_ kind: Model.Type, at address: URL,
+                                         stored: (etag: String, body: Data)?) async throws -> (Model, String?) {
+    var conditional = URLRequest(url: address)
+    if let stored { conditional.addValue(stored.etag, forHTTPHeaderField: "If-None-Match") }
+    let (fresh, reply) = try await session.data(for: conditional)
+    let head = reply as? HTTPURLResponse
+    if head?.statusCode == 304, let stored {
+        return (try JSONDecoder().decode(kind, from: stored.body), stored.etag)
+    }
+    return (try JSONDecoder().decode(kind, from: fresh), head?.value(forHTTPHeaderField: "ETag"))
 }
 ```
 
----
+A 304 means the stored copy is still current, so decode it and keep its tag;
+otherwise decode the fresh body and store the new tag.
 
-## Server-Sent Events (SSE) Parsing
-
-Use `bytes(for:)` to consume a streaming SSE endpoint.
+## Reading a server-sent event stream
 
 ```swift
-struct ServerSentEvent: Sendable {
-    var event: String?
+struct StreamEvent: Sendable {
+    var name: String?
     var data: String
     var id: String?
 }
 
-func sseStream(from url: URL) -> AsyncThrowingStream<ServerSentEvent, Error> {
-    AsyncThrowingStream { continuation in
-        let task = Task {
+func eventStream(for request: URLRequest, on session: URLSession) -> AsyncThrowingStream<StreamEvent, any Error> {
+    var accepting = request
+    accepting.addValue("text/event-stream", forHTTPHeaderField: "Accept")
+    let streaming = accepting
+    return AsyncThrowingStream { continuation in
+        let reader = Task {
             do {
-                var request = URLRequest(url: url)
-                request.setValue("text/event-stream", forHTTPHeaderField: "Accept")
-
-                let (bytes, _) = try await URLSession.shared.bytes(for: request)
-
-                var currentEvent: String?
-                var currentData = ""
-                var currentId: String?
-
-                for try await line in bytes.lines {
-                    if line.isEmpty {
-                        // Empty line = dispatch event
-                        if !currentData.isEmpty {
-                            continuation.yield(ServerSentEvent(
-                                event: currentEvent,
-                                data: currentData.trimmingCharacters(in: .newlines),
-                                id: currentId
-                            ))
+                let (feed, _) = try await session.bytes(for: streaming)
+                var pending = StreamEvent(data: "")
+                var dataLines: [String] = []
+                for try await row in feed.lines {
+                    if row.isEmpty {
+                        if !dataLines.isEmpty {
+                            pending.data = dataLines.joined(separator: "\n")
+                            continuation.yield(pending)
                         }
-                        currentEvent = nil
-                        currentData = ""
-                        currentId = nil
-                    } else if line.hasPrefix("event:") {
-                        currentEvent = String(line.dropFirst(6)).trimmingCharacters(in: .whitespaces)
-                    } else if line.hasPrefix("data:") {
-                        let value = String(line.dropFirst(5)).trimmingCharacters(in: .whitespaces)
-                        currentData += currentData.isEmpty ? value : "\n" + value
-                    } else if line.hasPrefix("id:") {
-                        currentId = String(line.dropFirst(3)).trimmingCharacters(in: .whitespaces)
+                        pending = StreamEvent(data: "")
+                        dataLines = []
+                    } else if let value = field("event", in: row) {
+                        pending.name = value
+                    } else if let value = field("data", in: row) {
+                        dataLines.append(value)
+                    } else if let value = field("id", in: row) {
+                        pending.id = value
                     }
                 }
                 continuation.finish()
@@ -1037,24 +771,32 @@ func sseStream(from url: URL) -> AsyncThrowingStream<ServerSentEvent, Error> {
                 continuation.finish(throwing: error)
             }
         }
-        continuation.onTermination = { _ in task.cancel() }
+        continuation.onTermination = { _ in reader.cancel() }
     }
 }
+
+private func field(_ name: String, in row: String) -> String? {
+    guard row.hasPrefix(name + ":") else { return nil }
+    return row.dropFirst(name.count + 1).trimmingCharacters(in: .whitespaces)
+}
 ```
 
----
+The request is copied into a `let` before the reader `Task` is created: a
+captured `var` would be shared with the task, and Swift 6 rejects that as a
+possible data race. A blank line ends an event; several `data:` lines join
+with newlines.
+`AsyncLineSequence` may not hand you empty lines on every OS release, and the
+parser depends on them. If events never dispatch, split `bytes` on `\n`
+yourself instead of using `lines`, and test against the real endpoint.
 
-## Configured URLSession for Production
+## A production-ready session setup
 
-Use a configured session for production clients instead of calling
-`URLSession.shared` from request methods. Set explicit request/resource
-timeouts, cache behavior, connectivity policy, and any delegates needed for
-authentication challenges, redirects, metrics, pinning boundaries, or
-background transfers before creating the `URLSession`.
+Decide timeouts, caching, connectivity behaviour and delegates once, when the
+session is created, and pass that session to clients.
 
 ```swift
 enum SessionFactory {
-    static func makeDefault(delegate: (any URLSessionDelegate)? = nil) -> URLSession {
+    static func standard(observer: (any URLSessionDelegate)? = nil) -> URLSession {
         let config = URLSessionConfiguration.default
         config.timeoutIntervalForRequest = 30
         config.timeoutIntervalForResource = 300
@@ -1065,18 +807,9 @@ enum SessionFactory {
             "Accept": "application/json",
             "Accept-Encoding": "gzip, deflate, br",
         ]
-
-        let cache = URLCache(
-            memoryCapacity: 25 * 1024 * 1024,
-            diskCapacity: 100 * 1024 * 1024
-        )
-        config.urlCache = cache
-
-        return URLSession(
-            configuration: config,
-            delegate: delegate,
-            delegateQueue: nil
-        )
+        let mb = 1_048_576
+        config.urlCache = URLCache(memoryCapacity: 25 * mb, diskCapacity: 100 * mb)
+        return URLSession(configuration: config, delegate: observer, delegateQueue: nil)
     }
 }
 ```