1# Hyper 2 3Hyper is a separate HTTP library written in Rust. curl can be told to use this 4library as a backend to deal with HTTP. 5 6## Experimental! 7 8Hyper support in curl is considered **EXPERIMENTAL** until further notice. It 9needs to be explicitly enabled at build-time. 10 11Further development and tweaking of the Hyper backend support in curl will 12happen in the master branch using pull-requests, just like ordinary 13changes. 14 15## Hyper version 16 17The C API for Hyper is brand new and is still under development. 18 19## build curl with hyper 20 21Since March 3 2022, hyper needs the nightly rustc to build, which you may need 22to install first with: 23 24 % rustup toolchain install nightly 25 26Then build hyper and enable its C API like this: 27 28 % git clone https://github.com/hyperium/hyper 29 % cd hyper 30 % RUSTFLAGS="--cfg hyper_unstable_ffi" cargo +nightly rustc --features client,http1,http2,ffi -Z unstable-options --crate-type cdylib 31 32Build curl to use hyper's C API: 33 34 % git clone https://github.com/curl/curl 35 % cd curl 36 % autoreconf -fi 37 % ./configure --with-hyper=<hyper dir> 38 % make 39 40# using Hyper internally 41 42Hyper is a low level HTTP transport library. curl itself provides all HTTP 43headers and Hyper provides all received headers back to curl. 44 45Therefore, most of the "header logic" in curl as in responding to and acting 46on specific input and output headers are done the same way in curl code. 47 48The API in Hyper delivers received HTTP headers as (cleaned up) name=value 49pairs, making it impossible for curl to know the exact byte representation 50over the wire with Hyper. 51 52## Limitations 53 54The hyper backend does not support 55 56- `CURLOPT_IGNORE_CONTENT_LENGTH` 57- `--raw` and disabling `CURLOPT_HTTP_TRANSFER_DECODING` 58- RTSP 59- hyper is much stricter about what HTTP header contents it allows 60- HTTP/0.9 61- HTTP/2 upgrade using HTTP:// URLs. Aka 'h2c' 62 63## Remaining issues 64 65This backend is still not feature complete with the native backend. Areas that 66still need attention and verification include: 67 68- multiplexed HTTP/2 69- h2 Upgrade: 70- pausing transfers 71- receiving HTTP/1 trailers 72- sending HTTP/1 trailers 73 74