reqwest::RequestBuilder is probably a misnomer

[JohnScience]

TL;DR

reqwest::RequestBuilder shouldn't depend on the client.

Full text:

Let's say we have a function that wants to prepare "requests" for execution.

When I say "requests", I don't mean reqwest::Request because it'd require a breaking change, which is undesirable.

These "requests" can be either regular reqwest::Request or reqwest::Request with extra data, such as JSON body, that needs to be sent along with the reqwest::Request.

These "requests" can be either regular reqwest::Request created with reqwest::Request::new (and not modified further) or reqwest::Request with extra data, such as JSON body.

Currently, the only way to do something like this is to use reqwest::RequestBuilder.

While it is also possible to manually add necessary data to reqwest::Request, it is usually not as convenient as with API provided by reqwest::RequestBuilder.

let request_builder = client.post(url).json(&body);
//
let resp = request_builder.send().await?;

On the surface, everything seems fine. However, you can notice that something is fishy when you realize that there's no way to create reqwest::RequestBuilder without supplying reqwest::Client in one way or another.

• https://docs.rs/reqwest/latest/reqwest/struct.RequestBuilder.html#method.from_parts
• https://docs.rs/reqwest/latest/reqwest/struct.Client.html#method.post

Indeed, for some reason, reqwest::RequestBuilder stores owned reqwest::Client.

While reqwest::Client is presumably cheaply cloneable, several questions naturally arise.

1. Is it zero cost?
2. If it is not zero cost, is it justified?
3. What if I want to prepare a request in advance? Does such a function really need to know which client will execute its request?
4. Are there good zero-cost alternatives?

Let's try answering them one by one.

1. Answering whether it is zero-cost requires considerable effort but my educated guess is that the optimizer won't be able to optimize cloning away, assuming atomic read/write operations are being performed. (I know it's a lackluster answer but bear with me).
2. Storing reqwest::Client is non-essential for the primary thing that people would want from a type called RequestBuilder (building requests). Moreover, the next answer will highlight the conflict of the non-essential and essential aspects of this type.
3. Let's assume that someone wants to write a function that prepares a request in advance. Let's say it is a POST request with a JSON body. The design choice for reqwest::RequestBuilder to contain reqwest::Client now creates an abstraction leak where the user code now is required to also supply reqwest::Client - either as an argument or as a local variable. Other than the implications of the design of reqwest::RequestBuilder, there are no reasons for the function preparing a request to know which client will execute its request.
4. There's an alternative to have a separate type for a building requests. Unfortunately, the name reqwest::RequestBuilder is already taken. In the short term, such a type can be called ClientlessRequestBuilder. And it can have .send_via(client) method instead of .send(). Once reqwest is ready to make breaking changes, reqwest::RequestBuilder can be redefined to ClientlessRequestBuilder and its documentation can provide a note on the legacy misnomer. Alternatively, convenience methods can be added to reqwest::Request.

[JohnScience]

Original issue: #2375.

Other problems caused by this pattern:

• Async Rate Limiting #491 (comment)

[MikailBag]

As a workaround, one can introduce a new abstraction, e.g.

type RequestBuilderProvider = Box<dyn FnOnce(reqwest::Client) -> reqwest::RequestBuilder>;

Now any Request-producing function can return a RequestBuilderProvider without requiring a Client.

However this approach doesn't look viable as a long-term solution because it creates an unnecessary abstraction.