v1.17.0

ADDED: * netx: ** docs updated ** added NOTES.adoc for more extensive info that doesn't need to be in the library docs ** Addr4in6Compat() ** Addr4in6Mapped() ** Addr4in6Mapped() ** HasSubnet() ** IP4MapPfx4to6() ** IP4MapPfx6to4() ** IPSetCombined() ** IPSetFrom() ** IPSetFromNative() ** IsAddr4Compat() ** IsPublic() ** MustIPSetCombined() ** MustIPSetFrom() ** MustIPSetFromNative() ** Pfx4in6Compat() (untested) ** Pfx4in6Mapped() (untested) ** UnmapAddr() ** UnmapPfx() ** Better support in other functions for IPv4-Compatible/IPv4-Mapped addressing
2026-07-29 15:05:36 -04:00
parent 5108b09df5
commit cbfaaddf34
13 changed files with 1068 additions and 149 deletions
@@ -1,4 +1,128 @@
 /*
 Package netx includes extensions to the stdlib [net] module.
+
+It provides many functions that should be significantly more helpful for those working with networking a significant amount.
+
+Some functions may be "missing". This is by design; the corresponding functionality should be available in stdlib.
+
+For example, while there is an [IsAddr4Compat] function, there is no "IsAddr4Mapped". This is because this can be accomplished via the following:
+
+	var ip netip.Addr
+
+	// ...
+
+	ip.Is4In6()
+
+	// ...
+
+If you are looking for specific functionality in this library but are unable to find it,
+this is because the functionality already exists in (in the author's opinion) a reasonably convenient
+methodology via one of the following:
+
+  - [net]
+  - [net/netip]
+  - [go4.org/netipx]
+
+# IP Family/Versioning
+
+There are different ways of expressing an IP address/network's version (e.g. IPv4, IPv6).
+
+Some libraries expect an integer representation (e.g. 4, 6).
+
+Some libraries expect a system/OS-constant instead (e.g. unix.AF_INET, unix.AF_INET6, windows.AF_INET, windows.AF_INET6).
+
+The following functions are offered to assist with this translation:
+
+  - [FamilyToVer]
+  - [GetAddrFamily]
+  - [GetIpFamily]
+  - [IpVerStr]
+  - [VerToFamily]
+
+The following constants are offered to make cross-platform development more fluid (these are set according to the build target):
+
+  - [AFUnspec]
+  - [AFInet]
+  - [AFInet6]
+
+# IP Sets
+
+This library provides convenience functions for getting a [netipx.IPSet] in single-entry functions:
+
+  - [IPSetCombined]
+  - [IPSetFrom]
+  - [IPSetFromNative]
+  - [MustIPSetCombined]
+  - [MustIPSetFrom]
+  - [MustIPSetFromNative]
+
+# Canonical String Representation
+
+Go's stdlib [net] and [net/netip] don't always properly display or handle the proper string formatting per RFC conventions.
+
+The following functions assist with this:
+
+  - [AddrRfc]
+  - [IpRfc]
+  - [IpRfcStr]
+  - [IpStripRfcStr]
+  - [IsBracketedIp6]
+  - [IsPrefixNet]
+
+# Netmask and CIDR Conversions
+
+An IPv4 network size can be represented by both a netmask (e.g. "255.255.255.0") or a CIDR prefix length (e.g. "/24"),
+as well as a numeric bitmask form (which is different from the prefix length).
+
+This module offers functions that assist with easy translation between these formats:
+
+  - [Cidr4ToIPMask]
+  - [Cidr4ToMask]
+  - [Cidr4ToStr]
+  - [IPMask4ToCidr]
+  - [IPMask4ToMask]
+  - [IPMask4ToStr]
+  - [Mask4StrToCidr]
+  - [Mask4StrToIPMask]
+  - [Mask4StrToMask]
+  - [Mask4ToCidr]
+  - [Mask4ToIPMask]
+  - [Mask4ToStr]
+
+# IPv4 Addresses as IPv6
+
+There are two canonical ways of representing an IPv4 address as an IPv6 address, per RFC 4291 ([section 2.5.5]):
+
+  - "IPv4-Compatible IPv6 Addresses" (RFC [4291 § 2.5.5.1]) — ::/96
+  - "IPv4-Mapped IPv6 Addresses" (RFC [4291 § 2.5.5.2]) — ::ffff:0:0/96
+
+The former (::/96) is considered deprecated, and there is only parsing support for it in Go stdlib.
+
+There are a number of functions tailored for use with both of these formats in this module:
+
+  - [Addr4in6Compat]
+  - [Addr4in6Mapped]
+  - [IP4MapPfx4to6]
+  - [IP4MapPfx6to4]
+  - [IsAddr4Compat]
+  - [Pfx4in6Compat]
+  - [Pfx4in6Mapped]
+  - [UnmapAddr]
+  - [UnmapPfx]
+
+For more technical/detailed information, refer to the ./NOTES.adoc file in this module's
+git repository, specifically the "IPv4 Addresses as IPv6" section.
+
+# Miscellaneous Functions
+
+Other functions that may be of use:
+
+  - [IsPublic] — Note that this does not guarantee that it is a *valid* public IP address (especially in the case of IPv6),
+    simply that it isn't in a non-WAN-routable prefix reserved by current standards.
+  - [HasSubnet]
+
+[section 2.5.5]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5
+[4291 § 2.5.5.1]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.1
+[4291 § 2.5.5.2]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2
 */
 package netx