golang
net: lack of guidance on dialing and addresses
Go 1.26 introduces four more Dial functions in package net (#49097), which means we now have a complicated combination of old and new ways to represent addresses and dial. What are the best practices today? At a minimum, the documentation should give guidance on how to navigate this. Is there an opportunity for a modernizer to automatically drive code toward the latest best practices?
For dialing, we now have
func Dial(network, address string) (Conn, error)
func DialTimeout(network, address string, timeout time.Duration) (Conn, error)
func DialIP(network string, laddr, raddr *IPAddr) (*IPConn, error)
func DialTCP(network string, laddr, raddr *TCPAddr) (*TCPConn, error)
func DialUDP(network string, laddr, raddr *UDPAddr) (*UDPConn, error)
func DialUnix(network string, laddr, raddr *UnixAddr) (*UnixConn, error)
func (*Dialer) Dial(network, address string) (Conn, error)
func (*Dialer) DialContext(ctx context.Context, network, address string) (Conn, error)
func (*Dialer) DialIP(ctx context.Context, network string, laddr, raddr netip.Addr) (*IPConn, error)
func (*Dialer) DialTCP(ctx context.Context, network string, laddr, raddr netip.AddrPort) (*TCPConn, error)
func (*Dialer) DialUDP(ctx context.Context, network string, laddr, raddr netip.AddrPort) (*UDPConn, error)
func (*Dialer) DialUnix(ctx context.Context, network string, laddr, raddr *UnixAddr) (*UnixConn, error)
For addresses, we now have
string
// Package net
type Addr interface { ... }
type IP []byte
type IPAddr struct {IP; string}
type TCPAddr struct {IP; int; string}
type UDPAddr struct {IP; int; string}
type UnixAddr struct {string; string}
// Package net/netip
type Addr struct { ... }
type AddrPort struct { ... }
CC @rsc @neild @bradfitz
Related Issues
- net: add context-aware Dialer methods DialTCP, DialUDP, DialIP, DialUnix #49097 (closed)
- proposal: net: add Listen and Dial for TCP and UDP that takes an AddrPort #49522 (closed)
- net: incomplete documentation on parameters for Dial, Listen and ListenPacket functions #17956 (closed)
- net: document Dial thread safety, timeout example #33743 (closed)
- proposal: net: change Dial to accept host+":"+port #44955 (closed)
- proposal: net: add IPConn methods to send/recv with netip.Addr #54262
- net, net/netip: unify address parsing #58098 (closed)
- x/net/ipv{4,6}: adopt net/netip address types #54883
Related Discussions
(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)
Unfortunately I think most of the choices are reasonable in different scenarios.
I think we could deprecate DialTimeout in favor of Dialer{}.DialContext. But the others all have their uses. It depends on whether you are bothering with context.Context, and it depends on what kind of address you happen to have.
Thanks. I don't think we need to deprecate anything, but right now it's hard to get the big picture. It makes sense that all the dial functions make sense depending on the situation. I'm less clear about the various address representations.
The address representations are essentially optimizations. If you've already parsed the address, perhaps to verify it or perhaps you are going to use it multiple times, there's not much reason to fall back to Dial and force the address to be re-parsed again.