[1/n] IPv6 support: address <-> host:port conversion for Python Part by Yicheng-Lu-llll · Pull Request #55281 · ray-project/ray

Yicheng-Lu-llll · 2025-08-06T02:55:50Z

Why are these changes needed?

Provide utilities that supports both ipv4 and ipv6 to combine host and port to address and split address to host and port.

This is a continuation of the work in #54662 (comment) and #55129. Please refer to the discussion for more context.

Related issue number

Checks

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 :(

gemini-code-assist

Summary of Changes

Hello @Yicheng-Lu-llll, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've implemented foundational changes to enhance Ray's network address handling, primarily to improve IPv6 support. This involved introducing a pair of core utility functions, parse_address and build_address, which provide a standardized and robust way to convert between host:port strings and their constituent parts, with special attention to IPv6 formatting. Following this, I've systematically refactored a large portion of the existing codebase to leverage these new utilities, replacing disparate and less robust string manipulation methods. This effort aims to ensure consistent and correct network communication across all Ray components, paving the way for full IPv6 compatibility.

Highlights

New Network Address Utilities: I've introduced two new core utility functions, parse_address and build_address, located in ray/_private/network_utils.py. These functions provide a standardized and robust way to handle network addresses (host:port strings) throughout the Ray codebase.
Enhanced IPv6 Compatibility: The build_address function now intelligently formats IPv6 addresses by enclosing them in square brackets (e.g., [::1]:8000), which is essential for correct parsing and communication in IPv6 environments. This ensures Ray components can properly interact over IPv6.
Extensive Code Refactoring: I've systematically refactored a significant portion of the Python codebase to replace various ad-hoc string manipulations (like .split(':') or f-strings) with calls to the new parse_address and build_address utilities. This change improves code consistency, readability, and correctness, especially when dealing with complex IPv6 addresses.
Broad System-Wide Impact: This refactoring impacts a wide array of Ray's internal components, including internal APIs, metrics agents, node management, dashboard services, autoscalers, data and serve modules, and numerous test utilities. This broad adoption ensures a consistent approach to address handling across the entire system.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces build_address and parse_address utility functions for robust handling of network addresses, including IPv6. The changes are largely a mechanical replacement of manual string operations with these new functions, which is a significant improvement for IPv6 support. The implementation of the new utilities is sound. I've identified one critical issue where build_address is misused for Docker port mappings, which could lead to incorrect behavior. I've also provided a suggestion to simplify the implementation of build_address for better maintainability. Overall, this is a valuable contribution to the project.

python/ray/autoscaler/_private/fake_multi_node/node_provider.py

python/ray/_private/network_utils.py

codope

Overall looks good. Thanks for refactoring. One comment related to docker.

codope · 2025-08-06T08:56:52Z

python/ray/_private/network_utils.py

+    return [host, port]
+
+
+def build_address(host: str, port: Union[int, str]) -> str:


How does it handle the docker port mapping? Docker's -p option can take the form ip:host_port:container_port. If build_address is used to generate the ip:host_port part of this string, it will correctly produce [ip]:host_port for an IPv6 address. However, the code that constructs the full port mapping string needs to be aware of this. I suggest covering this scenario in conftest_docker.py if not already done so.

Thanks for the suggestion! We're already using build_address() in conftest_docker.py (see line 129). Let me know if I missed anything!

Yicheng-Lu-llll · 2025-08-06T16:47:28Z

python/ray/_private/node.py

            # instance provided.
            if len(external_redis) == 1:
                external_redis.append(external_redis[0])
-            [primary_redis_ip, port] = parse_address(external_redis[0])


I found that the primary_redis_ip and port are actually unused.

aslonnie

(defering to core team; let me know if needs me)

jjyao · 2025-08-08T04:12:24Z

python/ray/_private/network_utils.py

@@ -0,0 +1,44 @@
+from typing import Optional, Tuple, Union
+


Could you move this file to python/ray/_common/network_utils.py.

jjyao · 2025-08-08T04:14:54Z

python/ray/util/spark/cluster_init.py

        "address" is in format of "<ray_head_node_ip>:<port>"
        "remote_connection_address" is in format of
-        "ray://<ray_head_node_ip>:<ray-client-server-port>",
+        "ray://<build_address(ray_head_node_ip, ray-client-server-port)>",


no need to change this, this is comment

jjyao

LG!

jjyao · 2025-08-08T04:19:30Z

Could you also rebase and resolve merge conflicts.

jjyao · 2025-08-08T15:17:28Z

doc/source/train/user-guides/persistent-storage.rst

            storage_path="/mnt/cluster_storage",
            # HDFS example:
-            # storage_path=f"hdfs://{hostname}:{port}/subpath",
+            # storage_path=f"hdfs://{build_address(hostname, port)}/subpath",


Let's not change this since it's doc.

jjyao · 2025-08-08T15:18:14Z

python/ray/_common/network_utils.py

+from typing import Optional, Tuple, Union
+
+
+def parse_address(address: str) -> Optional[Tuple[str, str]]:


Can you add some tests? In the follow-up, we can explore combining this with the c++ version via cython.

bveeramani

Stamp

jjyao · 2025-08-08T17:28:46Z

python/ray/_common/tests/test_network_utils.py

+    def test_parse_bare_addresses(self, address):
+        """Test parsing bare addresses returns None."""
+        result = parse_address(address)
+        assert result is None


I think you need main function

Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com>

…55281) Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com> Signed-off-by: sampan <sampan@anyscale.com>

