docs/ALTSVC.md: docs describing the approach

Closes #3498

2 files changed, 60 insertions, 0 deletions

diff --git a/docs/ALTSVC.md b/docs/ALTSVC.md
new file mode 100644
index 000000000..5aca1c950
--- /dev/null
+++ b/docs/ALTSVC.md
@@ -0,0 +1,59 @@
+# 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
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 4c0d55420..8eeabd478 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -42,6 +42,7 @@ CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) $(MANDISTPAGES) curl.1
 
 EXTRA_DIST =                                    \
  $(noinst_man_MANS)                             \
+ ALTSVC.md                                      \
  BINDINGS.md                                    \
  BUGS                                           \
  CHECKSRC.md                                    \