Abstract client evolution proposal#149
Conversation
guoye-zhang
requested review from
FranzBusch,
fabianfett,
nakulbajaj,
travarin and
xbhatnag
guoye-zhang
added
area/documentation
| The `HTTPClient` protocol provides a single `perform` method that handles all HTTP interactions. The request and response metadata are expressed as `HTTPRequest` and `HTTPResponse` types, from the Swift HTTP types package. The protocol requires `Sendable`, ensuring all conforming clients are safe to share across concurrency domains. | ||
|
|
||
| ```swift | ||
| public protocol HTTPClient<RequestOptions>: Sendable, ~Copyable, ~Escapable { |
There was a problem hiding this comment.
why is this potentially ~Copyable, ~Escapable
There was a problem hiding this comment.
I added a callout "allows ~Copyable and ~Escapable types to conform to the protocol" but don't know how to explain why. Also not sure how to explain why it has to be Sendable. Hope we are not giving the impression that we are adopting new compiler features just for the sake of it.
| Request bodies are supported via an `HTTPClientRequestBody`, which encapsulates a closure responsible for writing the request body, in a way that is either `seekable` or `restartable`. A `restartable` request body supports retries (for redirects and authentication challenges), and a `seekable` request body additionally supports resumable uploads. Trailer fields can also be returned from the closure. | ||
|
|
||
| ```swift | ||
| public struct HTTPClientRequestBody<Writer: AsyncWriter & ~Copyable>: Sendable |
There was a problem hiding this comment.
since this type is dependent on the client that will execute it, how can a user define a standalone request body?
There was a problem hiding this comment.
HTTPClientRequestBody is just a wrapper of the restarting callback, and is not expected to be created or passed around as a standalone entity. It's similar to HTTPServerClosureRequestHandler on the server-side.
I would recommend users to build their own type to represent the body (or use existing types like Data / FileHandle) and convert them to HTTPClientRequestBody when calling perform.
|
|
||
| The proposal consists of several interconnected modules, and the abstract API is defined as part of the `HTTPAPIs` module: | ||
| - **HTTPAPIs**: Protocol definitions for `HTTPClient` and shared types | ||
| - **NetworkTypes**: Currency types defined as needed for request option capabilities |
There was a problem hiding this comment.
Wow. Do we introduce a new Module here? What is this about? Where will it live?
There was a problem hiding this comment.
Added more details. This are the currency types below HTTP, and I think it should eventually live in the toolchain.
| } | ||
| ``` | ||
|
|
||
| Any code written against a generic `some HTTPClient` parameter can be tested by passing a `MockHTTPClient` instead of a real client, verifying requests and controlling responses without network access. |
There was a problem hiding this comment.
Should we also mention that we built a conformance testing suite that works on an arbitrary concrete client?
There was a problem hiding this comment.
Will do that in the concrete client proposal. This section is about testing the client user's logic through mocking a client.
guoye-zhang
changed the title
3 participants
Thank you @nakulbajaj for writing these up