curl/docs/examples
Stefan Eissing 671158242d
connections: introduce http/3 happy eyeballs
New cfilter HTTP-CONNECT for h3/h2/http1.1 eyeballing.
- filter is installed when `--http3` in the tool is used (or
  the equivalent CURLOPT_ done in the library)
- starts a QUIC/HTTP/3 connect right away. Should that not
  succeed after 100ms (subject to change), a parallel attempt
  is started for HTTP/2 and HTTP/1.1 via TCP
- both attempts are subject to IPv6/IPv4 eyeballing, same
  as happens for other connections
- tie timeout to the ip-version HAPPY_EYEBALLS_TIMEOUT
- use a `soft` timeout at half the value. When the soft timeout
  expires, the HTTPS-CONNECT filter checks if the QUIC filter
  has received any data from the server. If not, it will start
  the HTTP/2 attempt.

HTTP/3(ngtcp2) improvements.
- setting call_data in all cfilter calls similar to http/2 and vtls filters
  for use in callback where no stream data is available.
- returning CURLE_PARTIAL_FILE for prematurely terminated transfers
- enabling pytest test_05 for h3
- shifting functionality to "connect" UDP sockets from ngtcp2
  implementation into the udp socket cfilter. Because unconnected
  UDP sockets are weird. For example they error when adding to a
  pollset.

HTTP/3(quiche) improvements.
- fixed upload bug in quiche implementation, now passes 251 and pytest
- error codes on stream RESET
- improved debug logs
- handling of DRAIN during connect
- limiting pending event queue

HTTP/2 cfilter improvements.
- use LOG_CF macros for dynamic logging in debug build
- fix CURLcode on RST streams to be CURLE_PARTIAL_FILE
- enable pytest test_05 for h2
- fix upload pytests and improve parallel transfer performance.

GOAWAY handling for ngtcp2/quiche
- during connect, when the remote server refuses to accept new connections
  and closes immediately (so the local conn goes into DRAIN phase), the
  connection is torn down and a another attempt is made after a short grace
  period.
  This is the behaviour observed with nghttpx when we tell it to  shut
  down gracefully. Tested in pytest test_03_02.

TLS improvements
- ALPN selection for SSL/SSL-PROXY filters in one vtls set of functions, replaces
  copy of logic in all tls backends.
- standardized the infof logging of offered ALPNs
- ALPN negotiated: have common function for all backends that sets alpn proprty
  and connection related things based on the negotiated protocol (or lack thereof).

- new tests/tests-httpd/scorecard.py for testing h3/h2 protocol implementation.
  Invoke:
    python3 tests/tests-httpd/scorecard.py --help
  for usage.

Improvements on gathering connect statistics and socket access.
- new CF_CTRL_CONN_REPORT_STATS cfilter control for having cfilters
  report connection statistics. This is triggered when the connection
  has completely connected.
- new void Curl_pgrsTimeWas(..) method to report a timer update with
  a timestamp of when it happend. This allows for updating timers
  "later", e.g. a connect statistic after full connectivity has been
  reached.
- in case of HTTP eyeballing, the previous changes will update
  statistics only from the filter chain that "won" the eyeballing.
- new cfilter query CF_QUERY_SOCKET for retrieving the socket used
  by a filter chain.
  Added methods Curl_conn_cf_get_socket() and Curl_conn_get_socket()
  for convenient use of this query.
- Change VTLS backend to query their sub-filters for the socket when
  checks during the handshake are made.

HTTP/3 documentation on how https eyeballing works.

TLS improvements
- ALPN selection for SSL/SSL-PROXY filters in one vtls set of functions, replaces
  copy of logic in all tls backends.
- standardized the infof logging of offered ALPNs
- ALPN negotiated: have common function for all backends that sets alpn proprty
  and connection related things based on the negotiated protocol (or lack thereof).

Scorecard with Caddy.
- configure can be run with `--with-test-caddy=path` to specify which caddy to use for testing
- tests/tests-httpd/scorecard.py now measures download speeds with caddy

pytest improvements
- adding Makfile to clean gen dir
- adding nghttpx rundir creation on start
- checking httpd version 2.4.55 for test_05 cases where it is needed. Skipping with message if too old.
- catch exception when checking for caddy existance on system.

Closes #10349
2023-02-02 09:57:34 +01:00
..
.checksrc
.gitignore copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
10-at-a-time.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
adddocsref.pl copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
altsvc.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
anyauthput.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
cacertinmem.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
certinfo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
chkspeed.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
cookie_interface.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
crawler.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
debug.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ephiperfifo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
evhiperfifo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
externalsocket.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
fileupload.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftp-wildcard.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpget.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpgetinfo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpgetresp.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpsget.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpupload.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpuploadfrommem.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ftpuploadresume.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
getinfo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
getinmemory.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
getredirect.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
getreferrer.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
ghiper.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
headerapi.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
hiperfifo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
href_extractor.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
htmltidy.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
htmltitle.cpp copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http2-download.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http2-pushinmemory.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http2-serverpush.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http2-upload.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http3-present.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
http3.c connections: introduce http/3 happy eyeballs 2023-02-02 09:57:34 +01:00
http-post.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
httpcustomheader.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
httpput-postfields.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
httpput.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
https.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-append.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-authzid.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-copy.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-create.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-delete.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-examine.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-fetch.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-list.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-lsub.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-multi.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-noop.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-search.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-ssl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-store.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
imap-tls.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
Makefile.am copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
Makefile.example copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
Makefile.inc copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
Makefile.mk copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-app.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-debugcallback.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-double.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-event.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-formadd.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-legacy.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-post.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-single.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multi-uv.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
multithread.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
opensslthreadlock.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
parseurl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
persistent.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-authzid.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-dele.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-list.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-multi.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-noop.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-retr.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-ssl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-stat.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-tls.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-top.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
pop3-uidl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
post-callback.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
postinmemory.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
postit2-formadd.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
postit2.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
progressfunc.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
README.md copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
resolve.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sendrecv.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sepheaders.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sessioninfo.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sftpget.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sftpuploadresume.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
shared-connection-cache.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
simple.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
simplepost.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
simplessl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smooth-gtk-thread.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-authzid.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-expn.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-mail.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-mime.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-multi.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-ssl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-tls.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
smtp-vrfy.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
sslbackend.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
synctime.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
threaded-ssl.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
url2file.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
urlapi.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
usercertinmem.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
version-check.pl copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00
xmlstream.c copyright: update all copyright lines and remove year ranges 2023-01-03 09:19:21 +01:00

libcurl examples

This directory is for libcurl programming examples. They are meant to show some simple steps on how you can build your own application to take full advantage of libcurl.

If you end up with other small but still useful example sources, please mail them for submission in future packages and on the website.

Building

The Makefile.example is an example Makefile that could be used to build these examples. Just edit the file according to your system and requirements first.

Most examples should build fine using a command line like this:

`curl-config --cc --cflags --libs` -o example example.c

Some compilers do not like having the arguments in this order but instead want you do reorganize them like:

`curl-config --cc` -o example example.c `curl-config --cflags --libs`

Please do not use the curl.se site as a test target for your libcurl applications/experiments. Even if some of the examples use that site as a URL at some places, it does not mean that the URLs work or that we expect you to actually torture our website with your tests. Thanks.

Examples

Each example source code file is designed to be and work stand-alone and rather self-explanatory. The examples may at times lack the level of error checks you need in a real world, but that is then only for the sake of readability: to make the code smaller and easier to follow.