[serve] Migrate parse_uri from _private to _common

[ShuChenLin]

Description

This PR continues the migration from ray._private to ray._common. Ray Serve previously imported parse_uri from ray._private.runtime_env.packaging. This PR moves parse_uri and its minimal dependencies into _common, updates Serve to import from _common, and removes the private parse_uri implementation from runtime-env packaging.

Changes:

1. ray._common.runtime_env_uri

   • Adds Protocol, is_path and parse_uri for runtime-env URI parsing.
   • Keeps the implementation lightweight and parse-only.

2. Private runtime-env updates

   • Removes parse_uri from ray._private.runtime_env.packaging.
   • Updates remaining runtime-env callers to import parse_uri from ray._common.runtime_env_uri.
   • Reuses the common Protocol enum in ray._private.runtime_env.protocol, while keeping private download_remote_uri behavior attached there.

3. Ray Serve import update

   • Updates python/ray/serve/schema.py to import parse_uri from ray._common.runtime_env_uri instead of ray._private.runtime_env.packaging.

4. Tests

   • Adds python/ray/_common/tests/test_runtime_env_uri.py.
   • Mirrors the existing TestParseUri test cases from python/ray/tests/test_runtime_env_packaging.py.
   • Registers the new test in python/ray/_common/tests/BUILD.bazel.

Related issues

Related to #53478.

Additional information

• This PR only migrates the parse_uri function. It does not attempt to migrate or refactor the broader runtime_env package.

[gemini-code-assist]

Code Review

This pull request introduces cross-platform path and URI utilities under ray/_common, including a new is_path helper and a parse_uri function with associated unit tests, and updates ray/serve/schema.py to use the new module. Feedback on the changes includes importing urllib.parse directly to prevent potential runtime errors and refactoring the dynamically constructed Protocol enum into a standard Python class to improve readability, type safety, and IDE autocompletion.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Importing urllib does not automatically expose the urllib.parse submodule in Python. Relying on other modules to have imported it first can lead to a runtime AttributeError: module 'urllib' has no attribute 'parse'. Please import urllib.parse directly.

Suggested change

	import urllib
	import urllib.parse

[ShuChenLin]

fixed

[gemini-code-assist]

Instead of dynamically constructing the Protocol Enum using the functional API and monkey-patching a classmethod, it is much cleaner, more readable, and type-safe to define it as a standard Python class. This also enables better IDE autocompletion and static type checking.

_REMOTE_PROTOCOLS = ("http", "https", "s3", "gs", "azure", "abfss", "file")


class Protocol(enum.Enum):
    # For packages dynamically uploaded and managed by the GCS.
    GCS = "gcs"
    # For conda environments installed locally on each node.
    CONDA = "conda"
    # For pip environments installed locally on each node.
    PIP = "pip"
    # For uv environments installed locally on each node.
    UV = "uv"
    # Remote http path, assumes everything packed in one zip file.
    HTTP = "http"
    # Remote https path, assumes everything packed in one zip file.
    HTTPS = "https"
    # Remote s3 path, assumes everything packed in one zip file.
    S3 = "s3"
    # Remote google storage path, assumes everything packed in one zip file.
    GS = "gs"
    # Remote azure blob storage path, assumes everything packed in one zip file.
    AZURE = "azure"
    # Remote Azure Blob File System Secure path, assumes everything packed in one zip file.
    ABFSS = "abfss"
    # File storage path, assumes everything packed in one zip file.
    FILE = "file"

    @classmethod
    def remote_protocols(cls):
        # Returns a list of protocols that support remote storage.
        # These protocols should only be used with paths that end in
        # ".zip", ".whl", ".tar.gz", or ".tgz".
        return [cls[protocol.upper()] for protocol in _REMOTE_PROTOCOLS]

[ShuChenLin]

fixed

[abrarsheikh]

let's drop parse_uri from ray._private.runtime_env.packaging.

[ShuChenLin]

Fixed and updated the PR description.

I have updated the remaining callers in ray._private to import parse_uri from ray._common.runtime_env_uri instead.

[abrarsheikh]

can we drop is_path from path_utils?

[ShuChenLin]

Fixed. I removed ray._common.path_utils and inlined the path check as a private helper in runtime_env_uri.py.