net: TcpSocket::connect still renders resolver failures with ::gai_strerror, whose thread-safety is unestablished

[Yaraslaut]

TcpSocket::connect is now the one error path in morph::net whose renderer
has not been shown to be safe on the threads this subsystem runs. #625 replaced
the seven std::strerror calls in include/morph/net/detail/tcp_socket.hpp
with std::system_category().message(); it deliberately did not touch
::gai_strerror, and this issue records the residue rather than letting the
decision disappear into that pull request.

The site (include/morph/net/detail/tcp_socket.hpp:112 after #625, :111
before it):

throw std::runtime_error("TcpSocket::connect: getaddrinfo failed for " + host + ": " + ::gai_strerror(rc));

Why it was not folded into #625

There is no drop-in replacement. rc is an EAI_* code from ::getaddrinfo,
not an errno value, so std::system_category().message(rc) would render a
confidently wrong string (EAI_NONAME is -2 on glibc; system_category()
would describe errno -2). Any repair here needs its own design decision — a
hand-written EAI_* table, or an argument that the call is already safe — and
that is a different change from swapping one renderer for another.

Verification status

Not reproduced, and not resolved either way. What was actually measured, on
a8511aa6 with clang-tidy 22.1.8:

1. clang-tidy's concurrency-mt-unsafe does not classify ::gai_strerror as
   unsafe, while it classifies std::strerror in the same translation unit as
   unsafe. Probe file and output:

   #include <netdb.h>
   #include <cstring>
   #include <string>
   std::string f(int e) { return ::gai_strerror(e); }
   std::string g(int e) { return std::strerror(e); }

   $ clang-tidy --checks='-*,concurrency-mt-unsafe' net625_gai.cpp -- -std=c++23
   1 warning generated.
   net625_gai.cpp:5:31: warning: function is not thread safe [concurrency-mt-unsafe]
       5 | std::string g(int e) { return std::strerror(e); }
         |                               ^
   

2. The same check over the whole header reports nothing at the ::gai_strerror
   line — the six findings it does report on a8511aa6 are all std::strerror
   sites:

   $ clang-tidy -p build/net --checks='-*,concurrency-mt-unsafe' \
       --header-filter='include/morph/.*' tests/net/test_tcp_socket.cpp
   include/morph/net/detail/tcp_socket.hpp:195:92: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   include/morph/net/detail/tcp_socket.hpp:206:90: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   include/morph/net/detail/tcp_socket.hpp:211:92: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   include/morph/net/detail/tcp_socket.hpp:276:75: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   include/morph/net/detail/tcp_socket.hpp:353:81: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   include/morph/net/detail/tcp_socket.hpp:371:80: error: function is not thread safe [concurrency-mt-unsafe,-warnings-as-errors]
   

What was NOT verified, and is the substance of this issue:

• Whether POSIX requires gai_strerror to be thread-safe. Not checked against
  the standard text; man 3 gai_strerror is not installed on the machine this
  was measured on, so its ATTRIBUTES table was not read either.
• Whether glibc's implementation is in fact MT-Safe. Inferred-only, from
  clang-tidy's classification, which is a tool's opinion about a function name
  and not a reading of the implementation.
• Whether TcpSocket::connect is reachable from more than one thread at a
  time. It is called from SocketBackend's I/O thread
  (socket_backend.hpp:909) and directly from test threads; whether two
  connect calls can overlap in a real deployment was not established.

So the honest state is: a renderer whose thread-safety this project has
asserted nowhere, sitting on an error path in a subsystem that owns several
threads. That is smaller than #625 was, and it is not nothing.

What would change the verdict

• Close as invalid if POSIX requires gai_strerror to be thread-safe, or
  if the platforms this transport supports (Linux/macOS — the header is POSIX
  only) all document it MT-Safe. Cite the text, not a tool's check list.
• Close as fixed if the call is replaced with something whose guarantee is
  written down — most plausibly an explicit EAI_* switch, since
  std::system_category() cannot describe these codes.
• Keep open, and raise it, if it turns out connect() can run concurrently
  with itself on a supported platform where the function is not MT-Safe.

Found while implementing #625. Filed rather than folded, per AGENTS.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Triage: unverified — the call site and the thread are established; the hazard is not

