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 21Using Rust 1.64.0 or later, build hyper and enable its C API like this: 22 23 % git clone https://github.com/hyperium/hyper 24 % cd hyper 25 % RUSTFLAGS="--cfg hyper_unstable_ffi" cargo rustc --features client,http1,http2,ffi --crate-type cdylib 26 27Also, `--release` can be added for a release (optimized) build. 28 29Build curl to use hyper's C API: 30 31 % git clone https://github.com/curl/curl 32 % cd curl 33 % autoreconf -fi 34 % ./configure LDFLAGS="-Wl,-rpath,<hyper-dir>/target/debug -Wl,-rpath,<hyper-dir>/target/release" --with-openssl --with-hyper=<hyper-dir> 35 % make 36 37# using Hyper internally 38 39Hyper is a low level HTTP transport library. curl itself provides all HTTP 40headers and Hyper provides all received headers back to curl. 41 42Therefore, most of the "header logic" in curl as in responding to and acting 43on specific input and output headers are done the same way in curl code. 44 45The API in Hyper delivers received HTTP headers as (cleaned up) name=value 46pairs, making it impossible for curl to know the exact byte representation 47over the wire with Hyper. 48 49## Limitations 50 51The hyper backend does not support 52 53- `CURLOPT_IGNORE_CONTENT_LENGTH` 54- `--raw` and disabling `CURLOPT_HTTP_TRANSFER_DECODING` 55- RTSP 56- hyper is much stricter about what HTTP header contents it allows 57- leading whitespace in first HTTP/1 response header 58- HTTP/0.9 59- HTTP/2 upgrade using HTTP:// URLs. Aka 'h2c' 60 61## Remaining issues 62 63This backend is still not feature complete with the native backend. Areas that 64still need attention and verification include: 65 66- multiplexed HTTP/2 67- h2 Upgrade: 68- receiving HTTP/1 trailers 69- sending HTTP/1 trailers 70