New perform with protocols and make the default client a concrete type by guoye-zhang · Pull Request #60 · apple/swift-http-api-proposal

guoye-zhang · 2026-01-22T20:48:30Z

Update the design to the current proposal

FranzBusch

Can we add exhaustive public documentation to every method please?

FranzBusch · 2026-01-23T13:51:15Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+        body: consuming HTTPClientRequestBody<RequestWriter>? = nil,
+        options: RequestOptions = .init(),
+        responseHandler: (HTTPResponse, consuming ResponseConcludingReader) async throws -> Return,
+        configureOptions: (inout RequestOptions) -> Void = { _ in }


Do we really need this? Could we keep split adding this closure into a follow up PR to discuss it in isolation?

I'd be fine proposing this in a different PR, but it would be very handy to be able to adopt options inline with perform, and I'm in support of the convenience.

Removed for now

FranzBusch · 2026-01-23T13:51:55Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+        url: URL,
+        headerFields: HTTPFields = [:],


This is surprising to me. Why is this not taking an HTTPRequest? AFAIK HTTPRequest has methods to convert from a URL.

Not a deal-breaker, but I could see this as a welcome convenience - I wonder how often people will actually realize they can initialize an HTTPRequest with just a URL if they're less familiar with HTTP.

We want HTTP.get(url) to work. Yes, it could take a request, but then there is not much difference from a regular perform.

Also request already has a method. What if there is a mismatch, which one do we respect?

@FranzBusch what do we do here, if the users set the http method POST on the passed in request? I'm with Guoye, that those convenience methods should bypass creating a request completely.

Can we just subset the URL Conveniences out into a separate PR. In general, there is too much happening at once in this PR.

I removed them

Sources/HTTPAPIs/Client/HTTPClientRequestBody+Data.swift

FranzBusch · 2026-01-23T13:53:24Z

Sources/HTTPAPIs/Client/HTTPClientRequestBody+Data.swift