…ay-project#55281) Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com> Signed-off-by: Andrew Grosser <dioptre@gmail.com>

…ay-project#55281) Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com> Signed-off-by: jugalshah291 <shah.jugal291@gmail.com>

…ay-project#55281) Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com> Signed-off-by: Douglas Strodtman <douglas@anyscale.com>

Yicheng-Lu-llll requested review from a team, aslonnie, edoakes, jjyao and richardliaw as code owners August 6, 2025 02:55

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from be052ba to 41cdbad Compare August 6, 2025 02:57

gemini-code-assist bot reviewed Aug 6, 2025

View reviewed changes

python/ray/autoscaler/_private/fake_multi_node/node_provider.py Outdated Show resolved Hide resolved

python/ray/_private/network_utils.py Outdated Show resolved Hide resolved

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch 3 times, most recently from ae5f646 to 78bfd1a Compare August 6, 2025 03:16

jjyao assigned codope Aug 6, 2025

ray-gardener bot added community-contribution Contributed by the community core Issues that should be addressed in Ray Core labels Aug 6, 2025

codope reviewed Aug 6, 2025

View reviewed changes

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from bdf7b82 to 7133f24 Compare August 6, 2025 16:46

Yicheng-Lu-llll commented Aug 6, 2025

View reviewed changes

aslonnie reviewed Aug 6, 2025

View reviewed changes

robertnishihara mentioned this pull request Aug 7, 2025

Ray IPv6 support #44252

Closed

8 tasks

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from 6d40767 to c812f74 Compare August 7, 2025 06:09

jjyao reviewed Aug 8, 2025

View reviewed changes

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from 06c4848 to 821fdc4 Compare August 8, 2025 04:54

jjyao added the go add ONLY when ready to merge, run all tests label Aug 8, 2025

jjyao approved these changes Aug 8, 2025

View reviewed changes

bveeramani approved these changes Aug 8, 2025

View reviewed changes

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from 821fdc4 to 7d19f88 Compare August 8, 2025 17:08

jjyao reviewed Aug 8, 2025

View reviewed changes

justinvyu approved these changes Aug 8, 2025

View reviewed changes

Yicheng-Lu-llll added 3 commits August 8, 2025 11:02

IPv6 support: address <-> host:port conversion for Python Part

e60549b

Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com>

add unit test

92b6593

Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com>

fix lint

9d94ee1

Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com>

Yicheng-Lu-llll force-pushed the python-ip-port-utils branch from ee35499 to 9d94ee1 Compare August 8, 2025 18:02

kamil-kaczmarek approved these changes Aug 8, 2025

View reviewed changes

abrarsheikh approved these changes Aug 8, 2025

View reviewed changes

edoakes approved these changes Aug 8, 2025

View reviewed changes

jjyao merged commit 7b44918 into ray-project:master Aug 8, 2025
5 checks passed

sampan-s-nayak pushed a commit that referenced this pull request Aug 12, 2025

[1/n] IPv6 support: address <-> host:port conversion for Python Part (#…

aac8bd0

…55281) Signed-off-by: Yicheng-Lu-llll <luyc58576@gmail.com> Signed-off-by: sampan <sampan@anyscale.com>

richardliaw mentioned this pull request Dec 15, 2025

[Core] IPv6 Support #54660

Open

		return [host, port]


		def build_address(host: str, port: Union[int, str]) -> str:

		from typing import Optional, Tuple, Union


		def parse_address(address: str) -> Optional[Tuple[str, str]]:

Conversation

Yicheng-Lu-llll commented Aug 6, 2025 • edited by jjyao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why are these changes needed?

Related issue number

Checks

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

codope left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aslonnie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjyao left a comment

Choose a reason for hiding this comment

Uh oh!

jjyao commented Aug 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bveeramani left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Yicheng-Lu-llll commented Aug 6, 2025 •

edited by jjyao

Loading