@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,93 @@
+# Lightweight Clients (Closure-Based)
+
+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.
+
+## 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.
+
+## Minimal shape
+```swift
+struct SomeClient {
+    var fetchItems: (_ limit: Int) async throws -> [Item]
+    var search: (_ query: String, _ limit: Int) async throws -> [Item]
+}
+
+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
+            }
+        )
+    }
+}
+```
+
+## Usage pattern
+```swift
+@MainActor
+@Observable final class ItemsStore {
+    enum LoadState { case idle, loading, loaded, failed(String) }
+
+    var items: [Item] = []
+    var state: LoadState = .idle
+    private let client: SomeClient
+
+    init(client: SomeClient) {
+        self.client = client
+    }
+
+    func load(limit: Int = 20) async {
+        state = .loading
+        do {
+            items = try await client.fetchItems(limit)
+            state = .loaded
+        } catch {
+            state = .failed(error.localizedDescription)
+        }
+    }
+}
+```
+
+```swift
+struct ContentView: View {
+    @Environment(ItemsStore.self) private var store
+
+    var body: some View {
+        List(store.items) { item in
+            Text(item.title)
+        }
+        .task { await store.load() }
+    }
+}
+```
+
+```swift
+@main
+struct MyApp: App {
+    @State private var store = ItemsStore(client: .live())
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environment(store)
+        }
+    }
+}
+```
+
+## 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(...)`.
+
+## 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.

package/pipeline/skills/shared/external/ios-networking/references/network-framework.md

