Crate evaluation for 2017-05-30: reqwest

[dtolnay]

For additional contribution opportunities, see the main libz blitz thread.

This post is a wiki. Feel free to edit it.

Links

• https://crates.io/crates/reqwest
• https://github.com/seanmonstar/reqwest
• https://docs.rs/reqwest

Needs your help!

Anything that is not checked off still needs your help! There is no need to sign up or ask for permission - follow any of these links and leave your thoughts:

• Guidelines checklist This document is collaboratively editable. Pick a few of the guidelines, compare the reqwest crate against them, and fill in the checklist with [y] if the crate conforms to the guideline, [n] if the crate does not conform, and [/] if the guideline does not apply to this crate. Each guideline is explained in more detail here. If [n], please add a brief note on the following line with an explanation. For example:

  - [n] Crate name is a palindrome (C-PALINDROME)
        - reqwest backwards is tsewqer which is not the same as reqwest
  

• Cookbook example ideas Come up with ideas for nice introductory examples of using reqwest, possibly in combination with other crates, that would be good to show in the Rust Cookbook. Please leave a comment in that issue with your ideas! You don’t necessarily have to write the example code yourself but PRs are always welcome.

• API guideline updates What lessons can we learn from reqwest that will be broadly applicable to other crates? Please leave a comment in that issue with your ideas!

• Unstructured feedback Anything else you want to say! Please leave a comment here regarding your experience using reqwest, any functionality you think would be important before a potential 1.0 release, anything you think would be valuable for the libs team to discuss in their meeting, or anything else.

[newpavlov]

Not sure if it’s the right place to ask, but has anyone been able to get in contact with the Graham Lee, owner of request crate? This and his other crates were not updated for two years.

[dtolnay]

I think this was the most recent attempt at contacting them. @seanmonstar would you still be interested in grabbing the name if it became available?

https://github.com/ghmlee/rust-request/issues/7

[newpavlov]

Yes, I know about this issue, this is why I’ve asked if by a chance someone received an answer through other channels.

[KodrAus]

I was looking at macros, thinking there weren’t any, but apparently there is one that’s exported publicly. I suspect this is an error, so opened an issue. Hopefully that’s not breaking the rules

[KodrAus]

Something I’m wondering is if an async API is considered blocking for a stable release? And if so, how much of the current implementation we’re reviewing would change?

[seanmonstar]

Apologies, I was on vacation without much internet/laptop.

@seanmonstar would you still be interested in grabbing the name if it became available?

I believe so, yes. There was supposely a reply to someone else who email Graham, claiming that an update was indeed coming, but that was a while ago, and still no update. Still, I wouldn’t propose forcibly changing the author whatsoever.

The author of requests (with an “s”) has emailed me that they’d be willing to let reqwest change to requests, so that’s a possibility. I also had registered the agent crate name earlier, as another alternative.

I was looking at macros, thinking there weren’t any, but apparently there is one that’s exported publicly.

Thanks for noticing! That’s been fixed in 0.6.2.

Something I’m wondering is if an async API is considered blocking for a stable release?

I don’t know if must block 1.0 or not. I would expect to add it soon, which would mean depending on unstable tokio and futures (besides of course the already unstable hyper). I’d also expect to provide both a synchronous and asynchronous Client, naming TBD, and so the name Client would probably need to be updated as well.

Actually, with regards to stabilizing without stabilizing hyper, I’m not certain how that will work. hyper cannot stabilize while Futures and Tokio still are unstable. Possibly reqwest could remove all publicly exported types that come from hyper, and thus exist one whatever version of hyper. This would mean making new types for StatusCode, HttpVersion, Method, and the whole headers module.

[tom.prince]

Actually, with regards to stabilizing without stabilizing hyper, I’m not certain how that will work. hyper cannot stabilize while Futures and Tokio still are unstable. Possibly reqwest could remove all publicly exported types that come from hyper, and thus exist one whatever version of hyper. This would mean making new types for StatusCode, HttpVersion, Method, and the whole headers module.

Could those types be stabilized without stabilizing the rest of hyper?

[KodrAus]

There’s been discussion about pulling headers/status codes from hyper into separate crates, which is one way to stabilise them. I’m also keen on that idea personally.

[Nemo157]

I would be very keen for that as well. I’m just starting to extract part of an Iron web app into a framework agnostic helper, but realised that meant I’d have to pass status codes around as integers since I don’t want a hyper dependency there.

[seanmonstar]

pulling headers/status codes from hyper into separate crates, which is one way to stabilise them

While that is definitely the eventual goal, and we may be able to make some progress soonish, that still wouldn’t be a stabilized crate immediately.

[KodrAus]

that still wouldn’t be a stabilized crate immediately.

That’s totally reasonable, and worth pointing out It’s an avenue to consider that gives us a more fine grained way to stabilise parts of the API and gives other libraries a fine grained way to depend on it.

[dtolnay]

I started going over the API guidelines checklist in preparation for the libs team meeting on Tuesday and it would be great to get some more eyes on it, since this is one of the biggest crates we have looked at so far. There is plenty more room for feedback. Please help!

