Unverified Commit e1be8254 authored by Daniel Stenberg's avatar Daniel Stenberg
Browse files

alt-svc: the libcurl bits

parent 4331a3b8

configure.ac

+56 −20
Original line number Diff line number Diff line
@@ -2696,7 +2696,7 @@ 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)";
@@ -2704,7 +2704,7 @@ if test $with_libpsl != "no"; then 
     ]

  )

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

docs/libcurl/curl_easy_setopt.3

+5 −1
Original line number Diff line number Diff line
@@ -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

docs/libcurl/opts/CURLOPT_ALTSVC.3

0 → 100644
+61 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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), "

docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3

0 → 100644
+92 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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_CTRL 3 "5 Feb 2019" "libcurl 7.64.1" "curl_easy_setopt options"

.SH NAME

CURLOPT_ALTSVC_CTRL \- control alt-svc behavior

.SH SYNOPSIS

.nf

#include <curl/curl.h>



#define CURLALTSVC_IMMEDIATELY  (1<<0)

#define CURLALTSVC_ALTUSED      (1<<1)

#define CURLALTSVC_READONLYFILE (1<<2)

#define CURLALTSVC_H1           (1<<3)

#define CURLALTSVC_H2           (1<<4)

#define CURLALTSVC_H3           (1<<5)



CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask);

.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

Populate the long \fIbitmask\fP with the correct set of features to instruct

libcurl how to handle Alt-Svc for the transfers using this handle.



libcurl will only accept Alt-Svc headers over a secure transport, meaning

HTTPS. It will also only complete a request to an alternative origin if that

origin is properly hosted over HTTPS. These requirements are there to make

sure both the source and the destination are legitimate.



Setting any bit will enable the alt-svc engine.

.IP "CURLALTSVC_IMMEDIATELY"

If an Alt-Svc: header is received, this instructs libcurl to switch to one of

those alternatives asap rather than to save it and use for the next request.

.IP "CURLALTSVC_ALTUSED"

Issue the Alt-Used: header in all requests that have been redirected by

alt-svc.

.IP "CURLALTSVC_READONLYFILE"

Do not write the alt-svc cache back to the file specified with

\fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified

with that option will be read and written to as deemed necessary.

.IP "CURLALTSVC_H1"

Accept alternative services offered over HTTP/1.1.

.IP "CURLALTSVC_H2"

Accept alternative services offered over HTTP/2. This will only be used if

libcurl was also built to actually support HTTP/2, otherwise this bit will be

ignored.

.IP "CURLALTSVC_H3"

Accept alternative services offered over HTTP/3. This will only be used if

libcurl was also built to actually support HTTP/3, otherwise this bit will be

ignored.

.SH DEFAULT

0. No Alt-Svc treatment.

.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 "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), "

docs/libcurl/opts/Makefile.inc

+2 −0
Original line number Diff line number Diff line
@@ -83,6 +83,8 @@ man_MANS = \ 
  CURLOPT_ACCEPTTIMEOUT_MS.3                    \

  CURLOPT_ACCEPT_ENCODING.3                     \

  CURLOPT_ADDRESS_SCOPE.3                       \

  CURLOPT_ALTSVC.3                              \

  CURLOPT_ALTSVC_CTRL.3                         \

  CURLOPT_APPEND.3                              \

  CURLOPT_AUTOREFERER.3                         \

  CURLOPT_BUFFERSIZE.3                          \