@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,9 +1,9 @@
-# Network.framework
+# 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.3 / iOS 26+.
+Reach for Network.framework when URLSession is the wrong layer: raw TCP or
+UDP, a WebSocket at the protocol level, Bonjour discovery, a local server, or
+detailed path monitoring. Ordinary HTTP APIs stay on URLSession. Examples
+assume Swift 6.3 and iOS 26.
 
 ## Contents
 
@@ -14,575 +14,350 @@ Swift 6.3 / iOS 26+.
 - [NWParameters Configuration](#nwparameters-configuration)
 - [TLS Configuration](#tls-configuration)
 - [WebSocket Support](#websocket-support)
-- [NetworkConnection (iOS 26+)](#networkconnection-ios-26)
+- [The iOS 26 NetworkConnection API](#the-ios-26-networkconnection-api)
 
 ## 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
+`NWConnection` is one bidirectional connection. It speaks TCP, UDP, TLS,
+DTLS, QUIC and WebSocket depending on its parameters.
+API reference: [NWConnection docs](https://developer.apple.com/documentation/network/nwconnection).
 
 ```swift
+import Foundation
 import Network
+import OSLog
 
-let connection = NWConnection(
-    host: "api.example.com",
-    port: 443,
-    using: .tls
-)
+extension Logger { static let net = Logger(subsystem: "app.networking", category: "net") }
 
-connection.stateUpdateHandler = { state in
+let link = NWConnection(host: "telemetry.example.net", port: 443, using: .tls)
+link.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
+    case .ready: Logger.net.info("connected")
+    case .waiting(let error): Logger.net.notice("waiting for a path: \(error.localizedDescription)")
+    case .failed(let error): Logger.net.error("failed: \(error.localizedDescription)"); link.cancel()
+    case .cancelled: Logger.net.info("closed")
+    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)
+link.start(queue: .main)
+
+link.send(content: Data("HELLO\n".utf8), contentContext: .defaultMessage, isComplete: true,
+          completion: .contentProcessed { error in
+              if let error { Logger.net.error("send failed: \(error.localizedDescription)") }
+          })
+
+func readLoop(on connection: NWConnection) {
+    connection.receive(minimumIncompleteLength: 1, maximumLength: 65_536) { data, _, isComplete, error in
+        if let data, !data.isEmpty { consume(data) }
+        if let error {
+            Logger.net.error("receive failed: \(error.localizedDescription)")
+            return
         }
+        if isComplete { connection.cancel(); return }
+        readLoop(on: connection)
     }
 }
 ```
 
-### UDP Connection
+UDP uses the same type:
 
 ```swift
-let udpConnection = NWConnection(
-    host: "239.0.0.1",
-    port: 5000,
-    using: .udp
-)
-
-udpConnection.stateUpdateHandler = { state in
+let beacon = NWConnection(host: "239.255.10.20", port: 6200, using: .udp)
+beacon.stateUpdateHandler = { state in
     if case .ready = state {
-        let message = "Hello".data(using: .utf8)!
-        udpConnection.send(
-            content: message,
-            completion: .contentProcessed { _ in }
-        )
+        beacon.send(content: Data("ping".utf8), completion: .contentProcessed { _ in })
     }
 }
-
-udpConnection.start(queue: .main)
+beacon.start(queue: .global())
 ```
 
-### 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
-```
+- States run `setup`, `preparing`, `ready`, and end in `cancelled` or
+  `failed`.
+- `waiting(NWError)` means no usable path right now. The connection tries
+  again by itself when the network comes back.
+- Call `cancel()` when you are done. It frees the resources and moves the
+  connection 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
+`NWListener` accepts incoming connections, which is how you run a small TCP
+or UDP server on the device.
+API reference: [NWListener docs](https://developer.apple.com/documentation/network/nwlistener).
 
 ```swift
-import Network
-
-func startServer(port: UInt16) throws -> NWListener {
-    let listener = try NWListener(using: .tcp, on: NWEndpoint.Port(rawValue: port)!)
-
-    listener.stateUpdateHandler = { state in
+func startServer() throws -> NWListener {
+    let port: NWEndpoint.Port = 8080
+    let server = try NWListener(using: .tcp, on: port)
+    server.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
+        case .ready: Logger.net.info("listening on \(server.port?.rawValue ?? 0)")
+        case .failed(let error): Logger.net.error("\(error.localizedDescription)"); server.cancel()
+        default: break
         }
     }
-
-    listener.newConnectionHandler = { connection in
-        print("New connection from \(connection.endpoint)")
-        connection.stateUpdateHandler = { state in
-            if case .ready = state {
-                receive(on: connection)
-            }
+    server.newConnectionHandler = { incoming in
+        incoming.stateUpdateHandler = { state in
+            if case .ready = state { readLoop(on: incoming) }
         }
-        connection.start(queue: .main)
+        incoming.start(queue: .global())
     }
-
-    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
+    server.service = NWListener.Service(name: "Workbench", type: "_workbench._tcp")
+    server.serviceRegistrationUpdateHandler = { change in
+        if case .add(let endpoint) = change { Logger.net.info("advertised \(String(describing: endpoint))") }
     }
+    server.start(queue: .global())
+    return server
 }
-listener.start(queue: .main)
 ```
 
-## NWBrowser
-
-Discovers Bonjour/mDNS services on the local network.
+`NWEndpoint.Port` is expressible by an integer literal, so a fixed port
+needs no optional. For a port from user input, use
+`NWEndpoint.Port(rawValue:)` and handle `nil`. Setting `service` advertises
+the listener over Bonjour.
 
-**Documentation:**
-[sosumi.ai/documentation/network/nwbrowser](https://sosumi.ai/documentation/network/nwbrowser)
+## NWBrowser
 
-### Service Discovery
+`NWBrowser` discovers peers that advertise over Bonjour (multicast DNS) on the LAN.
+API reference: [NWBrowser docs](https://developer.apple.com/documentation/network/nwbrowser).
 
 ```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
-        }
-    }
-
+let scanner = NWBrowser(for: .bonjour(type: "_workbench._tcp", domain: nil), using: .tcp)
+scanner.browseResultsChangedHandler = { results, changes in
     for change in changes {
         switch change {
-        case .added(let result):
-            print("Added: \(result.endpoint)")
-        case .removed(let result):
-            print("Removed: \(result.endpoint)")
-        default:
-            break
+        case .added(let found):
+            if case .service(let name, _, _, _) = found.endpoint { Logger.net.info("found \(name)") }
+        case .removed(let gone):
+            Logger.net.info("lost \(String(describing: gone.endpoint))")
+        default: break
         }
     }
 }
+scanner.start(queue: .main)
 
-browser.start(queue: .main)
+func connect(to found: NWBrowser.Result) -> NWConnection {
+    NWConnection(to: found.endpoint, using: .tcp)
+}
 ```
 
-### 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)
-```
+The handler receives the full current `results` set and the `changes`
+(`.added`, `.removed`) since the last call.
 
 ## 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 AsyncSequence
+`NWPathMonitor` replaces the deprecated `SCNetworkReachability`. It reports
+whether a path exists and whether it is expensive or constrained.
+API reference: [NWPathMonitor docs](https://developer.apple.com/documentation/network/nwpathmonitor).
 
 ```swift
-import Network
-
 @MainActor @Observable
-class ConnectivityModel {
-    var isConnected = true
-    var isExpensive = false
-    var isConstrained = false
-
-    func startMonitoring() async {
-        let monitor = NWPathMonitor()
-
-        for await path in monitor {
-            isConnected = path.status == .satisfied
-            isExpensive = path.isExpensive       // Cellular
-            isConstrained = path.isConstrained   // Low Data Mode
+final class LinkQuality {
+    private(set) var online = true
+    private(set) var metered = false
+    private(set) var lowData = false
+
+    func watch() async {
+        for await path in NWPathMonitor() {
+            online = path.status == .satisfied
+            metered = path.isExpensive
+            lowData = path.isConstrained
         }
     }
+
+    var imagePolicy: ImagePolicy {
+        if lowData { return ImagePolicy(quality: .low, prefetch: false, preloadVideo: false) }
+        if metered { return ImagePolicy(quality: .standard, prefetch: true, preloadVideo: false) }
+        return ImagePolicy(quality: .high, prefetch: true, preloadVideo: true)
+    }
 }
 ```
 
-### Monitor Specific Interface
+Start `watch()` from a `.task` so the loop ends with the view. To watch one
+interface type, or on an SDK where the monitor is not yet an async sequence,
+use the handler API:
 
 ```swift
-// Monitor only Wi-Fi
-let wifiMonitor = NWPathMonitor(requiredInterfaceType: .wifi)
-wifiMonitor.pathUpdateHandler = { path in
-    print("Wi-Fi: \(path.status)")
+let wifiOnly = NWPathMonitor(requiredInterfaceType: .wifi)
+wifiOnly.pathUpdateHandler = { path in
+    Logger.net.info("wifi path: \(String(describing: path.status))")
 }
-wifiMonitor.start(queue: .global())
+wifiOnly.start(queue: .global())
 ```
 
-### Key NWPath Properties
-
-| Property | Description |
+| `NWPath` member | Meaning |
 |---|---|
-| `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 |
+| `status` | `.satisfied`, `.unsatisfied` or `.requiresConnection` |
+| `isExpensive` | Cellular or a personal hotspot |
+| `isConstrained` | Low Data Mode is on |
+| `availableInterfaces` | The `NWInterface` values the path can use |
+| `supportsDNS` | DNS resolution is available |
+| `supportsIPv4`, `supportsIPv6` | Address families the path supports |
 
-### Adapting Behavior
-
-```swift
-let monitor = NWPathMonitor()
-
-for await path in monitor {
-    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
-    }
-}
-```
+Adapt to the path: on a constrained path fetch low-quality images and skip
+prefetching; on an expensive path keep standard quality and skip video
+preloading; otherwise use high quality and prefetch freely.
 
 ## NWParameters Configuration
 
-`NWParameters` defines the protocols and options for connections and listeners.
+`NWParameters` describes the protocol stack and path rules for a connection
+or listener. Build options objects directly and pass them in, which avoids
+casting them back out of the stack:
 
 ```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
-)
+let tcp = NWProtocolTCP.Options()
+tcp.connectionTimeout = 10
+tcp.enableKeepalive = true
+tcp.keepaliveInterval = 30
+
+let lanOnly = NWParameters(tls: nil, tcp: tcp)
+lanOnly.requiredInterfaceType = .wifi
+lanOnly.prohibitExpensivePaths = true
+lanOnly.prohibitConstrainedPaths = true
+
+let udp = NWProtocolUDP.Options()
+udp.preferNoChecksum = true
+let datagrams = NWParameters(dtls: nil, udp: udp)
 ```
 
-### 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
-)
-```
+If you must adjust a stack you did not build, use a conditional cast:
+`if let tcp = params.defaultProtocolStack.transportProtocol as? NWProtocolTCP.Options`.
 
 ## TLS Configuration
 
-Configure TLS for secure connections using `NWProtocolTLS.Options`.
-Network.framework operates below the URL Loading System, so ATS does not
-automatically enforce URLSession-style policy here. When you use
-Network.framework for a secure protocol, configure TLS parameters and trust
-handling for that protocol stack; keep deep certificate-trust and SPKI pinning
-implementation in `swift-security`.
+TLS is configured with `NWProtocolTLS.Options`. ATS belongs to the URL
+Loading System and does not police this layer, so the TLS version, cipher
+choices and trust evaluation are yours to set. Deep trust work and SPKI
+pinning belong in `swift-security`.
 
 ```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)")
-        }
-    }
+let tls = NWProtocolTLS.Options()
+sec_protocol_options_set_min_tls_protocol_version(tls.securityProtocolOptions, .TLSv13)
+let secure = NWParameters(tls: tls)
+
+let session = NWConnection(host: "vault.example.net", port: 8443, using: secure)
+session.stateUpdateHandler = { state in
+    guard case .ready = state else { return }
+    let raw = session.metadata(definition: NWProtocolTLS.definition)
+    guard let meta = raw as? NWProtocolTLS.Metadata else { return }
+    let version = sec_protocol_metadata_get_negotiated_tls_protocol_version(meta.securityProtocolMetadata)
+    Logger.net.info("negotiated TLS \(version.rawValue)")
 }
+session.start(queue: .global())
 ```
 
 ## WebSocket Support
 
-Network.framework supports WebSocket via `NWProtocolWebSocket`.
-
-### WebSocket Client
+Network.framework exposes WebSocket through `NWProtocolWebSocket`, layered on
+top of TLS and TCP.
 
 ```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
+let ws = NWProtocolWebSocket.Options()
+ws.autoReplyPing = true
+let params = NWParameters.tls
+params.defaultProtocolStack.applicationProtocols.insert(ws, at: 0)
+let socket = NWConnection(host: "stream.example.net", port: 443, using: params)
+
+func sendText(_ message: String, over connection: NWConnection) {
+    let meta = NWProtocolWebSocket.Metadata(opcode: .text)
+    let context = NWConnection.ContentContext(identifier: "text", metadata: [meta])
+    connection.send(content: Data(message.utf8), contentContext: context, isComplete: true,
+                    completion: .contentProcessed { _ in })
 }
-```
 
-### 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
-            }
+func listen(on connection: NWConnection) {
+    connection.receiveMessage { data, context, _, error in
+        guard error == nil else { return }
+        let meta = context?.protocolMetadata(definition: NWProtocolWebSocket.definition)
+            as? NWProtocolWebSocket.Metadata
+        switch meta?.opcode {
+        case .text?, .binary?:
+            if let data { consume(data) }
+        case .close?:
+            connection.cancel()
+            return
+        default:
+            break
         }
-        // Continue receiving
-        receiveWebSocketMessage(on: connection)
+        listen(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.
+With `autoReplyPing` the framework answers pings for you. For app-level
+WebSockets, `URLSessionWebSocketTask` (see
+[background-websocket.md](background-websocket.md#urlsessionwebsockettask))
+is usually simpler.
 
-**Documentation:**
-[sosumi.ai/documentation/network/networkconnection](https://sosumi.ai/documentation/network/networkconnection)
+## The iOS 26 NetworkConnection API
 
-### Key Differences from NWConnection
+`NetworkConnection` is the Swift-first connection type added in iOS 26. It is
+generic over its protocol stack, uses async/await, and reports state through
+closures. API reference: [NetworkConnection docs](https://developer.apple.com/documentation/network/networkconnection).
 
 | | `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 Shape
+| Availability | iOS 12+ | iOS 26+ |
+| Stack typing | Untyped parameters | Generic `ApplicationProtocol` |
+| Streams | One connection | Many QUIC streams share one connection |
+| State | `stateUpdateHandler` | `onStateUpdate` and `onPathUpdate` closures |
+| Wi-Fi Aware | Not available | `wifiAware` property |
+| Style | Callbacks on a queue | Async calls, `Sendable`-aware closures |
 
 ```swift
-import Network
-
-let endpoint = NWEndpoint.hostPort(host: "api.example.com", port: 443)
-```
-
-Use the initializer variant that matches your protocol stack. The documented
-forms are:
+let endpoint = NWEndpoint.hostPort(host: "relay.example.net", port: 9443)
 
-```swift
-// Protocol-stack builder form.
-NetworkConnection(to: endpoint) {
-    // ProtocolStackBuilder<ApplicationProtocol>
+let relay = NetworkConnection(to: endpoint) {
+    TLS()
 }
 
-// Parameters-builder form.
-NetworkConnection(to: endpoint, using: builder)
-```
-
-After constructing a concrete connection for your app's protocol stack, install
-state handlers and start it:
-
-```swift
-func startConnection<ApplicationProtocol>(
-    _ connection: NetworkConnection<ApplicationProtocol>
-) where ApplicationProtocol: NetworkProtocolOptions {
-    connection.onStateUpdate { state in
+func logStates(of connection: NetworkConnection<TLS>) {
+    connection.onStateUpdate { _, state in
         switch state {
-        case .ready:
-            print("Connected")
-        case .failed(let error):
-            print("Failed: \(error)")
-        case .cancelled:
-            print("Cancelled")
-        default:
-            break
+        case .ready: Logger.net.info("ready")
+        case .failed(let error): Logger.net.error("failed: \(error.localizedDescription)")
+        case .cancelled: Logger.net.info("cancelled")
+        default: break
         }
     }
-
-    connection.start()
 }
+
+logStates(of: relay)
+try await relay.send(Data("status".utf8))
 ```
 
-`NetworkConnection` is for lower-level protocol stacks and QUIC-style transport
-work. Keep ordinary HTTP APIs on `URLSession` unless you need capabilities that
-the URL Loading System does not provide.
+The stack can also be built separately and passed with
+`NetworkConnection(to:using:)`. The connection establishes itself when it is
+first used, so the first `send` or `receive` drives it to `ready`.
+
+Keep HTTP on URLSession; `NetworkConnection` is for custom protocol stacks
+and QUIC transport.
 
 ### QUIC Multiplexed Streams
 
-`NetworkConnection<QUIC>` supports QUIC stream multiplexing natively.
-Opening and accepting streams are asynchronous and throwing operations.
+A `NetworkConnection<QUIC>` carries many independent QUIC streams over one
+connection. Opening and accepting streams are both `async throws`. Here `quic` is such a
+connection:
 
 ```swift
-func openBidirectionalStream(
-    on connection: NetworkConnection<QUIC>
-) async throws -> QUIC.Stream<QUICStream> {
-    try await connection.openStream(directionality: .bidirectional)
-}
+let outbound = try await quic.openStream(directionality: .bidirectional)
+try await outbound.send(Data("subscribe prices".utf8))
 
-func handleInboundStreams(
-    on connection: NetworkConnection<QUIC>
-) async throws {
-    try await connection.inboundStreams { stream in
-        // Process each incoming QUIC stream.
-    }
+try await quic.inboundStreams { stream in
+    let chunk = try await stream.receive(exactly: 64).content
+    route(chunk)
 }
 ```
 
+`openStream` returns a `QUIC.Stream`; `inboundStreams` calls the closure for
+every stream the peer opens. Treat both as fallible suspension points, never
+as synchronous callbacks.
+
 ### Migration Guidance
 
-For new iOS 26+ low-level networking work, evaluate `NetworkConnection` before
-adding new `NWConnection` code:
-- It provides stronger type safety through its generic `ApplicationProtocol`.
-- Stream multiplexing is a first-class concept for QUIC.
-- The API is designed for modern Swift with `Sendable` conformance.
+- New low-level code that can require iOS 26: evaluate `NetworkConnection`
+  first for typed stacks, first-class QUIC streams and `Sendable`-aware
+  design.
+- Apps that still support earlier releases keep `NWConnection`. It is not
+  deprecated, and the two can live in the same app.
 
-For projects supporting iOS versions before 26, continue using `NWConnection`.
-Both APIs coexist and `NWConnection` is not deprecated.
+The snippets log through `extension Logger { static let net = Logger(subsystem: "app.networking", category: "net") }`.