Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

alt-svc: experimental support #3498

Closed
wants to merge 5 commits into from
Closed
Changes from all commits
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -84,6 +84,10 @@ matrix:
compiler: clang
dist: trusty
env: T=debug
- os: linux
compiler: clang
dist: trusty
env: T=debug C="--enable-alt-svc"
- os: linux
compiler: clang
dist: trusty
@@ -285,7 +289,7 @@ script:
make
make TFLAGS=-n test-nonflaky
make "TFLAGS=-n -e" test-nonflaky
tests="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 200 201 202 300 301 302 500 501 502 503 504 506 507 508 509 510 511 512 513 514 515 516 517 518 519 600 601 700 701 702 800 801 802 803 900 901 902 903 1000 1001 1002 1004 1100 1101 1200 1201 1302 1303 1304 1305 1306 1308 1400 1401 1402 1404 1450 1451 1452 1502 1507 1508 1600 1602 1603 1605 1650 2001 2100 3000"
tests="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 200 201 202 300 301 302 500 501 502 503 504 506 507 508 509 510 511 512 513 514 515 516 517 518 519 600 601 700 701 702 800 801 802 803 900 901 902 903 1000 1001 1002 1004 1100 1101 1200 1201 1302 1303 1304 1305 1306 1308 1400 1401 1402 1404 1450 1451 1452 1502 1507 1508 1600 1602 1603 1605 1650 1651 1652 1653 1654 2001 2100 3000"
make "TFLAGS=-n -t $tests" test-nonflaky
coveralls --gcov /usr/bin/gcov-7 --gcov-options '\-lp' -i src -e lib -e tests -e docs -b $PWD/src
coveralls --gcov /usr/bin/gcov-7 --gcov-options '\-lp' -e src -i lib -e tests -e docs -b $PWD/lib
@@ -2696,15 +2696,15 @@ AC_ARG_WITH(libpsl,
with_libpsl=yes)
if test $with_libpsl != "no"; then
AC_SEARCH_LIBS(psl_builtin, psl,
[curl_psl_msg="yes";
[curl_psl_msg="enabled";
AC_DEFINE([USE_LIBPSL], [1], [PSL support enabled])
],
[curl_psl_msg="no (libpsl not found)";
AC_MSG_WARN([libpsl was not found])
]
)
fi
AM_CONDITIONAL([USE_LIBPSL], [test "$curl_psl_msg" = "yes"])
AM_CONDITIONAL([USE_LIBPSL], [test "$curl_psl_msg" = "enabled"])

dnl **********************************************************************
dnl Check for libmetalink
@@ -4062,6 +4062,32 @@ AC_HELP_STRING([--disable-cookies],[Disable cookies support]),
AC_MSG_RESULT(yes)
)

dnl ************************************************************
dnl switch on/off alt-svc
dnl
curl_altsvc_msg="no (--enable-alt-svc)";
AC_MSG_CHECKING([whether to support alt-svc])
AC_ARG_ENABLE(alt-svc,
AC_HELP_STRING([--enable-alt-svc],[Enable alt-svc support])
AC_HELP_STRING([--disable-alt-svc],[Disable alt-svc support]),
[ case "$enableval" in
no)
AC_MSG_RESULT(no)
;;
*) AC_MSG_RESULT(yes)
curl_altsvc_msg="enabled";
enable_altsvc="yes"
experimental="alt-svc"
;;
esac ],
AC_MSG_RESULT(no)
)

if test "$enable_altsvc" = "yes"; then
AC_DEFINE(USE_ALTSVC, 1, [to enable alt-svc])
experimental="alt-svc"
fi

dnl ************************************************************
dnl hiding of library internal symbols
dnl
@@ -4131,10 +4157,14 @@ if test "x$HAVE_GSSAPI" = "x1"; then
SUPPORT_FEATURES="$SUPPORT_FEATURES GSS-API"
fi

if test "x$curl_psl_msg" = "xyes"; then
if test "x$curl_psl_msg" = "xenabled"; then
SUPPORT_FEATURES="$SUPPORT_FEATURES PSL"
fi

if test "x$enable_altsvc" = "xyes"; then
SUPPORT_FEATURES="$SUPPORT_FEATURES alt-svc"
fi

