HDDS-15768. Bracket IPv6 literals in Ratis peer addresses

[smengcl]

Generated-by: Claude Code (Opus 4.8)

What changes were proposed in this pull request?

Ozone builds Ratis peer address strings by plainly concatenating a host and port (host + ":" + port). When the host is an IPv6 literal (for example 2001:db8::1), the result 2001:db8::1:9858 is ambiguous: it cannot be distinguished from a hostname, and neither Ratis nor gRPC can parse it. IPv6 literals must be wrapped in square brackets when combined with a port, e.g. [2001:db8::1]:9858.

This affects every Ratis transport in Ozone:

• Datanode pipelines via RatisHelper.toRaftPeerAddress (used for the RATIS_SERVER, RATIS_ADMIN, RATIS, and RATIS_DATASTREAM peer addresses).
• OM HA and SCM HA via NodeDetails.getRatisHostPortStr (consumed by OzoneManagerRatisServer, SCMRatisServerImpl, and SCMHAManagerImpl when calling RaftPeer.setAddress(...)).

Ratis itself needs no change: ratis-grpc passes the peer address string verbatim to NettyChannelBuilder.forTarget(...), which accepts the bracketed [::1]:port form, and Ratis's own NetUtils.createSocketAddr/address2String are already IPv6-aware. The defect is purely that Ozone hands Ratis unbracketed IPv6 strings.

This PR adds a small bracket-aware formatter and routes the two Ratis peer-address producers through it:

• New HddsUtils.getHostPortString(String host, int port), which delegates to Guava's HostAndPort.fromParts(host, port).toString(). It brackets bare and already-bracketed IPv6 literals, and leaves hostnames and IPv4 literals untouched. HddsUtils already depends on Guava HostAndPort (used by the sibling getHostPort), so no new dependency is introduced.
• RatisHelper.toRaftPeerAddress and NodeDetails.getRatisHostPortStr now use the helper instead of raw string concatenation.

Scope note: this PR fixes the Ratis peer-address path only. Other IPv6-unsafe address handling in Ozone (the 0.0.0.0 bind defaults, the S3G/OFS URI and admin-CLI colon splitting, and other host + ":" + port sites such as GrpcOMFailoverProxyProvider) is tracked separately and is out of scope here.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-15768

How was this patch tested?

• Added unit tests

[Copilot]

Pull request overview

Fixes construction of Ratis peer target strings when the host is an IPv6 literal by ensuring the host:port form is unambiguous ([ipv6]:port). This aligns Ozone’s Ratis peer addressing with what gRPC/Netty target parsing expects and prevents failures caused by unbracketed IPv6 literals.

Changes:

• Added HddsUtils.getHostPortString(host, port) to format host:port with IPv6 bracketing via Guava HostAndPort.
• Updated Ratis peer address generation in RatisHelper and HA node peer address generation in NodeDetails to use the new helper.
• Added unit tests covering IPv6 bracketing behavior in both the utility and Ratis helper paths.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/HddsUtils.java	Adds a shared helper to format host:port with correct IPv6 bracketing semantics.
hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/ratis/RatisHelper.java	Routes datanode Ratis peer address formatting through the new helper to support IPv6 literals.
hadoop-hdds/common/src/main/java/org/apache/hadoop/hdds/NodeDetails.java	Updates HA Ratis peer address formatting to use the new helper (avoids raw concatenation).
hadoop-hdds/common/src/test/java/org/apache/hadoop/hdds/TestHddsUtils.java	Adds focused unit coverage for getHostPortString across hostname/IPv4/IPv6 (bare and bracketed).
hadoop-hdds/common/src/test/java/org/apache/hadoop/hdds/ratis/TestRatisHelper.java	Adds a unit test validating IPv6 bracketing in RatisHelper.toRaftPeer(...) addresses.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adoroszlai]

Thanks @smengcl for the patch.

[adoroszlai]

Thanks @smengcl for updating the patch.

(Please update your fork, either "Sync fork" via GitHub UI, or push master manually. This will trigger populate-cache, which should help with frequent rocksdb source downloaderrors. The tarball is normally stored in Maven cache.)

[smengcl]

Thanks @adoroszlai for reviewing and merging this!

(Please update your fork, either "Sync fork" via GitHub UI, or push master manually. This will trigger populate-cache, which should help with frequent rocksdb source downloaderrors. The tarball is normally stored in Maven cache.)

Thanks for the tip! Just did.