header api: add curl_easy_header and curl_easy_nextheader

[bagder]

Early docs: https://github.com/curl/curl/wiki/get-headers-v2

• code for the two functions
• man pages for the functions
• example showing the API functions in use
• add test case for curl_easy_header
• figure out how to deal with CONNECT response headers
• figure out how to deal with 1xx response headers
• add test case for curl_easy_header with CONNECT
• documented as EXPERIMENTAL
• add test case for curl_easy_header with 1xx
• add test case for curl_easy_header with trailers
• add test case for curl_easy_header in a redirect case
• test case for curl_easy_nextheader
• make it build fine when HTTP support is disabled
• use a single malloc per stored header
• make the function calls able to access headers from multiple responses from the transfer
• allow curl -w to output header contents with %header{name}
• supports -w %{header_json} - ouputs all headers as JSON
• make -w %{header_json} handle duplicate headers
• add test case for -w %header{name}
• add test case for -w %{header_json}
• support/handle psuedo headers
• skip making a test for psuedo headers (due to lacking test infra)
• make the API (and -w options) build opt-in while EXPERIMENTAL
• make the tests run only if the headers API is enabled in the build
• make sure the docs appear nicely on the website (pending PR)

---

Remove the wiki page (to keep the docs in a single place) after initial merge

[jay]

does this cover 100 status responses, for example

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

[bagder]

I'm ready to merge this within the next few days. Any comments to take into account before that happens?

[nanonyme]

Hmm, was this supposed to hide the new experimental ABI by default if --enable-headers-api is not given? Because it doesn't seem it does.

[bagder]

Can you clarify what you're asking?

[nanonyme]

This post clearly states that these new functions should not be exposed as they are experimental. Yet it looks based on our ABI checks that they are indeed exposed by default even without the flag to expose them https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/jobs/2386983527 Is this intended behaviour or should I file a bug?

[bagder]

The functions are present even when disabled, but they don't do anything. They have no functionality.

[nanonyme]

I see. But just exposing them means people may call them. As it was said, the ABI is subject to change up to function signatures so isn't it completely unsafe to keep them there even as no-op functions?

[bagder]

Why would someone call them if they don't do anything? And yes, providing experimental features risks that users don't read our warnings and go ahead and use them anyway. I don't see an easy way to prevent that.

[nanonyme]

Couldn't you just use USE_HEADERS_API macro to hide them as private symbols?

[dfandrich]

On Thu, Apr 28, 2022 at 02:34:37PM -0700, Daniel Stenberg wrote: Why would someone call them if they don't do anything?

In an application in the year 2024 uses the functions then someone downgrades the library or runs the binary on CentOS with an old libcurl, it would silently fail instead of raising a run-time dynamic link error.