Measured on master @ c55ea5b7 (after #641 landed).

The call survives #641, as the issue says:

$ grep -rn "gai_strerror" include/morph/net/
include/morph/net/detail/tcp_socket.hpp:111:  throw std::runtime_error("TcpSocket::connect: getaddrinfo failed for " + host + ": " + ::gai_strerror(rc));

And it is reached from a thread morph::net spawns, which the issue inferred and I checked:

include/morph/net/socket_backend.hpp:905:    void ioThreadMain() {
include/morph/net/socket_backend.hpp:909:        auto socket = TcpSocket::connect(_url.host, _url.port, _cfg.connectTimeout);

Line 909 is inside ioThreadMain(), i.e. on _ioThread (socket_backend.hpp:106). So the structural half of the argument is the same as #625's and it holds.

What is not established is the part the title turns on: whether ::gai_strerror is actually unsafe. It differs from std::strerror in a way that matters — implementations typically return pointers to static constant strings, which is safe to share, rather than filling a shared mutable buffer. I could not check the platform's own answer:

$ man 3 gai_strerror
(no man page installed)
$ ls /usr/share/man/man3/gai_strerror*
(no man3 page on disk)

so I read neither the glibc ATTRIBUTES table nor the POSIX text, and I am not going to assert a thread-safety verdict from memory. The lane that filed this said the same thing and was right to.

Corroborating evidence pointing the other way, worth recording: clang-tidy's concurrency-mt-unsafe fires on std::strerror and not on ::gai_strerror in the same translation unit (measured by the #641 lane on a probe file). That check's function list is not authoritative, but it is one independent source treating the two differently.

triage: unverified, area: core (there is still no area: net label).

The experiment that would settle it

One of these, and it is cheap:

1. Read man 3 gai_strerror's ATTRIBUTES table on the CI image — glibc states MT-Safety there directly.
2. Read the POSIX text for gai_strerror, which says whether an implementation may return a pointer to a buffer that a later call can overwrite.

If MT-Safe: close as invalid, and record the answer in a comment at the call site so the next reader does not re-open it — that comment is the whole deliverable.
If not: it becomes valid, and note the fix is not std::system_category().message(rc) — rc is an EAI_* code, not an errno, so that would render a confidently wrong string. #641's PR body already establishes this; a correct fix needs its own mapping.

Priority note

Even if unsafe, this is narrower than #625 was: one call site on the resolver-failure path, versus seven on every socket error path. Worth doing, not worth a lane of its own.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VptDWG2fKr2vBnLSJcgzgW

[Yaraslaut]

Correction to my triage above: the call site is include/morph/net/detail/tcp_socket.hpp:112, not :111. I measured it on a checkout still at a8511aa6; on c55ea5b7 (after #641) the line moved by one.

Re-verified on the real master — ::gai_strerror is still the only suspected-non-thread-safe renderer left in morph::net, and no std::strerror call remains (the two remaining hits are doc comments inside #641's new helper):

112: throw std::runtime_error("TcpSocket::connect: getaddrinfo failed for " + host + ": " + ::gai_strerror(rc));
448: /// Describes `err` the way `std::strerror` would, without `std::strerror`'s
456: /// therefore be inside a throw site at the same moment, and `std::strerror`

The verdict (triage: unverified) and the experiment that would settle it are unchanged.

[Yaraslaut]

Experiment run: ::gai_strerror is MT-safe on every platform morph builds. Closing condition met.

The triage asked for one of two readings (glibc's ATTRIBUTES table, or the POSIX text) and said that if MT-safe, "the whole deliverable" is a comment at the call site recording the answer. Neither man page is installed here either, so I measured the property directly instead — which is stronger than reading a table, because it tests the hazard rather than the documentation of it.

What was measured

glibc 2.44, gcc -O0, this machine:

EAI_AGAIN ptr=0x7febd9bb62f2 str="Temporary failure in name resolution"
EAI_FAIL  ptr=0x7febd9bb632e str="Non-recoverable failure in name resolution"
EAI_AGAIN ptr=0x7febd9bb62f2 str="Temporary failure in name resolution"  (second call, same code)
distinct pointers for distinct codes: YES
first string intact after second call: YES
stable pointer across repeated calls:  YES
dladdr(EAI_AGAIN string) -> object=/usr/lib/libc.so.6 symbol=(anonymous: a literal in a data section)
unknown code 12345 ptr=0x7febd9bbaf2e str="Unknown error"
unknown code 54321 ptr=0x7febd9bbaf2e str="Unknown error"
unknown-code path shares a buffer: YES

and the mapping that address lives in:

gai_strerror(EAI_AGAIN) -> 0x7fa71e9b62f2 lives in:
7fa71e99f000-7fa71ea15000 r--p 0019f000 00:1c 15085232    /usr/lib/libc.so.6

r--p is the load-bearing line. std::strerror's hazard — the one morph#625 removed — is a shared mutable buffer that a second caller overwrites. A read-only mapping cannot be one. Distinct pointers per code and stability across repeated calls rule out the other shape (a single rotating slot), and even the unrecognised-code path returns a constant "Unknown error" rather than a formatted string, so there is no per-call buffer on any path, including the one a caller is least likely to test.

The other two libcs morph reaches

• musl / emscripten (the WASM build). Read from source on disk (emsdk .../musl/src/network/gai_strerror.c): a static const char msgs[] table, walked to the right NUL-separated entry, returned through LCTRANS_CUR. Same property, by inspection rather than by running it.
• Winsock, whose gai_strerrorA is documented unsafe — never compiled. include/morph/net/detail/tcp_socket.hpp includes <arpa/inet.h>, <netdb.h>, <poll.h>, <sys/socket.h>, <unistd.h>, and its own class comment says "Linux/macOS only today". CI's platforms are ubuntu-24.04, a self-hosted Linux runner, and windows-latest; the Windows leg cannot reach this file.

No macOS runner exists in any workflow, so libSystem is untested here — but it is also not a platform CI covers.

Verdict

invalid — not a defect. The call stays as it is, and correctly so: rc is an EAI_* code, not an errno, so the errnoMessage() helper morph#641 added would render a confidently wrong string, and there is no drop-in substitute. The reason it stays is now two independent reasons rather than one, which is the distinction the triage asked to be kept.

Recorded so this is not re-opened

Both, as the triage asked:

• a comment at the call site (include/morph/net/detail/tcp_socket.hpp, TcpSocket::connect) carrying the measurement, and
• docs/spec/security.md's "Socket errors are rendered with a thread-safe formatter" bullet, which previously said gai_strerror was "deliberately untouched" only because no substitution exists — now it also says it was measured not to need one.

What would re-open this

A platform with a different libc joining CI (macOS, a musl-based Linux runner), or a glibc release that changes gai_strerror to format into a buffer. The probe above is five lines of C and re-runs in a second; both records say so.

Verification status

Measured on glibc 2.44 / x86-64 Linux, on master @ c6f6d953. musl read, not run. Not verified: macOS/libSystem, any BSD, and POSIX's own text — which I still have not read, and which I am explicitly not claiming guarantees this. The entry is a measurement on the configurations morph builds, not a portability guarantee.