Crate isahc

source ·
Expand description

The practical HTTP client that is fun to use.

Here are some of Isahc’s key features:

  • Full support for HTTP/1.1 and HTTP/2.
  • Configurable request timeouts, redirect policies, Unix sockets, and many more settings.
  • Offers an ergonomic synchronous API as well as a runtime-agnostic asynchronous API with support for async/await.
  • Fully asynchronous core, with incremental reading and writing of request and response bodies and connection multiplexing.
  • Sessions and cookie persistence.
  • Automatic request cancellation on drop.

Getting started

Sending requests is as easy as calling a single function. Let’s make a simple GET request to an example website:

use isahc::prelude::*;

let mut response = isahc::get("https://example.org")?;
println!("{}", response.text()?);

By default, sending a request will wait for the response, up until the response headers are received. The returned response struct includes the response body as an open stream implementing Read.

Sending a POST request is also easy, and takes an additional argument for the request body:

let response = isahc::post("https://httpbin.org/post", "make me a salad")?;

Isahc provides several other simple functions for common HTTP request types:

isahc::put("https://httpbin.org/put", "have a salad")?;
isahc::head("https://httpbin.org/get")?;
isahc::delete("https://httpbin.org/delete")?;

If you want to customize the request by adding headers, setting timeouts, etc, then you can create a Request using a builder-style fluent interface, then finishing it off with a send:

use isahc::{prelude::*, Request};
use std::time::Duration;

let response = Request::post("https://httpbin.org/post")
    .header("Content-Type", "application/json")
    .timeout(Duration::from_secs(5))
    .body(r#"{
        "speed": "fast",
        "cool_name": true
    }"#)?
    .send()?;

For even more examples used in complete programs, please check out the examples directory in the project repo.

Feature tour

Below is a brief overview of some notable features of Isahc. Check out the rest of the documentation for even more guides and examples.

Easy request functions

You can start sending requests without any configuration by using the global functions in this module, including get, post, and send. These use a shared HTTP client instance with sane defaults, so it is easy to get up and running. They should work perfectly fine for many use-cases, so don’t worry about graduating to more complex APIs if you don’t need them.

Request and response traits

Isahc includes a number of traits in the prelude module that extend the Request and Response types with a plethora of extra methods that make common tasks convenient and allow you to configure more advanced connection and protocol details.

Here are some of the key traits to read about:

Custom clients

The free-standing functions for sending requests use a shared HttpClient instance, but you can also create your own client instances, which allows you to customize the default behavior for requests that use it.

See the documentation for HttpClient and HttpClientBuilder for more information on creating custom clients.

Asynchronous requests

Requests are always executed asynchronously under the hood. This allows a single client to execute a large number of requests concurrently with minimal overhead. Even synchronous applications can benefit!

If you are writing an asynchronous application, you can reap additional benefits from the async nature of the client by using the asynchronous methods available to prevent blocking threads in your code. All request methods have an asynchronous variant that ends with _async in the name. Here is our first example rewritten to use async/await syntax:

use isahc::prelude::*;

let mut response = isahc::get_async("https://httpbin.org/get").await?;
println!("{}", response.text().await?);

Since we sent our request using get_async, no blocking will occur, and the asynchronous versions of all response methods (such as text) will also automatically be selected by the compiler.

Feature flags

Isahc is designed to be as “pay-as-you-need” as possible using Cargo feature flags and optional dependencies. Unstable features are also initially released behind feature flags until they are stabilized. You can add the feature names below to your Cargo.toml file to enable them:

[dependencies.isahc]
version = "1.7"
features = ["psl"]

Below is a list of all available feature flags and their meanings.

cookies

Enable persistent HTTP cookie support. Disabled by default.

http2

Enable compile-time support for HTTP/2 in libcurl via libnghttp2. This does not actually affect whether HTTP/2 is used for a given request, but simply makes it available. To configure which HTTP versions to use in a request, see VersionNegotiation.

To check which HTTP versions are supported at runtime, you can use is_http_version_supported.

Enabled by default.

json

Additional serialization and deserialization of JSON bodies via serde. Disabled by default.

psl

Enable use of the Public Suffix List to filter out potentially malicious cross-domain cookies. Implies cookies, disabled by default.

spnego

Enable support for SPNEGO-based HTTP authentication (negotiate auth scheme). This makes the negotiate scheme available in the API and, if static-curl is enabled, compiles libcurl with GSS-API APIs. The MIT Kerberos headers must be pre-installed at compile time.

static-curl

Use a bundled libcurl version and statically link to it. Enabled by default.

text-decoding

Enable support for decoding text-based responses in various charsets into strings. Enabled by default.

Unstable APIs

There are also some features that enable new incubating APIs that do not have stability guarantees:

unstable-interceptors

Enable the new interceptors API (replaces the old unstable middleware API). Unstable until the API is finalized. This an unstable feature whose interface may change between patch releases.

unstable-rustls-tls

Use rustls as the TLS backend for HTTPS requests. Currently unstable as the rustls backend in libcurl currently has some known issues and is not yet recommended for production use.

Logging and tracing

Isahc logs quite a bit of useful information at various levels compatible with the log crate. For even more in-depth diagnostics, you can use a tracing subscriber to track log events grouped by individual requests. This can be especially useful if you are sending multiple requests concurrently.

If you set the log level to Trace for the isahc::wire target, Isahc will also log all incoming and outgoing data while in flight. This may come in handy if you are debugging code and need to see the exact data being sent to the server and being received.

Re-exports

pub use crate::error::Error;
pub use http;

Modules

Types for working with HTTP authentication methods.
Definition of all client and request configuration options.
cookiescookies
Types for cookie state management.
Types for error handling.
A “prelude” for importing commonly used Isahc types and traits.

Structs

Contains the body of an asynchronous HTTP request or response.
Contains the body of a synchronous HTTP request or response.
An HTTP client for making requests.
An HTTP client builder, capable of creating custom HttpClient instances with customized behavior.
An object that holds status updates and progress statistics on a particular request. A Metrics can be shared between threads, which allows an agent thread to post updates to the object while consumers can read from the object simultaneously.
Represents an HTTP request.
Represents an HTTP response
A future for a request being executed.
Holds the current state of a trailer for a response.

Traits

Provides extension methods for consuming asynchronous HTTP response streams.
Provides extension methods for consuming HTTP response streams.
Extension methods on an HTTP request.
Provides extension methods for working with HTTP responses.

Functions

Send a DELETE request to the given URI.
Send a DELETE request to the given URI asynchronously.
Send a GET request to the given URI.
Send a GET request to the given URI asynchronously.
Send a HEAD request to the given URI.
Send a HEAD request to the given URI asynchronously.
Check if runtime support is available for the given HTTP version.
Send a POST request to the given URI with a given request body.
Send a POST request to the given URI asynchronously with a given request body.
Send a PUT request to the given URI with a given request body.
Send a PUT request to the given URI asynchronously with a given request body.
Send an HTTP request and return the HTTP response.
Send an HTTP request and return the HTTP response asynchronously.
Gets a human-readable string with the version number of Isahc and its dependencies.