summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/HYPER.md47
-rw-r--r--docs/Makefile.am1
2 files changed, 48 insertions, 0 deletions
diff --git a/docs/HYPER.md b/docs/HYPER.md
new file mode 100644
index 000000000..655d0176c
--- /dev/null
+++ b/docs/HYPER.md
@@ -0,0 +1,47 @@
+# Hyper
+
+Hyper is a separate HTTP library written in Rust. curl can be told to use this
+library as a backend to deal with HTTP.
+
+## Experimental!
+
+Hyper support in curl is considered **EXPERIMENTAL** until further notice. It
+needs to be explicitly enabled at build-time.
+
+Further development and tweaking of the Hyper backend support in curl will
+happen in in the master branch using pull-requests, just like ordinary
+changes.
+
+## Hyper version
+
+The C API for Hyper is brand new and under development. This description
+assumes that you get and build that C API off [the branch in Hyper's git
+repository](https://github.com/hyperium/hyper/tree/hyper-capi).
+
+## build curl with hyper
+
+Build hyper and enable the C API:
+
+ % git clone -b hyper-capi https://github.com/hyperium/hyper
+ % cd hyper
+ % cargo build --no-default-features --features ffi
+
+Build curl to use hyper's C API:
+
+ % git clone https://github.com/curl/curl
+ % cd curl
+ % ./buildconf
+ % ./configure --with-hyper=<hyper dir>
+ % make
+
+# using Hyper internally
+
+Hyper is a low level HTTP transport library. curl itself provides all HTTP
+headers and Hyper provides all received headers back to curl.
+
+Therefore, msost of the "header logic" in curl as in responding to and acting
+on specific input and output headers are done the same way in curl code.
+
+The API in Hyper delivers received HTTP headers as (cleaned up) name=value
+pairs, making it impossible for curl to know the exact byte representation
+over the wire with Hyper.
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 6a79f82ec..5318ce206 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -67,6 +67,7 @@ EXTRA_DIST = \
HTTP-COOKIES.md \
HTTP2.md \
HTTP3.md \
+ HYPER.md \
INSTALL \
INSTALL.cmake \
INSTALL.md \