Feature Proposal: swift-configuration Integration (Configured)

[o-nnerb]

Overview

Adopt apple/swift-configuration to let a request's declarative properties be driven by external configuration (environment variables, a JSON file, in-memory defaults, etc.) instead of hardcoded Swift literals — via a new Configured property.

DataTask {
    Configured(appConfig)
}

It's already in the dependency graph

swift-configuration isn't a new dependency to evaluate in the abstract — it's already pinned transitively in this repo's own Package.resolved (swift-configuration 1.2.0, via async-http-client 1.37.0-beta.1). Worth separately confirming that async-http-client being resolved at a -beta.1 pre-release (while Package.swift declares from: "1.30.2") is intentional, independent of this proposal.

Platform note

Every public symbol in the Configuration module (ConfigReader, ConfigProvider, ConfigKey, ...) carries @available(Configuration 1.0, *), which expands to macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0. This is not a package-manifest platform floor — there's no platforms: array in swift-configuration's own Package.swift at all — it's a per-symbol availability gate. async-http-client already has direct precedent for handling this cleanly: HTTPClientConfiguration+SwiftConfiguration.swift gates just its own ConfigReader-consuming extension with @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *), leaving the rest of HTTPClient.Configuration on its normal, much older floor. Configured does the same: only it carries that availability annotation. Zero change to this package's own platforms: array, zero effect on any other type.

API

@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
public struct Configured: Property {
    let reader: ConfigReader

    public init(_ reader: ConfigReader) {
        self.reader = reader
    }

    public var body: some Property {
        if let baseURL = reader.string(forKey: "baseURL") {
            BaseURL(baseURL)
        }
        if let method = reader.string(forKey: "method") {
            RequestMethod(HTTPMethod(rawValue: method.uppercased()))
        }
        if let timeout = reader.int(forKey: "timeout") {
            Timeout(.seconds(timeout))
        }
        if let headerPairs = reader.stringArray(forKey: "headers") {
            HeaderGroup(headerPairs.splitPairsOnFirstColon())
        }
        if let queryPairs = reader.stringArray(forKey: "queries") {
            QueryGroup(queryPairs.splitPairsOnFirstEquals())
        }
    }
}

Design decisions worth calling out:

1. body composes existing properties (BaseURL, RequestMethod, Timeout, HeaderGroup, QueryGroup) rather than a custom PropertyNode writing into Make directly. A PropertyNode-based version, and later an AsyncProperty-wrapped version supporting a throwing/required baseURL lookup, were both considered and rejected in favor of this. The PropertyNode version would mean re-implementing each field's own validation (e.g. BaseURL's scheme/host checks) inside Configured instead of reusing it, and every future field would need hand-written Make-mutation logic rather than delegating to whatever Property already exists for it — composing existing properties scales better, since supporting a new field later is one more if let branch, not a reimplementation. Forcing baseURL specifically to be a required, throwing lookup was also considered (via AsyncProperty, which supports async/throwing content) and dropped as unnecessary: every field is treated identically — if baseURL is missing, Configured simply contributes nothing for it, the same as any other absent key, and BaseURL's own existing requirement is what surfaces a genuinely missing base URL, not a special case invented here.
2. Headers/Query are read as stringArray pair lists ("Name: Value" / "name=value"), parsed the same way async-http-client already parses dnsOverrides (colon-separated pairs) from a ConfigReader — ConfigReader has no generic "read this whole [String: String]" accessor, only scalars and arrays of scalars, so this is the same precedented shape rather than an invented one.

Each field is read with if let and only included when present, so Configured composes naturally alongside explicit properties declared elsewhere in the same @PropertyBuilder block — an explicit Headers(...) declared after it still wins, same "last one wins" precedent BaseURL/DNSOverride already establish. ConfigReader.scoped(to:) lets multiple endpoints share one reader under different key prefixes: Configured(appConfig.scoped(to: "myAPI")).

Out of scope (v1)

• Coverage of every possible Property type — v1 covers baseURL/method/timeout/headers/queries; extending to others (cache policy, secure connection, proxy, etc.) is additional if let branches on top of the same shape, not a redesign.
• The watching access pattern (live config reloads) — Configured reads a snapshot once per resolution, matching how every other property in this pipeline works today.
• Required/throwing config lookups — deliberately not used anywhere in Configured; every field is optional and independently absent-tolerant.

Milestone: 4.2.0

[o-nnerb]

Implemented as Configured in request-dl/request-dl-nio#308.

The final shape composes existing properties rather than reimplementing their logic, so validation stays with whichever property already owns it — matching the design direction laid out above. Supported configuration keys:

• baseURL → FlexibleURL (covers a complete URL, a relative path, or a query-only value in one field — broader than the BaseURL-only sketch above)
• method, timeout, headers, queries
• authorization (basic/bearer)
• dnsOverrides, urlOverrides
• systemProxy, proxy (http/socks, with its own scoped authorization/connectHeaders)
• cachePolicy, cacheStrategy
• secureConnection (trust roots, additional trust roots, client certificates, private key, TLS version range)
• redirect (follow/disallow)
• maximumConnectionsPerHost, maximumConcurrentConnections

Every key is read independently and is optional — a missing key contributes nothing. A handful of scoped keys with genuinely invalid combinations throw a new ConfiguredError (invalid authorization/proxy/secureConnection/redirect values); everything else delegates entirely to the property it composes.

A couple of things that came up along the way, in case they're useful for anyone tracking this:

• Found and fixed a real bug unrelated to Configured itself: HeaderGroup/QueryGroup silently dropped their content when nested inside Proxy's connectHeaders or Form's per-part headers (#299).
• Deprecated Proxy.Authorization in favor of a top-level ProxyAuthorization — the old one being nested inside the generic Proxy<Headers> made it a different type per Headers specialization for no reason (#300).
• swift-configuration's Configuration module links full Foundation on Linux by default (its JSON trait, enabled by default, has an unconditional import Foundation). Disabled that trait (traits: []) since Configured never needs JSON file parsing — keeps the package's Linux/FoundationEssentials-only linkage intact.

Also added a Configuration-driven-requests.md DocC article walking through the common cases.

Closing this out now that the PR is up and CI is green (all platforms + the Linux Foundation-linkage check).