diff --git a/docs/ALTSVC.md b/docs/ALTSVC.md deleted file mode 100644 index 4b5bcffcc9..0000000000 --- a/docs/ALTSVC.md +++ /dev/null @@ -1,50 +0,0 @@ - - -# Alt-Svc - -curl features support for the Alt-Svc: HTTP header. - -## Enable Alt-Svc in build - -`./configure --enable-alt-svc` - -(enabled by default since 7.73.0) - -## Standard - -[RFC 7838](https://datatracker.ietf.org/doc/html/rfc7838) - -# Alt-Svc cache file format - -This is a text based file with one line per entry and each line consists of nine -space separated fields. - -## Example - - h2 quic.tech 8443 h3-22 quic.tech 8443 "20190808 06:18:37" 0 0 - -## Fields - -1. The ALPN id for the source origin -2. The hostname for the source origin -3. The port number for the source origin -4. The ALPN id for the destination host -5. The hostname for the destination host -6. The port number for the destination host -7. The expiration date and time of this entry within double quotes. The date format is "YYYYMMDD HH:MM:SS" and the time zone is GMT. -8. Boolean (1 or 0) if "persist" was set for this entry -9. Integer priority value (not currently used) - -If the hostname is an IPv6 numerical address, it is stored with brackets such -as `[::1]`. - -# TODO - -- handle multiple response headers, when one of them says `clear` (should - override them all) -- using `Age:` value for caching age as per spec -- `CURLALTSVC_IMMEDIATELY` support diff --git a/docs/HSTS.md b/docs/HSTS.md deleted file mode 100644 index 85140ab30f..0000000000 --- a/docs/HSTS.md +++ /dev/null @@ -1,48 +0,0 @@ - - -# HSTS support - -HTTP Strict-Transport-Security. Added as experimental in curl -7.74.0. Supported "for real" since 7.77.0. - -## Standard - -[HTTP Strict Transport Security](https://datatracker.ietf.org/doc/html/rfc6797) - -## Behavior - -libcurl features an in-memory cache for HSTS hosts, so that subsequent -HTTP-only requests to a hostname present in the cache gets internally -"redirected" to the HTTPS version. - -## `curl_easy_setopt()` options: - - - `CURLOPT_HSTS_CTRL` - enable HSTS for this easy handle - - `CURLOPT_HSTS` - specify filename where to store the HSTS cache on close - (and possibly read from at startup) - -## curl command line options - - - `--hsts [filename]` - enable HSTS, use the file as HSTS cache. If filename - is `""` (no length) then no file is used, only in-memory cache. - -## HSTS cache file format - -Lines starting with `#` are ignored. - -For each hsts entry: - - [host name] "YYYYMMDD HH:MM:SS" - -The `[host name]` is dot-prefixed if it includes subdomains. - -The time stamp is when the entry expires. - -## Possible future additions - - - `CURLOPT_HSTS_PRELOAD` - provide a set of HSTS hostnames to load first - - ability to save to something else than a file diff --git a/docs/HTTP2.md b/docs/HTTP2.md deleted file mode 100644 index 55d3db5887..0000000000 --- a/docs/HTTP2.md +++ /dev/null @@ -1,108 +0,0 @@ - - -HTTP/2 with curl -================ - -[HTTP/2 Spec](https://www.rfc-editor.org/rfc/rfc7540.txt) -[http2 explained](https://daniel.haxx.se/http2/) - -Build prerequisites -------------------- - - nghttp2 - - OpenSSL, LibreSSL, BoringSSL, GnuTLS, mbedTLS, wolfSSL or Schannel - with a new enough version. - -[nghttp2](https://nghttp2.org/) -------------------------------- - -libcurl uses this 3rd party library for the low level protocol handling -parts. The reason for this is that HTTP/2 is much more complex at that layer -than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already -existing and well functional library. - -We require at least version 1.12.0. - -Over an http:// URL -------------------- - -If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl includes -an upgrade header in the initial request to the host to allow upgrading to -HTTP/2. - -Possibly we can later introduce an option that causes libcurl to fail if it is -not possible to upgrade. Possibly we introduce an option that makes libcurl -use HTTP/2 at once over http:// - -Over an https:// URL --------------------- - -If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl uses ALPN -to negotiate which protocol to continue with. Possibly introduce an option -that causes libcurl to fail if not possible to use HTTP/2. - -`CURL_HTTP_VERSION_2TLS` was added in 7.47.0 as a way to ask libcurl to prefer -HTTP/2 for HTTPS but stick to 1.1 by default for plain old HTTP connections. - -ALPN is the TLS extension that HTTP/2 is expected to use. - -`CURLOPT_SSL_ENABLE_ALPN` is offered to allow applications to explicitly -disable ALPN. - -Multiplexing ------------- - -Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the -term for doing multiple independent transfers over the same physical TCP -connection. - -To take advantage of multiplexing, you need to use the multi interface and set -`CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl -attempts to reuse existing HTTP/2 connections and just add a new stream over -that when doing subsequent parallel requests. - -While libcurl sets up a connection to an HTTP server there is a period during -which it does not know if it can pipeline or do multiplexing and if you add -new transfers in that period, libcurl defaults to starting new connections for -those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you -can ask that a transfer should rather wait and see in case there is a -connection for the same host in progress that might end up being possible to -multiplex on. It favors keeping the number of connections low to the cost of -slightly longer time to first byte transferred. - -Applications ------------- - -We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers -in HTTP 1.1 style. This allows applications to work unmodified. - -curl tool ---------- - -curl offers the `--http2` command line option to enable use of HTTP/2. - -curl offers the `--http2-prior-knowledge` command line option to enable use of -HTTP/2 without HTTP/1.1 Upgrade. - -Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections. - -curl tool limitations ---------------------- - -The command line tool does not support HTTP/2 server push. It supports -multiplexing when the parallel transfer option is used. - -HTTP Alternative Services -------------------------- - -Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that -tells the client about an alternative "route" to the same content for the same -origin server that you get the response from. A browser or long-living client -can use that hint to create a new connection asynchronously. For libcurl, we -may introduce a way to bring such clues to the application and/or let a -subsequent request use the alternate route automatically. - -[Detailed in RFC 7838](https://datatracker.ietf.org/doc/html/rfc7838) diff --git a/docs/Makefile.am b/docs/Makefile.am index 8243cb532d..9d82c3a1e6 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -60,7 +60,6 @@ INTERNALDOCS = \ EXTRA_DIST = \ $(CURLPAGES) \ $(INTERNALDOCS) \ - ALTSVC.md \ BINDINGS.md \ BUG-BOUNTY.md \ BUGS.md \ @@ -82,9 +81,7 @@ EXTRA_DIST = \ GOVERNANCE.md \ HELP-US.md \ HISTORY.md \ - HSTS.md \ HTTP-COOKIES.md \ - HTTP2.md \ HTTP3.md \ INSTALL \ INSTALL-CMAKE.md \ @@ -95,7 +92,6 @@ EXTRA_DIST = \ MAIL-ETIQUETTE.md \ MANUAL.md \ options-in-versions \ - PARALLEL-TRANSFERS.md \ README.md \ RELEASE-PROCEDURE.md \ RUSTLS.md \ diff --git a/docs/PARALLEL-TRANSFERS.md b/docs/PARALLEL-TRANSFERS.md deleted file mode 100644 index 08aac544a7..0000000000 --- a/docs/PARALLEL-TRANSFERS.md +++ /dev/null @@ -1,56 +0,0 @@ - - -# Parallel transfers - -curl 7.66.0 introduced support for doing multiple transfers simultaneously; in -parallel. - -## -Z, --parallel - -When this command line option is used, curl performs the transfers given to it -at the same time. It does up to `--parallel-max` concurrent transfers, with a -default value of 50. - -## Progress meter - -The progress meter that is displayed when doing parallel transfers is -completely different than the regular one used for each single transfer. - - It shows: - - o percent download (if known, which means *all* transfers need to have a - known size) - o percent upload (if known, with the same caveat as for download) - o total amount of downloaded data - o total amount of uploaded data - o number of transfers to perform - o number of concurrent transfers being transferred right now - o number of transfers queued up waiting to start - o total time all transfers are expected to take (if sizes are known) - o current time the transfers have spent so far - o estimated time left (if sizes are known) - o current transfer speed (the faster of upload/download speeds measured over - the last few seconds) - -Example: - - DL% UL% Dled Uled Xfers Live Qd Total Current Left Speed - 72 -- 37.9G 0 101 30 23 0:00:55 0:00:34 0:00:22 2752M - -## Behavior differences - -Connections are shared fine between different easy handles, but the -"authentication contexts" are not. For example doing HTTP Digest auth with one -handle for a particular transfer and then continue on with another handle that -reuses the same connection, the second handle cannot send the necessary -Authorization header at once since the context is only kept in the original -easy handle. - -To fix this, the authorization state could be made possible to share with the -share API as well, as a context per origin + path (realm?) basically. - -Visible in test 153, 1412 and more.