internals/backends.md: new section

SUMMARY.md

@@ -214,4 +214,5 @@
     * [Everything is multi](internals/multi.md)
     * [Everything is state machines](internals/statemachines.md)
     * [Protocol handler](internals/handler.md)
+    * [Backends](internals/backends.md)
 * [Index](bookindex.md)

bookindex.md

@@ -198,16 +198,16 @@
  - HTTP redirects: [Short options](cmdline/options.md#short-options), [Available exit codes](usingcurl/returns.md#available-exit-codes), [HTTP redirects](http/redirects.md#http-redirects), [Submit a login form over HTTP](libcurl/examples/login.md#submit-a-login-form-over-http)
  - HTTP Strict Transport Security: [HTTP Strict Transport Security](http/hsts.md#http-strict-transport-security)
  - HTTP/1.1: [HTTP](protocols/curl.md#http), [Verbose mode](usingcurl/verbose.md#verbose-mode), [--trace and --trace-ascii](usingcurl/verbose/trace.md#trace-and---trace-ascii), [Debugging with TELNET](usingcurl/telnet.md#debugging-with-telnet), [HTTP protocol basics](http/basics.md#http-protocol-basics), [HTTP versions](http/versions.md#http-versions), [The HTTP this generates](http/multipart.md#the-http-this-generates), [GET or POST?](http/redirects.md#get-or-post?), [Modify the request method](http/modify/method.md#modify-the-request-method), [Modify request target](http/modify/target.md#modify-request-target), [HTTP/2](http/http2.md#http/2), [Customize HTTP request headers](libcurl-http/requests.md#customize-http-request-headers), [HTTP versions](libcurl-http/versions.md#http-versions)
- - HTTP/2: [docs](source/layout.md#docs), [nghttp2](source/build/deps.md#nghttp2), [HTTP](protocols/curl.md#http), [HTTP/2 and HTTP/3](usingcurl/verbose.md#http/2-and-http/3), [Line 4: Features](usingcurl/version.md#line-4:-features), [Available exit codes](usingcurl/returns.md#available-exit-codes), [HTTP versions](http/versions.md#http-versions), [GET or POST?](http/redirects.md#get-or-post?), [HTTP/2](http/http2.md#http/2), [HTTP/3](http/altsvc.md#http/3), [DNS over HTTPS](libcurl/names.md#dns-over-https), [HTTP versions](libcurl-http/versions.md#http-versions), [Expect: headers](libcurl-http/upload.md#expect:-headers)
- - HTTP/3: [Select HTTP/3 back-end](source/build/fromsource.md#select-http/3-back-end), [HTTPS](protocols/curl.md#https), [HTTP/2 and HTTP/3](usingcurl/verbose.md#http/2-and-http/3), [Line 4: Features](usingcurl/version.md#line-4:-features), [Available exit codes](usingcurl/returns.md#available-exit-codes), [HTTP versions](http/versions.md#http-versions), [HTTP/3](http/altsvc.md#http/3), [HTTP/3](http/http3.md#http/3), [Which libcurl version runs](libcurl/api.md#which-libcurl-version-runs), [HTTP versions](libcurl-http/versions.md#http-versions), [Expect: headers](libcurl-http/upload.md#expect:-headers)
+ - HTTP/2: [docs](source/layout.md#docs), [nghttp2](source/build/deps.md#nghttp2), [HTTP](protocols/curl.md#http), [HTTP/2 and HTTP/3](usingcurl/verbose.md#http/2-and-http/3), [Line 4: Features](usingcurl/version.md#line-4:-features), [Available exit codes](usingcurl/returns.md#available-exit-codes), [HTTP versions](http/versions.md#http-versions), [GET or POST?](http/redirects.md#get-or-post?), [HTTP/2](http/http2.md#http/2), [HTTP/3](http/altsvc.md#http/3), [DNS over HTTPS](libcurl/names.md#dns-over-https), [HTTP versions](libcurl-http/versions.md#http-versions), [Expect: headers](libcurl-http/upload.md#expect:-headers), [Different backends](internals/backends.md#different-backends)
+ - HTTP/3: [Select HTTP/3 back-end](source/build/fromsource.md#select-http/3-back-end), [HTTPS](protocols/curl.md#https), [HTTP/2 and HTTP/3](usingcurl/verbose.md#http/2-and-http/3), [Line 4: Features](usingcurl/version.md#line-4:-features), [Available exit codes](usingcurl/returns.md#available-exit-codes), [HTTP versions](http/versions.md#http-versions), [HTTP/3](http/altsvc.md#http/3), [HTTP/3](http/http3.md#http/3), [Which libcurl version runs](libcurl/api.md#which-libcurl-version-runs), [HTTP versions](libcurl-http/versions.md#http-versions), [Expect: headers](libcurl-http/upload.md#expect:-headers), [Different backends](internals/backends.md#different-backends)
  - --http0.9: [Accepting HTTP/0.9](http/versions.md#accepting-http/0.9)
  - --http1.1: [HTTP versions](http/versions.md#http-versions)
  - --http2: [HTTP versions](http/versions.md#http-versions), [HTTP/2](http/http2.md#http/2)
  - --http2-prior-knowledge: [HTTP versions](http/versions.md#http-versions), [HTTP/2](http/http2.md#http/2)
  - --http3: [HTTP versions](http/versions.md#http-versions), [Enable](http/http3.md#enable)
  - HttpGet: [How it started](project/started.md#how-it-started)
 ## I
- - IDN: [libidn2](source/build/deps.md#libidn2), [Version](usingcurl/version.md#version)
+ - IDN: [libidn2](source/build/deps.md#libidn2), [Version](usingcurl/version.md#version), [Different backends](internals/backends.md#different-backends)
  - Indentation: [Indentation](source/style.md#indentation)
  - IPv4: [Host](cmdline/urls/host.md#host), [Port number](cmdline/urls/port.md#port-number), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Name resolving](libcurl/names.md#name-resolving)
  - IPv6: [Host](cmdline/urls/host.md#host), [Port number](cmdline/urls/port.md#port-number), [URL globbing](cmdline/globbing.md#url-globbing), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Version](usingcurl/version.md#version), [Name resolving](libcurl/names.md#name-resolving)
@@ -242,7 +242,7 @@
  - mTLS: [Client certificates](usingcurl/tls/clientcert.md#client-certificates)
  - multi-threading: [libcurl multi-threading](libcurl/threading.md#libcurl-multi-threading)
 ## N
- - name resolving: [Handling different build options](source/options.md#handling-different-build-options), [Host name resolving](protocols/network.md#host-name-resolving), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Name resolve tricks with c-ares](usingcurl/connections/name.md#name-resolve-tricks-with-c-ares), [SOCKS proxy](usingcurl/proxies/socks.md#socks-proxy), [Connection reuse](libcurl/connectionreuse.md#connection-reuse), [Name resolving](libcurl/names.md#name-resolving), [Proxy types](libcurl/proxies.md#proxy-types), [Available information](libcurl/getinfo.md#available-information)
+ - name resolving: [Handling different build options](source/options.md#handling-different-build-options), [Host name resolving](protocols/network.md#host-name-resolving), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Name resolve tricks with c-ares](usingcurl/connections/name.md#name-resolve-tricks-with-c-ares), [SOCKS proxy](usingcurl/proxies/socks.md#socks-proxy), [Connection reuse](libcurl/connectionreuse.md#connection-reuse), [Name resolving](libcurl/names.md#name-resolving), [Proxy types](libcurl/proxies.md#proxy-types), [Available information](libcurl/getinfo.md#available-information), [Different backends](internals/backends.md#different-backends)
  - --negotiate: [Network leakage](cmdline/passwords.md#network-leakage), [HTTP authentication](http/auth.md#http-authentication)
  - --netrc-file: [Enable netrc](usingcurl/netrc.md#enable-netrc)
  - --netrc-optional: [Enable netrc](usingcurl/netrc.md#enable-netrc)
@@ -269,8 +269,8 @@
  - --post303: [Decide what method to use in redirects](http/redirects.md#decide-what-method-to-use-in-redirects)
  - Progress callback: [timer_callback](libcurl/drive/multi-socket.md#timer_callback), [Progress callback](libcurl/callbacks/progress.md#progress-callback)
  - pronunciation: [Pronunciation](project/name.md#pronunciation)
- - proxy: [How it started](project/started.md#how-it-started), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Line 4: Features](usingcurl/version.md#line-4:-features), [Intermediaries' fiddlings](usingcurl/downloads/browsers.md#intermediaries'-fiddlings), [Proxies](usingcurl/proxies.md#proxies), [Discover your proxy](usingcurl/proxies/discover.md#discover-your-proxy), [PAC](usingcurl/proxies/pac.md#pac), [Proxy type](usingcurl/proxies/type.md#proxy-type), [HTTP proxy](usingcurl/proxies/http.md#http-proxy), [SOCKS proxy](usingcurl/proxies/socks.md#socks-proxy), [MITM proxy](usingcurl/proxies/mitm.md#mitm-proxy), [Proxy authentication](usingcurl/proxies/auth.md#proxy-authentication), [HTTPS proxy](usingcurl/proxies/https.md#https-proxy), [Proxy environment variables](usingcurl/proxies/env.md#proxy-environment-variables), [Proxy headers](usingcurl/proxies/headers.md#proxy-headers), [Available exit codes](usingcurl/returns.md#available-exit-codes), [CONNECT response codes](http/response.md#connect-response-codes), [HTTP authentication](http/auth.md#http-authentication), [Proxies](libcurl/proxies.md#proxies), [Available information](libcurl/getinfo.md#available-information), [Verification](libcurl/tlsoptions.md#verification), [HTTP proxy](libcurl-http.md#http-proxy)
  - --proxy: [HTTP proxy](usingcurl/proxies/http.md#http-proxy), [HTTP authentication](http/auth.md#http-authentication)
+ - proxy: [How it started](project/started.md#how-it-started), [Available --write-out variables](usingcurl/verbose/writeout.md#available---write-out-variables), [Line 4: Features](usingcurl/version.md#line-4:-features), [Intermediaries' fiddlings](usingcurl/downloads/browsers.md#intermediaries'-fiddlings), [Proxies](usingcurl/proxies.md#proxies), [Discover your proxy](usingcurl/proxies/discover.md#discover-your-proxy), [PAC](usingcurl/proxies/pac.md#pac), [Proxy type](usingcurl/proxies/type.md#proxy-type), [HTTP proxy](usingcurl/proxies/http.md#http-proxy), [SOCKS proxy](usingcurl/proxies/socks.md#socks-proxy), [MITM proxy](usingcurl/proxies/mitm.md#mitm-proxy), [Proxy authentication](usingcurl/proxies/auth.md#proxy-authentication), [HTTPS proxy](usingcurl/proxies/https.md#https-proxy), [Proxy environment variables](usingcurl/proxies/env.md#proxy-environment-variables), [Proxy headers](usingcurl/proxies/headers.md#proxy-headers), [Available exit codes](usingcurl/returns.md#available-exit-codes), [CONNECT response codes](http/response.md#connect-response-codes), [HTTP authentication](http/auth.md#http-authentication), [Proxies](libcurl/proxies.md#proxies), [Available information](libcurl/getinfo.md#available-information), [Verification](libcurl/tlsoptions.md#verification), [HTTP proxy](libcurl-http.md#http-proxy)
  - --proxy-user: [Proxy authentication](usingcurl/proxies/auth.md#proxy-authentication), [HTTP authentication](http/auth.md#http-authentication)
  - --proxy1.0: [HTTP proxy tunneling](usingcurl/proxies/http.md#http-proxy-tunneling)
  - --proxytunnel: [HTTP proxy tunneling](usingcurl/proxies/http.md#http-proxy-tunneling)
@@ -338,7 +338,7 @@
  - --socks5-hostname: [SOCKS proxy](usingcurl/proxies/socks.md#socks-proxy)
  - --speed-limit: [Transfer speeds slower than this means exit](usingcurl/timeouts.md#transfer-speeds-slower-than-this-means-exit)
  - --speed-time: [Transfer speeds slower than this means exit](usingcurl/timeouts.md#transfer-speeds-slower-than-this-means-exit)
- - SSH: [Select SSH back-end](source/build/fromsource.md#select-ssh-back-end), [SSH libraries](source/build/deps.md#ssh-libraries), [SCP](protocols/curl.md#scp), [Available exit codes](usingcurl/returns.md#available-exit-codes), [SCP and SFTP](usingcurl/scpsftp.md#scp-and-sftp), [Historic TELNET](usingcurl/telnet.md#historic-telnet), [SSH key callback](libcurl/callbacks/sshkey.md#ssh-key-callback), [Trace everything](libcurl/verbose.md#trace-everything)
+ - SSH: [Select SSH back-end](source/build/fromsource.md#select-ssh-back-end), [SSH libraries](source/build/deps.md#ssh-libraries), [SCP](protocols/curl.md#scp), [Available exit codes](usingcurl/returns.md#available-exit-codes), [SCP and SFTP](usingcurl/scpsftp.md#scp-and-sftp), [Historic TELNET](usingcurl/telnet.md#historic-telnet), [SSH key callback](libcurl/callbacks/sshkey.md#ssh-key-callback), [Trace everything](libcurl/verbose.md#trace-everything), [Different backends](internals/backends.md#different-backends)
  - SSL context callback: [SSL context callback](libcurl/callbacks/sslcontext.md#ssl-context-callback)
  - SSLKEYLOGFILE: [TLS](usingcurl/tls.md#tls), [SSLKEYLOGFILE](usingcurl/tls/sslkeylogfile.md#sslkeylogfile)
  - STARTTLS: [IMAP](protocols/curl.md#imap), [TLS for emails](usingcurl/reademail.md#tls-for-emails), [Explicit FTPS](ftp/ftps.md#explicit-ftps), [STARTTLS](libcurl/tlsoptions.md#starttls)
@@ -350,7 +350,7 @@
  - --tftp-blksize: [TFTP options](usingcurl/tftp.md#tftp-options)
  - --tftp-no-options: [TFTP options](usingcurl/tftp.md#tftp-options)
  - --time-cond: [Check by modification date](http/conditionals.md#check-by-modification-date)
- - TLS: [Ubuntu and Debian](get/linux.md#ubuntu-and-debian), [lib/vtls](source/layout.md#lib/vtls), [Handling different build options](source/options.md#handling-different-build-options), [Select TLS back-end](source/build/fromsource.md#select-tls-back-end), [TLS libraries](source/build/deps.md#tls-libraries), [Build to use a TLS library](source/build/tls.md#build-to-use-a-tls-library), [TLS](protocols/network.md#tls), [How much do protocols change?](protocols/protocols.md#how-much-do-protocols-change?), [GOPHERS](protocols/curl.md#gophers), [Connection reuse](cmdline/urls/connreuse.md#connection-reuse), [Verbose mode](usingcurl/verbose.md#verbose-mode), [Line 1: curl](usingcurl/version.md#line-1:-curl), [Change the Host: header](usingcurl/connections/name.md#change-the-host:-header), [MITM proxy](usingcurl/proxies/mitm.md#mitm-proxy), [Available exit codes](usingcurl/returns.md#available-exit-codes), [SCP and SFTP](usingcurl/scpsftp.md#scp-and-sftp), [TLS for emails](usingcurl/reademail.md#tls-for-emails), [Caveats](usingcurl/mqtt.md#caveats), [TLS](usingcurl/tls.md#tls), [TLS ciphers](usingcurl/tls/ciphers.md#tls-ciphers), [Enable TLS](usingcurl/tls/enable.md#enable-tls), [TLS versions](usingcurl/tls/versions.md#tls-versions), [Verifying server certificates](usingcurl/tls/verify.md#verifying-server-certificates), [Certificate pinning](usingcurl/tls/pinning.md#certificate-pinning), [OCSP stapling](usingcurl/tls/stapling.md#ocsp-stapling), [Client certificates](usingcurl/tls/clientcert.md#client-certificates), [TLS auth](usingcurl/tls/auth.md#tls-auth), [TLS backends](usingcurl/tls/backends.md#tls-backends), [SSLKEYLOGFILE](usingcurl/tls/sslkeylogfile.md#sslkeylogfile), [HTTP with curl](http.md#http-with-curl), [The URL converted to a request](http/basics.md#the-url-converted-to-a-request), [HTTPS](http/https.md#https), [Figure out what a browser sends](http/post.md#figure-out-what-a-browser-sends), [HTTPS only](http/http3.md#https-only), [FTPS](ftp/ftps.md#ftps), [Proxy types](libcurl/proxies.md#proxy-types), [Available information](libcurl/getinfo.md#available-information), [libcurl TLS options](libcurl/tlsoptions.md#libcurl-tls-options), [Trace everything](libcurl/verbose.md#trace-everything), [HTTPS](libcurl-http.md#https)
+ - TLS: [Ubuntu and Debian](get/linux.md#ubuntu-and-debian), [lib/vtls](source/layout.md#lib/vtls), [Handling different build options](source/options.md#handling-different-build-options), [Select TLS back-end](source/build/fromsource.md#select-tls-back-end), [TLS libraries](source/build/deps.md#tls-libraries), [Build to use a TLS library](source/build/tls.md#build-to-use-a-tls-library), [TLS](protocols/network.md#tls), [How much do protocols change?](protocols/protocols.md#how-much-do-protocols-change?), [GOPHERS](protocols/curl.md#gophers), [Connection reuse](cmdline/urls/connreuse.md#connection-reuse), [Verbose mode](usingcurl/verbose.md#verbose-mode), [Line 1: curl](usingcurl/version.md#line-1:-curl), [Change the Host: header](usingcurl/connections/name.md#change-the-host:-header), [MITM proxy](usingcurl/proxies/mitm.md#mitm-proxy), [Available exit codes](usingcurl/returns.md#available-exit-codes), [SCP and SFTP](usingcurl/scpsftp.md#scp-and-sftp), [TLS for emails](usingcurl/reademail.md#tls-for-emails), [Caveats](usingcurl/mqtt.md#caveats), [TLS](usingcurl/tls.md#tls), [TLS ciphers](usingcurl/tls/ciphers.md#tls-ciphers), [Enable TLS](usingcurl/tls/enable.md#enable-tls), [TLS versions](usingcurl/tls/versions.md#tls-versions), [Verifying server certificates](usingcurl/tls/verify.md#verifying-server-certificates), [Certificate pinning](usingcurl/tls/pinning.md#certificate-pinning), [OCSP stapling](usingcurl/tls/stapling.md#ocsp-stapling), [Client certificates](usingcurl/tls/clientcert.md#client-certificates), [TLS auth](usingcurl/tls/auth.md#tls-auth), [TLS backends](usingcurl/tls/backends.md#tls-backends), [SSLKEYLOGFILE](usingcurl/tls/sslkeylogfile.md#sslkeylogfile), [HTTP with curl](http.md#http-with-curl), [The URL converted to a request](http/basics.md#the-url-converted-to-a-request), [HTTPS](http/https.md#https), [Figure out what a browser sends](http/post.md#figure-out-what-a-browser-sends), [HTTPS only](http/http3.md#https-only), [FTPS](ftp/ftps.md#ftps), [Proxy types](libcurl/proxies.md#proxy-types), [Available information](libcurl/getinfo.md#available-information), [libcurl TLS options](libcurl/tlsoptions.md#libcurl-tls-options), [Trace everything](libcurl/verbose.md#trace-everything), [HTTPS](libcurl-http.md#https), [Different backends](internals/backends.md#different-backends)
  - TLS backend: [TLS](usingcurl/tls.md#tls), [TLS backends](usingcurl/tls/backends.md#tls-backends)
  - TODO: [Future](project/future.md#future), [Suggestions](source/contributing.md#suggestions)
  - --tr-encoding: [Compression](usingcurl/downloads/compression.md#compression), [Transfer encoding](http/response.md#transfer-encoding)

internals.md

@@ -13,3 +13,5 @@ library do something new.
  * [Everything is multi](internals/multi.md)
  * [Everything is state machines](internals/statemachines.md)
  * [Protocol handler](internals/handler.md)
+ * [Backends](internals/backends.md)
+

internals/backends.md

@@ -0,0 +1,42 @@
+# Backends
+
+A backend in curl is a **build-time selectable alternative implementation**.
+
+When you build curl, you can select alternative implementations for several
+different things. Different providers of the same feature set. You select
+which backend or backends (plural) to use when you build curl.
+
+- Backends are selectable and deselectable
+- Often platform dependent
+- Can differ in features
+- Can differ in 3rd party licenses
+- Can differ in maturity
+- The internal APIs are never exposed externally
+
+## Different backends
+
+In the libcurl source code, there are internal APIs for providing
+functionlity. In these different areas there are multiple different providers:
+
+1. IDN
+2. Name resolving
+3. TLS
+4. SSH
+5. HTTP/1 and HTTP/2
+6. HTTP/3
+7. HTTP content encoding
+
+## Backends visualized
+
+![libcurl backends](slide-libcurl-backends.jpg)
+
+Applications (in the upper yellow cloud) access libcurl through the public
+API. The API is fixed and stable.
+
+Internally, the "core" of libcurl uses internal APIs to perform the different
+duties it needs to do. Each of these internal APIs are powered by alternative
+implementations, in many times powered by different third party libraries.
+
+The image above shows the different third party libraries powering different
+internal APIs. The purple boxes are "one or more" and the dark grey ones are
+"one of these".