Documentation
¶
Overview ¶
Package ipnet contains utility functions for IPv4 and IPv6 families.
Index ¶
- Variables
- func All(yield func(Family) bool)
- func Bindings[V any](m map[Family]V) iter.Seq2[Family, V]
- func DescribeBadAddress(ip netip.Addr) (string, bool)
- func Emit4in6Hint(ppfmt pp.PP, wants4in6Hint bool)
- func IsCloudflareIP(ip netip.Addr) bool
- func ParseAddrOrPrefix(ppfmt pp.PP, s string) (netip.Prefix, bool)
- func ValidateAndNormalizeIP(ipFamily Family, ip netip.Addr) (normalized netip.Addr, unmapped bool, issue string, wants4in6Hint bool, ...)
- type CloudflareIPRejecter
- type Family
- func (t Family) Describe() string
- func (t Family) Int() int
- func (t Family) Matches(ip netip.Addr) bool
- func (t Family) NormalizeDetectedIPs(ppfmt pp.PP, ips []netip.Addr) ([]netip.Addr, bool)
- func (t Family) NormalizeDetectedRawEntries(ppfmt pp.PP, entries []RawEntry) ([]RawEntry, bool)
- func (t Family) RecordType() string
- func (t Family) UDPNetwork() string
- type RawEntry
- func LiftValidatedIPsToRawEntries(ips []netip.Addr, prefixLen int) []RawEntry
- func NormalizeRawEntryIP(family Family, entry RawEntry) (normalized RawEntry, problem string, wants4in6Hint bool, ok bool)
- func ParseRawEntry(s string, defaultPrefixLen int) (RawEntry, error)
- func RawEntryFrom(addr netip.Addr, prefixLen int) RawEntry
- func (r RawEntry) Addr() netip.Addr
- func (r RawEntry) Compare(other RawEntry) int
- func (r RawEntry) Describe(defaultPrefixLen int) string
- func (r RawEntry) IsValid() bool
- func (r RawEntry) Masked() netip.Prefix
- func (r RawEntry) Prefix() netip.Prefix
- func (r RawEntry) PrefixLen() int
- func (r RawEntry) String() string
- type RawIPRejecter
Constants ¶
This section is empty.
Variables ¶
var ErrRawEntryParse = errors.New("failed to parse as an IP address or an IP address in CIDR notation")
ErrRawEntryParse indicates that a string could not be parsed as an IP address or an IP address in CIDR notation.
Functions ¶
func DescribeBadAddress ¶ added in v1.16.0
DescribeBadAddress reports whether the address is unsuitable as a DNS/WAF target. If unsuitable, it returns a predicate phrase suitable for "(subject) %s" (e.g., "is a loopback address") and true. The caller is responsible for formatting the full message with context.
func Emit4in6Hint ¶ added in v1.16.0
Emit4in6Hint emits the standard IPv4-mapped IPv6 hint message when wants4in6Hint is true. Safe to call unconditionally; it is a no-op otherwise.
func IsCloudflareIP ¶ added in v1.16.0
IsCloudflareIP reports whether ip falls inside any of Cloudflare's published IP ranges. A detected IP inside these ranges is a Cloudflare egress IP, not a publishable client/public IP for DDNS.
func ParseAddrOrPrefix ¶ added in v1.16.0
ParseAddrOrPrefix parses a network prefix or a bare IP address. This is used for parsing Cloudflare WAF list items, not raw detection data.
func ValidateAndNormalizeIP ¶ added in v1.16.0
func ValidateAndNormalizeIP(ipFamily Family, ip netip.Addr) ( normalized netip.Addr, unmapped bool, issue string, wants4in6Hint bool, ok bool, )
ValidateAndNormalizeIP validates ip for ipFamily.
- On success, it returns the canonical normalized address, whether normalization unmapped an IPv4-mapped IPv6 address (unmapped), and ok=true.
- On failure, it returns an issue phrase suitable for "(subject) %s" (for example, "is a loopback address") and ok=false. When wants4in6Hint is true, callers should also show pp.MessageIP4MappedIP6Address.
The function does not emit messages; callers report errors in their own context.
Types ¶
type CloudflareIPRejecter ¶ added in v1.16.0
type CloudflareIPRejecter struct{}
CloudflareIPRejecter rejects IPs that fall inside Cloudflare's published IP ranges. Such IPs are Cloudflare egress/proxy IPs, not publishable client IPs for DDNS.
func (CloudflareIPRejecter) RejectRawIP ¶ added in v1.16.0
func (CloudflareIPRejecter) RejectRawIP(ip netip.Addr) (bool, string)
RejectRawIP rejects IPs inside Cloudflare's published ranges.
type Family ¶ added in v1.16.0
type Family int
Family identifies an IP family.
func (Family) Describe ¶ added in v1.16.0
Describe returns a human-readable description of the IP family.
func (Family) NormalizeDetectedIPs ¶ added in v1.16.0
NormalizeDetectedIPs normalizes a list of detected IPs.
Behavior: - fail-fast: return false on the first invalid IP - preserve emptiness: empty input returns empty output - canonicalize set semantics: output is sorted and deduplicated.
func (Family) NormalizeDetectedRawEntries ¶ added in v1.16.0
NormalizeDetectedRawEntries normalizes a list of detected raw-data IP addresses with prefix lengths while preserving host bits in the address portion.
Behavior:
- fail-fast: return false on the first invalid entry
- preserve emptiness: empty input returns empty output
- canonicalize set semantics: output is sorted and deduplicated.
func (Family) RecordType ¶ added in v1.16.0
RecordType prints out the DNS record type for the IP family. For IPv4, it is A; for IPv6, it is AAAA.
func (Family) UDPNetwork ¶ added in v1.16.0
UDPNetwork returns the net.Dial network name for this IP family.
type RawEntry ¶ added in v1.16.0
RawEntry carries one detected IP address together with its prefix length.
Unlike netip.Prefix, the full address is significant: host bits are preserved and used downstream (e.g., DNS derivation extracts the address; WAF derivation explicitly masks via RawEntry.Masked). The prefix length rides alongside the address but does not imply that host bits are irrelevant.
Construction: use RawEntryFrom or LiftValidatedIPsToRawEntries.
func LiftValidatedIPsToRawEntries ¶ added in v1.16.0
LiftValidatedIPsToRawEntries preserves the observed address bits and applies the given prefix length to each already-validated address.
func NormalizeRawEntryIP ¶ added in v1.16.0
func NormalizeRawEntryIP(family Family, entry RawEntry) ( normalized RawEntry, problem string, wants4in6Hint bool, ok bool, )
NormalizeRawEntryIP adjusts the prefix length for IPv4-mapped IPv6 addresses and validates the IP for the given family. No messages are emitted; callers use the returned problem description and wants4in6Hint for their own diagnostics.
On success problem is empty. On failure problem is a predicate phrase suitable for "(subject) %s" (e.g., "is not a valid IPv4 address").
The prefix-length adjustment follows RFC 6887 PCP FILTER semantics: when an IPv4 prefix is encoded in the ::ffff:0:0/96 mapped form, the encoded prefix length is the IPv4 prefix length plus the fixed 96-bit mapping prefix.
func ParseRawEntry ¶ added in v1.16.0
ParseRawEntry parses s as a CIDR prefix or a bare IP address. Bare IPs receive defaultPrefixLen. CIDR notation preserves the stated prefix length and the full address (host bits included).
Zoned addresses (e.g. "fe80::1%eth0") are rejected because netip.PrefixFrom silently strips zones, which would lose information.
func RawEntryFrom ¶ added in v1.16.0
RawEntryFrom constructs a RawEntry from an address and prefix length.
func (RawEntry) Compare ¶ added in v1.16.0
Compare returns an integer comparing two raw entries. The result is suitable for use with slices.SortFunc.
func (RawEntry) Describe ¶ added in v1.16.0
Describe returns a human-readable representation of the raw entry. The CIDR suffix is omitted only when the entry is a single host (prefix length == address bit length) AND that full-host length is also the effective default. This keeps output familiar: users whose effective default is /32 see bare "1.2.3.4", while users whose effective default is /24 always see the explicit "/24" or "/32" suffix so the distinction is never ambiguous.
func (RawEntry) IsValid ¶ added in v1.16.0
IsValid reports whether the entry was constructed from valid inputs.
func (RawEntry) Masked ¶ added in v1.16.0
Masked returns the network prefix with host bits zeroed. This is the explicit derivation step from raw entry to network prefix.
func (RawEntry) Prefix ¶ added in v1.16.0
Prefix converts back to netip.Prefix for stdlib or external API interop.
Source Files