Feature Proposal: Network Capabilities

[o-nnerb]

Overview

The goal is to add additional settings for requests that respect the capabilities of each device. URLSession is an excellent example of the options available to developers.

1. allowsCellularAccess: Bool

   Allows/prevents executing a request using cellular data.

2. allowsExpensiveNetworkAccess: Bool

   Allows/prevents executing a request on a network interface labeled by the operating system as expensive.

3. allowsConstrainedNetworkAccess: Bool

   Allows/prevents executing a request when the data-saving option is active.

4. waitsForConnectivity: Bool

   Waits for the device to be connected to the internet before executing the request.

5. multipathServiceType

   Mirrors NWParameters.multipathServiceType / URLSessionConfiguration.multipathServiceType.

Status (2026-08-27) — implemented, merged

All 5 fields are implemented and merged via #295:

• allowsCellularAccess, allowsExpensiveNetworkAccess, allowsConstrainedNetworkAccess, waitsForConnectivity — enforced via a pre-flight Internals.NetworkPathGate (Darwin-only, backed by NWPathMonitor), checked once immediately before a request is dispatched on the .nio/.nioTransportServices executors.
• multipathServiceType — forwards directly to AsyncHTTPClient's existing HTTPClient.Configuration.enableMultipath.
• Defaults match URLSessionConfiguration's own defaults (access flags permissive/true, multipathServiceType = .none, waitsForConnectivity = false), and the gate costs nothing for sessions that never touch this API.

New public API: Session.allowsCellularAccess(_:), .allowsExpensiveNetworkAccess(_:), .allowsConstrainedNetworkAccess(_:), .multipathServiceType(_:), plus the existing .waitsForConnectivity(_:) (reimplemented on the same gate — now uniform across every executor instead of NIOTransportServices-only).

Note: this shipped on top of main, independent of the separate, still-in-progress .urlSession executor migration (feature/urlsession-executor) — deliberately, so this win didn't have to wait on that larger effort. When the .urlSession executor lands, these same fields map directly onto URLSessionConfiguration's native equivalents there, no gate needed on that path — a small, self-contained follow-up at that point, not tracked further here.

Why the upstream path is closed

The proposal to add these fields to HTTPClient.Configuration in swift-server/async-http-client was pursued across two PRs:

• swift-server/async-http-client#915 — proposed 5 fields mirroring the full NWParameters surface. Closed: reviewers felt it overreached URLSessionConfiguration parity, and that Apple-platform-specific transport tuning belongs in URLSession/Network.framework directly, or in the emerging cross-platform HTTP client abstraction (apple/swift-http-api-proposal).
• swift-server/async-http-client#918 — follow-up, narrowed to just the 2 fields with a genuine 1:1 URLSessionConfiguration equivalent (allowsExpensiveNetworkAccess/allowsConstrainedNetworkAccess). Also closed.

There was no remaining path to get these into HTTPClient.Configuration — RequestDL implemented them on its own instead, as described above.

Milestone: 4.2.0

[o-nnerb]

This is being moved to 3.0.4 milestone because this will required some code before implementing this to all platforms.

[o-nnerb]

Body updated with the current status and root cause: waitsForConnectivity is implemented, but the other 3 flags are blocked upstream in AsyncHTTPClient — it doesn't expose a generic hook for the NWParameters settings (prohibitedInterfaceTypes/prohibitExpensivePaths/prohibitConstrainedPaths) that would be needed, only the specific field it chose to forward for waitsForConnectivity. A concrete proposal for the upstream change (mirroring how networkFrameworkWaitForConnectivity was added) is being prepared for swift-server/async-http-client; this discussion will move forward once that lands. Milestone moved to 4.2.0.

[o-nnerb]

Cross-linking: #189 (Network Reachability) was closed as a duplicate of this discussion. Reachability and the 3 blocked capability flags here share the same underlying mechanism on Darwin — NWPathMonitor's NWPath.isExpensive / .isConstrained / .usesInterfaceType(.cellular). Tracking both under this discussion going forward.

[o-nnerb]

Updating with the final decision: both PRs on async-http-client (#915, #918) were closed — there's no upstream path. Pivoting to a native implementation in RequestDL as part of the .urlSession executor work. Discussion body updated with the plan.

[o-nnerb]

Merged: #295. All 5 fields are implemented — allowsCellularAccess, allowsExpensiveNetworkAccess, allowsConstrainedNetworkAccess, and waitsForConnectivity via a pre-flight NWPathMonitor-backed gate, and multipathServiceType via a direct forward to AsyncHTTPClient's enableMultipath. Discussion body updated with the final status. Closing this out.