Provide a "minimal" version of makeDefaultOptions for libraries

[czechboy0]

I think we need a "minimal" variant of makeDefaultOptions (the way to create new options from a library, when you don't know which concrete HTTP client implementation you're using). Because as a library, you can't afford to have the client arbitrarily choose to enable various features you're a) not aware of and b) aren't expecting. For example, if there's a "Batching" feature, represented by a protocol like:

protocol BatchingOptions: RequestOptions {
    /// Defines the batch of body bytes that are filled up before being sent.
    var batchSize: Int64?
}

This could be a useful optimization, but always needs to be opt-in. Either by you using a known concrete client, or you requesting that feature through the protocol constraint:

func makeAnHTTPCall<Client: HTTPClient>(client: Client) where Client.RequestOptions: BatchingOptions async throws {
    var options = client.makeDefaultOptions()
    options.batchSize = 4096
    try await client.perform(request, options: options) {

    }
}

However, if you don't request it, and your library looks like this:

func makeAnHTTPCall<Client: HTTPClient>(client: Client) async throws {
    var options = client.makeDefaultOptions()
    try await client.perform(request, options: options) {

    }
}

Then client.makeDefaultOptions() absolutely must have batchSize = nil, otherwise the library won't work correctly with bidi streaming, as bytes will be held back until reaching the batch size, but the library has no way of learning or fixing that, without explicitly requiring that feature just to turn it off.

So if we assume that the set of options protocols will be open, and community libraries will be able to add additional ones, and the set of HTTP client implementations will also be an open set, it means that "default options" must mean "features disabled", and libraries will only enable those that they need by explicitly requesting that protocol and enabling them.

Now, some features are on/off, such as this batching example, and we can easily require that "default options" turns it off. However for other features that can't really negatively affect a library's observable behavior, we can still discuss what "on" vs "off" means. For example, I'd argue it's fine if the default value for "HTTP versions supported" is "all", even though some folks could consider that "on". Maybe that means we should re-spell that feature as "Subset of HTTP versions requested", so not allowing an HTTP version would be considered "on" for that feature.

This is why I think we need another variant of "default options" that makes it clear that it's not "nice-to-have, recommended options" (which is useful for applications, and can still exist e.g. under the name "recommended"), but must be "all features as disabled as they can be" (which is the only way to make behavior predictable to libraries, here called "minimal").

Maybe the simplest spelling that still allows this is:

protocol HTTPClient {

    // associated types

    func makeRecommendedOptions() -> RequestOptions
    func makeMinimalOptions() -> RequestOptions

    // perform method
}

