38 releases

✓ Uses Rust 2018 edition

0.11.4 Feb 6, 2020
0.11.2 Oct 20, 2019
0.11.0 Jun 21, 2019
0.9.1 Mar 30, 2019
0.4.5 Jul 15, 2018

#2 in HTTP client

Download history 695/week @ 2019-11-10 1517/week @ 2019-11-17 844/week @ 2019-11-24 1432/week @ 2019-12-01 1534/week @ 2019-12-08 1226/week @ 2019-12-15 650/week @ 2019-12-22 1173/week @ 2019-12-29 1746/week @ 2020-01-05 1627/week @ 2020-01-12 1652/week @ 2020-01-19 1200/week @ 2020-01-26 3201/week @ 2020-02-02 3462/week @ 2020-02-09 2423/week @ 2020-02-16

5,735 downloads per month
Used in 33 crates (24 directly)

MIT/Apache and maybe MPL-2.0

125KB
2.5K SLoC

ureq

CratesIO Documentation

Minimal request library in rust.

ureq's future

I asked for feedback on ureq's future direction and came to the conclusion that there's enough interest in a simple blocking http client to keep it going. Another motivation is that I use it extensively for my own work, to talk to S3.

I'll keep maintaining ureq. I will try to keep dependencies somewhat fresh and try to address bad bugs. I will however not personally implement new features in ureq, but I do welcome PR with open arms.

The code base is extremely simple, one might even call naive. It's a good project to hack on as first learning experience in Rust. I will uphold some base line of code hygiene, but won't block a PR due to something being a bit inelegant.

Usage

// requires feature: `ureq = { version = "*", features = ["json"] }`
#[macro_use]
extern crate ureq;

fn main() {

    // sync post request of some json.
    let resp = ureq::post("https://myapi.acme.com/ingest")
        .set("X-My-Header", "Secret")
        .send_json(json!({
            "name": "martin",
            "rust": true
        }));

    // .ok() tells if response is 200-299.
    if resp.ok() {
        // ...
    }
}

Features

To enable a minimal dependency tree, some features are off by default. You can control them when including ureq as a dependency.

    ureq = { version = "*", features = ["json", "charset"] }
  • tls enables https. This is enabled by default.
  • json enables response.into_json() and request.send_json() serde json.
  • charset enables interpreting the charset part of Content-Type: text/plain; charset=iso-8859-1. Without this, the library defaults to rust's built in utf-8.

Motivation

  • Minimal dependency tree
  • Obvious API
  • Convencience over correctness

This library tries to provide a convenient request library with a minimal dependency tree and an obvious API. It is inspired by libraries like superagent and fetch API.

This library does not try to enforce web standards correctness. It uses HTTP/1.1, but whether the request is perfect HTTP/1.1 compatible is up to the user of the library. For example:

    let resp = ureq::post("https://myapi.acme.com/blah")
        .set("Jättegött", "Vegankörv")
        .call();

The header name and value would be encoded in utf-8 and sent, but that is actually not correct according to spec cause an HTTP header name should be ascii. The absolutely correct way would be to have .set(header, value) return a Result. This library opts for convenience over correctness, so the decision is left to the user.

Sync forever

This library uses blocking socket reads and writes. When it was created, there wasn't any async/await support in rust, and for my own purposes, blocking IO was fine. At this point, one good reason to keep this library going is that it is blocking (the other is that it relies on very little use of unsafe).

TODO

  • Forms with application/x-www-form-urlencoded
  • multipart/form-data
  • Expect 100-continue
  • Use rustls when ring with versioned asm symbols is released. (PR is not resolved, but most implementations have settled on 0.13)

License

Copyright (c) 2019 Martin Algesten

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~1.5–3.5MB
~92K SLoC