Researched guidance: How should ETIMEDOUT distinguish connection establishment from response-body delay?

Summary

Classify ETIMEDOUT by the last completed request phase and by the timer that fired, not by the error code alone. Instrument DNS, connection, request-write, response-header/first-byte, and body-complete boundaries; then distinguish connection establishment failure from post-connect pre-header delay and from a response-body stall.

Candidate action

Use monotonic timestamps and phase markers for every request. Record DNS start/end, each connection attempt start/end, TLS handshake completion when applicable, connection acquisition and whether it was reused, request-write completion, response headers/first byte, each body-read or data event, and body end. On timeout, record the timer name, last completed marker, and whether the connection was reused. Classify as establishment timeout when the relevant connection was never obtained (or the last phase is DNS, TCP, TLS, or QUIC setup); classify as post-connect pre-header/TTFB delay when a new or reused connection exists but response headers have not arrived; classify as response-body delay when response headers/first byte have arrived but body progress or end has not. Use phase-specific controls where the client provides them: curl’s connect timeout is for DNS and connection handshakes, while its maximum-time limit covers the whole operation including transfer. In Node, treat ClientRequest response as the header boundary, IncomingMessage data/end as body progress/completion, and remember that request/socket timeout reports inactivity and does not destroy the request automatically. In Go, attach httptrace.ClientTrace and use DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn (including Reused), WroteRequest, and GotFirstResponseByte, plus body-read timestamps; use the RoundTrip error for failures to obtain a connection. Preserve separate connect, response-idle, and overall deadlines so a total deadline firing during any phase is not mislabeled as a connection failure.

Applicability

• HTTP clients and integrations that expose ETIMEDOUT or an equivalent timeout while establishing a connection, waiting for response headers, or reading a response body.
• Node.js HTTP/HTTPS clients, Go net/http clients, curl-based diagnostics, and similar clients where phase timing can be instrumented.
• Requests using pooled or reused connections, where a new TCP connection may not be created for the request.

Key findings

• Node HTTP defines the response event as the point at which response headers have been received; the response body is delivered separately through IncomingMessage, and request timeout is a socket inactivity notification that does not itself abort the request. (S1)
• Node net distinguishes lookup before connecting, connection attempts and their timeouts, successful connect, and socket inactivity timeout; a connect problem emits error instead of connect. (S2)
• Node TLS documents secureConnect after the client handshake completes, while certificate authorization must still be checked separately. (S3)
• Go httptrace exposes DNSStart/DNSDone, ConnectStart/ConnectDone, GotConn with reuse information, WroteRequest, and GotFirstResponseByte; it notes that hooks may be absent or repeated and that RoundTrip errors cover failure to obtain a connection. (S4)
• curl separates connection establishment timing from total operation timing: connect timeout covers DNS and TCP/TLS/QUIC handshakes, whereas maximum time applies regardless of whether data is still being transferred. (S5)

Known limitations

• ETIMEDOUT is not a universal phase-specific diagnosis; libraries and operating systems may report different error names or collapse DNS, TCP, TLS, and idle-read failures.
• A response-header marker proves that the server has started the HTTP response, not that the body is available or complete; body progress still needs a read/data/end measurement.
• Connection reuse, HTTP/2 multiplexing, proxies, and QUIC can make connection-level timing distinct from per-request timing; correlate the request with the client’s connection or stream identifiers when available.
• Node socket/request timeouts are inactivity notifications and do not abort automatically; Go httptrace provides hooks but not timeout policy and its hooks may be nil, concurrent, or repeated for retries and address-family attempts.
• This is researched guidance only: no endpoint, client request, timeout, or independent reproduction was executed.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• The cited documentation defines phase boundaries and timeout semantics; it does not establish how a particular production client or operating system maps its ETIMEDOUT error.

What remains unknown

• Which runtime, HTTP library, proxy path, protocol version, and operating system produced the target ETIMEDOUT.
• Whether the failing request had a fresh connection or reused an existing connection, and whether DNS, TCP, TLS, proxy CONNECT, or QUIC was the last active phase.
• Which timer fired: a connect deadline, socket inactivity timer, response/body idle timer, or overall request deadline.
• Whether any response headers or body bytes arrived before the timeout, and whether the server or an intermediary intentionally delayed them.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 HTTP | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S2 Net | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S3 TLS (SSL) | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S4 net/http/httptrace - Go Packages · official_documentation · accessed 2026-09-21
• S5 Timeouts - everything curl · official_documentation · accessed 2026-09-21