So applications and concrete client utils would default to recommended, while libraries would always start with minimal (though I don't like the name, so please suggest a better one).

[guoye-zhang]

minimal is somewhat difficult to define. Would you expect HTTP/2 and HTTP/3 to be disabled in a minimal client? HTTP/2 brings in the TLS requirement and ALPN negotiation, while HTTP/3 relies on even more infrastructure such as an Alt-Svc storage database.

Maybe we could consider use case based default options? e.g. defaultProxyRequestOptions.

[czechboy0]

I'm not sure that use cases is what matters here. The point is that the library can't anticipate unknown features that will interfere with the expected "base" behavior of any compliant client it gets passed (defining the base behavior, without any additional RequestOptions protocols, is still an open task: #67).

"Minimal" (or hopefully a better name) is something we would define. Then when we discuss every new capability protocol on RequestOptions, maybe there should be a section in each proposal about what "minimal" means for that feature, but I fully expect that to be case-by-base. I suspect we'll want to follow the principle of least surprise: "What would a library unaware of this feature expect? How can it still safely function?".

Would you expect HTTP/2 and HTTP/3 to be disabled in a minimal client?

See my original post, I talk to this example there.

[FranzBusch]

I am not yet sure if I agree that we need a minimal case with the recent changes in #97. This moves the control of what the default options are to the client. IMO a client can always enable to add more default options, in fact I think it is expected. Imagine a client starts off with no cookie support. It should be able to add cookie request options and enable them by default and all current users should get those enabled by default. I think this is true regardless off if we speak about the abstract APIs or the protocol here. A client generally speaking should be able to add more functionality that it enables by default as long as it has no negative impact on existing users.

[czechboy0]

It should be able to add cookie request options and enable them by default and all current users should get those enabled by default.

That doesn't work for libraries. A library needs to work consistently across different client implementations, regardless of when each of them gained various features.

This is why I think we need two variants. One for "recommended" options, usable by apps, who know exactly which client they're using and can e.g. watch their release notes. But we also need a "minimal" for libraries, who have no idea which client is passed in.

It's important to remember that the library knows exactly the semantics of the server it's talking to, while the concrete client implementation doesn't. So let's consider redirects: the library needs to be confident about whether redirects will always happen on a default client, or will never happen. It can't be anything in between.

Which one it is we'll want to discuss when we're establishing the "base" functionality of the protocol (#67). I could see it going both ways: clients always having to handle redirects, and there's an option to turn that off, or clients never being allowed to handle redirects, and you can turn it on. But a library can't handle a concrete HTTP client changing its mind on this post-1.0.

[guoye-zhang]

The term we use internally is http_messaging for message-parsing-only clients, vs http_client which is a full-featured client. However, the boundary isn't super clear, e.g. when we receive an H3_VERSION_FALLBACK error code, the messaging layer translates it into a specific error code which is caught by the client layer to retry over h1. Also should 421 & 425 status codes be handled by the messaging layer since they affect which connection to reuse?

Back in the day Transfer-Encoding: chunked wasn't handled by the CFNetwork API and users had to decode the body manually, but we consider it a required feature today.

[czechboy0]

You know more about this than me, so you're in a better position to decide for these features what "recommended" vs "minimal" would be.

My point is: we'll have to decide this, for each feature, before stabilizing the protocol API, otherwise it won't be possible to write reliable libraries on top of the protocol.

At some point it'd be good to check in a handful of examples of simple libraries that connect to a known server with its specific semantics, and we could even run that as part of an extended integration validation test suite for concrete client implementations.

It's important we internalize this - the library knows the server it talks to, but not over which concrete client. So the protocol still needs to provide enough hard guarantees to unlock useful and reliable libraries.

An ambiguous protocol would mean unreliable libraries, and libraries in the end taking a dependency on a concrete client, making the protocol unnecessary.

In a world without the protocol, every HTTP client would have full flexibility over what it does. By introducing the protocol, we take some flexibility away from concrete clients, and put them on the protocol in the form of hard requirements.

[FranzBusch]

My point is: we'll have to decide this, for each feature, before stabilizing the protocol API, otherwise it won't be possible to write reliable libraries on top of the protocol.

I am still not sure if I agree with this. I think my next point applies to both a concrete client or the protocol of a client but let's take a concrete client. Assume with a client A that offers empty request options in version 1.0.0 i.e. nothing can be configured on a per-request level.

// Version 1.0.0
public struct ClientARequestOptions {
  public init() {}
}

Now the client adds support for following redirects and extends its request options. Since following redirects is in general the right behavior by default it enables it by default. The request options becomes this:

// Version 1.1.0
public struct ClientARequestOptions {
  public var followRedirects: Bool = true
  public init() {}
}

This seems like a very valid evolution of a concrete client that we have personally done many times. Would you agree that this is a valid evolution for a client? If yes what in your mind is the difference from that to a client used behind a protocol? What I am trying to say is that we must be able to add more request options over time and we must be able to provide defaults for those request options.

[czechboy0]

I agree the API spelling is not difficult, and that's not where the issue lies.

The problem is that it's currently unclear how anyone writing code that uses an HTTP client can, under all circumstances, deal with not knowing if the client will or will not handle redirects.

Imagine one concrete client doesn't. Another one does, but only up to 1 redirect. Another one handles up to 5. And so on.

How do you implement a library for communicating with a server where you know exactly what the requests/responses are (libraries know the semantics of the server they're talking to, the client implementation doesn't), but the underlying client's redirect behavior is not known to you? How do you write a reliable library?

This is also about progressive disclosure. Nobody can be aware of all the possible features, even those that haven't been implemented, so they can't make their code robust against a client that turns on/off features arbitrarily.

I don't believe changing something like redirect behavior within a major version is okay. Any first-class observable behavior must be stable within a major version. Otherwise you can't write reliable code against it, because there's no way to prove that changing redirect behavior doesn't break someone.

One way to address this is to carefully consider the features we include in 1.0 of the protocol, and the concrete client. But everything added after that fact must be opt-in. That's the logical conclusion of SemVer to observable behaviors, not just APIs.

Many projects invent a concept of "editions" for exactly this purpose (and we do the same in e.g. Swift OpenAPI Generator - we can't enable new features by default if there's a chance it might break someone).

So at time of shipping 1.0, we could start with:

1. Recommended
2. Minimal (for libraries)

Then we add more features over time to the concrete client, and a year later, we can add:

3. Recommended2027 (name to be bikeshed, I'm sure)

---

Post 1.0, SemVer dictates that you can only add features, but not remove or change existing features. The "default config" is a feature that you add in 1.0, so you can't realistically change it in a way that can break people.

[guoye-zhang]

What if minimal disables trailers and request body streaming, behaves like fetch, and requires you to enable those features separately?

[czechboy0]

It's less about which way individual features go, and more about the principle of a "minimal" configuration existing, and having to stay stable, so that libraries can get consistent experience across different concrete HTTP clients. I don't have strong feelings about which feature is enabled/disabled in "minimal" mode, we'll just need to lock that in for the 1.0.

Trailers/streaming seems orthogonal to the topic of "minimal" configuration, and I think we can keep discussing that in #65 and other threads focused on that topic.

[guoye-zhang]

I do not think these are orthogonal problems. The fundamental problem is that there is a feature X that client A does not support, but client B supports and enables by default (might not even offer a way to disable it). How does a library work on all clients without needing to exhaustively test on all of them?

I have a proposal that I will write up and share tomorrow.

[czechboy0]

there is a feature X that client A does not support, but client B supports and enables by default

That's fine, as long as the "minimal" configuration has this feature disabled. Client B can have an extra client-specific initializer for its client-specific configuration that enables it by default, but it's not the initializer that libraries can use, only applications.

[fabianfett]

It's important to remember that the library knows exactly the semantics of the server it's talking to, while the concrete client implementation doesn't.

I don't think this is true: Libraries don't know about proxies. But application developers do.