Migration guide

This page provides supplemental migration guides for major version bumps with notable breaking changes.

2.0

The most significant part of this release is added support for rustls, but also includes a significant refactoring of the TLS API in order to break prior assumptions about how backends work, and to improve the API's ergonomics.

Crate features

The nightly feature has been removed. It was only intended for internal development. Simply remove reference to it if somehow you were using it before with Isahc v1.

Support for exposing logs is now behind a new log feature, which is enabled by default. If you were using Isahc v1's logs emitted via the log crate and also were setting default-features = false, you will now need to add features = ["log"] to restore the old behavior. If you were not disabling default features then you will not be affected.

The static-ssl feature has been removed, and replaced with a native-tls-static feature. See the next section if you were using this feature with Isahc v1.

A new default-tls feature has been added to the default features. This means it is now possible to disable support for TLS entirely if you wish. If you were setting default-features = false for Isahc v1 and making requests to HTTPS servers, you will now need to explicitly enable TLS again using features = ["default-tls"] to enable HTTPS again with Isahc v2. Or choose another feature to select a different TLS backend, as described below.

TLS backends

Isahc now allows you to select your preference of TLS backend at compile time using crate features. Additionally, the default backend has changed. Isahc v1 always used the backends described below:

• When static-curl is disabled and dynamically linking to a system libcurl, use whatever the system libcurl was compiled to use.
• Otherwise,
  • OpenSSL on Linux
  • Secure Transport on macOS
  • Schannel on Windows

In Isahc v2, the default behavior is decided by a new set of crate features containing the word tls. The default enabled feature is default-tls which is an alias for rustls-tls, meaning Isahc v2 uses rustls by default on all platforms unconditionally. If you want to restore the previous behavior, you must disable the default-tls feature and instead enable the native-tls feature.

For example, if you had this in your Cargo.toml:

[dependencies]
isahc = "1"

To use the native TLS API, you must now use:

[dependencies.isahc]
version = "2"
default-features = false
features = ["native-tls", "http2", "log", "static-curl", "text-decoding"]

If you were also previously enabling static linking to OpenSSL on Linux like this:

[dependencies]
isahc = { version = "1", features = ["static-ssl"] }

You must now replace the default-tls feature with the native-tls-static feature, like so:

[dependencies.isahc]
version = "2"
default-features = false
features = ["native-tls-static", "http2", "log", "static-curl", "text-decoding"]

However, if you are satisfied with the change from native TLS to rustls, then you do not need to make any changes. Note that by default, the rustls backend will still use the platform's native trust store for trusted root certificates. Though exact behavior between the native TLS API and rustls even when using the same trust store is not guaranteed.

There are also other new ways of configuring your TLS backend and trust stores that were not previously possible in Isahc v1. See the Isahc v2 documentation for new features.

Network interfaces

The interface API has been redesigned to prevent mistakes and to allow specifying a network interface to bind to using multiple criteria. isahc::config::NetworkInterface has been removed, and split into multiple types in the isahc::net::interface module. Replacement should be as simple as the following:

• .interface(NetworkInterface::any()) becomes .interface(Any)
• .interface(NetworkInterface::name("eth0")) becomes .interface(Name("eth0"))
• .interface(NetworkInterface::host("192.168.1.2")) becomes .interface(IpAddr::from_str("192.168.1.2")?)
  • Any of std::net::IpAddr, std::net::Ipv4Addr, and std::net::Ipv6Addr are now instead passed directly to bind to an IP address.

TLS configuration

All SSL/TLS configuration is now consolidated into the new isahc::tls::TlsConfig struct instead of individual methods on isahc::config::Configurable. Additionally, each TLS option's APIs have been revamped as well. If you have any custom configuration related to TLS, see individual changes below.

In-memory certificates

If you were previously supplying in-memory certificates for any TLS option in Isahc v1, these previously accepted types implementing Into<Vec<u8>> and Isahc v1 would first convert the bytes to Vec<u8>. Isahc v2 instead accepts types implementing AsRef<[u8]>, taking ownership of the bytes and referencing them as needed without copying.