if test "x$CURL_DISABLE_CRYPTO_AUTH" != "x1" -a \
\( "x$HAVE_GSSAPI" = "x1" -o "x$USE_WINDOWS_SSPI" = "x1" \); then
SUPPORT_FEATURES="$SUPPORT_FEATURES SPNEGO"
@@ -4330,32 +4360,38 @@ AC_MSG_NOTICE([Configured to build curl/libcurl:
LIBS: ${LIBS}

curl version: ${CURLVERSION}
SSL support: ${curl_ssl_msg}
SSH support: ${curl_ssh_msg}
zlib support: ${curl_zlib_msg}
brotli support: ${curl_brotli_msg}
GSS-API support: ${curl_gss_msg}
TLS-SRP support: ${curl_tls_srp_msg}
SSL: ${curl_ssl_msg}
SSH: ${curl_ssh_msg}
zlib: ${curl_zlib_msg}
brotli: ${curl_brotli_msg}
GSS-API: ${curl_gss_msg}
TLS-SRP: ${curl_tls_srp_msg}
resolver: ${curl_res_msg}
IPv6 support: ${curl_ipv6_msg}
Unix sockets support: ${curl_unix_sockets_msg}
IDN support: ${curl_idn_msg}
IPv6: ${curl_ipv6_msg}
Unix sockets: ${curl_unix_sockets_msg}
IDN: ${curl_idn_msg}
Build libcurl: Shared=${enable_shared}, Static=${enable_static}
Built-in manual: ${curl_manual_msg}
--libcurl option: ${curl_libcurl_msg}
Verbose errors: ${curl_verbose_msg}
Code coverage: ${curl_coverage_msg}
SSPI support: ${curl_sspi_msg}
SSPI: ${curl_sspi_msg}
ca cert bundle: ${ca}${ca_warning}
ca cert path: ${capath}${capath_warning}
ca fallback: ${with_ca_fallback}
LDAP support: ${curl_ldap_msg}
LDAPS support: ${curl_ldaps_msg}
RTSP support: ${curl_rtsp_msg}
RTMP support: ${curl_rtmp_msg}
metalink support: ${curl_mtlnk_msg}
PSL support: ${curl_psl_msg}
HTTP2 support: ${curl_h2_msg}
LDAP: ${curl_ldap_msg}
LDAPS: ${curl_ldaps_msg}
RTSP: ${curl_rtsp_msg}
RTMP: ${curl_rtmp_msg}
Metalink: ${curl_mtlnk_msg}
PSL: ${curl_psl_msg}
Alt-svc: ${curl_altsvc_msg}
HTTP2: ${curl_h2_msg}
Protocols: ${SUPPORT_PROTOCOLS}
Features: ${SUPPORT_FEATURES}
])
if test -n "$experimental"; then
cat >&2 << _EOF
WARNING: $experimental is enabled but marked EXPERIMENTAL. Use with caution!
_EOF
fi
@@ -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
@@ -42,6 +42,7 @@ CLEANFILES = $(GENHTMLPAGES) $(PDFPAGES) $(MANDISTPAGES) curl.1

EXTRA_DIST = \
$(noinst_man_MANS) \
ALTSVC.md \
BINDINGS.md \
BUGS \
CHECKSRC.md \
@@ -2,6 +2,7 @@

DPAGES = \
abstract-unix-socket.d \
alt-svc.d \
anyauth.d \
append.d basic.d \
cacert.d capath.d \
@@ -0,0 +1,17 @@
Long: alt-svc
Arg: <file name>
Protocols: HTTPS
Help: Enable alt-svc with this cache file
Added: 7.64.1
---
WARNING: this option is experiemental. Do not use in production.

This option enables the alt-svc parser in curl. If the file name points to an
existing alt-svc cache file, that will be used. After a completed transfer,
the cache will be saved to the file name again if it has been modified.

Specifiy a "" file name (zero length) to avoid loading/saving and make curl
just handle the cache in memory.

If this option is used several times, curl will load contents from all the
files but the the last one will be used for saving.
@@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@@ -313,6 +313,10 @@ File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP
Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP
.IP CURLOPT_COOKIELIST
Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP
.IP CURLOPT_ALTSVC
Specify the Alt-Svc: cache file name. See \fICURLOPT_ALTSVC(3)\fP
.IP CURLOPT_ALTSVC_CTRL
Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP
.IP CURLOPT_HTTPGET
Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP
.IP CURLOPT_REQUEST_TARGET
@@ -0,0 +1,61 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ALTSVC 3 "5 Feb 2019" "libcurl 7.64.1" "curl_easy_setopt options"
.SH NAME
CURLOPT_ALTSVC \- set alt-svc cache file name
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
.fi
.SH EXPERIMENTAL
Warning: this feature is early code and is marked as experimental. It can only
be enabled by explictly telling configure with \fB--enable-alt-svc\fP. You are
advised to not ship this in production before the experimental label is
removed.
.SH DESCRIPTION
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
the Alt-Svc cache to read existing cache contents from and possibly also write
it back to a after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
\fICURLOPT_ALTSVC_CTRL(3)\fP.
.SH DEFAULT
NULL. The alt-svc cache is not read nor written to file.
.SH PROTOCOLS
HTTPS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1);
curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.64.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_ALTSVC_CTRL "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), "
.BR CURLOPT_COOKIEFILE "(3), "
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.