proposal: net: add `Dialer.LocalAddr4` and `Dialer.LocalAddr6`

[database64128]

Proposal Details

net.Dialer has a LocalAddr field for specifying the local address to bind to. It gained support for RFC 6555 Happy Eyeballs v1 years ago, and this was subsequently enabled by default.

Unfortunately, these two features have an implicit, undocumented incompatibility. Setting a LocalAddr causes Happy Eyeballs to be disabled, because a single net.Addr cannot represent both IPv4 and IPv6.

To allow specifying local IPv4 and IPv6 addresses while keeping Happy Eyeballs active, I propose we add the following fields to net.Dialer:

type Dialer struct {
	// ...

	// LocalAddr4 specifies the local IPv4 address to use when
	// dialing an IPv4 address.
	//
	//  - If either LocalAddr4 or LocalAddr6 is specified, LocalAddr
	//    is ignored.
	//  - If only one of LocalAddr4 or LocalAddr6 is specified,
	//    the other address family is disabled.
	//  - If both LocalAddr4 and LocalAddr6 are specified, RFC 6555
	//    Happy Eyeballs will use these local addresses.
	LocalAddr4 netip.AddrPort

	// LocalAddr6 specifies the local IPv6 address to use when
	// dialing an IPv6 address.
	//
	//  - If either LocalAddr4 or LocalAddr6 is specified, LocalAddr
	//    is ignored.
	//  - If only one of LocalAddr4 or LocalAddr6 is specified,
	//    the other address family is disabled.
	//  - If both LocalAddr4 and LocalAddr6 are specified, RFC 6555
	//    Happy Eyeballs will use these local addresses.
	LocalAddr6 netip.AddrPort
}

Using netip.AddrPort instead of net.Addr aligns with the new context-aware dialer methods introduced in #49097.

The old LocalAddr is ignored when either LocalAddr4 or LocalAddr6 is set. This is similar to how the newer ControlContext field overrides Control.

[database64128]

It would make implementation easier if we first convert the internal logic to use the new netip types. This can happen independent of whether this proposal is accepted, as an optimization for #49097 and perhaps #76774.

@neild I can start working on this, if you are OK with it.

[gabyhelp]

Related Issues

• proposal: net: an easy way to make Dialer.Dial("tcp", "DNS reg-name") prefer IPv4 to IPv6 or vice versa #14760 (closed)
• proposal: net: Add IP version preference #70591 (closed)
• proposal: net: add Listen and Dial for TCP and UDP that takes an AddrPort #49522 (closed)
• net: enable happy eyeballs by default #22225 (closed)
• proposal: net/v2: Listen is unfriendly to multiple address families, endpoints and subflows #9334
• proposal: net: only request DNS A record when IPv6 not support, when using the net.Dial method #58995
• net: Setting LocalAddr to v4 address in net.Dialer not effective if v6 available #14672 (closed)

Related Code Changes

• net: Improve multi-address support in net.Dial()
• net: add sequential and RFC 6555-compliant TCP dialing.

Related Discussions

• Multi-address support for net.Dial()

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}