2019-03-03 05:17:52 -05:00
|
|
|
# Alt-Svc
|
|
|
|
|
|
|
|
|
|
curl features **EXPERIMENTAL** support for the Alt-Svc: HTTP header.
|
|
|
|
|
|
|
|
|
|
## Experimental
|
|
|
|
|
|
|
|
|
|
Experimental support in curl means:
|
|
|
|
|
|
|
|
|
|
1. Experimental features are provided to allow users to try them out and
|
|
|
|
|
provide feedback on functionality and API etc before they ship and get
|
|
|
|
|
"carved in stone".
|
|
|
|
|
2. You must enable the feature when invoking configure as otherwise curl will
|
|
|
|
|
not be built with the feature present.
|
|
|
|
|
3. We strongly advice against using this feature in production.
|
|
|
|
|
4. **We reserve the right to change behavior** of the feature without sticking
|
|
|
|
|
to our API/ABI rules as we do for regular features, as long as it is marked
|
|
|
|
|
experimental.
|
|
|
|
|
5. Experimental features are clearly marked so in documentation. Beware.
|
|
|
|
|
|
|
|
|
|
## Enable Alt-Svc in build
|
|
|
|
|
|
|
|
|
|
`./configure --enable-alt-svc`
|
|
|
|
|
|
|
|
|
|
## Standard
|
|
|
|
|
|
|
|
|
|
[RFC 7838](https://tools.ietf.org/html/rfc7838)
|
|
|
|
|
|
|
|
|
|
## What works
|
|
|
|
|
|
|
|
|
|
- read alt-svc file from disk
|
|
|
|
|
- write alt-svc file from disk
|
|
|
|
|
- parse `Alt-Svc:` response headers, including `ma`, `clear` and `persist`.
|
|
|
|
|
- replaces old entries when new alternatives are received
|
|
|
|
|
- unit tests to verify most of this functionality (test 1654)
|
|
|
|
|
- act on `Alt-Svc:` response headers
|
|
|
|
|
- build conditionally on `configure --enable-alt-svc` only, feature marked as
|
|
|
|
|
**EXPERIMENTAL**
|
|
|
|
|
- implement `CURLOPT_ALTSVC_CTRL`
|
|
|
|
|
- implement `CURLOPT_ALTSVC`
|
|
|
|
|
- document `CURLOPT_ALTSVC_CTRL`
|
|
|
|
|
- document `CURLOPT_ALTSVC`
|
|
|
|
|
- document `--alt-svc`
|
|
|
|
|
- add `CURL_VERSION_ALTSVC`
|
|
|
|
|
- make `curl -V` show 'alt-svc' as a feature if built-in
|
|
|
|
|
- support `curl --alt-svc [file]` to enable caching, using that file
|
|
|
|
|
- make `tests/runtests.pl` able to filter tests on the feature `alt-svc`
|
|
|
|
|
- actually use the existing in-memory alt-svc cache for outgoing connections
|
|
|
|
|
- alt-svc cache expiry
|
|
|
|
|
- test 355 and 356 verify curl acting on Alt-Svc, received from header and
|
|
|
|
|
loaded from cache. The latter needs a debug build since it enables Alt-Svc
|
|
|
|
|
for plain HTTP.
|
|
|
|
|
|
|
|
|
|
## What is left
|
|
|
|
|
|
|
|
|
|
- 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
|
|
|
|
|
- `CURLALTSVC_ALTUSED` support
|
2019-08-07 08:18:42 -04:00
|
|
|
|
|
|
|
|
# Alt-Svc cache file format
|
|
|
|
|
|
|
|
|
|
This 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 host name for the source origin
|
|
|
|
|
3. The port number for the source origin
|
|
|
|
|
4. The ALPN id for the destination host
|
|
|
|
|
5. The host name for the destination host
|
|
|
|
|
6. The host number for the destination host
|
|
|
|
|
7. Within double quotes, the expiration date of this entry
|
|
|
|
|
8. Boolean (1 or 0) if "persist" was set for this entry
|
|
|
|
|
9. Integer priority value (not currently used)
|
