[DESIGN] HTTP transport requirements and options

[thc1006]

This is the requirements and options document @lalitb asked for in #4448, as a pull request so it can be reviewed before anyone chooses an implementation direction.

It answers the question that was actually asked, which is whether the HTTP transport needs to manage asynchronous concurrency itself or whether a request and result model is enough with concurrency owned somewhere else. It does not propose class names, and it does not assume that HttpOperation has to go, that a Session carries one request, or where retry belongs. Those are listed as decisions.

What is in it

The three shapes named in the discussion, compared against the criteria named with them: throughput and connection reuse, cancellation and shutdown, who owns retry and concurrency, and compatibility with the installed interfaces and custom clients.

Before that, a table of what every in-tree consumer does today, read from main rather than from memory. That table is the load-bearing part of the argument, so here is where each row came from:

• Zipkin takes a HttpClientSync, in zipkin_exporter.h and its factory.
• Elasticsearch calls handler->waitForResponse() in Export, at es_log_record_exporter.cc:475.
• OtlpHttpClient::Export takes a max_running_requests budget, and its own comment says that zero means a synchronous export; the default path passes zero and waits for the result.
• WITH_ASYNC_EXPORT_PREVIEW is OFF at CMakeLists.txt:241.

So in the configuration almost everyone builds, every exporter blocks until its request is done, and two of the three do it by handing the request to an asynchronous client and then waiting. That is the fact the rest of the document turns on.

What is deliberately not in it

No requirement numbering scheme, no benchmark matrix, no migration plan. You asked for something short, and the six decisions at the end are the part that has to be settled before any of that is worth writing.

The bug to invariant mapping is not repeated here either. It is the matrix already in the discussion thread, linked from the document, which also marks which reports are measured and which are only reasoned.

On the recommendation section

There is one, it is labelled as an opinion, and it is meant to be argued with rather than accepted. Short version: define the one attempt semantics as the contract, keep the current interface working through an adapter, and treat the single owner event loop as the curl backend's implementation for the case where concurrency is actually wanted. I would also want the concurrency question settled by a measurement rather than by assumption.

If the shape of the document is useful but the recommendation is not, the recommendation is one section and can go.

For significant contributions please make sure you have completed the following items:

• CHANGELOG.md updated for non-trivial changes
• Unit tests have been added
• Changes in public API reviewed

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (1c2b007) to head (0fea657).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4458      +/-   ##
==========================================
+ Coverage   82.67%   83.12%   +0.45%     
==========================================
  Files         516      519       +3     
  Lines       20197    20256      +59     
==========================================
+ Hits        16696    16835     +139     
+ Misses       3501     3421      -80     

see 15 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.