Document thread safety

[cremor]

As requested on Stack Overflow:

It is documented that Flurl reuses the same IFlurlClient per host by default. This is fine and what I need.

I've found a few places that say that certain parts of IFlurlClient are not thread safe, e.g. headers (#314) and cookies (#318). But I didn't find a documentation that says which parts are threadsafe. Could you please document that?

I'm especially interested in the thread safety of basic GET, POST, etc. operations and its corresponding ReceiveXyz() methods, because those are thread safe in the underlying HttpClient (see documentation).

[tmenier]

Flurl sets things at the request level as much possible, so generally speaking, all "normal" usage (building and making HTTP calls) is completely thread-safe. For example:

x = await "https://api.com/endpoint".WithHeader("foo", "bar").GetJsonAsync<T>();

Under the hood, this is taking a the following steps:

1. Find a cached FlurlClient to use (or create one), based on the host by default.
2. Create a Request off the client.
3. Set a header on the request.
4. Send the request and deserialize the response.

If you're working with FlurlClient explicitly. methods like WithHeader are available at both the client level (which you can use for "default" headers that you want sent with every request off that client), and at the request level.

So this is not a thread-safe way to send request-specific headers:

x = await flurlClient.WithHeader("foo", "bar").Request("endpoint").GetJsonAsync<T>();

But if you flip things around so you're adding the header to the request instead of the client, it becomes thread-safe:

x = await flurlClient.Request("endpoint").WithHeader("foo", "bar").GetJsonAsync<T>();

The one big exception to all of this is cookies. They're a little bit of a gotcha in that when it appears you're adding them to the request, they're actually being added to the client. While it made for a much easier implementation, it is a shortcoming that I'd like to fix someday. In the mean time, I generally recommend one FlurlClient per user session being simulated when using cookies.

You're right that this could all be documented better. For now does this clear things up?

[cremor]

Yes, that's great. Thank you!

[tmenier]

I'm in the process of organizing/moving documentation requests. (Updates are a high priority.) This is not done but I've added it to my personal notes for now.

[tmenier]

To anyone still interested, the the cookie problem discussed above has been addressed in a big way and is ready for some testing in the latest prerelease. I'd like to get as many eyeballs on this as possible before the changes are set in stone with the final release (date TBD).