https://public.etherpad-mozilla.org/p/rust-api-guidelines-reqwest

[dtolnay]

Today the libs team along with our guests @seanmonstar, @KodrAus and @stephanbuys met to talk about the reqwest crate.

• Video of the meeting
• Tracking issue of improvements we recommend to reqwest

Discussion topics

When is it okay to use private types in the public API?

There are three cases where the reqwest public API refers to types that are private - meaning they cannot be named by any code outside of reqwest.

One of the three was unintentional and we just need to publicly expose the types involved (reqwest#105).

The other two cases were intentional but result in confusing rustdoc documentation. We will need to make changes to keep the intended behavior but make the rustdoc more easily understandable (hyper#1194 and reqwest#106). There may also be a way that rustdoc could improve this situation (rust#42323).

We will clarify these private-in-public patterns as an API guideline (guidelines#73).

Do &Error trait objects need to be Send and Sync?

It probably doesn’t matter. For consistency with io::Error we will change this in reqwest (reqwest#107) and also clarify the applicable API guideline (guidelines#80).

Are the StatusCode and HttpVersion enums a compatibility hazard?

Yes. New HTTP status codes and versions will be added in the future and we would not want that to require a breaking change in hyper or reqwest.

Associated constants will be stable soon so we will switch to those (hyper#1195).

What are the stability implications of re-exporting types from hyper?

Reqwest would like to release a stable version. Currently reqwest re-exports the Method, StatusCode, and HttpVersion types from hyper, so it couldn’t be stable until hyper is stable. Stable hyper is waiting on stable tokio. Stable tokio is not imminent.

We will resolve this by factoring some of the foundational types like StatusCode into a separate crate that can be stabilized sooner than all of hyper (hyper#1196).

How to deal with fallible methods on a builder that takes self by value?

The existing RequestBuilder was designed before Rust’s question mark feature. It is a self-by-value builder with fallible methods that pretend to be infallible by stashing away an error until the request is about to be dispatched.

In today’s Rust this would be more ergonomic as a &mut self builder with fallible methods (reqwest#108).

This calls for some API guidelines updates as well (guidelines#81 and guidelines#82 and guidelines#83).

What is the deal with html_root_url?

It is annoying and limited, and a small amount of tooling work could go a long way (rust#42300 and rust#42301).

Isn’t there a better name for this crate?

No, reqwest is a great name.

Do we really want CI badges on crates.io?

Probably. But there is a lot of work we need to ask from the infrastructure team before the badges would be as meaningful as we would like. @sfackler will follow up.

Guideline improvements

• Enumerate the circumstances in which private in public is acceptable
• Send and Sync errors guideline should call attention to trait objects
• Strengthen the recommendation to use &mut self builders
• Self-by-value builders returning ownership of the builder after an error
• Builders that take &mut self should panic when used a second time

[johnthagen]

The author of requests (with an “s”) has emailed me that they’d be willing to let reqwest change to requests, so that’s a possibility.

Could this be done? As as casual user of the crate and talking to others about, referring to it as “Rust has this cool request package for HTTP, oh but you spell it R-E-Q-W-E-S-T” I think “requests” would be more ergonomic long term, since the owner of request doesn’t want to give it up. I even found it a little awkward in the code to write reqwest::. My fingers naturally wanted to type request.

This also matches the name of the popular Python package requests.

[seanmonstar]

In the video meeting, when it was brought up, many felt that reqwest was a better name. I can list the reasons people have given me (I’m not saying that it is objectively better, I questioned it too):

• reqwest is a unique name, so it doesn’t get confused with request from JavaScript, or requests from Python.
• Remembering to include an ‘s’ seemed just as arbitrary as remembering to spell with a ‘w’.
• It’s already used by many, changing the name causes disruption, which would be fine if it were an immense win, but it doesn’t feel like it is.

In the meeting, it sounded like people liked most the ‘branding’ aspect of it being a unique name. But if anyone that was there (or otherwise) wants to share their opinion on why the name should remain, please share!

[fbstj]

is it worth highlighting a pronunciation like ‘rek west’ or ‘ree quest’ or something?

[zackw]

• Remembering to include an ‘s’ seemed just as arbitrary as remembering to spell with a ‘w’.

I don’t super care what the name of this crate is, but I think I understand the position of the people who find “reqwest” more arbitrary than “requests”: “requests” is a correctly-spelled English word, and that makes it much easier to type. When I just now tried to type “reqwest” at full speed, I produced “requew” before the “no, that’s not right” signal got to my fingers.

Perhaps if I wrote a lot of code using this crate I would get used to it, but perhaps not.

(“reqwest” is a 1-character substitution from a correctly spelled word, which is arguably the worst case for a speed typist. If it was called something that bore no resemblance at all to English, the motor programs for typing English quickly and accurately wouldn’t be getting in the way.)

[withoutboats]

I can see how typing reqwest is frustrating, but I have to admit I have it engrained in my memory which library it is that I want, which I don’t think would be the case if it were called requests.

To make this a bit easier, you can extern crate reqwest as request; if you want.

[johnthagen]

Also in English Q is almost always followed by a U, so I too always find myself typing requ… before I have a chance to even think about it.