luo980/curl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove ALTSVC.md, HSTS.md, HTTP2.md and PARALLEL-TRANSFERS.md

Browse Source 
These are files and documentation for established functionality that
should by now be covered properly and completely in the standard
documentation and in everything curl. Having these extra files provides
duplicated information where they risk being out of sync.

Closes #14553
This commit is contained in:
Daniel Stenberg 2024-08-15 10:04:03 +02:00
parent 1e03d4bc0b
commit 0e06603b23
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
5 changed files with 0 additions and 266 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/ALTSVC.md
View File

@ -1,50 +0,0 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# 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

48
docs/HSTS.md
View File

@ -1,48 +0,0 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# 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

108
docs/HTTP2.md
View File

@ -1,108 +0,0 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
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)

4
docs/Makefile.am
View File

@ -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 \

56
docs/PARALLEL-TRANSFERS.md
View File

@ -1,56 +0,0 @@
<!--
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
SPDX-License-Identifier: curl
-->
# 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.