Sockets: fix getipaddr/getipaddrs documentation, add islinklocaladdr function (#34300)

* fix getipaddr/getipaddrs documentation

- resolved IPv4/IPv6 confusion, e.g. getipaddrs() does _not_ return only IPv4

- more realistic example addresses

- example addresses taken from address ranges reserved for documentation
  https://en.wikipedia.org/wiki/Reserved_IP_addresses

* add Sockets.islinklocaladdr

IPv6 interfaces always have a link-local address configured, which is
also reported by getipaddrs(). However, typical application servers
are not reachable under their link-local address, therefore this
convenience function helps users of getipaddrs() to filter
out such addresses with `filter(!islinklocaladdr, getipaddrs())`.

This commits also adds a "See also" hint that in applications where
a server process has been started remotely via ssh that
`split(ENV["SSH_CONNECTION"], ' ')[3]` can be a preferable
alternative source for the IP address under which this server
is reachable (namely the address that ssh has already used
successfully to get here).

Author: mgkuhn

stdlib/Sockets/docs/src/index.md

@@ -9,6 +9,7 @@ Sockets.listen(::AbstractString)
 Sockets.getaddrinfo
 Sockets.getipaddr
 Sockets.getipaddrs
+Sockets.islinklocaladdr
 Sockets.getalladdrinfo
 Sockets.DNSError
 Sockets.getnameinfo

stdlib/Sockets/src/IPAddr.jl

@@ -238,7 +238,7 @@ function parse(::Type{IPv6}, str::AbstractString)
 end
 
 #
-# This support IPv4 addresses in the common dot (IPv4) or colon (IPv6)
+# This supports IP addresses in the common dot (IPv4) or colon (IPv6)
 # separated formats. Most other common formats use a standard integer encoding
 # of the appropriate size and should use the appropriate constructor
 #

stdlib/Sockets/src/Sockets.jl

@@ -14,6 +14,7 @@ export
     getnameinfo,
     getipaddr,
     getipaddrs,
+    islinklocaladdr,
     getpeername,
     getsockname,
     listen,

stdlib/Sockets/src/addrinfo.jl

@@ -241,6 +241,9 @@ addresses are available.
 Get an IP address of the local machine of the specified type. Throws if no
 addresses of the specified type are available.
 
+This function is a backwards-compatibility wrapper around [`getipaddrs`](@ref).
+New applications should use [`getipaddrs`](@ref) instead.
+
 # Examples
 ```julia-repl
 julia> getipaddr()
@@ -249,6 +252,8 @@ ip"192.168.1.28"
 julia> getipaddr(IPv6)
 ip"fe80::9731:35af:e1c5:6e49"
 ```
+
+See also: [`getipaddrs`](@ref)
 """
 function getipaddr(addr_type::Type{T}) where T<:IPAddr
     addrs = getipaddrs(addr_type)
@@ -265,31 +270,35 @@ getipaddr() = getipaddr(IPv4)
 
 
 """
-    getipaddrs(; loopback::Bool=false) -> Vector{IPAddr}
+    getipaddrs(addr_type::Type{T}=IPAddr; loopback::Bool=false) where T<:IPAddr -> Vector{T}
 
-Get the IPv4 addresses of the local machine.
+Get the IP addresses of the local machine.
 
-    getipaddrs(addr_type::Type{T}; loopback::Bool=false) where T<:IPAddr -> Vector{T}
+Setting the optional `addr_type` parameter to `IPv4` or `IPv6` causes only addresses of that type to be returned.
 
-Get the IP addresses of the local machine of the specified type.
-
-The `loopback` keyword argument dictates whether loopback addresses are included.
+The `loopback` keyword argument dictates whether loopback addresses (e.g. `ip"127.0.0.1"`, `ip"::1"`) are included.
 
 !!! compat "Julia 1.2"
     This function is available as of Julia 1.2.
 
 # Examples
 ```julia-repl
 julia> getipaddrs()
-2-element Array{IPv4,1}:
- ip"10.255.0.183"
- ip"172.17.0.1"
+5-element Array{IPAddr,1}:
+ ip"198.51.100.17"
+ ip"203.0.113.2"
+ ip"2001:db8:8:4:445e:5fff:fe5d:5500"
+ ip"2001:db8:8:4:c164:402e:7e3c:3668"
+ ip"fe80::445e:5fff:fe5d:5500"
 
 julia> getipaddrs(IPv6)
-2-element Array{IPv6,1}:
- ip"fe80::9731:35af:e1c5:6e49"
+3-element Array{IPv6,1}:
+ ip"2001:db8:8:4:445e:5fff:fe5d:5500"
+ ip"2001:db8:8:4:c164:402e:7e3c:3668"
  ip"fe80::445e:5fff:fe5d:5500"
 ```
+
+See also: [`islinklocaladdr`](@ref), `split(ENV["SSH_CONNECTION"], ' ')[3]`
 """
 function getipaddrs(addr_type::Type{T}=IPAddr; loopback::Bool=false) where T<:IPAddr
     addresses = T[]
@@ -319,3 +328,29 @@ function getipaddrs(addr_type::Type{T}=IPAddr; loopback::Bool=false) where T<:IP
     ccall(:uv_free_interface_addresses, Cvoid, (Ptr{UInt8}, Int32), addr, count)
     return addresses
 end
+
+"""
+    islinklocaladdr(addr::IPAddr)
+
+Tests if an IP address is a link-local address. Link-local addresses
+are not guaranteed to be unique beyond their network segment,
+therefore routers do not forward them. Link-local addresses are from
+the address blocks `169.254.0.0/16` or `fe80::/10`.
+
+# Example
+```julia
+filter(!islinklocaladdr, getipaddrs())
+```
+"""
+function islinklocaladdr(addr::IPv4)
+    # RFC 3927
+    return (addr.host &
+            0xFFFF0000) ==
+            0xA9FE0000
+end
+function islinklocaladdr(addr::IPv6)
+    # RFC 4291
+    return (addr.host &
+            0xFFC00000000000000000000000000000) ==
+            0xFE800000000000000000000000000000
+end

stdlib/Sockets/test/runtests.jl

@@ -507,6 +507,16 @@ end
     end
 end
 
+@testset "address scope" begin
+    @test islinklocaladdr(ip"169.254.1.0")
+    @test islinklocaladdr(ip"169.254.254.255")
+    @test islinklocaladdr(ip"fe80::")
+    @test islinklocaladdr(ip"febf::")
+    @test !islinklocaladdr(ip"127.0.0.1")
+    @test !islinklocaladdr(ip"2001::")
+
+end
+
 @static if !Sys.iswindows()
     # Issue #29234
     @testset "TCPSocket stdin" begin