Requiring OpenSSL 3.0.0 should be a breaking change

[gabrielcradden]

curl-sys 0.4.85 switched to require OpenSSL 3.0.0 or greater. This should be a breaking change not a patch change. It means if you have an older version of OpenSSL, you can't use the curl crate with any version above 0.4.9 (which is when the crate switched to require curl-sys ^0.4) as cargo will select version curl-sys 0.4.85 which fails to build.

RHEL 8 images are pinned to the 1.1.1 version of OpenSSL and this won't ever be updated so effectively having the 3.0.0 requirement as a patch change means if you're on RHEL 8 you have to pin to curl 0.4.9 which was released 9 years ago - unless I'm missing something.

Would it be possible to yank the 0.4.85 release and re-release as 0.5.0? Then you could pin to a more recent downlevel version of curl on RHEL 8 and any other OSes which have older OpenSSL.

[alexcrichton]

This crate is basically just following upstream in terms of versioning. Given that it might be better to raise this with upstream.

[merl-twin]

It seems to me that upstream DO NOT follow semver, but cargo do.
So since the last release, rust curl crate v0.4.49 become broken (for systems with openssl v1.x), but some days before it was OK.
Is it right?

[gabrielcradden]

Exactly, because Cargo trusts that crate versioning follows semver, curl crate versions above 0.4.9 can't be used on systems with openssl v1.x now, whereas they could before curl-sys 0.4.85.

Yes, I don't think curl follow semver - I'm pretty sure they've been releasing curl versions since before the semver specification was defined in any case. They say "The main version number is bumped when really big, world colliding changes are made" https://curl.se/docs/versions.html. So it sounds like they can make breaking changes in a release that only bumps the semver "minor" version number.

[merl-twin]

Summarizing, please, correct me if I'm wrong.

There won't be new version of curl crate?

And there are only 2 solutions to fix build for curl 0.4.49 with openssl-1.x:

1. Manually patch Cargo.lock - downgrade curl-sys 0.4.84+curl-8.17.0 (and then repeat this operation after each cargo update).
2. Fork curl-rust and publish new crate with only one version (previous release: curl 0.4.49 + curl-sys 0.4.84+curl-8.17.0).

Are there any other possibilities?

[gabrielcradden]

Yes I think that's right in terms of that's the only way for downstream consumers on openssl 1.x to adapt.

My suggestion for curl-rust maintainers is:

• yank the 0.4.85 curl-sys crate
• re-release changes as 0.5.0
• release a new curl crate version using 0.5.0

Then anyone who's on OpenSSL < 3 can just pin to the previous curl crate version 0.4.49 which will pull in (working) curl-sys 0.4.84, if 0.4.85 is yanked.

I don't know how feasible it is to yank a version of the crate but I think that would be the "correct" thing to do since a breaking change was mistakenly released as a patch version.

[sagebind]

I don't know how feasible it is to yank a version of the crate but I think that would be the "correct" thing to do since a breaking change was mistakenly released as a patch version.

I don't know that it is a mistake.

The minimum required version of libraries expected to be installed on the host system is continually a moving target in general, and particularly for curl-rust. Multiple times we've released an update in which the minimum libcurl version supported was increased, and within the 0.4.x series of curl-rust. Now, generally this is done pretty conservatively, but there's always the possibility of a very old system with very old libcurl breaking due to this.

Honestly, SemVer is not equipped to deal with the scenario that curl-rust is in. Conventionally speaking, SemVer declares the library API as the thing in question breaking or not, to decide whether a major version bump is required. Quoting SemVer:

8. Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented. ¹

and

What should I do if I update my own dependencies without changing the public API?

That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. We would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment. ²

In other words, the way I read SemVer, requiring your build environment or system libraries to be updated is not something that mandates a major version bump, as that is not related to the API. It just isn't information that SemVer intends to communicate, and I think people are expecting it to do something that it just doesn't.

The concept of Minimum Supported Rust Version (MSRV) is a similar problem, and given that rust-version was introduced in Rust 1.56 and then in Rust 1.84, the dependency resolver was updated to filter out dependency versions requiring a too-new Rust version. This isn't directly relevant, but does show that it was necessary to create a separate indicator outside of SemVer to properly communicate this information in dependency relationships.

as a patch version

It is worth remembering that Cargo does not strictly follow SemVer, but instead uses its own flavor of SemVer that provides a more strict definition about major version 0. Particularly, the meaning of each number shifts rightward, so instead of MAJOR.MINOR.PATCH, we have 0.MAJOR.MINOR. Most importantly, Cargo does not treat it as 0.MINOR.PATCH.