@@ -0,0 +1,563 @@
+# Network.framework
+
+Low-level networking with the Network framework. Use when you need TCP/UDP
+connections, WebSockets, Bonjour service discovery, local servers, or network
+path monitoring beyond what URLSession provides. All examples target
+Swift 6.2 / iOS 26+.
+
+## Contents
+
+- [NWConnection](#nwconnection)
+- [NWListener](#nwlistener)
+- [NWBrowser](#nwbrowser)
+- [NWPathMonitor](#nwpathmonitor)
+- [NWParameters Configuration](#nwparameters-configuration)
+- [TLS Configuration](#tls-configuration)
+- [WebSocket Support](#websocket-support)
+- [NetworkConnection (iOS 26+)](#networkconnection-ios-26)
+
+## NWConnection
+
+A bidirectional data connection between a local and remote endpoint. Supports
+TCP, UDP, TLS, DTLS, QUIC, and WebSocket protocols.
+
+**Documentation:**
+[sosumi.ai/documentation/network/nwconnection](https://sosumi.ai/documentation/network/nwconnection)
+
+### TCP Connection
+
+```swift
+import Network
+
+let connection = NWConnection(
+    host: "api.example.com",
+    port: 443,
+    using: .tls
+)
+
+connection.stateUpdateHandler = { state in
+    switch state {
+    case .ready:
+        print("Connected")
+    case .waiting(let error):
+        print("Waiting: \(error.localizedDescription)")
+    case .failed(let error):
+        print("Failed: \(error.localizedDescription)")
+    case .cancelled:
+        print("Cancelled")
+    default:
+        break
+    }
+}
+
+connection.start(queue: .main)
+```
+
+### Sending Data
+
+```swift
+func send(_ data: Data, on connection: NWConnection) {
+    connection.send(
+        content: data,
+        contentContext: .defaultMessage,
+        isComplete: true,
+        completion: .contentProcessed { error in
+            if let error {
+                print("Send error: \(error)")
+            }
+        }
+    )
+}
+```
+
+### Receiving Data
+
+```swift
+func receive(on connection: NWConnection) {
+    connection.receive(
+        minimumIncompleteLength: 1,
+        maximumLength: 65536
+    ) { content, contentContext, isComplete, error in
+        if let data = content {
+            handleData(data)
+        }
+        if isComplete {
+            connection.cancel()
+        } else if let error {
+            print("Receive error: \(error)")
+        } else {
+            // Continue receiving
+            receive(on: connection)
+        }
+    }
+}
+```
+
+### UDP Connection
+
+```swift
+let udpConnection = NWConnection(
+    host: "239.0.0.1",
+    port: 5000,
+    using: .udp
+)
+
+udpConnection.stateUpdateHandler = { state in
+    if case .ready = state {
+        let message = "Hello".data(using: .utf8)!
+        udpConnection.send(
+            content: message,
+            completion: .contentProcessed { _ in }
+        )
+    }
+}
+
+udpConnection.start(queue: .main)
+```
+
+### Connection Lifecycle
+
+States flow in order: `setup` → `preparing` → `ready` → `cancelled`/`failed`.
+A connection may enter `waiting(NWError)` if the network path is unavailable
+and retry when connectivity returns.
+
+Always cancel connections when done:
+
+```swift
+connection.cancel()  // Releases resources, transitions to .cancelled
+```
+
+## NWListener
+
+An object that listens for incoming network connections. Use to create local
+TCP/UDP servers.
+
+**Documentation:**
+[sosumi.ai/documentation/network/nwlistener](https://sosumi.ai/documentation/network/nwlistener)
+
+### TCP Server
+
+```swift
+import Network
+
+func startServer(port: UInt16) throws -> NWListener {
+    let listener = try NWListener(using: .tcp, on: NWEndpoint.Port(rawValue: port)!)
+
+    listener.stateUpdateHandler = { state in
+        switch state {
+        case .ready:
+            print("Listening on port \(listener.port?.rawValue ?? 0)")
+        case .failed(let error):
+            print("Listener failed: \(error)")
+            listener.cancel()
+        default:
+            break
+        }
+    }
+
+    listener.newConnectionHandler = { connection in
+        print("New connection from \(connection.endpoint)")
+        connection.stateUpdateHandler = { state in
+            if case .ready = state {
+                receive(on: connection)
+            }
+        }
+        connection.start(queue: .main)
+    }
+
+    listener.start(queue: .main)
+    return listener
+}
+```
+
+### Advertising via Bonjour
+
+```swift
+let listener = try NWListener(using: .tcp)
+listener.service = NWListener.Service(
+    name: "MyApp",
+    type: "_myapp._tcp"
+)
+listener.serviceRegistrationUpdateHandler = { change in
+    switch change {
+    case .add(let endpoint):
+        print("Service registered: \(endpoint)")
+    default:
+        break
+    }
+}
+listener.start(queue: .main)
+```
+
+## NWBrowser
+
+Discovers Bonjour/mDNS services on the local network.
+
+**Documentation:**
+[sosumi.ai/documentation/network/nwbrowser](https://sosumi.ai/documentation/network/nwbrowser)
+
+### Service Discovery
+
+```swift
+import Network
+
+let browser = NWBrowser(
+    for: .bonjour(type: "_myapp._tcp", domain: nil),
+    using: .tcp
+)
+
+browser.stateUpdateHandler = { state in
+    if case .failed(let error) = state {
+        print("Browser failed: \(error)")
+    }
+}
+
+browser.browseResultsChangedHandler = { results, changes in
+    for result in results {
+        switch result.endpoint {
+        case .service(let name, let type, let domain, _):
+            print("Found: \(name).\(type)\(domain)")
+        default:
+            break
+        }
+    }
+
+    for change in changes {
+        switch change {
+        case .added(let result):
+            print("Added: \(result.endpoint)")
+        case .removed(let result):
+            print("Removed: \(result.endpoint)")
+        default:
+            break
+        }
+    }
+}
+
+browser.start(queue: .main)
+```
+
+### Connecting to a Discovered Service
+
+```swift
+// result is an NWBrowser.Result from browseResultsChangedHandler
+let connection = NWConnection(to: result.endpoint, using: .tcp)
+connection.start(queue: .main)
+```
+
+## NWPathMonitor
+
+Monitors network path changes. Replaces the deprecated `SCNetworkReachability`
+API. Use to detect connectivity changes, expensive paths (cellular), and
+constrained paths (Low Data Mode).
+
+**Documentation:**
+[sosumi.ai/documentation/network/nwpathmonitor](https://sosumi.ai/documentation/network/nwpathmonitor)
+
+### Basic Reachability with AsyncStream
+
+```swift
+import Network
+
+func networkStatusStream() -> AsyncStream<NWPath> {
+    AsyncStream { continuation in
+        let monitor = NWPathMonitor()
+        monitor.pathUpdateHandler = { path in
+            continuation.yield(path)
+        }
+        continuation.onTermination = { _ in
+            monitor.cancel()
+        }
+        monitor.start(queue: DispatchQueue(label: "NetworkMonitor"))
+    }
+}
+
+// Usage in a view model
+@MainActor @Observable
+class ConnectivityModel {
+    var isConnected = true
+    var isExpensive = false
+    var isConstrained = false
+
+    func startMonitoring() async {
+        for await path in networkStatusStream() {
+            isConnected = path.status == .satisfied
+            isExpensive = path.isExpensive       // Cellular
+            isConstrained = path.isConstrained   // Low Data Mode
+        }
+    }
+}
+```
+
+### Monitor Specific Interface
+
+```swift
+// Monitor only Wi-Fi
+let wifiMonitor = NWPathMonitor(requiredInterfaceType: .wifi)
+wifiMonitor.pathUpdateHandler = { path in
+    print("Wi-Fi: \(path.status)")
+}
+wifiMonitor.start(queue: .global())
+```
+
+### Key NWPath Properties
+
+| Property | Description |
+|---|---|
+| `status` | `.satisfied`, `.unsatisfied`, or `.requiresConnection` |
+| `isExpensive` | `true` on cellular or personal hotspot |
+| `isConstrained` | `true` when Low Data Mode is enabled |
+| `availableInterfaces` | Array of available `NWInterface` objects |
+| `supportsDNS` | Whether DNS resolution is available |
+| `supportsIPv4` / `supportsIPv6` | Protocol family support |
+
+### Adapting Behavior
+
+```swift
+for await path in networkStatusStream() {
+    if path.isConstrained {
+        // Low Data Mode: reduce image quality, skip prefetch
+        imageQuality = .low
+    } else if path.isExpensive {
+        // Cellular: use standard quality, skip video preload
+        imageQuality = .standard
+    } else {
+        // Wi-Fi: full quality, prefetch aggressively
+        imageQuality = .high
+    }
+}
+```
+
+## NWParameters Configuration
+
+`NWParameters` defines the protocols and options for connections and listeners.
+
+```swift
+import Network
+
+// TCP with custom options
+let tcpParams = NWParameters.tcp
+tcpParams.requiredInterfaceType = .wifi
+tcpParams.prohibitExpensivePaths = true
+tcpParams.prohibitConstrainedPaths = true
+
+let tcpOptions = tcpParams.defaultProtocolStack
+    .transportProtocol as! NWProtocolTCP.Options
+tcpOptions.connectionTimeout = 10
+tcpOptions.enableKeepalive = true
+tcpOptions.keepaliveInterval = 30
+
+let connection = NWConnection(
+    host: "api.example.com",
+    port: 8080,
+    using: tcpParams
+)
+```
+
+### UDP Parameters
+
+```swift
+let udpParams = NWParameters.udp
+let udpOptions = udpParams.defaultProtocolStack
+    .transportProtocol as! NWProtocolUDP.Options
+udpOptions.preferNoChecksum = true
+
+let connection = NWConnection(
+    host: "239.0.0.1",
+    port: 5000,
+    using: udpParams
+)
+```
+
+## TLS Configuration
+
+Configure TLS for secure connections using `NWProtocolTLS.Options`.
+
+```swift
+import Network
+
+let tlsParams = NWParameters(tls: NWProtocolTLS.Options())
+
+// Access TLS options for customization
+let tlsOptions = tlsParams.defaultProtocolStack
+    .applicationProtocols.first as! NWProtocolTLS.Options
+
+sec_protocol_options_set_min_tls_protocol_version(
+    tlsOptions.securityProtocolOptions,
+    .TLSv13
+)
+
+let connection = NWConnection(
+    host: "secure.example.com",
+    port: 443,
+    using: tlsParams
+)
+```
+
+### Inspecting TLS Metadata
+
+```swift
+connection.stateUpdateHandler = { state in
+    if case .ready = state {
+        if let metadata = connection.metadata(
+            definition: NWProtocolTLS.definition
+        ) as? NWProtocolTLS.Metadata {
+            let secMetadata = metadata.securityProtocolMetadata
+            let negotiatedProtocol = sec_protocol_metadata_get_negotiated_tls_protocol_version(secMetadata)
+            print("TLS version: \(negotiatedProtocol)")
+        }
+    }
+}
+```
+
+## WebSocket Support
+
+Network.framework supports WebSocket via `NWProtocolWebSocket`.
+
+### WebSocket Client
+
+```swift
+import Network
+
+func createWebSocketConnection(url: String) -> NWConnection {
+    let wsOptions = NWProtocolWebSocket.Options()
+    wsOptions.autoReplyPing = true
+
+    let params = NWParameters.tls
+    params.defaultProtocolStack.applicationProtocols.insert(
+        wsOptions, at: 0
+    )
+
+    let connection = NWConnection(
+        host: NWEndpoint.Host(url),
+        port: 443,
+        using: params
+    )
+
+    return connection
+}
+```
+
+### Sending WebSocket Messages
+
+```swift
+func sendWebSocketMessage(_ text: String, on connection: NWConnection) {
+    let metadata = NWProtocolWebSocket.Metadata(opcode: .text)
+    let context = NWConnection.ContentContext(
+        identifier: "textMessage",
+        metadata: [metadata]
+    )
+
+    let data = text.data(using: .utf8)
+    connection.send(
+        content: data,
+        contentContext: context,
+        isComplete: true,
+        completion: .contentProcessed { error in
+            if let error {
+                print("WebSocket send error: \(error)")
+            }
+        }
+    )
+}
+```
+
+### Receiving WebSocket Messages
+
+```swift
+func receiveWebSocketMessage(on connection: NWConnection) {
+    connection.receiveMessage { data, context, isComplete, error in
+        if let data,
+           let metadata = context?.protocolMetadata(
+               definition: NWProtocolWebSocket.definition
+           ) as? NWProtocolWebSocket.Metadata {
+            switch metadata.opcode {
+            case .text:
+                let text = String(data: data, encoding: .utf8) ?? ""
+                print("Received text: \(text)")
+            case .binary:
+                print("Received binary: \(data.count) bytes")
+            case .close:
+                print("Connection closed")
+                return
+            default:
+                break
+            }
+        }
+        // Continue receiving
+        receiveWebSocketMessage(on: connection)
+    }
+}
+```
+
+## NetworkConnection (iOS 26+)
+
+`NetworkConnection` is a new Swift-native API introduced in iOS 26 that
+provides a modern, type-safe alternative to `NWConnection`. It uses generics
+over protocol stacks, supports structured concurrency patterns, and integrates
+with async/await via closure-based state handlers.
+
+**Documentation:**
+[sosumi.ai/documentation/network/networkconnection](https://sosumi.ai/documentation/network/networkconnection)
+
+### Key Differences from NWConnection
+
+| | `NWConnection` | `NetworkConnection` |
+|---|---|---|
+| **Availability** | iOS 12+ | iOS 26+ |
+| **Type safety** | Untyped protocol stack | Generic `ApplicationProtocol` parameter |
+| **Streams** | Single connection | Built-in QUIC stream multiplexing |
+| **State updates** | `stateUpdateHandler` callback | `onStateUpdate`, `onPathUpdate` closures |
+| **Wi-Fi Aware** | Not supported | `wifiAware` property |
+| **API style** | Callback-based | Closure-based with `Sendable` support |
+
+### Basic Usage
+
+```swift
+import Network
+
+// Create with protocol stack parameters
+let connection = NetworkConnection(
+    to: .hostPort(host: "api.example.com", port: 443),
+    using: .tls
+)
+
+connection.onStateUpdate { state in
+    switch state {
+    case .ready:
+        print("Connected")
+    case .failed(let error):
+        print("Failed: \(error)")
+    case .cancelled:
+        print("Cancelled")
+    default:
+        break
+    }
+}
+
+connection.start()
+```
+
+### QUIC Multiplexed Streams
+
+`NetworkConnection` supports QUIC stream multiplexing natively:
+
+```swift
+// Open a new bidirectional stream
+let stream = connection.openStream(directionality: .bidirectional)
+
+// Handle inbound streams
+connection.inboundStreams { stream in
+    // Process incoming stream
+}
+```
+
+### Migration Guidance
+
+For new iOS 26+ projects, prefer `NetworkConnection` over `NWConnection`:
+- It provides stronger type safety through its generic `ApplicationProtocol`.
+- Stream multiplexing is a first-class concept.
+- The API is designed for modern Swift with `Sendable` conformance.
+
+For projects supporting iOS versions before 26, continue using `NWConnection`.
+Both APIs coexist and `NWConnection` is not deprecated.