Isahc 1.0 and Retrospective

3 years ago by Stephen Coakleyprogrammingrustisahc
6 min read

Today I am pleased to announce the public release of version 1.0 of Isahc, an HTTP client for Rust that I have been working on for more than 3 years now. This has been a long time coming and has involved a lot of my spare time, so I am quite relieved to see it finally ready!

Check the official announcement post on Isahc’s snazzy new discussions page for a deep dive into some of the major changes. I also invite you to check the release notes for a complete list of changes.

Instead of repeating the list of changes here in this article, I will take some time to reflect on some other announcements, some things it took to get to this release, and some lessons learned.

Discussions forum

I think any moderately successful open-source project that has an interest in community involvement should have a go-to place online for beginners, expert users, and maintainers alike to converse, whether it is with IRC, a mailing list, or a public forum. It is a great way to invite questions and feedback on the project without cluttering the issue tracker, which tends to be perceived as having a higher barrier to entry.

GitHub very recently released their Discussions feature, something I had been keeping a close eye on and eagerly awaiting the arrival of. As long as you don’t mind investing in the GitHub ecosystem, I’ve found it to already be a great feature that takes good ideas from traditional forums without the burden of hosting a separate site.

Therefore as part of the 1.0 push, Isahc has officially launched its own Discussions page. I encourage you to check it out and would love to hear from you there!

Project rebranding

When I last wrote an article about Isahc over a year ago, it had not yet even been renamed from cHTTP, the former project name, though I had discussed wishing to change the name.

My initial naming attempt of “cHTTP” was a bit of a throwaway name appropriate for what I thought would be a throwaway project. Once the project began to gather momentum and attention, it seemed like a good idea to rebrand since the last thing I wanted was the strange and generic-sounding name to hamper adoption. I think we can all agree that naming things can be hard!

If you are confused by what the name meant, then you’re not alone, as it seemed pretty much everyone was. It was meant to pay homage to the meaning of the name cURL which is “Client for URLs”. Since the project simply started out as a high-level wrapper around the HTTP-specific APIs of cURL, it seemed fitting then to name it cHTTP for “Client for HTTP” referencing the same naming pattern.

Of course, this is when “Isahc” showed up and the now familiar mascot was created:

I drew this mascot with my own hand (ink and paper), scanned it, and then digitized and edited it using Inkscape, my preferred graphic art tool. I’ve actually since been asked a few times if I take art commissions, which I’m flattered by, but no I don’t, sorry. I use my art talents so rarely that it would hardly be a fair exchange. You might say that I’m a bit, ahem, rusty 😏.

Refining the project vision

While thinking about the project rename, I also gave a good deal of thought as to what I wanted Isahc to look like in the future and what it’s role would be in the Rust ecosystem. After some consideration, I decided that it would be best to limit Isahc to being a libcurl wrapper, at least for now. Things such as WebAssembly support would be out of scope, as other clients already with this focus would probably be better at it anyway.

A key focus of Isahc then and continuing now into the future is on API ergonomics. I care a lot about how APIs are designed (maybe even a little obsessed). Isahc has been my playground for this experimentation, allowing the API to evolve over time into what we have now for 1.0 (which actually came into focus around 0.8). Personally I think one of Isahc’s strongest advantages is its elegant API, which is one of the best around if I say so myself!

Lessons learned

I may not have initially planned to put this much work into Isahc, but am glad that I did. Creating Isahc and building up to this release, there were many things I learned along the way. Two learnings especially stand out though, one technical and one less so.

I acquired a great deal of experience running a proper open-source project during this process, something I had not previously had much of. I’ve been a maintainer for a couple large projects before, but as pretty much the sole owner of Isahc I’ve had to handle things like issues, accepting contributions, and releases myself.

You can’t always please everyone, and it is important to have a clear vision for a project that you can follow. Even so, interacting with every person in a gracious and welcoming manner regardless is definitely is worth it. It sure does take a lot of time and patience to write detailed replies, and scaling this process up will absolutely require more volunteers, but I don’t think I’d have it any other way.

The second, more technical, lesson is that protocols can sometimes be deceptively simple at first look, but become very complicated once you go deeper. Even though Isahc interfaces to libcurl, I still learned quite a bit about how HTTP works in practice. It is a lot more involved than it seems once you start adding all the modern features and extensions that people expect! Being so tightly integrated with libcurl, I think I’ve closely studied about 75% of it’s source code now (excluding non-HTTP protocol support) and have a pretty decent understanding of its internals.

Thanks

Isahc would not be where it is today if not for the many helpful people who submitted suggestions, ideas, and bug reports over the lifetime of the project. In addition, the growing user base was definitely a source of motivation to deliver something solid and feature-complete as Isahc seemingly fills a niche for a highly-configurable HTTP client that people want.

I’d also like to give a brief shout-out to Surf, a generalized async HTTP client interface that abstracts over multiple backends. It was very humbling to have Isahc selected as one of the first Surf backends, and I am committed to keep Isahc as a runtime-agnostic async HTTP client.