WARNING

Curio is no longer being actively developed and new updates will no longer be added. This repository is being archived. I want to thank all of you who provided me with such wonderful feadback over the last two months, and i want to say a big thanks to TwentyFourMinutes without whom, this project would never have made it past the concept stage.

Thanks for helping me make my proof of concept a wonderful little library, even if it did have its limitations.

About

What is Curio?

Curio is a small HTTP client built in the Rust Programming Language from Mozilla. It was started by myself as a way to learn the ins and outs of HTTP and its quirks, after all there is nothing more interesting to me than the standards that define the internet. Its primary goal above all else is performance, closely followed by ease of use. If you are proficient in Rust, and know how to help me improve the performance of Curio, please do not hesitate to open an issue tagged with the optimization tag. If you have a feature you think would be perfect for Curio and would be useful to more than just yourself, please open an issue with the feature tag.

Whilst Curio is ready to use, I am always looking to improve it. If you have any suggestions please open an issue

Values

Curio values performance, usability, and security. in the event one of these items should conflict with another, the following focus is put in place: Security comes first. Usability seconds. and last of all, performance.

I am happy to sacrifice a few hundred microseconds per request, and i am happy to sacrifice a few users to a less friendly api if it means that Curio is more secure for everyone who does use it.

Goals

I personally wish to see that Curio grows into a powerful HTTP client, with a focus on minimizing unsafe code in the codebase it has. currently Curio itself has 0 unsafe code, however I am aware that some of it's dependancies do have unsafe code, and that fact I will have to live with.

Another one of my goals for curio is to ensure that it stays true to the specification of HTTP. This includes both version 1.1, and version 2 of the specification. both of which will have seperate APIs open to them in future, once both have been built up.

Limitations

Curio does have a few shortcomings in it's current version. chief among those is lack of connection pooling, I do have this planned and have been working hard to bring a major (breaking) overhaul to the user experience which I admit; I left in the dark in the name of performance.

Another shortcoming is not being able to set headers for requests. whilst the functions do exist within the library, due to how I was handling the parsing of a request, I never actually got around to making the headers dynamic in any way.

It also does not support GZIPed or DEFLATEd encoding, i plan to add this in the future.

Curio does not support JSON serialization of response bodies. It is highly unconfigurable, and it is also not capable of setting a timeout on a request.

You should know this before you read the information below.

Where will I not take Curio?

Honestly, I do not have an answer to this question yet. I currently do not know what might be requested of me for this library, this is my first foray into making things other people can use and so I do not know what you will ask of me. Once I have an idea of what I will restrict for Curio, i will revisit this area of the README

Why should I use Curio over other HTTP clients?

Curio is a fresh take on how to handle HTTP clients and aims to provide a cross-platform, cross-language library which can be used almost anywhere.

Does Curio support X?

Curio supports most of the most common HTTP methods:

• GET
• POST
• DELETE

Curio also supports the following HTTP methods:

• OPTIONS
• HEAD

It also supports CORS request moderation. It performs a preflight request to the requested resource to ensure that the request can go ahead .

This library also supports automatic HTTPS upgrading.

In a future version, all of these features will be configurable, for example you could disable CORS blocking for that request, or you could force the client to use TCP instead of TLS.

Documentation

You can view the most up-to-date documentation here however as this is not promised to be in-sync with the docs on docs.rs you should probably use those if you are not importing from this repository

Examples:

Simple GET request:

A simple GET request to some-domain.tld/path/to/resource should look something like this:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = Request::get("https://some-domain.tld/path/to/resource")
        .send()?;

    println!("{:#?}", response);
    Ok(())
}

POST plaintext content:

A simple POST request that is posting plaintext content looks like this:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut post_body = "This is some example content to POST";

    // convert the string into a format accepted by the `set_body` method.
    let post_data = PostData::from_str(post_body);

    // below, set the destination of the post body using the `post` method,
    // set the body using the `set_body` method,
    // and send the request by using the `send` method
    let response = Request::post("https://some-domain.tld/documents")
        .set_body(&post_data)
        .send()?;

    println!("{:#?}", response);
    Ok(())
}

Milestones

Wed 26th Aug 2020 - First fully capable GET request handler: Commit 496ae5f

Sat 29th Aug 2020 - Curio 0.0.3 (preflight for 0.1.0) is completed, and preperations for release begin.

Benchmarks

You can help imrpove these benchmarks by looking into how we got these numbers in this respository

Cargo-Geiger

Output last verified Sept 2nd 2020, (2 days after V0.0.3 launched)

Metric output format: x/y
    x = unsafe code used by the build
    y = total unsafe code found in the crate

Symbols: 
    :) = No `unsafe` usage found, declares #![forbid(unsafe_code)]
    ?  = No `unsafe` usage found, missing #![forbid(unsafe_code)]
    !  = `unsafe` usage found

Functions  Expressions  Impls  Traits  Methods  Dependency

0/0        0/0          0/0    0/0     0/0      :) curio 0.0.3
0/0        0/0          0/0    0/0     0/0      ?  ├── chunked_transfer 1.2.0
0/0        0/0          0/0    0/0     0/0      :) ├── rustls 0.18.1
0/0        0/0          0/0    0/0     0/0      :) │   ├── base64 0.12.3
1/1        16/28        0/0    0/0     0/2      !  │   ├── log 0.4.11
0/0        0/0          0/0    0/0     0/0      ?  │   │   └── cfg-if 0.1.10
1/1        468/468      13/13  5/5     1/1      !  │   ├── ring 0.16.15
0/5        12/259       0/0    0/0     2/22     !  │   │   ├── libc 0.2.76
0/0        57/74        3/5    0/0     2/3      !  │   │   ├── once_cell 1.4.1
0/0        49/49        6/6    0/0     3/3      !  │   │   ├── spin 0.5.2
0/0        0/0          0/0    0/0     0/0      :) │   │   └── untrusted 0.7.1
0/0        0/0          0/0    0/0     0/0      :) │   ├── sct 0.6.0
1/1        468/468      13/13  5/5     1/1      !  │   │   ├── ring 0.16.15
0/0        0/0          0/0    0/0     0/0      :) │   │   └── untrusted 0.7.1
0/0        0/0          0/0    0/0     0/0      :) │   └── webpki 0.21.3
1/1        468/468      13/13  5/5     1/1      !  │       ├── ring 0.16.15
0/0        0/0          0/0    0/0     0/0      :) │       └── untrusted 0.7.1
0/0        0/0          0/0    0/0     0/0      :) ├── webpki 0.21.3
0/0        0/0          0/0    0/0     0/0      ?  └── webpki-roots 0.20.0
0/0        0/0          0/0    0/0     0/0      :)     └── webpki 0.21.3

2/7        602/878      22/24  5/5     8/31```