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