checking in some WIP

* added some netx funcs
* added netx/dnsx
* currently updating docs and adding *x funcs to sprigx

netx/funcs.go

@@ -102,11 +102,37 @@ func Cidr4ToStr(cidr uint8) (maskStr string, err error) {
 	return
 }
 
+/*
+FamilyToVer returns a more "human-friendly" IP version from a system/lower-level IP family
+([AFUnspec], [AFInet], [AFInet6]).
+
+ipVer will be int(4) for [AFInet], int(6) for [AFInet6], int(0) for [AFUnspec], or
+int(-1) for an unknown family.
+*/
+func FamilyToVer(family uint16) (ipVer int) {
+
+	switch family {
+	case AFInet:
+		ipVer = 4
+	case AFInet6:
+		ipVer = 6
+	case AFUnspec:
+		ipVer = 0
+	default:
+		ipVer = -1
+	}
+
+	return
+}
+
 /*
 GetAddrFamily returns the network family of a [net/netip.Addr].
 
 See also [GetIpFamily].
 
+Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
+(See [FamilyToVer] to get the associated higher-level value.)
+
 If addr is not a "valid" IP address or the version can't be determined, family will be AFUnspec (usually 0x00/0).
 */
 func GetAddrFamily(addr netip.Addr) (family uint16) {
@@ -131,6 +157,9 @@ func GetAddrFamily(addr netip.Addr) (family uint16) {
 /*
 GetIpFamily returns the network family of a [net.IP].
 
+Note that this returns [AFInet] or [AFInet6], NOT uint16(4) or uint16(6).
+(See [FamilyToVer] to get the associated higher-level value.)
+
 See also [GetAddrFamily].
 
 If ip is not a "valid" IP address or the version can't be determined,
@@ -158,6 +187,8 @@ If ip is an IPv4 address, it will simmply be the string representation (e.g. "20
 If ip is an IPv6 address, it will be enclosed in brackets (e.g. "[2001:db8::1]").
 
 If the version can't be determined, rfcStr will be an empty string.
+
+See also [IpRfcStr] for providing an IP address as a string.
 */
 func IpRfc(ip net.IP) (rfcStr string) {
 
@@ -170,6 +201,56 @@ func IpRfc(ip net.IP) (rfcStr string) {
 	return
 }
 
+/*
+IpRfcStr implements [IpRfc]/[AddrRfc] for string representations of an IP address s.
+
+If s is an IPv6 address already in the bracketed RFC format,
+then rfcStr will be equal to s.
+
+If s is not a string representation of an IP address, rfcStr will be empty.
+
+See [IpStripRfcStr] for the inverse (removing any brackets from s if present).
+*/
+func IpRfcStr(s string) (rfcStr string) {
+
+	var ip net.IP
+
+	if !IsIpAddr(s) {
+		return
+	}
+	if IsBracketedIp6(s) {
+		rfcStr = s
+		return
+	}
+	ip = net.ParseIP(s)
+	if ip == nil {
+		return
+	}
+	rfcStr = IpRfc(ip)
+
+	return
+}
+
+/*
+IpStripRfcStr returns IP address string s without any brackets.
+
+If s is not a valid IP address, stripStr will be empty.
+*/
+func IpStripRfcStr(s string) (stripStr string) {
+
+	if !IsIpAddr(s) {
+		return
+	}
+	if !IsBracketedIp6(s) {
+		stripStr = s
+		return
+	}
+	stripStr = strings.TrimPrefix(s, "[")
+	stripStr = strings.TrimSuffix(stripStr, "]")
+
+	return
+}
+
 /*
 IPMask4ToCidr returns a CIDR prefix size/bit size/bit length from a [net.IPMask].
 
@@ -257,6 +338,123 @@ func IPMask4ToStr(ipMask net.IPMask) (maskStr string, err error) {
 	return
 }
 
+/*
+IpVerStr provides the IP family of IP address/network string s.
+
+s may be one of the following formats/syntaxes:
+
+	* 203.0.113.0
+	* 203.0.113.1
+	* 203.0.113.0/24
+	* 203.0.113.1/24
+	* 2001:db8::
+	* 2001:db8::1
+	* 2001:db8::/32
+	* 2001:db8::1/32
+	* [2001:db8::]
+	* [2001:db8::1]
+
+
+Unlike [GetAddrFamily]/[GetIpFamily], this returns a more "friendly"
+version - if s is not valid syntax, ipVer will be int(0),
+otherwise ipVer will be int(4) for family IPv4 and int(6) for family IPv6.
+(See [VerToFamily] to get the associated system/lower-level value.)
+*/
+func IpVerStr(s string) (ipVer int) {
+
+	var err error
+	var ipstr string
+	var p netip.Prefix
+
+	ipstr = strings.TrimPrefix(s, "[")
+	ipstr = strings.TrimSuffix(ipstr, "]")
+
+	if p, err = netip.ParsePrefix(ipstr); err != nil {
+		return
+	}
+	if p.Addr().Is6() {
+		ipVer = 6
+	} else {
+		ipVer = 4
+	}
+
+	return
+}
+
+/*
+IsBracketedIp6 returns a boolean indicating if s is a valid bracket-enclosed IPv6 in string format
+(e.g. "[2001:db8::1]").
+
+It will return false for *non-bracketed* IPv6 addresses (e.g. "2001:db8::1"), IPv4 addresses,
+or if s is not a valid IPv6 address string.
+
+[IpRfcStr] or [IpStripRfcStr] can be used to coerce a string to a specific format.
+*/
+func IsBracketedIp6(s string) (isBrktdIp bool) {
+
+	var ip net.IP
+	var ipstr string
+
+	if IpVerStr(s) != 6 {
+		return
+	}
+
+	ipstr = strings.TrimPrefix(s, "[")
+	ipstr = strings.TrimSuffix(ipstr, "]")
+
+	if ip = net.ParseIP(ipstr); ip == nil {
+		return
+	}
+
+	isBrktdIp = ipstr == s
+
+	return
+}
+
+/*
+IsIpAddr returns a boolean indicating if s is an IP address (either IPv4 or IPv6) in string format.
+
+For IPv6, it will return true for both of these formats:
+
+	* 2001:db8::1
+	* [2001:db8::1]
+
+[IsBracketedIp6] can be used to narrow down which form.
+*/
+func IsIpAddr(s string) (isIp bool) {
+
+	var err error
+	var a netip.Addr
+
+	if a, err = netip.ParseAddr(s); err != nil {
+		return
+	}
+
+	isIp = a.IsValid()
+
+	return
+}
+
+/*
+IsPrefixNet returns true if s is a (valid) IP address or network (either IPv4 or IPv6) in:
+
+	<addr_or_net>/<prefix_len>
+
+format.
+*/
+func IsPrefixNet(s string) (isNet bool) {
+
+	var err error
+	var p netip.Prefix
+
+	if p, err = netip.ParsePrefix(s); err != nil {
+		return
+	}
+	isNet = p.Masked().IsValid()
+
+	return
+}
+
 /*
 Mask4ToCidr converts an IPv4 netmask *in bitmask form* to a CIDR prefix size/bit size/bit length.
 
@@ -408,3 +606,25 @@ func Mask4StrToMask(maskStr string) (mask uint32, err error) {
 
 	return
 }
+
+/*
+VerToFamily takes a "human-readable" IP version ipVer (4 or 6) and returns
+a system-level constant (e.g. [AFUnspec], [AFInet], [AFInet6]).
+
+If not a known IP version (i.e. neither 4 nor 6), family will be [AFUnspec].
+
+It is the inverse of [FamilyToVer].
+*/
+func VerToFamily(ipVer int) (family uint16) {
+
+	switch ipVer {
+	case 4:
+		family = AFInet
+	case 6:
+		family = AFInet6
+	default:
+		family = AFUnspec
+	}
+
+	return
+}