fix: enable TCP keepalive on default httpx transports to prevent NAT idle-timeout drops

[gsagrawal-binocs]

Summary

Non-streaming OpenAI API calls hang indefinitely when run behind a NAT gateway. The OpenAI server successfully generates the response (visible in the dashboard), but the client never receives it because the TCP connection was silently dropped mid-generation.

Root cause: the default httpx transport has no TCP keepalive (SO_KEEPALIVE is off). During a long non-streaming call, the TCP connection sits idle while the server generates. NAT gateways silently drop idle connections:

NAT type	Typical idle timeout
AWS NAT Gateway	~350 s
GCP Cloud NAT	~120 s
Home routers / ISP NAT	60–300 s

With o-series and GPT-5.x models under medium/high reasoning, server-side generation routinely takes 300–700 s — well past these thresholds. The client hangs indefinitely because the default SDK timeout measures time since the last received byte, and a NAT-dropped connection never sends another byte.

This affects any deployment behind NAT — EKS, ECS, Cloud Run, GKE, and even local development behind a home router.

Fix

Enable TCP keepalive on the default httpx transport for both sync (_DefaultHttpxClient) and async (_DefaultAsyncHttpxClient) clients in _base_client.py:

def _build_keepalive_socket_options() -> list[tuple[int, int, int]]:
    options: list[tuple[int, int, int]] = [(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)]
    if hasattr(socket, "TCP_KEEPIDLE"):   # Linux
        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 60))
    elif hasattr(socket, "TCP_KEEPALIVE"):  # macOS
        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPALIVE, 60))
    if hasattr(socket, "TCP_KEEPINTVL"):
        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 60))
    if hasattr(socket, "TCP_KEEPCNT"):
        options.append((socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 5))
    return options

Applied via kwargs.setdefault so any caller that passes a custom transport is completely unaffected.

This is identical to the pattern already used by the Anthropic Python SDK.

Tests

Added to tests/test_client.py for both TestOpenAI and TestAsyncOpenAI:

• test_default_transport_has_tcp_keepalive — asserts SO_KEEPALIVE=1 is set on the default transport
• test_custom_http_client_transport_is_not_overridden — asserts a caller-supplied http_client is not replaced

Reproducer

See linked issue for a standalone reproducer script demonstrating the hang : #3269

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa0246e7d4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[gsagrawal-binocs]

@apcha-oai could you please review this PR ?