1 // Copyright 2010 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.
17 // defaultTCPKeepAlive is a default constant value for TCPKeepAlive times
18 // See go.dev/issue/31510
19 defaultTCPKeepAlive = 15 * time.Second
21 // For the moment, MultiPath TCP is not used by default
22 // See go.dev/issue/56539
23 defaultMPTCPEnabled = false
26 var multipathtcp = godebug.New("multipathtcp")
28 // mptcpStatus is a tristate for Multipath TCP, see go.dev/issue/56539
29 type mptcpStatus uint8
32 // The value 0 is the system default, linked to defaultMPTCPEnabled
33 mptcpUseDefault mptcpStatus = iota
38 func (m *mptcpStatus) get() bool {
46 // If MPTCP is forced via GODEBUG=multipathtcp=1
47 if multipathtcp.Value() == "1" {
48 multipathtcp.IncNonDefault()
53 return defaultMPTCPEnabled
56 func (m *mptcpStatus) set(use bool) {
64 // A Dialer contains options for connecting to an address.
66 // The zero value for each field is equivalent to dialing
67 // without that option. Dialing with the zero value of Dialer
68 // is therefore equivalent to just calling the Dial function.
70 // It is safe to call Dialer's methods concurrently.
72 // Timeout is the maximum amount of time a dial will wait for
73 // a connect to complete. If Deadline is also set, it may fail
76 // The default is no timeout.
78 // When using TCP and dialing a host name with multiple IP
79 // addresses, the timeout may be divided between them.
81 // With or without a timeout, the operating system may impose
82 // its own earlier timeout. For instance, TCP timeouts are
83 // often around 3 minutes.
86 // Deadline is the absolute point in time after which dials
87 // will fail. If Timeout is set, it may fail earlier.
88 // Zero means no deadline, or dependent on the operating system
89 // as with the Timeout option.
92 // LocalAddr is the local address to use when dialing an
93 // address. The address must be of a compatible type for the
94 // network being dialed.
95 // If nil, a local address is automatically chosen.
98 // DualStack previously enabled RFC 6555 Fast Fallback
99 // support, also known as "Happy Eyeballs", in which IPv4 is
100 // tried soon if IPv6 appears to be misconfigured and
103 // Deprecated: Fast Fallback is enabled by default. To
104 // disable, set FallbackDelay to a negative value.
107 // FallbackDelay specifies the length of time to wait before
108 // spawning a RFC 6555 Fast Fallback connection. That is, this
109 // is the amount of time to wait for IPv6 to succeed before
110 // assuming that IPv6 is misconfigured and falling back to
113 // If zero, a default delay of 300ms is used.
114 // A negative value disables Fast Fallback support.
115 FallbackDelay time.Duration
117 // KeepAlive specifies the interval between keep-alive
118 // probes for an active network connection.
119 // If zero, keep-alive probes are sent with a default value
120 // (currently 15 seconds), if supported by the protocol and operating
121 // system. Network protocols or operating systems that do
122 // not support keep-alives ignore this field.
123 // If negative, keep-alive probes are disabled.
124 KeepAlive time.Duration
126 // Resolver optionally specifies an alternate resolver to use.
129 // Cancel is an optional channel whose closure indicates that
130 // the dial should be canceled. Not all types of dials support
133 // Deprecated: Use DialContext instead.
134 Cancel <-chan struct{}
136 // If Control is not nil, it is called after creating the network
137 // connection but before actually dialing.
139 // Network and address parameters passed to Control function are not
140 // necessarily the ones passed to Dial. For example, passing "tcp" to Dial
141 // will cause the Control function to be called with "tcp4" or "tcp6".
143 // Control is ignored if ControlContext is not nil.
144 Control func(network, address string, c syscall.RawConn) error
146 // If ControlContext is not nil, it is called after creating the network
147 // connection but before actually dialing.
149 // Network and address parameters passed to ControlContext function are not
150 // necessarily the ones passed to Dial. For example, passing "tcp" to Dial
151 // will cause the ControlContext function to be called with "tcp4" or "tcp6".
153 // If ControlContext is not nil, Control is ignored.
154 ControlContext func(ctx context.Context, network, address string, c syscall.RawConn) error
156 // If mptcpStatus is set to a value allowing Multipath TCP (MPTCP) to be
157 // used, any call to Dial with "tcp(4|6)" as network will use MPTCP if
158 // supported by the operating system.
159 mptcpStatus mptcpStatus
162 func (d *Dialer) dualStack() bool { return d.FallbackDelay >= 0 }
164 func minNonzeroTime(a, b time.Time) time.Time {
168 if b.IsZero() || a.Before(b) {
174 // deadline returns the earliest of:
177 // - the context's deadline
179 // Or zero, if none of Timeout, Deadline, or context's deadline is set.
180 func (d *Dialer) deadline(ctx context.Context, now time.Time) (earliest time.Time) {
181 if d.Timeout != 0 { // including negative, for historical reasons
182 earliest = now.Add(d.Timeout)
184 if d, ok := ctx.Deadline(); ok {
185 earliest = minNonzeroTime(earliest, d)
187 return minNonzeroTime(earliest, d.Deadline)
190 func (d *Dialer) resolver() *Resolver {
191 if d.Resolver != nil {
194 return DefaultResolver
197 // partialDeadline returns the deadline to use for a single address,
198 // when multiple addresses are pending.
199 func partialDeadline(now, deadline time.Time, addrsRemaining int) (time.Time, error) {
200 if deadline.IsZero() {
203 timeRemaining := deadline.Sub(now)
204 if timeRemaining <= 0 {
205 return time.Time{}, errTimeout
207 // Tentatively allocate equal time to each remaining address.
208 timeout := timeRemaining / time.Duration(addrsRemaining)
209 // If the time per address is too short, steal from the end of the list.
210 const saneMinimum = 2 * time.Second
211 if timeout < saneMinimum {
212 if timeRemaining < saneMinimum {
213 timeout = timeRemaining
215 timeout = saneMinimum
218 return now.Add(timeout), nil
221 func (d *Dialer) fallbackDelay() time.Duration {
222 if d.FallbackDelay > 0 {
223 return d.FallbackDelay
225 return 300 * time.Millisecond
229 func parseNetwork(ctx context.Context, network string, needsProto bool) (afnet string, proto int, err error) {
230 i := bytealg.LastIndexByteString(network, ':')
231 if i < 0 { // no colon
233 case "tcp", "tcp4", "tcp6":
234 case "udp", "udp4", "udp6":
235 case "ip", "ip4", "ip6":
237 return "", 0, UnknownNetworkError(network)
239 case "unix", "unixgram", "unixpacket":
241 return "", 0, UnknownNetworkError(network)
243 return network, 0, nil
247 case "ip", "ip4", "ip6":
248 protostr := network[i+1:]
249 proto, i, ok := dtoi(protostr)
250 if !ok || i != len(protostr) {
251 proto, err = lookupProtocol(ctx, protostr)
256 return afnet, proto, nil
258 return "", 0, UnknownNetworkError(network)
261 // resolveAddrList resolves addr using hint and returns a list of
262 // addresses. The result contains at least one address when error is
264 func (r *Resolver) resolveAddrList(ctx context.Context, op, network, addr string, hint Addr) (addrList, error) {
265 afnet, _, err := parseNetwork(ctx, network, true)
269 if op == "dial" && addr == "" {
270 return nil, errMissingAddress
273 case "unix", "unixgram", "unixpacket":
274 addr, err := ResolveUnixAddr(afnet, addr)
278 if op == "dial" && hint != nil && addr.Network() != hint.Network() {
279 return nil, &AddrError{Err: "mismatched local address type", Addr: hint.String()}
281 return addrList{addr}, nil
283 addrs, err := r.internetAddrList(ctx, afnet, addr)
284 if err != nil || op != "dial" || hint == nil {
293 switch hint := hint.(type) {
296 wildcard = tcp.isWildcard()
299 wildcard = udp.isWildcard()
302 wildcard = ip.isWildcard()
305 for _, addr := range addrs {
306 if addr.Network() != hint.Network() {
307 return nil, &AddrError{Err: "mismatched local address type", Addr: hint.String()}
309 switch addr := addr.(type) {
311 if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(tcp.IP) {
314 naddrs = append(naddrs, addr)
316 if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(udp.IP) {
319 naddrs = append(naddrs, addr)
321 if !wildcard && !addr.isWildcard() && !addr.IP.matchAddrFamily(ip.IP) {
324 naddrs = append(naddrs, addr)
327 if len(naddrs) == 0 {
328 return nil, &AddrError{Err: errNoSuitableAddress.Error(), Addr: hint.String()}
333 // MultipathTCP reports whether MPTCP will be used.
335 // This method doesn't check if MPTCP is supported by the operating
337 func (d *Dialer) MultipathTCP() bool {
338 return d.mptcpStatus.get()
341 // SetMultipathTCP directs the Dial methods to use, or not use, MPTCP,
342 // if supported by the operating system. This method overrides the
343 // system default and the GODEBUG=multipathtcp=... setting if any.
345 // If MPTCP is not available on the host or not supported by the server,
346 // the Dial methods will fall back to TCP.
347 func (d *Dialer) SetMultipathTCP(use bool) {
348 d.mptcpStatus.set(use)
351 // Dial connects to the address on the named network.
353 // Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only),
354 // "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4"
355 // (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
358 // For TCP and UDP networks, the address has the form "host:port".
359 // The host must be a literal IP address, or a host name that can be
360 // resolved to IP addresses.
361 // The port must be a literal port number or a service name.
362 // If the host is a literal IPv6 address it must be enclosed in square
363 // brackets, as in "[2001:db8::1]:80" or "[fe80::1%zone]:80".
364 // The zone specifies the scope of the literal IPv6 address as defined
366 // The functions JoinHostPort and SplitHostPort manipulate a pair of
367 // host and port in this form.
368 // When using TCP, and the host resolves to multiple IP addresses,
369 // Dial will try each IP address in order until one succeeds.
373 // Dial("tcp", "golang.org:http")
374 // Dial("tcp", "192.0.2.1:http")
375 // Dial("tcp", "198.51.100.1:80")
376 // Dial("udp", "[2001:db8::1]:domain")
377 // Dial("udp", "[fe80::1%lo0]:53")
378 // Dial("tcp", ":80")
380 // For IP networks, the network must be "ip", "ip4" or "ip6" followed
381 // by a colon and a literal protocol number or a protocol name, and
382 // the address has the form "host". The host must be a literal IP
383 // address or a literal IPv6 address with zone.
384 // It depends on each operating system how the operating system
385 // behaves with a non-well known protocol number such as "0" or "255".
389 // Dial("ip4:1", "192.0.2.1")
390 // Dial("ip6:ipv6-icmp", "2001:db8::1")
391 // Dial("ip6:58", "fe80::1%lo0")
393 // For TCP, UDP and IP networks, if the host is empty or a literal
394 // unspecified IP address, as in ":80", "0.0.0.0:80" or "[::]:80" for
395 // TCP and UDP, "", "0.0.0.0" or "::" for IP, the local system is
398 // For Unix networks, the address must be a file system path.
399 func Dial(network, address string) (Conn, error) {
401 return d.Dial(network, address)
404 // DialTimeout acts like Dial but takes a timeout.
406 // The timeout includes name resolution, if required.
407 // When using TCP, and the host in the address parameter resolves to
408 // multiple IP addresses, the timeout is spread over each consecutive
409 // dial, such that each is given an appropriate fraction of the time
412 // See func Dial for a description of the network and address
414 func DialTimeout(network, address string, timeout time.Duration) (Conn, error) {
415 d := Dialer{Timeout: timeout}
416 return d.Dial(network, address)
419 // sysDialer contains a Dial's parameters and configuration.
420 type sysDialer struct {
422 network, address string
423 testHookDialTCP func(ctx context.Context, net string, laddr, raddr *TCPAddr) (*TCPConn, error)
426 // Dial connects to the address on the named network.
428 // See func Dial for a description of the network and address
431 // Dial uses context.Background internally; to specify the context, use
433 func (d *Dialer) Dial(network, address string) (Conn, error) {
434 return d.DialContext(context.Background(), network, address)
437 // DialContext connects to the address on the named network using
438 // the provided context.
440 // The provided Context must be non-nil. If the context expires before
441 // the connection is complete, an error is returned. Once successfully
442 // connected, any expiration of the context will not affect the
445 // When using TCP, and the host in the address parameter resolves to multiple
446 // network addresses, any dial timeout (from d.Timeout or ctx) is spread
447 // over each consecutive dial, such that each is given an appropriate
448 // fraction of the time to connect.
449 // For example, if a host has 4 IP addresses and the timeout is 1 minute,
450 // the connect to each single address will be given 15 seconds to complete
451 // before trying the next one.
453 // See func Dial for a description of the network and address
455 func (d *Dialer) DialContext(ctx context.Context, network, address string) (Conn, error) {
459 deadline := d.deadline(ctx, time.Now())
460 if !deadline.IsZero() {
462 if d, ok := ctx.Deadline(); !ok || deadline.Before(d) {
463 subCtx, cancel := context.WithDeadline(ctx, deadline)
468 if oldCancel := d.Cancel; oldCancel != nil {
469 subCtx, cancel := context.WithCancel(ctx)
475 case <-subCtx.Done():
481 // Shadow the nettrace (if any) during resolve so Connect events don't fire for DNS lookups.
483 if trace, _ := ctx.Value(nettrace.TraceKey{}).(*nettrace.Trace); trace != nil {
485 shadow.ConnectStart = nil
486 shadow.ConnectDone = nil
487 resolveCtx = context.WithValue(resolveCtx, nettrace.TraceKey{}, &shadow)
490 addrs, err := d.resolver().resolveAddrList(resolveCtx, "dial", network, address, d.LocalAddr)
492 return nil, &OpError{Op: "dial", Net: network, Source: nil, Addr: nil, Err: err}
501 var primaries, fallbacks addrList
502 if d.dualStack() && network == "tcp" {
503 primaries, fallbacks = addrs.partition(isIPv4)
508 return sd.dialParallel(ctx, primaries, fallbacks)
511 // dialParallel races two copies of dialSerial, giving the first a
512 // head start. It returns the first established connection and
513 // closes the others. Otherwise it returns an error from the first
515 func (sd *sysDialer) dialParallel(ctx context.Context, primaries, fallbacks addrList) (Conn, error) {
516 if len(fallbacks) == 0 {
517 return sd.dialSerial(ctx, primaries)
520 returned := make(chan struct{})
521 defer close(returned)
523 type dialResult struct {
529 results := make(chan dialResult) // unbuffered
531 startRacer := func(ctx context.Context, primary bool) {
536 c, err := sd.dialSerial(ctx, ras)
538 case results <- dialResult{Conn: c, error: err, primary: primary, done: true}:
546 var primary, fallback dialResult
548 // Start the main racer.
549 primaryCtx, primaryCancel := context.WithCancel(ctx)
550 defer primaryCancel()
551 go startRacer(primaryCtx, true)
553 // Start the timer for the fallback racer.
554 fallbackTimer := time.NewTimer(sd.fallbackDelay())
555 defer fallbackTimer.Stop()
559 case <-fallbackTimer.C:
560 fallbackCtx, fallbackCancel := context.WithCancel(ctx)
561 defer fallbackCancel()
562 go startRacer(fallbackCtx, false)
564 case res := <-results:
565 if res.error == nil {
573 if primary.done && fallback.done {
574 return nil, primary.error
576 if res.primary && fallbackTimer.Stop() {
577 // If we were able to stop the timer, that means it
578 // was running (hadn't yet started the fallback), but
579 // we just got an error on the primary path, so start
580 // the fallback immediately (in 0 nanoseconds).
581 fallbackTimer.Reset(0)
587 // dialSerial connects to a list of addresses in sequence, returning
588 // either the first successful connection, or the first error.
589 func (sd *sysDialer) dialSerial(ctx context.Context, ras addrList) (Conn, error) {
590 var firstErr error // The error from the first address is most relevant.
592 for i, ra := range ras {
595 return nil, &OpError{Op: "dial", Net: sd.network, Source: sd.LocalAddr, Addr: ra, Err: mapErr(ctx.Err())}
600 if deadline, hasDeadline := ctx.Deadline(); hasDeadline {
601 partialDeadline, err := partialDeadline(time.Now(), deadline, len(ras)-i)
605 firstErr = &OpError{Op: "dial", Net: sd.network, Source: sd.LocalAddr, Addr: ra, Err: err}
609 if partialDeadline.Before(deadline) {
610 var cancel context.CancelFunc
611 dialCtx, cancel = context.WithDeadline(ctx, partialDeadline)
616 c, err := sd.dialSingle(dialCtx, ra)
626 firstErr = &OpError{Op: "dial", Net: sd.network, Source: nil, Addr: nil, Err: errMissingAddress}
631 // dialSingle attempts to establish and returns a single connection to
632 // the destination address.
633 func (sd *sysDialer) dialSingle(ctx context.Context, ra Addr) (c Conn, err error) {
634 trace, _ := ctx.Value(nettrace.TraceKey{}).(*nettrace.Trace)
637 if trace.ConnectStart != nil {
638 trace.ConnectStart(sd.network, raStr)
640 if trace.ConnectDone != nil {
641 defer func() { trace.ConnectDone(sd.network, raStr, err) }()
645 switch ra := ra.(type) {
647 la, _ := la.(*TCPAddr)
648 if sd.MultipathTCP() {
649 c, err = sd.dialMPTCP(ctx, la, ra)
651 c, err = sd.dialTCP(ctx, la, ra)
654 la, _ := la.(*UDPAddr)
655 c, err = sd.dialUDP(ctx, la, ra)
657 la, _ := la.(*IPAddr)
658 c, err = sd.dialIP(ctx, la, ra)
660 la, _ := la.(*UnixAddr)
661 c, err = sd.dialUnix(ctx, la, ra)
663 return nil, &OpError{Op: "dial", Net: sd.network, Source: la, Addr: ra, Err: &AddrError{Err: "unexpected address type", Addr: sd.address}}
666 return nil, &OpError{Op: "dial", Net: sd.network, Source: la, Addr: ra, Err: err} // c is non-nil interface containing nil pointer
671 // ListenConfig contains options for listening to an address.
672 type ListenConfig struct {
673 // If Control is not nil, it is called after creating the network
674 // connection but before binding it to the operating system.
676 // Network and address parameters passed to Control method are not
677 // necessarily the ones passed to Listen. For example, passing "tcp" to
678 // Listen will cause the Control function to be called with "tcp4" or "tcp6".
679 Control func(network, address string, c syscall.RawConn) error
681 // KeepAlive specifies the keep-alive period for network
682 // connections accepted by this listener.
683 // If zero, keep-alives are enabled if supported by the protocol
684 // and operating system. Network protocols or operating systems
685 // that do not support keep-alives ignore this field.
686 // If negative, keep-alives are disabled.
687 KeepAlive time.Duration
689 // If mptcpStatus is set to a value allowing Multipath TCP (MPTCP) to be
690 // used, any call to Listen with "tcp(4|6)" as network will use MPTCP if
691 // supported by the operating system.
692 mptcpStatus mptcpStatus
695 // MultipathTCP reports whether MPTCP will be used.
697 // This method doesn't check if MPTCP is supported by the operating
699 func (lc *ListenConfig) MultipathTCP() bool {
700 return lc.mptcpStatus.get()
703 // SetMultipathTCP directs the Listen method to use, or not use, MPTCP,
704 // if supported by the operating system. This method overrides the
705 // system default and the GODEBUG=multipathtcp=... setting if any.
707 // If MPTCP is not available on the host or not supported by the client,
708 // the Listen method will fall back to TCP.
709 func (lc *ListenConfig) SetMultipathTCP(use bool) {
710 lc.mptcpStatus.set(use)
713 // Listen announces on the local network address.
715 // See func Listen for a description of the network and address
717 func (lc *ListenConfig) Listen(ctx context.Context, network, address string) (Listener, error) {
718 addrs, err := DefaultResolver.resolveAddrList(ctx, "listen", network, address, nil)
720 return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
728 la := addrs.first(isIPv4)
729 switch la := la.(type) {
731 if sl.MultipathTCP() {
732 l, err = sl.listenMPTCP(ctx, la)
734 l, err = sl.listenTCP(ctx, la)
737 l, err = sl.listenUnix(ctx, la)
739 return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
742 return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: err} // l is non-nil interface containing nil pointer
747 // ListenPacket announces on the local network address.
749 // See func ListenPacket for a description of the network and address
751 func (lc *ListenConfig) ListenPacket(ctx context.Context, network, address string) (PacketConn, error) {
752 addrs, err := DefaultResolver.resolveAddrList(ctx, "listen", network, address, nil)
754 return nil, &OpError{Op: "listen", Net: network, Source: nil, Addr: nil, Err: err}
762 la := addrs.first(isIPv4)
763 switch la := la.(type) {
765 c, err = sl.listenUDP(ctx, la)
767 c, err = sl.listenIP(ctx, la)
769 c, err = sl.listenUnixgram(ctx, la)
771 return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: &AddrError{Err: "unexpected address type", Addr: address}}
774 return nil, &OpError{Op: "listen", Net: sl.network, Source: nil, Addr: la, Err: err} // c is non-nil interface containing nil pointer
779 // sysListener contains a Listen's parameters and configuration.
780 type sysListener struct {
782 network, address string
785 // Listen announces on the local network address.
787 // The network must be "tcp", "tcp4", "tcp6", "unix" or "unixpacket".
789 // For TCP networks, if the host in the address parameter is empty or
790 // a literal unspecified IP address, Listen listens on all available
791 // unicast and anycast IP addresses of the local system.
792 // To only use IPv4, use network "tcp4".
793 // The address can use a host name, but this is not recommended,
794 // because it will create a listener for at most one of the host's IP
796 // If the port in the address parameter is empty or "0", as in
797 // "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
798 // The Addr method of Listener can be used to discover the chosen
801 // See func Dial for a description of the network and address
804 // Listen uses context.Background internally; to specify the context, use
805 // ListenConfig.Listen.
806 func Listen(network, address string) (Listener, error) {
808 return lc.Listen(context.Background(), network, address)
811 // ListenPacket announces on the local network address.
813 // The network must be "udp", "udp4", "udp6", "unixgram", or an IP
814 // transport. The IP transports are "ip", "ip4", or "ip6" followed by
815 // a colon and a literal protocol number or a protocol name, as in
816 // "ip:1" or "ip:icmp".
818 // For UDP and IP networks, if the host in the address parameter is
819 // empty or a literal unspecified IP address, ListenPacket listens on
820 // all available IP addresses of the local system except multicast IP
822 // To only use IPv4, use network "udp4" or "ip4:proto".
823 // The address can use a host name, but this is not recommended,
824 // because it will create a listener for at most one of the host's IP
826 // If the port in the address parameter is empty or "0", as in
827 // "127.0.0.1:" or "[::1]:0", a port number is automatically chosen.
828 // The LocalAddr method of PacketConn can be used to discover the
831 // See func Dial for a description of the network and address
834 // ListenPacket uses context.Background internally; to specify the context, use
835 // ListenConfig.ListenPacket.
836 func ListenPacket(network, address string) (PacketConn, error) {
838 return lc.ListenPacket(context.Background(), network, address)