We are glad to announce the upcoming release of cohttp 4.0.0, a low-level OCaml library for HTTP clients and servers.
This release comes with a big update of the documentation and the examples, both in the README and in the codebase, and improvements and bug fixes from many contributors 
which you will find listed below.
A huge thank you to all the people that helped to get this release ready by raising issues, participating in discussions, sending PRs, and otherwise using our library.
The future of cohttp
To quote @avsm from another post
The development process […] is driven by a simple principle that is inspired by OCaml itself: don’t needlessly break backwards compatibility without good reason, and when it is necessary, justify it. Our tools are embedded in projects that have lifespans measured in the decades, and we take compatibility seriously. That’s why we take pains to provide migration paths […] that are as invisible as possible.
Since in this release we have decided to include a number of fixes and improvements which modified Cohttp module signatures, we decided to signal the potential breackage by bumping the major version of the library. In most cases, however, you don’t need to do anything and your code will keep working with the latest cohttp.
Moving forward, we have agreed to start working on the API and the internals of cohttp to modernize it and get it ready for multicore support and also for eventual unification with the h2 stack that offers HTTP2/3 support.
To be able to move forward and avoid stalling improvements for months, we will be less shy of major releases. However, to remain true to the principle above, we will be careful to introduce one breakage at a time, carefully justify its need and provide a clear upgrade path in the changelog.
The version history is:
- cohttp 2.5.5: security backports (changelog below)
- cohttp 3.0.0: skipped (explained below)
- cohttp 4.0.0: the next release (changelog below)
- cohttp 5.0.0: will include a long-awaited change in how headers are treated: which fixes a multitude of past issues and simplifies the internals of the module.
For the people that need stability, we have decided to keep backporting important security fixes to the 2.5.x branch of the project. In fact, cohttp 2.5.5, released just a few days ago was the first release with the backport of a security issue.
What happened to 3.0.0?
The release of cohttp 3.0.0 has been long awaited, and we are extremely grateful to @dinosaure for the enormous work that went into designing and implementing conduit 3.0.0 and cohttp 3.0.0 (part of which remained in 4.0.0 as bug fixes and API improvements).
However, a discussion started soon after the release pointing out that there could be further room of improvement also with the new design, particularly with respect to backwards compatibility. Since the design discussion did not reach consensus, these changes were reverted to preserve better compatibility with existing cohttp users and cohttp 3.0.0 was marked as unavailable on the opam repository. As maintainers, our “lesson learnt” is to not do releases incrementally when they span multiple libraries: we were caught in an awkward spot when conduit 3 was released, but without cohttp 3.
The work on the new conduit is steadily progressing and will be integrated in a new major release of cohttp in the future, once we will be confident that the API is settled. If you want to try using it immediately, then it is available as the mimic library in ocaml-git.
Change Log
v4.0.0
- cohttp.response: fix malformed status header for custom status codes (@mseri @aalekseyev #752)
- remove dependency to base (@samoht #745)
- add GitHub Actions workflow (@smorimoto #739)
cohttp-lwt-jsoo: Forward exceptions to caller when response is null (@mefyl #738)- Use implicit executable dependency for generate.exe (@TheLortex #735)
- cohttp: fix chunked encoding of empty body (@mefyl #715)
- cohttp-async: fix body not being uploaded with unchunked Async.Pipe (@mefyl #706)
- cohttp-{async, lwt}: fix suprising behaviours of Body.is_empty (@anuragsoni #714 #712 #713)
- refactoring of tests (@mseri #709, @dinosaure #692)
- update documentation (@dinosaure #716, @mseri #720)
- fix deadlock in logging (@dinosaure #722)
- improve media type parsing (@seliopou #542, @dinosaure #725)
- [reverted] breaking changes to client and server API to use conduit 3.0.0 (@dinosaure #692). However, as the design discussion did not reach consensus, these changes were reverted to preserve better compatibility with existing cohttp users. (#741, @samoht)
Potentially breaking changes
- remove
wrapped falsefrom the codebase (@rgrinberg #734) - cohttp: add Uri.scheme to Request.t (@brendanlong #707)
- cohttp: update HTTP codes (@emillon #711)
- cohttp-lwt-jsoo: rename Cohttp_lwt_xhr to Cohttp_lwt_jsoo for consistency (@mseri #717)
- cohttp: fix transfer-encoding ordering in headers (@mseri #721)
- lower-level support for long-running cohttp-async connections (@brendanlong #704)
- add of_form and to_form functions to body (@seliopou #440, @mseri #723)
- cohttp-lwt: partly inline read_response, fix body stream leak (@madroach @dinosaure #696).
Note: there is a new warning that may show up in your logs when bodies are leaked, see also #730. - add comparison functions for Request.t and Response.t via ppx_compare (@msaffer-js @dinosaure #686)
v2.5.5
-
Cohttp_async.resolve_local_file,Cohttp_lwt.resolve_local_fileandCohttp_lwt_unix.resolve_fileare now the same code under the hood (Cohttp.Path.resolve_local_file). The old names have been preserved for compatibility, but will be marked as deprecated in the next release. This changes the behavior ofCohttp_lwt_unix.resolve_file: it now percent-decodes the paths and blocks escaping from the docroot correctly. This also fixes and tests the corner cases in these methods when the docroot is empty. (@ewanmellor #755)Double check your code base for uses of
Cohttp_lwt_unix.resolve_file: it is unsafe with respect to path handling. If you cannot upgrade tocohttp 2.5.5, you should modify your code to callCohttp_lwt.resolve_local_fileinstead.