Stable futures API

[sagebind]

Re-implement the core of chttp using std futures / futures 0.3 and async/await, and provide an API that can be used with async/await as well.

We may want to put this behind a compile-time feature somehow if possible...

• Change Body to be async.
• Implement Wakers for waking the agent thread.
• Use an asynchronous pipe for streaming the response data from the agent thread to the main / request thread.
• Fix anything that may have been broken during the refactor. (That's why we have integration tests!)
  • Fix redirect handling
  • Fix error handling

[ta3pks]

I just cannot wrap my head around this idea. Why would anyone want an always async http client? Most of the time waiting for the response actually makes sense. In general what is wrong with opening threads for async requests?

[sagebind]

It's primarily an efficiency thing. If you have a service that may need to make a request from more than one thread, or potentially parallel requests, you have three options:

• Create a brand new connection for every request that operates totally independently. Advantages: simple to do. Disadvantages: you cannot take advantage of pipelining, HTTP/2+ advancements, or persistent connections to reduce latency.
• Create a shared HTTP client that uses mutexes to protect concurrent access to a connection pool. This is the approach taken by several popular clients in other languages. Advantages: reduced latency by re-using connections. Disadvantages: parallel requests is limited by number of connections and threads in your thread pool.
• Multiplex many connections at once using an event loop. This is the approach chttp uses (since 0.2). Advantages: reduced latency by re-using connections, low memory overhead by using only one extra thread for all requests, theoretically unlimited parallel requests. Disadvantages: most complex to implement.

I've benchmarked these approaches; chttp is actually 30% faster than using a vanilla curl request, because of its asynchronous design that takes advantage of curl's built-in (but optional) async features. It's more work for me to implement, but worth it in my book.

This particular PR will not make any major changes to the API; the default will be a synchronous API. If you want to make requests asynchronously (which a number of people do), then it will be offered also. In fact chttp's core is already asynchronous and powered by futures. The fact that no one notices this is a success in my book. It means I already successfully abstracted away the complexity involved.

All this PR does is change the guts from using futures version 0.2 to using std::future::Future (soon to be released) and also includes some additional optimizations to improve performance even more.

The nice thing about an asynchronous core is that it benefits both normal synchronous users and asynchronous users.

[sagebind]

Most of the time waiting for the response actually makes sense.

Indeed it does. But waiting does not always imply "blocking a thread". There are ways of waiting for something without blocking a thread. And that's valuable because threads are expensive and you want to use them as efficiently as possible.

In general what is wrong with opening threads for async requests?

I'm not sure exactly what you mean by this. Async and threads are not the same thing, if that's what you meant. In general, spawning new threads is really expensive, and you want to avoid doing it if you can. That's why for decades people have used things like thread pools or event loops, in order to conserve, control, and re-use threads efficiently without incurring a high cost.

[sagebind]

All this being said, I understand that this is a lot of complex talk, when there's a ton of users who don't care and really just want to make a few HTTP requests? Why does that have to be so difficult in Rust!? I sympathize, and that's exactly why I created chttp in the first place, and my vision has not changed. Making a GET request using chttp will never be harder than just chttp::get("http://example.org") if you don't want it to be.

My goal is to make the easy thing also the fast and efficient thing.

[ta3pks]

Thanks for you answers I guess I need to understand the futures deeper. Right now when people say async I remember the horribleness of writing javascript code and callbacks and stuff and to be honest that's really not how I want to write rust I just love being able to block when I need it. Again thanks for your detailed explanation and this amazing library. I guess I need to understand the futures and how to use them effectively first

[sagebind]

While futures and async/await in Rust seek to accomplish similar goals to promises and async/await in JavaScript, it is designed quite differently (and admittedly has a bit of essential complexity). Either way, you don't have to use futures in order to use chttp if you don't want to.

If you want to learn more about async in Rust, I'd wait until async/await syntax is stabilized in a month or so. It will be a lot easier then. I'm glad to help, and am glad if my HTTP client is useful to you.

[sagebind]

After more than a month of work, this PR is just about ready!