So in SemVer parlance, moving from version 0.4.84 to version 0.4.85 is semantically a minor version bump, not a patch version bump, since the syntax is 0.MAJOR.MINOR. So from that perspective, updating our minimum dependency requirements between 0.4.84 and 0.4.85 counts as a minor bump, not a patch bump, and does vaguely comport with the recommendations in the Cargo reference:

Possibly-breaking: changing the platform and environment requirements

There is a very wide range of assumptions a library makes about the environment that it runs in, such as the host platform, operating system version, available services, filesystem support, etc. It can be a breaking change if you make a new release that restricts what was previously supported, for example requiring a newer version of an operating system. These changes can be difficult to track, since you may not always know if a change breaks in an environment that is not automatically tested.

Some projects may deem this acceptable breakage, particularly if the breakage is unlikely for most users, or the project doesn’t have the resources to support all environments. Another notable situation is when a vendor discontinues support for some hardware or OS, the project may deem it reasonable to also discontinue support. ³

A good guideline that is often used by the community is looking at Debian versions and what Debian supports to get an idea of how old or new something is, and what minimum version of system dependencies are reasonable to expect. For OpenSSL, we can see that all currently-supported Debian versions have been upgraded to OpenSSL 3+, except for Debian 11 ("oldoldstable"). ⁴⁵ And the normal support cycle for Debian 11 ended already, and LTS support is about to end this year. ⁶

So while I suppose an argument could be made that we should not require OpenSSL 3+ in a minor version bump until August 31st, 2026 (end of Debian 11 LTS), but I don't know that it is necessary to be that strict. Even this is pretty generous, and I don't know that it is the job of curl-rust to be even more generous than upstream libcurl is.

---

Now, even having said all that, it still should be possible to use curl-rust on older versions, using one of two methods:

• Do a static build of everything, meaning the bundled version of libcurl will be used, and a bundled version of OpenSSL, thus removing the need to require anything in particular to be present on the host system. This can be done by enabling the static-curl and static-ssl crate features.
• Dynamically link to libcurl on the host. Odds are, even the current version of curl-sys should work fine with older versions of libcurl. You are not required to make use of the version of libcurl which is bundled with curl-sys, and you can instead compile curl-sys against the older libcurl headers you have installed and link to an older version. curl-sys will attempt to dynamically link this way by default, and will only statically link to the libcurl it is bundled with if (1) a global libcurl cannot be found, or (2) the static-curl crate feature is explicitly enabled.

Footnotes

1. https://semver.org/#spec-item-8 ↩

2. https://semver.org/#what-should-i-do-if-i-update-my-own-dependencies-without-changing-the-public-api ↩

3. https://doc.rust-lang.org/cargo/reference/semver.html#env-new-rust ↩

4. https://packages.debian.org/search?searchon=names&keywords=openssl ↩

5. https://packages.debian.org/bullseye/openssl ↩

6. https://www.debian.org/releases/bullseye/ ↩

[merl-twin]

Sounds great!

But why not curl 0.5 with curl-sys 0.5.x?

Or why not curl v0.4.50 with curl-sys 0.5.x?

[gabrielcradden]

I take your point @sagebind that the curl-sys versioning was not unambiguously wrong according to Cargo's semver definition, but it is quite annoying that it has made the crate very difficult to use for anyone stuck on OpenSSL 1.1. Simply bumping to 0.5.0 would have avoided this pain for consumers of the crate, and it would definitely not be "wrong" to do that, since as you point out, the Cargo docs say this kind of change is "possibly breaking".

Obviously now it has already been released, I understand if it's not possible to yank the crate when the OpenSSL requirement won't be an issue for most users of the crate.

For extra context RHEL 8 end-of-life is May 2029 and I expect that RedHat won't update OpenSSL until then, they'll probably just patch any CVEs.

[sagebind]

The reason why we do not "simply" bump to 0.5 is that such a change has the potential to be incredibly disruptive to the Crates ecosystem, as curl-rust is a dependency of a lot of projects. And because curl-sys links to libcurl, multiple versions of curl-rust in a project is forbidden. This means that there would be a period of time where the ecosystem might experience a lot of pain of dependency conflicts, because they are now no longer allowed to use two different libraries that transiently depend on 0.5.x (the newest) or 0.4.x (the vast majority of existing crates).

For this reason, we've been very hesitant to release a 0.5 version unless we're absolutely sure that it is necessary and the benefit of doing so is overwhelmingly worth the pain we might cause; instead we prefer to avoid that if we can.

[sagebind]

Just to close the loop on this thread (which is old now, I know), I've written a page documenting the current versioning process of curl-rust which will hopefully at least reduce some frustration so that our process is clearly explained: https://github.com/sagebind/curl-rust/wiki/Crate-versioning-strategy