-    UnsupportedPlatformHTTPClient()
-    #endif
+extension HTTPClientRequestBody where Writer: ~Copyable {
+    public init(_ data: Data) {


What if we make this take a RawSpan instead of Data? This would make it more generally useful.

We will have to make a copy since HTTPClientRequestBody needs to own the data

I am going to argue it has to anyways and Data is the wrong type right now since it requires a FoundationEssentials dependency. I would start off with Array<UInt8> and copy.

I removed this file for now since it's only used by the conveniences. Foundation team disliked our usage of [UInt8] in the previous iteration and told us that Data will be moved to the stdlib, so we should use Data.

FranzBusch · 2026-01-23T13:55:11Z

Sources/HTTPAPIs/Client/HTTPClientRequestBody.swift

+        self.writeBody = writeBody
+    }
+
+    public init<OtherWriter: ~Copyable>(


Why do we need this?

It is to convert HTTPRequestBody<ConcreteHTTPClient> to HTTPRequestBody<URLSessionHTTPClient> for our internal backend implementation use. I can make this package instead of public?

You can just write that in the internal backend as well right? This convenience conversion doesn't require to have internal knowledge. You can just wrap it in another closure. package is okay for now but once we split into separate packages you need to implement this with just the public API.

It does require internal knowledge since all the closures are private. I guess I could wrap the entire struct and call produce on it, but it would be less maintainable since it might not be updated when a new case is added.

If we can erase the generic from HTTPRequestBody, this workaround wouldn't be necessary.

Let's make it package and we can sort it out in a follow up

Sources/HTTPClient/HTTPConnectionPool.swift

FranzBusch · 2026-01-23T14:01:22Z

Sources/HTTPClient/HTTPRequestOptions.swift

+#endif
+
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
+public struct HTTPRequestOptions: HTTPRequestOptionsRedirectionHandler, HTTPRequestOptionsTLSVersion,


Should we nest this type in HTTPClient or rename it to HTTPClientHTTPRequestOptions?

This will be one of the most commonly used types, while the abstract protocol is only typed by backend implementation developers. I think we should rename the protocol instead?

FranzBusch · 2026-01-23T14:01:34Z

Sources/HTTPClient/HTTPRequestOptionsDeclarativePathSelection.swift

+//===----------------------------------------------------------------------===//
+
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
+public protocol HTTPRequestOptionsDeclarativePathSelection: HTTPAPIs.HTTPRequestOptions {


Suggested change

public protocol HTTPRequestOptionsDeclarativePathSelection: HTTPAPIs.HTTPRequestOptions {

public protocol DeclarativePathSelectionHTTPRequestOptions: HTTPAPIs.HTTPRequestOptions {

Flipping the order makes them less discoverable. Currently they all share the same prefix and naturally group together. Maybe we could scope them instead?

In Swift it's more common to share the suffix. And yeah, some scoping could make sense here.

I put all protocols in a scope HTTPClientCapability which also addressed the HTTPRequestOptions naming conflict

Sources/HTTPClient/HTTPRequestOptionsDeclarativeTLSHandler.swift

nakulbajaj · 2026-01-23T16:12:35Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+        body: consuming HTTPClientRequestBody<RequestWriter>? = nil,
+        options: RequestOptions = .init(),
+        responseHandler: (HTTPResponse, consuming ResponseConcludingReader) async throws -> Return,
+        configureOptions: (inout RequestOptions) -> Void = { _ in }


I'd be fine proposing this in a different PR, but it would be very handy to be able to adopt options inline with perform, and I'm in support of the convenience.

nakulbajaj · 2026-01-23T16:16:46Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+        url: URL,
+        headerFields: HTTPFields = [:],


Not a deal-breaker, but I could see this as a welcome convenience - I wonder how often people will actually realize they can initialize an HTTPRequest with just a URL if they're less familiar with HTTP.

nakulbajaj · 2026-01-23T16:17:35Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+
+    public func get(
+        url: URL,
+        headerFields: HTTPFields = [:],


Any reason we couldn't name this parameter to just headers?

headers is not proper terminology. A header can contain multiple fields, so "headers" is ambiguous whether it's referring to fields or multiple request headers.

@guoye-zhang While I understand the reasoning here, I wonder if this makes more Catholic than the Pope? I assume for most users headerFields adds more confusion than just pure headers.

Well I actually initially named the property headers on HTTPRequest and HTTPResponse, and it was called out for using improper terminology during management review. We have precedence for using the IETF-recommended terminology even on the old NSURLRequest so we'd like to avoid backsliding.

https://github.com/apple/swift-http-types/blob/main/Sources/HTTPTypes/HTTPRequest.swift#L305
https://developer.apple.com/documentation/foundation/urlrequest/value(forhttpheaderfield:)

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

Sources/HTTPAPIs/Client/HTTPClientRequestBody.swift

Sources/HTTPClient/HTTP+Conveniences.swift

Sources/HTTPAPIs/Client/HTTPClient.swift

FranzBusch · 2026-01-28T13:04:35Z

Sources/HTTPAPIs/Client/HTTPClientCapability+RequestOptions.swift

+
+/// The namespace for all protocols defining HTTP client capabilities.
+@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
+public enum HTTPClientCapability {


Why do we need this namespace?

This is from the earlier discussion: #60 (comment)

Hm, let's go ahead with this for now then.

FranzBusch · 2026-01-28T13:05:33Z

Sources/HTTPAPIs/Client/HTTPClient+Conveniences.swift

+        url: URL,
+        headerFields: HTTPFields = [:],


Can we just subset the URL Conveniences out into a separate PR. In general, there is too much happening at once in this PR.

FranzBusch · 2026-01-28T13:06:37Z

Sources/HTTPAPIs/Client/HTTPClientRequestBody+Data.swift

-    UnsupportedPlatformHTTPClient()
-    #endif
+extension HTTPClientRequestBody where Writer: ~Copyable {
+    public init(_ data: Data) {


I am going to argue it has to anyways and Data is the wrong type right now since it requires a FoundationEssentials dependency. I would start off with Array<UInt8> and copy.

FranzBusch · 2026-01-28T13:10:01Z

Sources/HTTPAPIs/Client/HTTPClientRequestBody.swift

+        self.writeBody = writeBody
+    }
+
+    public init<OtherWriter: ~Copyable>(


You can just write that in the internal backend as well right? This convenience conversion doesn't require to have internal knowledge. You can just wrap it in another closure. package is okay for now but once we split into separate packages you need to implement this with just the public API.

New perform with protocols and make the default client a concrete type

0ce07c7

guoye-zhang requested review from FranzBusch and nakulbajaj January 22, 2026 20:48

guoye-zhang added the ⚠️ semver/major Breaks existing public API. label Jan 22, 2026

guoye-zhang requested review from czechboy0 and fabianfett January 22, 2026 20:48

guoye-zhang added 2 commits January 22, 2026 13:00

Fix Linux

6a4b7fd

Fix upload

0a85579

FranzBusch reviewed Jan 23, 2026

View reviewed changes

nakulbajaj reviewed Jan 23, 2026

View reviewed changes

guoye-zhang added 3 commits January 23, 2026 11:29

Review comment

fcdbc35

Remove configureOptions closure

5f13540

Remove client certificate data

a95ad88

czechboy0 mentioned this pull request Jan 25, 2026

Predictable client options for library callers #64

Open

guoye-zhang added 2 commits January 26, 2026 17:47

Add docs and namespace capabilities

fb6cd6f

Format

214531c

FranzBusch reviewed Jan 28, 2026

View reviewed changes

guoye-zhang added 3 commits January 28, 2026 08:52

Remove conveniences

6abed71

Review comments

457f211

Merge branch 'main' into new-perform

acd6ab2

FranzBusch approved these changes Jan 28, 2026

View reviewed changes

FranzBusch merged commit 8e3b18e into apple:main Jan 28, 2026
15 of 21 checks passed

guoye-zhang deleted the new-perform branch January 28, 2026 20:41

nakulbajaj mentioned this pull request Jan 29, 2026

Add configureOptions closure to perform to allow editing configuration options in-line with perform #71

Open

	public protocol HTTPRequestOptionsDeclarativePathSelection: HTTPAPIs.HTTPRequestOptions {
	public protocol DeclarativePathSelectionHTTPRequestOptions: HTTPAPIs.HTTPRequestOptions {

Conversation

guoye-zhang commented Jan 22, 2026

Uh oh!

FranzBusch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment