[4/n] IPv6 support: Add IPv6 support for sockets

[Yicheng-Lu-llll]

Why are these changes needed?

This PR updates all socket-related code to ensure compatibility with both IPv4 and IPv6.

Related issue number

Checks

See all the tests I have done here: https://docs.google.com/document/d/129aZnlNu4U3KaJbbriLHvUizUaZDnx9WgdNh50tp-c8/edit?tab=t.0

• I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
• I've run scripts/format.sh to lint the changes in this PR.
• I've included any doc changes needed for https://docs.ray.io/en/master/.
  • I've added any new APIs to the API Reference. For example, if I added a
    method in Tune, I've added it in doc/source/tune/api/ under the
    corresponding .rst file.
• I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
• Testing Strategy
  • Unit tests
  • Release tests
  • This PR is not tested :(

---

Note

Introduces IPv6-aware networking (address parsing, IP detection, socket binding, and port checks) across C++ and Python, updating services and helpers to prefer correct AF and exposing new utilities.

• Networking Utilities (C++)
  • Add IsIPv6, GetNodeIpAddressFromPerspective, and CheckPortFree(family, port) in ray/util/network_util.{h,cc}; keep BuildAddress/ParseAddress and URL helpers; extend tests.
  • Update build to include gflags; migrate C++ callers to new IP detection and port-check APIs (raylet WorkerPool, tests, redis async context, runtime init paths).
• Python Networking Helpers
  • Expose C++ functions via Cython (node_ip_address_from_perspective, is_ipv6), add get_localhost_ip, and adjust is_localhost.
  • Replace legacy IP detection and use IPv6-aware logic in services (get_node_ip_address, dashboard bind checks, TLS cert SANs).
• Socket Binding & Port Utilities
  • Bind sockets with AF_INET6 when host is IPv6 across Serve HTTP, client proxier, rpdb, node startup, Spark utils, AIR/train/collective utilities; make find_free_port accept family.
• Raylet/Workers
  • Track node address family and use family-aware CheckPortFree; improve port selection robustness.
• Docs/Examples
  • Simplify LM training address to tcp://{ip}:{port} replacing build_address.

^{Written by Cursor Bugbot for commit 3e235d8. This will update automatically on new commits. Configure here.}

[Yicheng-Lu-llll]

I renamed the function to GetNodeIpAddressFromPerspective to keep it consistent with the Python function node_ip_address_from_perspective. Additionally, I used CPython bindings to avoid maintaining duplicate implementations in both C++ and Python.

[aslonnie]

(for core team to review)

[jjyao]

Sorry for the late review.

[jjyao]

prefer to use std::optional instead of empty string since it's more explicit.

[jjyao]

Is this target address must be ip, if so we can check whether it's ipv4 or ipv6 and use the protocol correspondingly. We don't need to try both everytime?

[jjyao]

Why does the performance matter here? I'd imagine that for each Ray node, we only detect it once and use it for all the other places by passing node_ip_address around.

[Yicheng-Lu-llll]

Got it. The reason I did this was that I had a create_socket function that’s called in many places, and it called node_ip_address_from_perspective() to automatically decide which socket to create.

Now I understand your point — I’ll try using node_ip_address directly to decide which socket to create, so node_ip_address_from_perspective() won’t need to be cached.

[jjyao]

At this point, we should alway know the node-ip-address and whether it's ipv4 or ipv6 and we should select AF_INET based on that so I think the code should be like

s = socket.socket(socket.AF_INET6 if is_ip_ipv6(self.node_ip_address) else socket.AF_INET, socket.SOCK_STREAM)

We don't need another function for it.

[Yicheng-Lu-llll]

I see your point!
My original idea was to add a safe helper create_socket for cases where node_ip_address wasn’t set yet or was hard to retrieve (but that assumption seems turn out to be false). It would:

    node_ip = get_node_ip_address() # which might call `node_ip_address_from_perspective`
    family = socket.AF_INET6 if is_ipv6_ip(node_ip) else socket.AF_INET

    return socket.socket(family, socket_type)

This lets call sites avoid worrying about IPv4 vs. IPv6.
Since create_socket is used in many places, I cached node_ip_address_from_perspective() to avoid repeated lookups.

I’ll try using node_ip_address directly in all places, which should let us remove the cache entirely for node_ip_address_from_perspective()

[jjyao]

Suggested change

	def get_node_ip_address(address=""):
	def get_node_ip_address(address=None):

[jjyao]

we should pick family based on whether address is ipv4 or ipv6

[Yicheng-Lu-llll]

Got it — my previous thought was to unify the behavior based on the node IP. I’ll make the change!

[Yicheng-Lu-llll]

I’m going to reset the commit to b473c14, which is the last commit before I started reverting and debugging. I’ll update the branch once the flaky tests are fixed.

[cursor]

Bug: IPv6 Support Issue in Localhost Handling

The code hardcodes host = "127.0.0.1" (IPv4) and then immediately checks is_ipv6(host) to determine socket family. Since "127.0.0.1" is always IPv4, is_ipv6(host) will always return False, effectively disabling IPv6 support in this code path. In IPv6-only environments, this could prevent proper functionality. The code should use get_localhost_ip() instead to get the appropriate localhost address for the system.

 

[cursor]

Bug: IPv6 Address Formatting Error

The code was changed from address = f"tcp://{build_address(ip, port)}" to address = f"tcp://{ip}:{port}". This breaks IPv6 address formatting because IPv6 addresses must be wrapped in brackets when combined with a port (e.g., "[::1]:8080" not "::1:8080"). The build_address() function handles this correctly, but the manual string formatting does not, resulting in malformed URLs for IPv6 addresses.

 

[jjyao]

Failed windows and mac tests are unrelated.