@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/ios-networking/references/lightweight-clients.md

@@ -1,93 +1,133 @@
-# Lightweight Clients (Closure-Based)
+# Lightweight Closure-Based Clients
 
-Use this pattern to keep networking or service dependencies simple and testable without introducing a full view model or heavy DI framework. It works well for SwiftUI apps where you want a small, composable API surface that can be swapped in previews/tests.
+In an MV-style SwiftUI app a full view model plus a dependency injection
+container is often more ceremony than the feature needs. A client made of a
+few async closures keeps the service boundary swappable for previews and
+tests with almost no code.
 
 ## Intent
-- Provide a tiny "client" type made of async closures.
-- Keep business logic in a store or feature layer, not the view.
-- Enable easy stubbing in previews/tests.
+
+- The client is a small value type whose members are async closures.
+- Business rules and state live in a store (or feature layer), not in the
+  view and not in the client.
+- A preview or a test replaces the whole client with a stub in one line.
 
 ## Minimal shape
+
 ```swift
-struct SomeClient {
-    var fetchItems: (_ limit: Int) async throws -> [Item]
-    var search: (_ query: String, _ limit: Int) async throws -> [Item]
+struct RecipeClient: Sendable {
+    var popular: @Sendable (_ count: Int) async throws -> [Recipe]
+    var search: @Sendable (_ text: String, _ count: Int) async throws -> [Recipe]
 }
 
-extension SomeClient {
-    static func live(baseURL: URL = URL(string: "https://example.com")!) -> SomeClient {
-        let session = URLSession.shared  // Prototyping only. For production, create a URLSession with timeoutIntervalForRequest: 30, timeoutIntervalForResource: 300, waitsForConnectivity: true, and a URLCache.
-        return SomeClient(
-            fetchItems: { limit in
-                // build URL, call session, decode
-            },
-            search: { query, limit in
-                // build URL, call session, decode
+extension RecipeClient {
+    static func live(baseURL: URL, session: URLSession) -> RecipeClient {
+        let decoder = JSONDecoder()
+        decoder.keyDecodingStrategy = .convertFromSnakeCase
+
+        @Sendable func get(_ path: String, _ query: [URLQueryItem]) async throws -> [Recipe] {
+            guard var parts = URLComponents(url: baseURL.appending(path: path),
+                                            resolvingAgainstBaseURL: false) else { throw NetworkError.invalidURL }
+            parts.queryItems = query
+            guard let url = parts.url else { throw NetworkError.invalidURL }
+            let (data, response) = try await session.data(from: url)
+            guard let http = response as? HTTPURLResponse, (200..<300).contains(http.statusCode) else {
+                throw NetworkError.invalidResponse
+            }
+            return try decoder.decode([Recipe].self, from: data)
+        }
+
+        return RecipeClient(
+            popular: { count in try await get("recipes/popular", [URLQueryItem(name: "limit", value: "\(count)")]) },
+            search: { text, count in
+                try await get("recipes/search", [URLQueryItem(name: "q", value: text),
+                                                 URLQueryItem(name: "limit", value: "\(count)")])
             }
         )
     }
 }
 ```
 
+The base URL and session are parameters, not defaults. There is no URL
+literal to force-unwrap, and the caller passes a configured session:
+`timeoutIntervalForRequest` 30, `timeoutIntervalForResource` 300,
+`waitsForConnectivity` on, and a `URLCache`. `URLSession.shared` is fine for a
+throwaway prototype and nothing more. Read the base URL from configuration
+at the composition root and handle a missing value there.
+
 ## Usage pattern
+
 ```swift
-@MainActor
-@Observable final class ItemsStore {
-    enum LoadState { case idle, loading, loaded, failed(String) }
+@MainActor @Observable
+final class RecipeStore {
+    enum Phase: Equatable { case idle, loading, ready, failed(String) }
 
-    var items: [Item] = []
-    var state: LoadState = .idle
-    private let client: SomeClient
+    private(set) var phase: Phase = .idle
+    private(set) var recipes: [Recipe] = []
+    private let client: RecipeClient
 
-    init(client: SomeClient) {
-        self.client = client
-    }
+    init(client: RecipeClient) { self.client = client }
 
-    func load(limit: Int = 20) async {
-        state = .loading
+    func loadPopular(count: Int = 20) async {
+        phase = .loading
         do {
-            items = try await client.fetchItems(limit)
-            state = .loaded
+            recipes = try await client.popular(count)
+            phase = .ready
         } catch {
-            state = .failed(error.localizedDescription)
+            phase = .failed(error.localizedDescription)
         }
     }
 }
-```
 
-```swift
-struct ContentView: View {
-    @Environment(ItemsStore.self) private var store
+struct PopularRecipesView: View {
+    @Environment(RecipeStore.self) private var store
 
     var body: some View {
-        List(store.items) { item in
-            Text(item.title)
-        }
-        .task { await store.load() }
+        List(store.recipes) { Text($0.title) }
+            .task { await store.loadPopular() }
     }
 }
-```
 
-```swift
 @main
-struct MyApp: App {
-    @State private var store = ItemsStore(client: .live())
+struct CookbookApp: App {
+    @State private var store: RecipeStore
+
+    init() {
+        let apiRoot = AppConfiguration.apiRoot
+        store = RecipeStore(client: .live(baseURL: apiRoot, session: SessionFactory.standard()))
+    }
 
     var body: some Scene {
-        WindowGroup {
-            ContentView()
-                .environment(store)
-        }
+        WindowGroup { PopularRecipesView().environment(store) }
     }
 }
 ```
 
+`AppConfiguration.apiRoot` stands for however the app resolves its base URL
+without a force unwrap (for example a validated `Info.plist` value).
+`SessionFactory` is in [urlsession-patterns.md](urlsession-patterns.md#a-production-ready-session-setup).
+
 ## Guidance
-- Keep decoding and URL-building in the client; keep state changes in the store.
-- Make the store accept the client in `init` and keep it private.
-- Avoid global singletons; use `.environment` for store injection.
-- If you need multiple variants (mock/stub), add `static func mock(...)`.
+
+- URL building and decoding belong in the client; state transitions belong
+  in the store.
+- The store gets its client through `init` and keeps it `private`.
+- Share the store through `.environment`, not through a global singleton.
+- Offer stubs next to `live`:
+
+```swift
+extension RecipeClient {
+    static func stub(_ recipes: [Recipe] = [], failure: (any Error)? = nil) -> RecipeClient {
+        RecipeClient(
+            popular: { _ in if let failure { throw failure }; return recipes },
+            search: { _, _ in if let failure { throw failure }; return recipes }
+        )
+    }
+}
+```
 
 ## Pitfalls
-- Don't put UI state in the client; keep state in the store.
-- Don't capture `self` or view state in the client closures.
+
+- No UI state in the client. It fetches; the store remembers.
+- Client closures must not capture `self`, a view, or view state. Capture
+  only what `live` was given (session, base URL, decoder).