curl-curl/docs
Stefan Eissing 2b3dfb4ad4
lib: make resolving HTTPS DNS records reliable:
- allow to specify when they are wanted on starting a resolve
- match dns cache entries accordingly. An entry which never
  tried to get HTTPS-RRs is no answer for a resolve that wants
  it.
- fix late arrivals of resolve answers to match the "async"
  records that started them - if it still exists.
- provide for multiple "async" resolves in a transfer at the
  same time. We may need to resolve an IP interface while the
  main connection resolve has not finished yet.
- allow lookup of HTTPS-RR information as soon as it is
  available, even if A/AAAA queries are still ongoing.

For this, the "async" infrastructure is changed:

- Defined bits for DNS queries `CURL_DNSQ_A`, `CURL_DNSQ_AAAA`
  and `CURL_DNSQ_HTTPS`. These replace `ip_version` which says
  nothing about HTTPS.
  Use them in dns cache entries for matching.
- enhance the `async->id` to be a unique `uint32_t` for
  resolves inside one multi. This is weak, as the id may
  wrap around. However it is combined with the `mid` of
  the easy handle, making collisions highly unlikely.
  `data->state.async` is only accessed in few places where
  the mid/async-id match is performed.
- vtls: for ECH supporting TLS backends (openssl, rustls, wolfssl),
  retrieve the HTTPS-RR information from the dns connection filter.
  Delay the connect if the HTTPS-RR is needed, but has not
  been resolved yet.

The implementation of all this is complete for the threaded
resolver. c-ares resolver and DoH do not take advantage of
all new async features yet. To be done in separate PRs.

Details:

c-ares: cleanup settings and initialisation. Any ares channel
is only being created on starting a resolve and propagating
operations in setopt.c to the channel are not helpful.

Changed threaded+ares pollset handling so that they do not
overwrite each others `ASYNC_NAME` timeouts.

Add trace name 'threads' for tracing thread queue and
pool used by threaded resolver.

