brent saner
cbfaaddf34
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
129 lines
3.8 KiB
Go
129 lines
3.8 KiB
Go
/*
|
|
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
|