Skip to content

Commit

Permalink
Document that isInetAddress and forString perform slightly differ…
Browse files Browse the repository at this point in the history 
…ent validation.

...and blame it on Java :)

We'd gotten this right for the lesser-used `isUriInetAddress` and `forUriString` but not for these more commonly used methods.

See #2587 (comment)

RELNOTES=n/a
PiperOrigin-RevId: 696253161
  • Loading branch information
@cpovirk
cpovirk authored and Google Java Core Libraries committed Nov 13, 2024
1 parent c309175 commit f7bb711
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 12 deletions.
20 changes: 14 additions & 6 deletions android/guava/src/com/google/common/net/InetAddresses.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@ private static Inet4Address getInet4Address(byte[] bytes) {
* @param ipString {@code String} containing an IPv4 or IPv6 string literal, e.g. {@code
* "192.168.0.1"} or {@code "2001:db8::1"} or with a scope ID, e.g. {@code "2001:db8::1%eth0"}
* @return {@link InetAddress} representing the argument
* @throws IllegalArgumentException if the argument is not a valid IP string literal
* @throws IllegalArgumentException if the argument is not a valid IP string literal or if the
* address has a scope ID that fails validation against the interfaces on the machine (as
* required by Java's {@link InetAddress})
*/
@CanIgnoreReturnValue // TODO(b/219820829): consider removing
public static InetAddress forString(String ipString) {
Expand All @@ -175,6 +177,10 @@ public static InetAddress forString(String ipString) {
* want to accept ASCII digits only, you can use something like {@code
* CharMatcher.ascii().matchesAllOf(ipString)}.
*
* <p>Note that if this method returns {@code true}, a call to {@link #forString(String)} can
* still throw if the address has a scope ID that fails validation against the interfaces on the
* machine.
*
* @param ipString {@code String} to evaluated as an IP string literal
* @return {@code true} if the argument is a valid IP string literal
*/
Expand Down Expand Up @@ -481,8 +487,8 @@ public static String toAddrString(InetAddress ip) {
}

private static String scopeWithDelimiter(Inet6Address ip) {
// getHostAddress on android sometimes maps the scope id to an invalid interface name; if the
// mapped interface isn't present, fallback to use the scope id (which has no validation against
// getHostAddress on android sometimes maps the scope ID to an invalid interface name; if the
// mapped interface isn't present, fallback to use the scope ID (which has no validation against
// present interfaces)
NetworkInterface scopedInterface = ip.getScopedInterface();
if (scopedInterface != null) {
Expand Down Expand Up @@ -601,8 +607,9 @@ public static String toUriString(InetAddress ip) {
* @param hostAddr an RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address
* @return an InetAddress representing the address in {@code hostAddr}
* @throws IllegalArgumentException if {@code hostAddr} is not a valid IPv4 address, or IPv6
* address surrounded by square brackets, or if the address has a scope id that fails
* validation against interfaces on the machine
* address surrounded by square brackets, or if the address has a scope ID that fails
* validation against the interfaces on the machine (as required by Java's {@link
* InetAddress})
*/
public static InetAddress forUriString(String hostAddr) {
InetAddress addr = forUriStringOrNull(hostAddr, /* parseScope= */ true);
Expand Down Expand Up @@ -648,7 +655,8 @@ private static InetAddress forUriStringOrNull(String hostAddr, boolean parseScop
* CharMatcher.ascii().matchesAllOf(ipString)}.
*
* <p>Note that if this method returns {@code true}, a call to {@link #forUriString(String)} can
* throw if the address has a scope id fails validation against interfaces on the machine.
* still throw if the address has a scope ID that fails validation against the interfaces on the
* machine.
*
* @param ipString {@code String} to evaluated as an IP URI host string literal
* @return {@code true} if the argument is a valid IP URI host
Expand Down
20 changes: 14 additions & 6 deletions guava/src/com/google/common/net/InetAddresses.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@ private static Inet4Address getInet4Address(byte[] bytes) {
* @param ipString {@code String} containing an IPv4 or IPv6 string literal, e.g. {@code
* "192.168.0.1"} or {@code "2001:db8::1"} or with a scope ID, e.g. {@code "2001:db8::1%eth0"}
* @return {@link InetAddress} representing the argument
* @throws IllegalArgumentException if the argument is not a valid IP string literal
* @throws IllegalArgumentException if the argument is not a valid IP string literal or if the
* address has a scope ID that fails validation against the interfaces on the machine (as
* required by Java's {@link InetAddress})
*/
@CanIgnoreReturnValue // TODO(b/219820829): consider removing
public static InetAddress forString(String ipString) {
Expand All @@ -175,6 +177,10 @@ public static InetAddress forString(String ipString) {
* want to accept ASCII digits only, you can use something like {@code
* CharMatcher.ascii().matchesAllOf(ipString)}.
*
* <p>Note that if this method returns {@code true}, a call to {@link #forString(String)} can
* still throw if the address has a scope ID that fails validation against the interfaces on the
* machine.
*
* @param ipString {@code String} to evaluated as an IP string literal
* @return {@code true} if the argument is a valid IP string literal
*/
Expand Down Expand Up @@ -481,8 +487,8 @@ public static String toAddrString(InetAddress ip) {
}

private static String scopeWithDelimiter(Inet6Address ip) {
// getHostAddress on android sometimes maps the scope id to an invalid interface name; if the
// mapped interface isn't present, fallback to use the scope id (which has no validation against
// getHostAddress on android sometimes maps the scope ID to an invalid interface name; if the
// mapped interface isn't present, fallback to use the scope ID (which has no validation against
// present interfaces)
NetworkInterface scopedInterface = ip.getScopedInterface();
if (scopedInterface != null) {
Expand Down Expand Up @@ -601,8 +607,9 @@ public static String toUriString(InetAddress ip) {
* @param hostAddr an RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address
* @return an InetAddress representing the address in {@code hostAddr}
* @throws IllegalArgumentException if {@code hostAddr} is not a valid IPv4 address, or IPv6
* address surrounded by square brackets, or if the address has a scope id that fails
* validation against interfaces on the machine
* address surrounded by square brackets, or if the address has a scope ID that fails
* validation against the interfaces on the machine (as required by Java's {@link
* InetAddress})
*/
public static InetAddress forUriString(String hostAddr) {
InetAddress addr = forUriStringOrNull(hostAddr, /* parseScope= */ true);
Expand Down Expand Up @@ -648,7 +655,8 @@ private static InetAddress forUriStringOrNull(String hostAddr, boolean parseScop
* CharMatcher.ascii().matchesAllOf(ipString)}.
*
* <p>Note that if this method returns {@code true}, a call to {@link #forUriString(String)} can
* throw if the address has a scope id fails validation against interfaces on the machine.
* still throw if the address has a scope ID that fails validation against the interfaces on the
* machine.
*
* @param ipString {@code String} to evaluated as an IP URI host string literal
* @return {@code true} if the argument is a valid IP URI host
Expand Down

0 comments on commit f7bb711

Please sign in to comment.