Closes #21175
2026-04-01 15:36:31 +02:00
..
cmdline-opts docs/cmdline-opts: tidy up retry-connrefused 2026-04-01 08:34:56 +02:00
examples build: drop redundant HAVE_PTHREAD_H guard 2026-03-30 18:57:07 +02:00
internals spacecheck: verify filename lengths and characters 2026-03-25 18:56:40 +01:00
libcurl lib: make resolving HTTPS DNS records reliable: 2026-04-01 15:36:31 +02:00
tests docs: list more dependencies for running Python HTTP tests 2026-03-30 21:54:39 -07:00
.gitignore docs: add RELEASE-TOOLS.md.dist to .gitignore 2024-07-01 22:49:55 +02:00
ALTSVC.md docs: fold long lines 2025-12-11 11:42:28 +01:00
BINDINGS.md docs: some nitpicks 2026-02-27 23:05:37 +01:00
BUG-BOUNTY.md BUG-BOUNTY.md: minor rephrase to say there is no bug bounty 2026-03-10 17:34:08 +01:00
BUGS.md docs: avoid using the word 'magic' 2026-03-03 15:32:13 +01:00
CIPHERS-TLS12.md docs: update CIPHERS.md 2024-08-12 23:35:56 +02:00
CIPHERS.md docs: avoid starting sentences with However, 2026-03-07 23:49:11 +01:00
CMakeLists.txt tests: move test docs into /docs 2025-05-28 15:00:03 +02:00
CODE_OF_CONDUCT.md tidy-up: Markdown, clang-format nits 2026-01-22 23:44:47 +01:00
CODE_REVIEW.md docs: fix broken link in CODE_REVIEW.md 2025-06-21 10:32:06 +02:00
CONTRIBUTE.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
curl-config.md docs: minor edits to please the new spellchecker regime 2025-02-27 13:15:21 +01:00
CURL-DISABLE.md lib: make SMB support opt-in 2026-03-22 11:55:39 +01:00
CURLDOWN.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
DEPRECATE.md DEPRECATE.md: fix copy-and-paste mistaken subtitles 2026-03-26 11:06:25 +01:00
DISTROS.md docs: add LibreELEC to DISTROS.md 2026-01-26 12:12:05 -08:00
EARLY-RELEASE.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
ECH.md spacecheck: check long lines and repeat spaces, fix fallouts 2026-03-25 11:02:08 +01:00
EXPERIMENTAL.md docs/EXPERIMENTAL.md: add a mention of HTTPSRR as experimental 2025-01-16 19:41:42 +01:00
FAQ.md spacecheck: check long lines and repeat spaces, fix fallouts 2026-03-25 11:02:08 +01:00
FEATURES.md tidy-up: miscellaneous 2026-01-20 12:37:56 +01:00
GOVERNANCE.md docs: avoid starting sentences with However, 2026-03-07 23:49:11 +01:00
HELP-US.md tidy-up: miscellaneous 2026-01-15 13:06:13 +01:00
HISTORY.md rtmp: drop support 2026-03-21 14:56:06 +01:00
HSTS.md tidy-up: miscellaneous 2026-01-20 12:37:56 +01:00
HTTP3.md spacecheck: check long lines and repeat spaces, fix fallouts 2026-03-25 11:02:08 +01:00
HTTP-COOKIES.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
HTTPSRR.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
INFRASTRUCTURE.md BUG-BOUNTY.md: we stop the bug-bounty end of Jan 2026 2026-01-26 08:26:28 +01:00
INSTALL INSTALL: converted to markdown => INSTALL.md 2016-10-21 15:57:29 +02:00
INSTALL-CMAKE.md cmake: add CMake Config-based dependency detection for c-ares, wolfSSL 2026-03-26 11:20:03 +01:00
INSTALL.md INSTALL.md: refer to as Cygwin 2026-03-31 17:17:47 +02:00
INTERNALS.md wolfssl: document v5.0.0 (2021-11-01) as minimum required 2026-03-24 11:08:23 +01:00
IPFS.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
KNOWN_BUGS.md docs: avoid starting sentences with However, 2026-03-07 23:49:11 +01:00
KNOWN_RISKS.md progress: count amount of data "delivered" to application 2026-03-21 23:21:55 +01:00
MAIL-ETIQUETTE.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
Makefile.am docs/VERIFY.md: verify curl 2026-03-26 07:57:25 +01:00
MANUAL.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
mk-ca-bundle.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
options-in-versions tool_getparam: add --knownhosts 2025-10-06 13:41:22 +02:00
README.md reuse: add copyright + license info to individual docs/*.md files 2024-03-31 12:01:18 +02:00
RELEASE-PROCEDURE.md RELEASE-PROCEDURE.md: update future release dates 2026-01-26 12:28:25 +01:00
ROADMAP.md CI: add whitespace checker 2024-06-27 13:33:30 +02:00
runtests.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
RUSTLS.md tidy-up: URLs 2025-09-23 00:34:46 +02:00
SECURITY-ADVISORY.md stop using the word 'just' 2026-03-03 15:30:22 +01:00
SPONSORS.md BUG-BOUNTY.md: we stop the bug-bounty end of Jan 2026 2026-01-26 08:26:28 +01:00
SSL-PROBLEMS.md tidy-up: Markdown, clang-format nits 2026-01-22 23:44:47 +01:00
SSLCERTS.md tidy-up: miscellaneous 2025-12-12 04:18:48 +01:00
testcurl.md tidy-up: Markdown, clang-format nits 2026-01-22 23:44:47 +01:00
THANKS THANKS: add contributors from 8.19.0 release 2026-03-11 07:46:12 +01:00
THANKS-filter THANKS-filter: update with a new entry 2026-03-09 11:35:19 +01:00
TheArtOfHttpScripting.md badwords: avoid 'simply' 2026-03-10 19:34:06 +01:00
TODO.md docs: avoid starting sentences with However, 2026-03-07 23:49:11 +01:00
URL-SYNTAX.md rtmp: drop support 2026-03-21 14:56:06 +01:00
VERIFY.md docs/VERIFY.md: verify curl 2026-03-26 07:57:25 +01:00
VERSIONS.md VERSIONS: add 8.19.0 2026-03-11 07:46:12 +01:00
VULN-DISCLOSURE-POLICY.md BUG-BOUNTY.md: minor rephrase to say there is no bug bounty 2026-03-10 17:34:08 +01:00
wcurl.md spacecheck: check long lines and repeat spaces, fix fallouts 2026-03-25 11:02:08 +01:00

curl logo

Documentation

You find a mix of various documentation in this directory and subdirectories, using several different formats. Some of them are not ideal for reading directly in your browser.

If you would rather see the rendered version of the documentation, check out the curl website's documentation section for general curl stuff or the libcurl section for libcurl related documentation.