1<!-- 2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4SPDX-License-Identifier: curl 5--> 6 7# Hyper 8 9Hyper is a separate HTTP library written in Rust. curl can be told to use this 10library as a backend to deal with HTTP. 11 12## EXPERIMENTAL 13 14Hyper support in curl is considered **EXPERIMENTAL** until further notice. It 15needs to be explicitly enabled at build-time. 16 17Further development and tweaking of the Hyper backend support in curl happens 18in the master branch using pull-requests, just like ordinary changes. 19 20## Hyper version 21 22The C API for Hyper is brand new and is still under development. 23 24## Build curl with hyper 25 26Using Rust 1.64.0 or later, 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 rustc --features client,http1,http2,ffi --crate-type cdylib 31 32Also, `--release` can be added for a release (optimized) build. 33 34Build curl to use hyper's C API: 35 36 % git clone https://github.com/curl/curl 37 % cd curl 38 % autoreconf -fi 39 % ./configure LDFLAGS="-Wl,-rpath,<hyper-dir>/target/debug -Wl,-rpath,<hyper-dir>/target/release" --with-openssl --with-hyper=<hyper-dir> 40 % make 41 42# Using Hyper internally 43 44Hyper is a low level HTTP transport library. curl itself provides all HTTP 45headers and Hyper provides all received headers back to curl. 46 47Therefore, most of the "header logic" in curl as in responding to and acting 48on specific input and output headers are done the same way in curl code. 49 50The API in Hyper delivers received HTTP headers as (cleaned up) name=value 51pairs, making it impossible for curl to know the exact byte representation 52over the wire with Hyper. 53 54## Limitations 55 56The hyper backend does not support 57 58- `CURLOPT_IGNORE_CONTENT_LENGTH` 59- `--raw` and disabling `CURLOPT_HTTP_TRANSFER_DECODING` 60- RTSP 61- hyper is much stricter about what HTTP header contents it allows 62- leading whitespace in first HTTP/1 response header 63- HTTP/0.9 64- HTTP/2 upgrade using HTTP:// URLs. Aka 'h2c' 65- HTTP/2 in general. Hyper has support for HTTP/2 but the curl side 66 needs changes so that a `hyper_clientconn` can last for the duration 67 of a connection. Probably this means turning the Hyper HTTP/2 backend 68 into a connection filter. 69 70## Remaining issues 71 72This backend is still not feature complete with the native backend. Areas that 73still need attention and verification include: 74 75- multiplexed HTTP/2 76- h2 Upgrade: 77- receiving HTTP/1 trailers 78- sending HTTP/1 trailers 79
