Source file src/net/netip/netip.go

     1  // Copyright 2020 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package netip defines an IP address type that's a small value type.
     6  // Building on that [Addr] type, the package also defines [AddrPort] (an
     7  // IP address and a port) and [Prefix] (an IP address and a bit length
     8  // prefix).
     9  //
    10  // Compared to the [net.IP] type, [Addr] type takes less memory, is immutable,
    11  // and is comparable (supports == and being a map key).
    12  package netip
    13  
    14  import (
    15  	"cmp"
    16  	"errors"
    17  	"internal/bytealg"
    18  	"internal/byteorder"
    19  	"math"
    20  	"strconv"
    21  	"unique"
    22  )
    23  
    24  // Sizes: (64-bit)
    25  //   net.IP:     24 byte slice header + {4, 16} = 28 to 40 bytes
    26  //   net.IPAddr: 40 byte slice header + {4, 16} = 44 to 56 bytes + zone length
    27  //   netip.Addr: 24 bytes (zone is per-name singleton, shared across all users)
    28  
    29  // Addr represents an IPv4 or IPv6 address (with or without a scoped
    30  // addressing zone), similar to [net.IP] or [net.IPAddr].
    31  //
    32  // Unlike [net.IP] or [net.IPAddr], Addr is a comparable value
    33  // type (it supports == and can be a map key) and is immutable.
    34  //
    35  // The zero Addr is not a valid IP address.
    36  // Addr{} is distinct from both 0.0.0.0 and ::.
    37  type Addr struct {
    38  	// addr is the hi and lo bits of an IPv6 address. If z==z4,
    39  	// hi and lo contain the IPv4-mapped IPv6 address.
    40  	//
    41  	// hi and lo are constructed by interpreting a 16-byte IPv6
    42  	// address as a big-endian 128-bit number. The most significant
    43  	// bits of that number go into hi, the rest into lo.
    44  	//
    45  	// For example, 0011:2233:4455:6677:8899:aabb:ccdd:eeff is stored as:
    46  	//  addr.hi = 0x0011223344556677
    47  	//  addr.lo = 0x8899aabbccddeeff
    48  	//
    49  	// We store IPs like this, rather than as [16]byte, because it
    50  	// turns most operations on IPs into arithmetic and bit-twiddling
    51  	// operations on 64-bit registers, which is much faster than
    52  	// bytewise processing.
    53  	addr uint128
    54  
    55  	// Details about the address, wrapped up together and canonicalized.
    56  	z unique.Handle[addrDetail]
    57  }
    58  
    59  // addrDetail represents the details of an Addr, like address family and IPv6 zone.
    60  type addrDetail struct {
    61  	isV6   bool   // IPv4 is false, IPv6 is true.
    62  	zoneV6 string // != "" only if IsV6 is true.
    63  }
    64  
    65  // z0, z4, and z6noz are sentinel Addr.z values.
    66  // See the Addr type's field docs.
    67  var (
    68  	z0    unique.Handle[addrDetail]
    69  	z4    = unique.Make(addrDetail{})
    70  	z6noz = unique.Make(addrDetail{isV6: true})
    71  )
    72  
    73  // IPv6LinkLocalAllNodes returns the IPv6 link-local all nodes multicast
    74  // address ff02::1.
    75  func IPv6LinkLocalAllNodes() Addr { return AddrFrom16([16]byte{0: 0xff, 1: 0x02, 15: 0x01}) }
    76  
    77  // IPv6LinkLocalAllRouters returns the IPv6 link-local all routers multicast
    78  // address ff02::2.
    79  func IPv6LinkLocalAllRouters() Addr { return AddrFrom16([16]byte{0: 0xff, 1: 0x02, 15: 0x02}) }
    80  
    81  // IPv6Loopback returns the IPv6 loopback address ::1.
    82  func IPv6Loopback() Addr { return AddrFrom16([16]byte{15: 0x01}) }
    83  
    84  // IPv6Unspecified returns the IPv6 unspecified address "::".
    85  func IPv6Unspecified() Addr { return Addr{z: z6noz} }
    86  
    87  // IPv4Unspecified returns the IPv4 unspecified address "0.0.0.0".
    88  func IPv4Unspecified() Addr { return AddrFrom4([4]byte{}) }
    89  
    90  // AddrFrom4 returns the address of the IPv4 address given by the bytes in addr.
    91  func AddrFrom4(addr [4]byte) Addr {
    92  	return Addr{
    93  		addr: uint128{0, 0xffff00000000 | uint64(addr[0])<<24 | uint64(addr[1])<<16 | uint64(addr[2])<<8 | uint64(addr[3])},
    94  		z:    z4,
    95  	}
    96  }
    97  
    98  // AddrFrom16 returns the IPv6 address given by the bytes in addr.
    99  // An IPv4-mapped IPv6 address is left as an IPv6 address.
   100  // (Use Unmap to convert them if needed.)
   101  func AddrFrom16(addr [16]byte) Addr {
   102  	return Addr{
   103  		addr: uint128{
   104  			byteorder.BEUint64(addr[:8]),
   105  			byteorder.BEUint64(addr[8:]),
   106  		},
   107  		z: z6noz,
   108  	}
   109  }
   110  
   111  // ParseAddr parses s as an IP address, returning the result. The string
   112  // s can be in dotted decimal ("192.0.2.1"), IPv6 ("2001:db8::68"),
   113  // or IPv6 with a scoped addressing zone ("fe80::1cc0:3e8c:119f:c2e1%ens18").
   114  func ParseAddr(s string) (Addr, error) {
   115  	for i := 0; i < len(s); i++ {
   116  		switch s[i] {
   117  		case '.':
   118  			return parseIPv4(s)
   119  		case ':':
   120  			return parseIPv6(s)
   121  		case '%':
   122  			// Assume that this was trying to be an IPv6 address with
   123  			// a zone specifier, but the address is missing.
   124  			return Addr{}, parseAddrError{in: s, msg: "missing IPv6 address"}
   125  		}
   126  	}
   127  	return Addr{}, parseAddrError{in: s, msg: "unable to parse IP"}
   128  }
   129  
   130  // MustParseAddr calls [ParseAddr](s) and panics on error.
   131  // It is intended for use in tests with hard-coded strings.
   132  func MustParseAddr(s string) Addr {
   133  	ip, err := ParseAddr(s)
   134  	if err != nil {
   135  		panic(err)
   136  	}
   137  	return ip
   138  }
   139  
   140  type parseAddrError struct {
   141  	in  string // the string given to ParseAddr
   142  	msg string // an explanation of the parse failure
   143  	at  string // optionally, the unparsed portion of in at which the error occurred.
   144  }
   145  
   146  func (err parseAddrError) Error() string {
   147  	q := strconv.Quote
   148  	if err.at != "" {
   149  		return "ParseAddr(" + q(err.in) + "): " + err.msg + " (at " + q(err.at) + ")"
   150  	}
   151  	return "ParseAddr(" + q(err.in) + "): " + err.msg
   152  }
   153  
   154  func parseIPv4Fields(in string, off, end int, fields []uint8) error {
   155  	var val, pos int
   156  	var digLen int // number of digits in current octet
   157  	s := in[off:end]
   158  	for i := 0; i < len(s); i++ {
   159  		if s[i] >= '0' && s[i] <= '9' {
   160  			if digLen == 1 && val == 0 {
   161  				return parseAddrError{in: in, msg: "IPv4 field has octet with leading zero"}
   162  			}
   163  			val = val*10 + int(s[i]) - '0'
   164  			digLen++
   165  			if val > 255 {
   166  				return parseAddrError{in: in, msg: "IPv4 field has value >255"}
   167  			}
   168  		} else if s[i] == '.' {
   169  			// .1.2.3
   170  			// 1.2.3.
   171  			// 1..2.3
   172  			if i == 0 || i == len(s)-1 || s[i-1] == '.' {
   173  				return parseAddrError{in: in, msg: "IPv4 field must have at least one digit", at: s[i:]}
   174  			}
   175  			// 1.2.3.4.5
   176  			if pos == 3 {
   177  				return parseAddrError{in: in, msg: "IPv4 address too long"}
   178  			}
   179  			fields[pos] = uint8(val)
   180  			pos++
   181  			val = 0
   182  			digLen = 0
   183  		} else {
   184  			return parseAddrError{in: in, msg: "unexpected character", at: s[i:]}
   185  		}
   186  	}
   187  	if pos < 3 {
   188  		return parseAddrError{in: in, msg: "IPv4 address too short"}
   189  	}
   190  	fields[3] = uint8(val)
   191  	return nil
   192  }
   193  
   194  // parseIPv4 parses s as an IPv4 address (in form "192.168.0.1").
   195  func parseIPv4(s string) (ip Addr, err error) {
   196  	var fields [4]uint8
   197  	err = parseIPv4Fields(s, 0, len(s), fields[:])
   198  	if err != nil {
   199  		return Addr{}, err
   200  	}
   201  	return AddrFrom4(fields), nil
   202  }
   203  
   204  // parseIPv6 parses s as an IPv6 address (in form "2001:db8::68").
   205  func parseIPv6(in string) (Addr, error) {
   206  	s := in
   207  
   208  	// Split off the zone right from the start. Yes it's a second scan
   209  	// of the string, but trying to handle it inline makes a bunch of
   210  	// other inner loop conditionals more expensive, and it ends up
   211  	// being slower.
   212  	zone := ""
   213  	i := bytealg.IndexByteString(s, '%')
   214  	if i != -1 {
   215  		s, zone = s[:i], s[i+1:]
   216  		if zone == "" {
   217  			// Not allowed to have an empty zone if explicitly specified.
   218  			return Addr{}, parseAddrError{in: in, msg: "zone must be a non-empty string"}
   219  		}
   220  	}
   221  
   222  	var ip [16]byte
   223  	ellipsis := -1 // position of ellipsis in ip
   224  
   225  	// Might have leading ellipsis
   226  	if len(s) >= 2 && s[0] == ':' && s[1] == ':' {
   227  		ellipsis = 0
   228  		s = s[2:]
   229  		// Might be only ellipsis
   230  		if len(s) == 0 {
   231  			return IPv6Unspecified().WithZone(zone), nil
   232  		}
   233  	}
   234  
   235  	// Loop, parsing hex numbers followed by colon.
   236  	i = 0
   237  	for i < 16 {
   238  		// Hex number. Similar to parseIPv4, inlining the hex number
   239  		// parsing yields a significant performance increase.
   240  		off := 0
   241  		acc := uint32(0)
   242  		for ; off < len(s); off++ {
   243  			c := s[off]
   244  			if c >= '0' && c <= '9' {
   245  				acc = (acc << 4) + uint32(c-'0')
   246  			} else if c >= 'a' && c <= 'f' {
   247  				acc = (acc << 4) + uint32(c-'a'+10)
   248  			} else if c >= 'A' && c <= 'F' {
   249  				acc = (acc << 4) + uint32(c-'A'+10)
   250  			} else {
   251  				break
   252  			}
   253  			if off > 3 {
   254  				//more than 4 digits in group, fail.
   255  				return Addr{}, parseAddrError{in: in, msg: "each group must have 4 or less digits", at: s}
   256  			}
   257  			if acc > math.MaxUint16 {
   258  				// Overflow, fail.
   259  				return Addr{}, parseAddrError{in: in, msg: "IPv6 field has value >=2^16", at: s}
   260  			}
   261  		}
   262  		if off == 0 {
   263  			// No digits found, fail.
   264  			return Addr{}, parseAddrError{in: in, msg: "each colon-separated field must have at least one digit", at: s}
   265  		}
   266  
   267  		// If followed by dot, might be in trailing IPv4.
   268  		if off < len(s) && s[off] == '.' {
   269  			if ellipsis < 0 && i != 12 {
   270  				// Not the right place.
   271  				return Addr{}, parseAddrError{in: in, msg: "embedded IPv4 address must replace the final 2 fields of the address", at: s}
   272  			}
   273  			if i+4 > 16 {
   274  				// Not enough room.
   275  				return Addr{}, parseAddrError{in: in, msg: "too many hex fields to fit an embedded IPv4 at the end of the address", at: s}
   276  			}
   277  
   278  			end := len(in)
   279  			if len(zone) > 0 {
   280  				end -= len(zone) + 1
   281  			}
   282  			err := parseIPv4Fields(in, end-len(s), end, ip[i:i+4])
   283  			if err != nil {
   284  				return Addr{}, err
   285  			}
   286  			s = ""
   287  			i += 4
   288  			break
   289  		}
   290  
   291  		// Save this 16-bit chunk.
   292  		ip[i] = byte(acc >> 8)
   293  		ip[i+1] = byte(acc)
   294  		i += 2
   295  
   296  		// Stop at end of string.
   297  		s = s[off:]
   298  		if len(s) == 0 {
   299  			break
   300  		}
   301  
   302  		// Otherwise must be followed by colon and more.
   303  		if s[0] != ':' {
   304  			return Addr{}, parseAddrError{in: in, msg: "unexpected character, want colon", at: s}
   305  		} else if len(s) == 1 {
   306  			return Addr{}, parseAddrError{in: in, msg: "colon must be followed by more characters", at: s}
   307  		}
   308  		s = s[1:]
   309  
   310  		// Look for ellipsis.
   311  		if s[0] == ':' {
   312  			if ellipsis >= 0 { // already have one
   313  				return Addr{}, parseAddrError{in: in, msg: "multiple :: in address", at: s}
   314  			}
   315  			ellipsis = i
   316  			s = s[1:]
   317  			if len(s) == 0 { // can be at end
   318  				break
   319  			}
   320  		}
   321  	}
   322  
   323  	// Must have used entire string.
   324  	if len(s) != 0 {
   325  		return Addr{}, parseAddrError{in: in, msg: "trailing garbage after address", at: s}
   326  	}
   327  
   328  	// If didn't parse enough, expand ellipsis.
   329  	if i < 16 {
   330  		if ellipsis < 0 {
   331  			return Addr{}, parseAddrError{in: in, msg: "address string too short"}
   332  		}
   333  		n := 16 - i
   334  		for j := i - 1; j >= ellipsis; j-- {
   335  			ip[j+n] = ip[j]
   336  		}
   337  		clear(ip[ellipsis : ellipsis+n])
   338  	} else if ellipsis >= 0 {
   339  		// Ellipsis must represent at least one 0 group.
   340  		return Addr{}, parseAddrError{in: in, msg: "the :: must expand to at least one field of zeros"}
   341  	}
   342  	return AddrFrom16(ip).WithZone(zone), nil
   343  }
   344  
   345  // AddrFromSlice parses the 4- or 16-byte byte slice as an IPv4 or IPv6 address.
   346  // Note that a [net.IP] can be passed directly as the []byte argument.
   347  // If slice's length is not 4 or 16, AddrFromSlice returns [Addr]{}, false.
   348  func AddrFromSlice(slice []byte) (ip Addr, ok bool) {
   349  	switch len(slice) {
   350  	case 4:
   351  		return AddrFrom4([4]byte(slice)), true
   352  	case 16:
   353  		return AddrFrom16([16]byte(slice)), true
   354  	}
   355  	return Addr{}, false
   356  }
   357  
   358  // v4 returns the i'th byte of ip. If ip is not an IPv4, v4 returns
   359  // unspecified garbage.
   360  func (ip Addr) v4(i uint8) uint8 {
   361  	return uint8(ip.addr.lo >> ((3 - i) * 8))
   362  }
   363  
   364  // v6 returns the i'th byte of ip. If ip is an IPv4 address, this
   365  // accesses the IPv4-mapped IPv6 address form of the IP.
   366  func (ip Addr) v6(i uint8) uint8 {
   367  	return uint8(*(ip.addr.halves()[(i/8)%2]) >> ((7 - i%8) * 8))
   368  }
   369  
   370  // v6u16 returns the i'th 16-bit word of ip. If ip is an IPv4 address,
   371  // this accesses the IPv4-mapped IPv6 address form of the IP.
   372  func (ip Addr) v6u16(i uint8) uint16 {
   373  	return uint16(*(ip.addr.halves()[(i/4)%2]) >> ((3 - i%4) * 16))
   374  }
   375  
   376  // isZero reports whether ip is the zero value of the IP type.
   377  // The zero value is not a valid IP address of any type.
   378  //
   379  // Note that "0.0.0.0" and "::" are not the zero value. Use IsUnspecified to
   380  // check for these values instead.
   381  func (ip Addr) isZero() bool {
   382  	// Faster than comparing ip == Addr{}, but effectively equivalent,
   383  	// as there's no way to make an IP with a nil z from this package.
   384  	return ip.z == z0
   385  }
   386  
   387  // IsValid reports whether the [Addr] is an initialized address (not the zero Addr).
   388  //
   389  // Note that "0.0.0.0" and "::" are both valid values.
   390  func (ip Addr) IsValid() bool { return ip.z != z0 }
   391  
   392  // BitLen returns the number of bits in the IP address:
   393  // 128 for IPv6, 32 for IPv4, and 0 for the zero [Addr].
   394  //
   395  // Note that IPv4-mapped IPv6 addresses are considered IPv6 addresses
   396  // and therefore have bit length 128.
   397  func (ip Addr) BitLen() int {
   398  	switch ip.z {
   399  	case z0:
   400  		return 0
   401  	case z4:
   402  		return 32
   403  	}
   404  	return 128
   405  }
   406  
   407  // Zone returns ip's IPv6 scoped addressing zone, if any.
   408  func (ip Addr) Zone() string {
   409  	if ip.z == z0 {
   410  		return ""
   411  	}
   412  	return ip.z.Value().zoneV6
   413  }
   414  
   415  // Compare returns an integer comparing two IPs.
   416  // The result will be 0 if ip == ip2, -1 if ip < ip2, and +1 if ip > ip2.
   417  // The definition of "less than" is the same as the [Addr.Less] method.
   418  func (ip Addr) Compare(ip2 Addr) int {
   419  	f1, f2 := ip.BitLen(), ip2.BitLen()
   420  	if f1 < f2 {
   421  		return -1
   422  	}
   423  	if f1 > f2 {
   424  		return 1
   425  	}
   426  	hi1, hi2 := ip.addr.hi, ip2.addr.hi
   427  	if hi1 < hi2 {
   428  		return -1
   429  	}
   430  	if hi1 > hi2 {
   431  		return 1
   432  	}
   433  	lo1, lo2 := ip.addr.lo, ip2.addr.lo
   434  	if lo1 < lo2 {
   435  		return -1
   436  	}
   437  	if lo1 > lo2 {
   438  		return 1
   439  	}
   440  	if ip.Is6() {
   441  		za, zb := ip.Zone(), ip2.Zone()
   442  		if za < zb {
   443  			return -1
   444  		}
   445  		if za > zb {
   446  			return 1
   447  		}
   448  	}
   449  	return 0
   450  }
   451  
   452  // Less reports whether ip sorts before ip2.
   453  // IP addresses sort first by length, then their address.
   454  // IPv6 addresses with zones sort just after the same address without a zone.
   455  func (ip Addr) Less(ip2 Addr) bool { return ip.Compare(ip2) == -1 }
   456  
   457  // Is4 reports whether ip is an IPv4 address.
   458  //
   459  // It returns false for IPv4-mapped IPv6 addresses. See [Addr.Unmap].
   460  func (ip Addr) Is4() bool {
   461  	return ip.z == z4
   462  }
   463  
   464  // Is4In6 reports whether ip is an "IPv4-mapped IPv6 address"
   465  // as defined by RFC 4291.
   466  // That is, it reports whether ip is in ::ffff:0:0/96.
   467  func (ip Addr) Is4In6() bool {
   468  	return ip.Is6() && ip.addr.hi == 0 && ip.addr.lo>>32 == 0xffff
   469  }
   470  
   471  // Is6 reports whether ip is an IPv6 address, including IPv4-mapped
   472  // IPv6 addresses.
   473  func (ip Addr) Is6() bool {
   474  	return ip.z != z0 && ip.z != z4
   475  }
   476  
   477  // Unmap returns ip with any IPv4-mapped IPv6 address prefix removed.
   478  //
   479  // That is, if ip is an IPv6 address wrapping an IPv4 address, it
   480  // returns the wrapped IPv4 address. Otherwise it returns ip unmodified.
   481  func (ip Addr) Unmap() Addr {
   482  	if ip.Is4In6() {
   483  		ip.z = z4
   484  	}
   485  	return ip
   486  }
   487  
   488  // WithZone returns an IP that's the same as ip but with the provided
   489  // zone. If zone is empty, the zone is removed. If ip is an IPv4
   490  // address, WithZone is a no-op and returns ip unchanged.
   491  func (ip Addr) WithZone(zone string) Addr {
   492  	if !ip.Is6() {
   493  		return ip
   494  	}
   495  	if zone == "" {
   496  		ip.z = z6noz
   497  		return ip
   498  	}
   499  	ip.z = unique.Make(addrDetail{isV6: true, zoneV6: zone})
   500  	return ip
   501  }
   502  
   503  // withoutZone unconditionally strips the zone from ip.
   504  // It's similar to WithZone, but small enough to be inlinable.
   505  func (ip Addr) withoutZone() Addr {
   506  	if !ip.Is6() {
   507  		return ip
   508  	}
   509  	ip.z = z6noz
   510  	return ip
   511  }
   512  
   513  // hasZone reports whether ip has an IPv6 zone.
   514  func (ip Addr) hasZone() bool {
   515  	return ip.z != z0 && ip.z != z4 && ip.z != z6noz
   516  }
   517  
   518  // IsLinkLocalUnicast reports whether ip is a link-local unicast address.
   519  func (ip Addr) IsLinkLocalUnicast() bool {
   520  	if ip.Is4In6() {
   521  		ip = ip.Unmap()
   522  	}
   523  
   524  	// Dynamic Configuration of IPv4 Link-Local Addresses
   525  	// https://datatracker.ietf.org/doc/html/rfc3927#section-2.1
   526  	if ip.Is4() {
   527  		return ip.v4(0) == 169 && ip.v4(1) == 254
   528  	}
   529  	// IP Version 6 Addressing Architecture (2.4 Address Type Identification)
   530  	// https://datatracker.ietf.org/doc/html/rfc4291#section-2.4
   531  	if ip.Is6() {
   532  		return ip.v6u16(0)&0xffc0 == 0xfe80
   533  	}
   534  	return false // zero value
   535  }
   536  
   537  // IsLoopback reports whether ip is a loopback address.
   538  func (ip Addr) IsLoopback() bool {
   539  	if ip.Is4In6() {
   540  		ip = ip.Unmap()
   541  	}
   542  
   543  	// Requirements for Internet Hosts -- Communication Layers (3.2.1.3 Addressing)
   544  	// https://datatracker.ietf.org/doc/html/rfc1122#section-3.2.1.3
   545  	if ip.Is4() {
   546  		return ip.v4(0) == 127
   547  	}
   548  	// IP Version 6 Addressing Architecture (2.4 Address Type Identification)
   549  	// https://datatracker.ietf.org/doc/html/rfc4291#section-2.4
   550  	if ip.Is6() {
   551  		return ip.addr.hi == 0 && ip.addr.lo == 1
   552  	}
   553  	return false // zero value
   554  }
   555  
   556  // IsMulticast reports whether ip is a multicast address.
   557  func (ip Addr) IsMulticast() bool {
   558  	if ip.Is4In6() {
   559  		ip = ip.Unmap()
   560  	}
   561  
   562  	// Host Extensions for IP Multicasting (4. HOST GROUP ADDRESSES)
   563  	// https://datatracker.ietf.org/doc/html/rfc1112#section-4
   564  	if ip.Is4() {
   565  		return ip.v4(0)&0xf0 == 0xe0
   566  	}
   567  	// IP Version 6 Addressing Architecture (2.4 Address Type Identification)
   568  	// https://datatracker.ietf.org/doc/html/rfc4291#section-2.4
   569  	if ip.Is6() {
   570  		return ip.addr.hi>>(64-8) == 0xff // ip.v6(0) == 0xff
   571  	}
   572  	return false // zero value
   573  }
   574  
   575  // IsInterfaceLocalMulticast reports whether ip is an IPv6 interface-local
   576  // multicast address.
   577  func (ip Addr) IsInterfaceLocalMulticast() bool {
   578  	// IPv6 Addressing Architecture (2.7.1. Pre-Defined Multicast Addresses)
   579  	// https://datatracker.ietf.org/doc/html/rfc4291#section-2.7.1
   580  	if ip.Is6() && !ip.Is4In6() {
   581  		return ip.v6u16(0)&0xff0f == 0xff01
   582  	}
   583  	return false // zero value
   584  }
   585  
   586  // IsLinkLocalMulticast reports whether ip is a link-local multicast address.
   587  func (ip Addr) IsLinkLocalMulticast() bool {
   588  	if ip.Is4In6() {
   589  		ip = ip.Unmap()
   590  	}
   591  
   592  	// IPv4 Multicast Guidelines (4. Local Network Control Block (224.0.0/24))
   593  	// https://datatracker.ietf.org/doc/html/rfc5771#section-4
   594  	if ip.Is4() {
   595  		return ip.v4(0) == 224 && ip.v4(1) == 0 && ip.v4(2) == 0
   596  	}
   597  	// IPv6 Addressing Architecture (2.7.1. Pre-Defined Multicast Addresses)
   598  	// https://datatracker.ietf.org/doc/html/rfc4291#section-2.7.1
   599  	if ip.Is6() {
   600  		return ip.v6u16(0)&0xff0f == 0xff02
   601  	}
   602  	return false // zero value
   603  }
   604  
   605  // IsGlobalUnicast reports whether ip is a global unicast address.
   606  //
   607  // It returns true for IPv6 addresses which fall outside of the current
   608  // IANA-allocated 2000::/3 global unicast space, with the exception of the
   609  // link-local address space. It also returns true even if ip is in the IPv4
   610  // private address space or IPv6 unique local address space.
   611  // It returns false for the zero [Addr].
   612  //
   613  // For reference, see RFC 1122, RFC 4291, and RFC 4632.
   614  func (ip Addr) IsGlobalUnicast() bool {
   615  	if ip.z == z0 {
   616  		// Invalid or zero-value.
   617  		return false
   618  	}
   619  
   620  	if ip.Is4In6() {
   621  		ip = ip.Unmap()
   622  	}
   623  
   624  	// Match package net's IsGlobalUnicast logic. Notably private IPv4 addresses
   625  	// and ULA IPv6 addresses are still considered "global unicast".
   626  	if ip.Is4() && (ip == IPv4Unspecified() || ip == AddrFrom4([4]byte{255, 255, 255, 255})) {
   627  		return false
   628  	}
   629  
   630  	return ip != IPv6Unspecified() &&
   631  		!ip.IsLoopback() &&
   632  		!ip.IsMulticast() &&
   633  		!ip.IsLinkLocalUnicast()
   634  }
   635  
   636  // IsPrivate reports whether ip is a private address, according to RFC 1918
   637  // (IPv4 addresses) and RFC 4193 (IPv6 addresses). That is, it reports whether
   638  // ip is in 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, or fc00::/7. This is the
   639  // same as [net.IP.IsPrivate].
   640  //
   641  // IsPrivate does not describe a security property of addresses,
   642  // and should not be used for access control.
   643  func (ip Addr) IsPrivate() bool {
   644  	if ip.Is4In6() {
   645  		ip = ip.Unmap()
   646  	}
   647  
   648  	// Match the stdlib's IsPrivate logic.
   649  	if ip.Is4() {
   650  		// RFC 1918 allocates 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16 as
   651  		// private IPv4 address subnets.
   652  		return ip.v4(0) == 10 ||
   653  			(ip.v4(0) == 172 && ip.v4(1)&0xf0 == 16) ||
   654  			(ip.v4(0) == 192 && ip.v4(1) == 168)
   655  	}
   656  
   657  	if ip.Is6() {
   658  		// RFC 4193 allocates fc00::/7 as the unique local unicast IPv6 address
   659  		// subnet.
   660  		return ip.v6(0)&0xfe == 0xfc
   661  	}
   662  
   663  	return false // zero value
   664  }
   665  
   666  // IsUnspecified reports whether ip is an unspecified address, either the IPv4
   667  // address "0.0.0.0" or the IPv6 address "::".
   668  //
   669  // Note that the zero [Addr] is not an unspecified address.
   670  func (ip Addr) IsUnspecified() bool {
   671  	return ip == IPv4Unspecified() || ip == IPv6Unspecified()
   672  }
   673  
   674  // Prefix keeps only the top b bits of IP, producing a Prefix
   675  // of the specified length.
   676  // If ip is a zero [Addr], Prefix always returns a zero Prefix and a nil error.
   677  // Otherwise, if bits is less than zero or greater than ip.BitLen(),
   678  // Prefix returns an error.
   679  func (ip Addr) Prefix(b int) (Prefix, error) {
   680  	if b < 0 {
   681  		return Prefix{}, errors.New("negative Prefix bits")
   682  	}
   683  	effectiveBits := b
   684  	switch ip.z {
   685  	case z0:
   686  		return Prefix{}, nil
   687  	case z4:
   688  		if b > 32 {
   689  			return Prefix{}, errors.New("prefix length " + strconv.Itoa(b) + " too large for IPv4")
   690  		}
   691  		effectiveBits += 96
   692  	default:
   693  		if b > 128 {
   694  			return Prefix{}, errors.New("prefix length " + strconv.Itoa(b) + " too large for IPv6")
   695  		}
   696  	}
   697  	ip.addr = ip.addr.and(mask6(effectiveBits))
   698  	return PrefixFrom(ip, b), nil
   699  }
   700  
   701  // As16 returns the IP address in its 16-byte representation.
   702  // IPv4 addresses are returned as IPv4-mapped IPv6 addresses.
   703  // IPv6 addresses with zones are returned without their zone (use the
   704  // [Addr.Zone] method to get it).
   705  // The ip zero value returns all zeroes.
   706  func (ip Addr) As16() (a16 [16]byte) {
   707  	byteorder.BEPutUint64(a16[:8], ip.addr.hi)
   708  	byteorder.BEPutUint64(a16[8:], ip.addr.lo)
   709  	return a16
   710  }
   711  
   712  // As4 returns an IPv4 or IPv4-in-IPv6 address in its 4-byte representation.
   713  // If ip is the zero [Addr] or an IPv6 address, As4 panics.
   714  // Note that 0.0.0.0 is not the zero Addr.
   715  func (ip Addr) As4() (a4 [4]byte) {
   716  	if ip.z == z4 || ip.Is4In6() {
   717  		byteorder.BEPutUint32(a4[:], uint32(ip.addr.lo))
   718  		return a4
   719  	}
   720  	if ip.z == z0 {
   721  		panic("As4 called on IP zero value")
   722  	}
   723  	panic("As4 called on IPv6 address")
   724  }
   725  
   726  // AsSlice returns an IPv4 or IPv6 address in its respective 4-byte or 16-byte representation.
   727  func (ip Addr) AsSlice() []byte {
   728  	switch ip.z {
   729  	case z0:
   730  		return nil
   731  	case z4:
   732  		var ret [4]byte
   733  		byteorder.BEPutUint32(ret[:], uint32(ip.addr.lo))
   734  		return ret[:]
   735  	default:
   736  		var ret [16]byte
   737  		byteorder.BEPutUint64(ret[:8], ip.addr.hi)
   738  		byteorder.BEPutUint64(ret[8:], ip.addr.lo)
   739  		return ret[:]
   740  	}
   741  }
   742  
   743  // Next returns the address following ip.
   744  // If there is none, it returns the zero [Addr].
   745  func (ip Addr) Next() Addr {
   746  	ip.addr = ip.addr.addOne()
   747  	if ip.Is4() {
   748  		if uint32(ip.addr.lo) == 0 {
   749  			// Overflowed.
   750  			return Addr{}
   751  		}
   752  	} else {
   753  		if ip.addr.isZero() {
   754  			// Overflowed
   755  			return Addr{}
   756  		}
   757  	}
   758  	return ip
   759  }
   760  
   761  // Prev returns the IP before ip.
   762  // If there is none, it returns the IP zero value.
   763  func (ip Addr) Prev() Addr {
   764  	if ip.Is4() {
   765  		if uint32(ip.addr.lo) == 0 {
   766  			return Addr{}
   767  		}
   768  	} else if ip.addr.isZero() {
   769  		return Addr{}
   770  	}
   771  	ip.addr = ip.addr.subOne()
   772  	return ip
   773  }
   774  
   775  // String returns the string form of the IP address ip.
   776  // It returns one of 5 forms:
   777  //
   778  //   - "invalid IP", if ip is the zero [Addr]
   779  //   - IPv4 dotted decimal ("192.0.2.1")
   780  //   - IPv6 ("2001:db8::1")
   781  //   - "::ffff:1.2.3.4" (if [Addr.Is4In6])
   782  //   - IPv6 with zone ("fe80:db8::1%eth0")
   783  //
   784  // Note that unlike package net's IP.String method,
   785  // IPv4-mapped IPv6 addresses format with a "::ffff:"
   786  // prefix before the dotted quad.
   787  func (ip Addr) String() string {
   788  	switch ip.z {
   789  	case z0:
   790  		return "invalid IP"
   791  	case z4:
   792  		return ip.string4()
   793  	default:
   794  		if ip.Is4In6() {
   795  			return ip.string4In6()
   796  		}
   797  		return ip.string6()
   798  	}
   799  }
   800  
   801  // AppendTo appends a text encoding of ip,
   802  // as generated by [Addr.MarshalText],
   803  // to b and returns the extended buffer.
   804  func (ip Addr) AppendTo(b []byte) []byte {
   805  	switch ip.z {
   806  	case z0:
   807  		return b
   808  	case z4:
   809  		return ip.appendTo4(b)
   810  	default:
   811  		if ip.Is4In6() {
   812  			return ip.appendTo4In6(b)
   813  		}
   814  		return ip.appendTo6(b)
   815  	}
   816  }
   817  
   818  // digits is a string of the hex digits from 0 to f. It's used in
   819  // appendDecimal and appendHex to format IP addresses.
   820  const digits = "0123456789abcdef"
   821  
   822  // appendDecimal appends the decimal string representation of x to b.
   823  func appendDecimal(b []byte, x uint8) []byte {
   824  	// Using this function rather than strconv.AppendUint makes IPv4
   825  	// string building 2x faster.
   826  
   827  	if x >= 100 {
   828  		b = append(b, digits[x/100])
   829  	}
   830  	if x >= 10 {
   831  		b = append(b, digits[x/10%10])
   832  	}
   833  	return append(b, digits[x%10])
   834  }
   835  
   836  // appendHex appends the hex string representation of x to b.
   837  func appendHex(b []byte, x uint16) []byte {
   838  	// Using this function rather than strconv.AppendUint makes IPv6
   839  	// string building 2x faster.
   840  
   841  	if x >= 0x1000 {
   842  		b = append(b, digits[x>>12])
   843  	}
   844  	if x >= 0x100 {
   845  		b = append(b, digits[x>>8&0xf])
   846  	}
   847  	if x >= 0x10 {
   848  		b = append(b, digits[x>>4&0xf])
   849  	}
   850  	return append(b, digits[x&0xf])
   851  }
   852  
   853  // appendHexPad appends the fully padded hex string representation of x to b.
   854  func appendHexPad(b []byte, x uint16) []byte {
   855  	return append(b, digits[x>>12], digits[x>>8&0xf], digits[x>>4&0xf], digits[x&0xf])
   856  }
   857  
   858  func (ip Addr) string4() string {
   859  	const max = len("255.255.255.255")
   860  	ret := make([]byte, 0, max)
   861  	ret = ip.appendTo4(ret)
   862  	return string(ret)
   863  }
   864  
   865  func (ip Addr) appendTo4(ret []byte) []byte {
   866  	ret = appendDecimal(ret, ip.v4(0))
   867  	ret = append(ret, '.')
   868  	ret = appendDecimal(ret, ip.v4(1))
   869  	ret = append(ret, '.')
   870  	ret = appendDecimal(ret, ip.v4(2))
   871  	ret = append(ret, '.')
   872  	ret = appendDecimal(ret, ip.v4(3))
   873  	return ret
   874  }
   875  
   876  func (ip Addr) string4In6() string {
   877  	const max = len("::ffff:255.255.255.255%enp5s0")
   878  	ret := make([]byte, 0, max)
   879  	ret = ip.appendTo4In6(ret)
   880  	return string(ret)
   881  }
   882  
   883  func (ip Addr) appendTo4In6(ret []byte) []byte {
   884  	ret = append(ret, "::ffff:"...)
   885  	ret = ip.Unmap().appendTo4(ret)
   886  	if ip.z != z6noz {
   887  		ret = append(ret, '%')
   888  		ret = append(ret, ip.Zone()...)
   889  	}
   890  	return ret
   891  }
   892  
   893  // string6 formats ip in IPv6 textual representation. It follows the
   894  // guidelines in section 4 of RFC 5952
   895  // (https://tools.ietf.org/html/rfc5952#section-4): no unnecessary
   896  // zeros, use :: to elide the longest run of zeros, and don't use ::
   897  // to compact a single zero field.
   898  func (ip Addr) string6() string {
   899  	// Use a zone with a "plausibly long" name, so that most zone-ful
   900  	// IP addresses won't require additional allocation.
   901  	//
   902  	// The compiler does a cool optimization here, where ret ends up
   903  	// stack-allocated and so the only allocation this function does
   904  	// is to construct the returned string. As such, it's okay to be a
   905  	// bit greedy here, size-wise.
   906  	const max = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0")
   907  	ret := make([]byte, 0, max)
   908  	ret = ip.appendTo6(ret)
   909  	return string(ret)
   910  }
   911  
   912  func (ip Addr) appendTo6(ret []byte) []byte {
   913  	zeroStart, zeroEnd := uint8(255), uint8(255)
   914  	for i := uint8(0); i < 8; i++ {
   915  		j := i
   916  		for j < 8 && ip.v6u16(j) == 0 {
   917  			j++
   918  		}
   919  		if l := j - i; l >= 2 && l > zeroEnd-zeroStart {
   920  			zeroStart, zeroEnd = i, j
   921  		}
   922  	}
   923  
   924  	for i := uint8(0); i < 8; i++ {
   925  		if i == zeroStart {
   926  			ret = append(ret, ':', ':')
   927  			i = zeroEnd
   928  			if i >= 8 {
   929  				break
   930  			}
   931  		} else if i > 0 {
   932  			ret = append(ret, ':')
   933  		}
   934  
   935  		ret = appendHex(ret, ip.v6u16(i))
   936  	}
   937  
   938  	if ip.z != z6noz {
   939  		ret = append(ret, '%')
   940  		ret = append(ret, ip.Zone()...)
   941  	}
   942  	return ret
   943  }
   944  
   945  // StringExpanded is like [Addr.String] but IPv6 addresses are expanded with leading
   946  // zeroes and no "::" compression. For example, "2001:db8::1" becomes
   947  // "2001:0db8:0000:0000:0000:0000:0000:0001".
   948  func (ip Addr) StringExpanded() string {
   949  	switch ip.z {
   950  	case z0, z4:
   951  		return ip.String()
   952  	}
   953  
   954  	const size = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")
   955  	ret := make([]byte, 0, size)
   956  	for i := uint8(0); i < 8; i++ {
   957  		if i > 0 {
   958  			ret = append(ret, ':')
   959  		}
   960  
   961  		ret = appendHexPad(ret, ip.v6u16(i))
   962  	}
   963  
   964  	if ip.z != z6noz {
   965  		// The addition of a zone will cause a second allocation, but when there
   966  		// is no zone the ret slice will be stack allocated.
   967  		ret = append(ret, '%')
   968  		ret = append(ret, ip.Zone()...)
   969  	}
   970  	return string(ret)
   971  }
   972  
   973  // AppendText implements the [encoding.TextAppender] interface,
   974  // It is the same as [Addr.AppendTo].
   975  func (ip Addr) AppendText(b []byte) ([]byte, error) {
   976  	return ip.AppendTo(b), nil
   977  }
   978  
   979  // MarshalText implements the [encoding.TextMarshaler] interface,
   980  // The encoding is the same as returned by [Addr.String], with one exception:
   981  // If ip is the zero [Addr], the encoding is the empty string.
   982  func (ip Addr) MarshalText() ([]byte, error) {
   983  	buf := []byte{}
   984  	switch ip.z {
   985  	case z0:
   986  	case z4:
   987  		const maxCap = len("255.255.255.255")
   988  		buf = make([]byte, 0, maxCap)
   989  	default:
   990  		if ip.Is4In6() {
   991  			const maxCap = len("::ffff:255.255.255.255%enp5s0")
   992  			buf = make([]byte, 0, maxCap)
   993  			break
   994  		}
   995  		const maxCap = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0")
   996  		buf = make([]byte, 0, maxCap)
   997  	}
   998  	return ip.AppendText(buf)
   999  }
  1000  
  1001  // UnmarshalText implements the encoding.TextUnmarshaler interface.
  1002  // The IP address is expected in a form accepted by [ParseAddr].
  1003  //
  1004  // If text is empty, UnmarshalText sets *ip to the zero [Addr] and
  1005  // returns no error.
  1006  func (ip *Addr) UnmarshalText(text []byte) error {
  1007  	if len(text) == 0 {
  1008  		*ip = Addr{}
  1009  		return nil
  1010  	}
  1011  	var err error
  1012  	*ip, err = ParseAddr(string(text))
  1013  	return err
  1014  }
  1015  
  1016  // AppendBinary implements the [encoding.BinaryAppender] interface.
  1017  func (ip Addr) AppendBinary(b []byte) ([]byte, error) {
  1018  	switch ip.z {
  1019  	case z0:
  1020  	case z4:
  1021  		b = byteorder.BEAppendUint32(b, uint32(ip.addr.lo))
  1022  	default:
  1023  		b = byteorder.BEAppendUint64(b, ip.addr.hi)
  1024  		b = byteorder.BEAppendUint64(b, ip.addr.lo)
  1025  		b = append(b, ip.Zone()...)
  1026  	}
  1027  	return b, nil
  1028  }
  1029  
  1030  func (ip Addr) marshalBinarySize() int {
  1031  	switch ip.z {
  1032  	case z0:
  1033  		return 0
  1034  	case z4:
  1035  		return 4
  1036  	default:
  1037  		return 16 + len(ip.Zone())
  1038  	}
  1039  }
  1040  
  1041  // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
  1042  // It returns a zero-length slice for the zero [Addr],
  1043  // the 4-byte form for an IPv4 address,
  1044  // and the 16-byte form with zone appended for an IPv6 address.
  1045  func (ip Addr) MarshalBinary() ([]byte, error) {
  1046  	return ip.AppendBinary(make([]byte, 0, ip.marshalBinarySize()))
  1047  }
  1048  
  1049  // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
  1050  // It expects data in the form generated by MarshalBinary.
  1051  func (ip *Addr) UnmarshalBinary(b []byte) error {
  1052  	n := len(b)
  1053  	switch {
  1054  	case n == 0:
  1055  		*ip = Addr{}
  1056  		return nil
  1057  	case n == 4:
  1058  		*ip = AddrFrom4([4]byte(b))
  1059  		return nil
  1060  	case n == 16:
  1061  		*ip = AddrFrom16([16]byte(b))
  1062  		return nil
  1063  	case n > 16:
  1064  		*ip = AddrFrom16([16]byte(b[:16])).WithZone(string(b[16:]))
  1065  		return nil
  1066  	}
  1067  	return errors.New("unexpected slice size")
  1068  }
  1069  
  1070  // AddrPort is an IP and a port number.
  1071  type AddrPort struct {
  1072  	ip   Addr
  1073  	port uint16
  1074  }
  1075  
  1076  // AddrPortFrom returns an [AddrPort] with the provided IP and port.
  1077  // It does not allocate.
  1078  func AddrPortFrom(ip Addr, port uint16) AddrPort { return AddrPort{ip: ip, port: port} }
  1079  
  1080  // Addr returns p's IP address.
  1081  func (p AddrPort) Addr() Addr { return p.ip }
  1082  
  1083  // Port returns p's port.
  1084  func (p AddrPort) Port() uint16 { return p.port }
  1085  
  1086  // splitAddrPort splits s into an IP address string and a port
  1087  // string. It splits strings shaped like "foo:bar" or "[foo]:bar",
  1088  // without further validating the substrings. v6 indicates whether the
  1089  // ip string should parse as an IPv6 address or an IPv4 address, in
  1090  // order for s to be a valid ip:port string.
  1091  func splitAddrPort(s string) (ip, port string, v6 bool, err error) {
  1092  	i := bytealg.LastIndexByteString(s, ':')
  1093  	if i == -1 {
  1094  		return "", "", false, errors.New("not an ip:port")
  1095  	}
  1096  
  1097  	ip, port = s[:i], s[i+1:]
  1098  	if len(ip) == 0 {
  1099  		return "", "", false, errors.New("no IP")
  1100  	}
  1101  	if len(port) == 0 {
  1102  		return "", "", false, errors.New("no port")
  1103  	}
  1104  	if ip[0] == '[' {
  1105  		if len(ip) < 2 || ip[len(ip)-1] != ']' {
  1106  			return "", "", false, errors.New("missing ]")
  1107  		}
  1108  		ip = ip[1 : len(ip)-1]
  1109  		v6 = true
  1110  	}
  1111  
  1112  	return ip, port, v6, nil
  1113  }
  1114  
  1115  // ParseAddrPort parses s as an [AddrPort].
  1116  //
  1117  // It doesn't do any name resolution: both the address and the port
  1118  // must be numeric.
  1119  func ParseAddrPort(s string) (AddrPort, error) {
  1120  	var ipp AddrPort
  1121  	ip, port, v6, err := splitAddrPort(s)
  1122  	if err != nil {
  1123  		return ipp, err
  1124  	}
  1125  	port16, err := strconv.ParseUint(port, 10, 16)
  1126  	if err != nil {
  1127  		return ipp, errors.New("invalid port " + strconv.Quote(port) + " parsing " + strconv.Quote(s))
  1128  	}
  1129  	ipp.port = uint16(port16)
  1130  	ipp.ip, err = ParseAddr(ip)
  1131  	if err != nil {
  1132  		return AddrPort{}, err
  1133  	}
  1134  	if v6 && ipp.ip.Is4() {
  1135  		return AddrPort{}, errors.New("invalid ip:port " + strconv.Quote(s) + ", square brackets can only be used with IPv6 addresses")
  1136  	} else if !v6 && ipp.ip.Is6() {
  1137  		return AddrPort{}, errors.New("invalid ip:port " + strconv.Quote(s) + ", IPv6 addresses must be surrounded by square brackets")
  1138  	}
  1139  	return ipp, nil
  1140  }
  1141  
  1142  // MustParseAddrPort calls [ParseAddrPort](s) and panics on error.
  1143  // It is intended for use in tests with hard-coded strings.
  1144  func MustParseAddrPort(s string) AddrPort {
  1145  	ip, err := ParseAddrPort(s)
  1146  	if err != nil {
  1147  		panic(err)
  1148  	}
  1149  	return ip
  1150  }
  1151  
  1152  // IsValid reports whether p.Addr() is valid.
  1153  // All ports are valid, including zero.
  1154  func (p AddrPort) IsValid() bool { return p.ip.IsValid() }
  1155  
  1156  // Compare returns an integer comparing two AddrPorts.
  1157  // The result will be 0 if p == p2, -1 if p < p2, and +1 if p > p2.
  1158  // AddrPorts sort first by IP address, then port.
  1159  func (p AddrPort) Compare(p2 AddrPort) int {
  1160  	if c := p.Addr().Compare(p2.Addr()); c != 0 {
  1161  		return c
  1162  	}
  1163  	return cmp.Compare(p.Port(), p2.Port())
  1164  }
  1165  
  1166  func (p AddrPort) String() string {
  1167  	var b []byte
  1168  	switch p.ip.z {
  1169  	case z0:
  1170  		return "invalid AddrPort"
  1171  	case z4:
  1172  		const max = len("255.255.255.255:65535")
  1173  		b = make([]byte, 0, max)
  1174  		b = p.ip.appendTo4(b)
  1175  	default:
  1176  		if p.ip.Is4In6() {
  1177  			const max = len("[::ffff:255.255.255.255%enp5s0]:65535")
  1178  			b = make([]byte, 0, max)
  1179  			b = append(b, '[')
  1180  			b = p.ip.appendTo4In6(b)
  1181  		} else {
  1182  			const max = len("[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0]:65535")
  1183  			b = make([]byte, 0, max)
  1184  			b = append(b, '[')
  1185  			b = p.ip.appendTo6(b)
  1186  		}
  1187  		b = append(b, ']')
  1188  	}
  1189  	b = append(b, ':')
  1190  	b = strconv.AppendUint(b, uint64(p.port), 10)
  1191  	return string(b)
  1192  }
  1193  
  1194  // AppendTo appends a text encoding of p,
  1195  // as generated by [AddrPort.MarshalText],
  1196  // to b and returns the extended buffer.
  1197  func (p AddrPort) AppendTo(b []byte) []byte {
  1198  	switch p.ip.z {
  1199  	case z0:
  1200  		return b
  1201  	case z4:
  1202  		b = p.ip.appendTo4(b)
  1203  	default:
  1204  		b = append(b, '[')
  1205  		if p.ip.Is4In6() {
  1206  			b = p.ip.appendTo4In6(b)
  1207  		} else {
  1208  			b = p.ip.appendTo6(b)
  1209  		}
  1210  		b = append(b, ']')
  1211  	}
  1212  	b = append(b, ':')
  1213  	b = strconv.AppendUint(b, uint64(p.port), 10)
  1214  	return b
  1215  }
  1216  
  1217  // AppendText implements the [encoding.TextAppender] interface. The
  1218  // encoding is the same as returned by [AddrPort.AppendTo].
  1219  func (p AddrPort) AppendText(b []byte) ([]byte, error) {
  1220  	return p.AppendTo(b), nil
  1221  }
  1222  
  1223  // MarshalText implements the [encoding.TextMarshaler] interface. The
  1224  // encoding is the same as returned by [AddrPort.String], with one exception: if
  1225  // p.Addr() is the zero [Addr], the encoding is the empty string.
  1226  func (p AddrPort) MarshalText() ([]byte, error) {
  1227  	buf := []byte{}
  1228  	switch p.ip.z {
  1229  	case z0:
  1230  	case z4:
  1231  		const maxCap = len("255.255.255.255:65535")
  1232  		buf = make([]byte, 0, maxCap)
  1233  	default:
  1234  		const maxCap = len("[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0]:65535")
  1235  		buf = make([]byte, 0, maxCap)
  1236  	}
  1237  	return p.AppendText(buf)
  1238  }
  1239  
  1240  // UnmarshalText implements the encoding.TextUnmarshaler
  1241  // interface. The [AddrPort] is expected in a form
  1242  // generated by [AddrPort.MarshalText] or accepted by [ParseAddrPort].
  1243  func (p *AddrPort) UnmarshalText(text []byte) error {
  1244  	if len(text) == 0 {
  1245  		*p = AddrPort{}
  1246  		return nil
  1247  	}
  1248  	var err error
  1249  	*p, err = ParseAddrPort(string(text))
  1250  	return err
  1251  }
  1252  
  1253  // AppendBinary implements the [encoding.BinaryAppendler] interface.
  1254  // It returns [Addr.AppendBinary] with an additional two bytes appended
  1255  // containing the port in little-endian.
  1256  func (p AddrPort) AppendBinary(b []byte) ([]byte, error) {
  1257  	b, err := p.Addr().AppendBinary(b)
  1258  	if err != nil {
  1259  		return nil, err
  1260  	}
  1261  	return byteorder.LEAppendUint16(b, p.Port()), nil
  1262  }
  1263  
  1264  // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
  1265  // It returns [Addr.MarshalBinary] with an additional two bytes appended
  1266  // containing the port in little-endian.
  1267  func (p AddrPort) MarshalBinary() ([]byte, error) {
  1268  	return p.AppendBinary(make([]byte, 0, p.Addr().marshalBinarySize()+2))
  1269  }
  1270  
  1271  // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
  1272  // It expects data in the form generated by [AddrPort.MarshalBinary].
  1273  func (p *AddrPort) UnmarshalBinary(b []byte) error {
  1274  	if len(b) < 2 {
  1275  		return errors.New("unexpected slice size")
  1276  	}
  1277  	var addr Addr
  1278  	err := addr.UnmarshalBinary(b[:len(b)-2])
  1279  	if err != nil {
  1280  		return err
  1281  	}
  1282  	*p = AddrPortFrom(addr, byteorder.LEUint16(b[len(b)-2:]))
  1283  	return nil
  1284  }
  1285  
  1286  // Prefix is an IP address prefix (CIDR) representing an IP network.
  1287  //
  1288  // The first [Prefix.Bits]() of [Addr]() are specified. The remaining bits match any address.
  1289  // The range of Bits() is [0,32] for IPv4 or [0,128] for IPv6.
  1290  type Prefix struct {
  1291  	ip Addr
  1292  
  1293  	// bitsPlusOne stores the prefix bit length plus one.
  1294  	// A Prefix is valid if and only if bitsPlusOne is non-zero.
  1295  	bitsPlusOne uint8
  1296  }
  1297  
  1298  // PrefixFrom returns a [Prefix] with the provided IP address and bit
  1299  // prefix length.
  1300  //
  1301  // It does not allocate. Unlike [Addr.Prefix], [PrefixFrom] does not mask
  1302  // off the host bits of ip.
  1303  //
  1304  // If bits is less than zero or greater than ip.BitLen, [Prefix.Bits]
  1305  // will return an invalid value -1.
  1306  func PrefixFrom(ip Addr, bits int) Prefix {
  1307  	var bitsPlusOne uint8
  1308  	if !ip.isZero() && bits >= 0 && bits <= ip.BitLen() {
  1309  		bitsPlusOne = uint8(bits) + 1
  1310  	}
  1311  	return Prefix{
  1312  		ip:          ip.withoutZone(),
  1313  		bitsPlusOne: bitsPlusOne,
  1314  	}
  1315  }
  1316  
  1317  // Addr returns p's IP address.
  1318  func (p Prefix) Addr() Addr { return p.ip }
  1319  
  1320  // Bits returns p's prefix length.
  1321  //
  1322  // It reports -1 if invalid.
  1323  func (p Prefix) Bits() int { return int(p.bitsPlusOne) - 1 }
  1324  
  1325  // IsValid reports whether p.Bits() has a valid range for p.Addr().
  1326  // If p.Addr() is the zero [Addr], IsValid returns false.
  1327  // Note that if p is the zero [Prefix], then p.IsValid() == false.
  1328  func (p Prefix) IsValid() bool { return p.bitsPlusOne > 0 }
  1329  
  1330  func (p Prefix) isZero() bool { return p == Prefix{} }
  1331  
  1332  // IsSingleIP reports whether p contains exactly one IP.
  1333  func (p Prefix) IsSingleIP() bool { return p.IsValid() && p.Bits() == p.ip.BitLen() }
  1334  
  1335  // Compare returns an integer comparing two prefixes.
  1336  // The result will be 0 if p == p2, -1 if p < p2, and +1 if p > p2.
  1337  // Prefixes sort first by validity (invalid before valid), then
  1338  // address family (IPv4 before IPv6), then masked prefix address, then
  1339  // prefix length, then unmasked address.
  1340  func (p Prefix) Compare(p2 Prefix) int {
  1341  	// Aside from sorting based on the masked address, this use of
  1342  	// Addr.Compare also enforces the valid vs. invalid and address
  1343  	// family ordering for the prefix.
  1344  	if c := p.Masked().Addr().Compare(p2.Masked().Addr()); c != 0 {
  1345  		return c
  1346  	}
  1347  
  1348  	if c := cmp.Compare(p.Bits(), p2.Bits()); c != 0 {
  1349  		return c
  1350  	}
  1351  
  1352  	return p.Addr().Compare(p2.Addr())
  1353  }
  1354  
  1355  type parsePrefixError struct {
  1356  	in  string // the string given to ParsePrefix
  1357  	msg string // an explanation of the parse failure
  1358  }
  1359  
  1360  func (err parsePrefixError) Error() string {
  1361  	return "netip.ParsePrefix(" + strconv.Quote(err.in) + "): " + err.msg
  1362  }
  1363  
  1364  // ParsePrefix parses s as an IP address prefix.
  1365  // The string can be in the form "192.168.1.0/24" or "2001:db8::/32",
  1366  // the CIDR notation defined in RFC 4632 and RFC 4291.
  1367  // IPv6 zones are not permitted in prefixes, and an error will be returned if a
  1368  // zone is present.
  1369  //
  1370  // Note that masked address bits are not zeroed. Use Masked for that.
  1371  func ParsePrefix(s string) (Prefix, error) {
  1372  	i := bytealg.LastIndexByteString(s, '/')
  1373  	if i < 0 {
  1374  		return Prefix{}, parsePrefixError{in: s, msg: "no '/'"}
  1375  	}
  1376  	ip, err := ParseAddr(s[:i])
  1377  	if err != nil {
  1378  		return Prefix{}, parsePrefixError{in: s, msg: err.Error()}
  1379  	}
  1380  	// IPv6 zones are not allowed: https://go.dev/issue/51899
  1381  	if ip.Is6() && ip.z != z6noz {
  1382  		return Prefix{}, parsePrefixError{in: s, msg: "IPv6 zones cannot be present in a prefix"}
  1383  	}
  1384  
  1385  	bitsStr := s[i+1:]
  1386  
  1387  	// strconv.Atoi accepts a leading sign and leading zeroes, but we don't want that.
  1388  	if len(bitsStr) > 1 && (bitsStr[0] < '1' || bitsStr[0] > '9') {
  1389  		return Prefix{}, parsePrefixError{in: s, msg: "bad bits after slash: " + strconv.Quote(bitsStr)}
  1390  	}
  1391  
  1392  	bits, err := strconv.Atoi(bitsStr)
  1393  	if err != nil {
  1394  		return Prefix{}, parsePrefixError{in: s, msg: "bad bits after slash: " + strconv.Quote(bitsStr)}
  1395  	}
  1396  	maxBits := 32
  1397  	if ip.Is6() {
  1398  		maxBits = 128
  1399  	}
  1400  	if bits < 0 || bits > maxBits {
  1401  		return Prefix{}, parsePrefixError{in: s, msg: "prefix length out of range"}
  1402  	}
  1403  	return PrefixFrom(ip, bits), nil
  1404  }
  1405  
  1406  // MustParsePrefix calls [ParsePrefix](s) and panics on error.
  1407  // It is intended for use in tests with hard-coded strings.
  1408  func MustParsePrefix(s string) Prefix {
  1409  	ip, err := ParsePrefix(s)
  1410  	if err != nil {
  1411  		panic(err)
  1412  	}
  1413  	return ip
  1414  }
  1415  
  1416  // Masked returns p in its canonical form, with all but the high
  1417  // p.Bits() bits of p.Addr() masked off.
  1418  //
  1419  // If p is zero or otherwise invalid, Masked returns the zero [Prefix].
  1420  func (p Prefix) Masked() Prefix {
  1421  	m, _ := p.ip.Prefix(p.Bits())
  1422  	return m
  1423  }
  1424  
  1425  // Contains reports whether the network p includes ip.
  1426  //
  1427  // An IPv4 address will not match an IPv6 prefix.
  1428  // An IPv4-mapped IPv6 address will not match an IPv4 prefix.
  1429  // A zero-value IP will not match any prefix.
  1430  // If ip has an IPv6 zone, Contains returns false,
  1431  // because Prefixes strip zones.
  1432  func (p Prefix) Contains(ip Addr) bool {
  1433  	if !p.IsValid() || ip.hasZone() {
  1434  		return false
  1435  	}
  1436  	if f1, f2 := p.ip.BitLen(), ip.BitLen(); f1 == 0 || f2 == 0 || f1 != f2 {
  1437  		return false
  1438  	}
  1439  	if ip.Is4() {
  1440  		// xor the IP addresses together; mismatched bits are now ones.
  1441  		// Shift away the number of bits we don't care about.
  1442  		// Shifts in Go are more efficient if the compiler can prove
  1443  		// that the shift amount is smaller than the width of the shifted type (64 here).
  1444  		// We know that p.bits is in the range 0..32 because p is Valid;
  1445  		// the compiler doesn't know that, so mask with 63 to help it.
  1446  		// Now truncate to 32 bits, because this is IPv4.
  1447  		// If all the bits we care about are equal, the result will be zero.
  1448  		return uint32((ip.addr.lo^p.ip.addr.lo)>>((32-p.Bits())&63)) == 0
  1449  	} else {
  1450  		// xor the IP addresses together.
  1451  		// Mask away the bits we don't care about.
  1452  		// If all the bits we care about are equal, the result will be zero.
  1453  		return ip.addr.xor(p.ip.addr).and(mask6(p.Bits())).isZero()
  1454  	}
  1455  }
  1456  
  1457  // Overlaps reports whether p and o contain any IP addresses in common.
  1458  //
  1459  // If p and o are of different address families or either have a zero
  1460  // IP, it reports false. Like the Contains method, a prefix with an
  1461  // IPv4-mapped IPv6 address is still treated as an IPv6 mask.
  1462  func (p Prefix) Overlaps(o Prefix) bool {
  1463  	if !p.IsValid() || !o.IsValid() {
  1464  		return false
  1465  	}
  1466  	if p == o {
  1467  		return true
  1468  	}
  1469  	if p.ip.Is4() != o.ip.Is4() {
  1470  		return false
  1471  	}
  1472  	var minBits int
  1473  	if pb, ob := p.Bits(), o.Bits(); pb < ob {
  1474  		minBits = pb
  1475  	} else {
  1476  		minBits = ob
  1477  	}
  1478  	if minBits == 0 {
  1479  		return true
  1480  	}
  1481  	// One of these Prefix calls might look redundant, but we don't require
  1482  	// that p and o values are normalized (via Prefix.Masked) first,
  1483  	// so the Prefix call on the one that's already minBits serves to zero
  1484  	// out any remaining bits in IP.
  1485  	var err error
  1486  	if p, err = p.ip.Prefix(minBits); err != nil {
  1487  		return false
  1488  	}
  1489  	if o, err = o.ip.Prefix(minBits); err != nil {
  1490  		return false
  1491  	}
  1492  	return p.ip == o.ip
  1493  }
  1494  
  1495  // AppendTo appends a text encoding of p,
  1496  // as generated by [Prefix.MarshalText],
  1497  // to b and returns the extended buffer.
  1498  func (p Prefix) AppendTo(b []byte) []byte {
  1499  	if p.isZero() {
  1500  		return b
  1501  	}
  1502  	if !p.IsValid() {
  1503  		return append(b, "invalid Prefix"...)
  1504  	}
  1505  
  1506  	// p.ip is non-nil, because p is valid.
  1507  	if p.ip.z == z4 {
  1508  		b = p.ip.appendTo4(b)
  1509  	} else {
  1510  		if p.ip.Is4In6() {
  1511  			b = append(b, "::ffff:"...)
  1512  			b = p.ip.Unmap().appendTo4(b)
  1513  		} else {
  1514  			b = p.ip.appendTo6(b)
  1515  		}
  1516  	}
  1517  
  1518  	b = append(b, '/')
  1519  	b = appendDecimal(b, uint8(p.Bits()))
  1520  	return b
  1521  }
  1522  
  1523  // AppendText implements the [encoding.TextAppender] interface.
  1524  // It is the same as [Prefix.AppendTo].
  1525  func (p Prefix) AppendText(b []byte) ([]byte, error) {
  1526  	return p.AppendTo(b), nil
  1527  }
  1528  
  1529  // MarshalText implements the [encoding.TextMarshaler] interface,
  1530  // The encoding is the same as returned by [Prefix.String], with one exception:
  1531  // If p is the zero value, the encoding is the empty string.
  1532  func (p Prefix) MarshalText() ([]byte, error) {
  1533  	buf := []byte{}
  1534  	switch p.ip.z {
  1535  	case z0:
  1536  	case z4:
  1537  		const maxCap = len("255.255.255.255/32")
  1538  		buf = make([]byte, 0, maxCap)
  1539  	default:
  1540  		const maxCap = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%enp5s0/128")
  1541  		buf = make([]byte, 0, maxCap)
  1542  	}
  1543  	return p.AppendText(buf)
  1544  }
  1545  
  1546  // UnmarshalText implements the encoding.TextUnmarshaler interface.
  1547  // The IP address is expected in a form accepted by [ParsePrefix]
  1548  // or generated by [Prefix.MarshalText].
  1549  func (p *Prefix) UnmarshalText(text []byte) error {
  1550  	if len(text) == 0 {
  1551  		*p = Prefix{}
  1552  		return nil
  1553  	}
  1554  	var err error
  1555  	*p, err = ParsePrefix(string(text))
  1556  	return err
  1557  }
  1558  
  1559  // AppendBinary implements the [encoding.AppendMarshaler] interface.
  1560  // It returns [Addr.AppendBinary] with an additional byte appended
  1561  // containing the prefix bits.
  1562  func (p Prefix) AppendBinary(b []byte) ([]byte, error) {
  1563  	b, err := p.Addr().withoutZone().AppendBinary(b)
  1564  	if err != nil {
  1565  		return nil, err
  1566  	}
  1567  	return append(b, uint8(p.Bits())), nil
  1568  }
  1569  
  1570  // MarshalBinary implements the [encoding.BinaryMarshaler] interface.
  1571  // It returns [Addr.MarshalBinary] with an additional byte appended
  1572  // containing the prefix bits.
  1573  func (p Prefix) MarshalBinary() ([]byte, error) {
  1574  	// without the zone the max length is 16, plus an additional byte is 17
  1575  	return p.AppendBinary(make([]byte, 0, p.Addr().withoutZone().marshalBinarySize()+1))
  1576  }
  1577  
  1578  // UnmarshalBinary implements the [encoding.BinaryUnmarshaler] interface.
  1579  // It expects data in the form generated by [Prefix.MarshalBinary].
  1580  func (p *Prefix) UnmarshalBinary(b []byte) error {
  1581  	if len(b) < 1 {
  1582  		return errors.New("unexpected slice size")
  1583  	}
  1584  	var addr Addr
  1585  	err := addr.UnmarshalBinary(b[:len(b)-1])
  1586  	if err != nil {
  1587  		return err
  1588  	}
  1589  	*p = PrefixFrom(addr, int(b[len(b)-1]))
  1590  	return nil
  1591  }
  1592  
  1593  // String returns the CIDR notation of p: "<ip>/<bits>".
  1594  func (p Prefix) String() string {
  1595  	if !p.IsValid() {
  1596  		return "invalid Prefix"
  1597  	}
  1598  	var b []byte
  1599  	switch {
  1600  	case p.ip.z == z4:
  1601  		const maxCap = len("255.255.255.255/32")
  1602  		b = make([]byte, 0, maxCap)
  1603  		b = p.ip.appendTo4(b)
  1604  	case p.ip.Is4In6():
  1605  		const maxCap = len("::ffff:255.255.255.255/32")
  1606  		b = make([]byte, 0, maxCap)
  1607  		b = append(b, "::ffff:"...)
  1608  		b = p.ip.Unmap().appendTo4(b)
  1609  	default:
  1610  		const maxCap = len("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/128")
  1611  		b = make([]byte, 0, maxCap)
  1612  		b = p.ip.appendTo6(b)
  1613  	}
  1614  	b = append(b, '/')
  1615  	b = appendDecimal(b, uint8(p.Bits()))
  1616  	return string(b)
  1617  }
  1618  

View as plain text