Conversation
guoye-zhang
requested review from
FranzBusch,
fabianfett,
nakulbajaj,
travarin and
xbhatnag
guoye-zhang
added
area/documentation
| We propose a new HTTP Client API built on two pieces: | ||
|
|
||
| 1. **Abstract protocol interface** (`HTTPClient`) for dependency injection and testability | ||
| 2. **Convenience methods** for common use cases with progressive disclosure |
There was a problem hiding this comment.
should we mention the concrete implementation here again? And say that this gets its own proposal?
| ### Middleware | ||
|
|
||
| A separate `Middleware` module provides a generic, composable protocol for intercepting and transforming values through a chain. The `Middleware` protocol defines a single `intercept(input:next:)` method that receives a value, processes it, and passes a (potentially transformed) value to the next stage. Middleware pipelines can be built declaratively using the `@MiddlewareBuilder` result builder: | ||
|
|
||
| ```swift | ||
| @MiddlewareBuilder | ||
| var pipeline: some Middleware<MyRequest, MyRequest> { | ||
| LoggingMiddleware() | ||
| AuthenticationMiddleware() | ||
| RetryMiddleware() | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Can we move this into the Future directions - Middleware section, as it isn't part of this proposal.
|
|
||
| var defaultRequestOptions: RequestOptions { get } | ||
|
|
||
| mutating func perform<Return: ~Copyable>( |
There was a problem hiding this comment.
we need an explanation why this is mutable.
| 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
| ```swift | ||
| public protocol HTTPClient<RequestOptions>: Sendable, ~Copyable, ~Escapable { | ||
| associatedtype RequestOptions: HTTPClientCapability.RequestOptions | ||
| associatedtype RequestWriter: AsyncWriter, ~Copyable, SendableMetatype |
| request: HTTPRequest, | ||
| body: consuming HTTPClientRequestBody<RequestWriter>?, | ||
| options: RequestOptions, | ||
| responseHandler: (HTTPResponse, consuming ResponseConcludingReader) async throws -> Return |
There was a problem hiding this comment.
why do we supply the ResponseConcludingReader in a closure?
| 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?
| } | ||
| ``` | ||
|
|
||
| ### Convenience methods for progressive disclosure |
There was a problem hiding this comment.
I think we should put all the convenience methods into its own proposal, and refer to them from this proposal with a Future directions.
I think this proposal should just focus on the protocol, its associatedTypes and the perform method.
|
|
||
| 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?
| @@ -0,0 +1,326 @@ | |||
| # Concrete HTTP Client Implementations | |||
There was a problem hiding this comment.
can we put this into a separate pr please?
2 participants
Thank you @nakulbajaj for writing these up