tfo

README

tfo-go

tfo-go provides TCP Fast Open support for the net dialer and listener.

go get github.com/metacubex/tfo-go

License

MIT

Documentation

Overview

Package tfo provides TCP Fast Open support for the net dialer and listener.

The dial functions have an additional buffer parameter, which specifies data in SYN. If the buffer is empty, TFO is not used.

This package supports Linux, Windows, macOS, and FreeBSD. On unsupported platforms, ErrPlatformUnsupported is returned.

FreeBSD code is completely untested. Use at your own risk. Feedback is welcome.

Index

• Constants
• Variables
• func Dial(network, address string, b []byte) (net.Conn, error)
• func DialTCP(network string, laddr, raddr *net.TCPAddr, b []byte) (*net.TCPConn, error)
• func DialTimeout(network, address string, timeout time.Duration, b []byte) (net.Conn, error)
• func Listen(network, address string) (net.Listener, error)
• func ListenContext(ctx context.Context, network, address string) (net.Listener, error)
• func ListenTCP(network string, laddr *net.TCPAddr) (*net.TCPListener, error)
• func SetTFODialer(fd uintptr) error
• func SetTFOListener(fd uintptr) error
• func SetTFOListenerWithBacklog(fd uintptr, backlog int) error
• type Dialer
  • func (d *Dialer) Dial(network, address string, b []byte) (net.Conn, error)
  • func (d *Dialer) DialContext(ctx context.Context, network, address string, b []byte) (net.Conn, error)
• type ListenConfig
  • func (lc *ListenConfig) Listen(ctx context.Context, network, address string) (net.Listener, error)
• type PlatformUnsupportedError
  • func (PlatformUnsupportedError) Error() string
  • func (PlatformUnsupportedError) Is(target error) bool

Constants

const TCPFastopenQueueLength = 4096

TCPFastopenQueueLength is the maximum number of total pending TFO connection requests, see https://datatracker.ietf.org/doc/html/rfc7413#section-5.1 for why this limit exists. The current value aligns with Go std's listen(2) backlog (4096, as of the current version).

Deprecated: This constant is no longer used in this module and will be removed in v3.

Variables

var ErrUnsupported = errors.ErrUnsupported

Functions

func Dial

func Dial(network, address string, b []byte) (net.Conn, error)

Dial is like net.Dial but enables TFO whenever possible.

func DialTCP

func DialTCP(network string, laddr, raddr *net.TCPAddr, b []byte) (*net.TCPConn, error)

DialTCP is like net.DialTCP but enables TFO whenever possible.

func DialTimeout

func DialTimeout(network, address string, timeout time.Duration, b []byte) (net.Conn, error)

DialTimeout is like net.DialTimeout but enables TFO whenever possible.

func Listen

func Listen(network, address string) (net.Listener, error)

Listen is like net.Listen but enables TFO whenever possible.

func ListenContext

func ListenContext(ctx context.Context, network, address string) (net.Listener, error)

ListenContext is like net.ListenContext but enables TFO whenever possible.

func ListenTCP

func ListenTCP(network string, laddr *net.TCPAddr) (*net.TCPListener, error)

ListenTCP is like net.ListenTCP but enables TFO whenever possible.

func SetTFODialer

func SetTFODialer(fd uintptr) error

SetTFODialer enables TCP Fast Open on the dialer.

func SetTFOListener

func SetTFOListener(fd uintptr) error

SetTFOListener enables TCP Fast Open on the listener. On platforms where a backlog argument is required, Go std's listen(2) backlog is used. To specify a custom backlog, use SetTFOListenerWithBacklog.

func SetTFOListenerWithBacklog

func SetTFOListenerWithBacklog(fd uintptr, backlog int) error

SetTFOListenerWithBacklog enables TCP Fast Open on the listener with the given backlog. If the platform does not support custom backlog, the specified backlog is ignored.

Types

type Dialer

type Dialer struct {
	net.Dialer

	// DisableTFO controls whether TCP Fast Open is disabled when the dial methods are called.
	// TFO is enabled by default.
	// Set to true to disable TFO and it will behave exactly the same as [net.Dialer].
	DisableTFO bool

	// Fallback controls whether to proceed without TFO when TFO is enabled but not supported
	// on the system.
	// On Linux this also controls whether the sendto(MSG_FASTOPEN) fallback path is tried
	// before giving up on TFO.
	Fallback bool
}

Dialer wraps net.Dialer with an additional option that allows you to disable TFO.

func (*Dialer) Dial

func (d *Dialer) Dial(network, address string, b []byte) (net.Conn, error)

Dial is like net.Dialer.Dial but enables TFO whenever possible, unless [Dialer.DisableTFO] is set to true.

func (*Dialer) DialContext

func (d *Dialer) DialContext(ctx context.Context, network, address string, b []byte) (net.Conn, error)

DialContext is like net.Dialer.DialContext but enables TFO whenever possible, unless [Dialer.DisableTFO] is set to true.

type ListenConfig

type ListenConfig struct {
	net.ListenConfig

	// Backlog specifies the maximum number of pending TFO connections on supported platforms.
	// If the value is 0, Go std's listen(2) backlog (4096, as of the current version) is used.
	// If the value is negative, TFO is disabled.
	Backlog int

	// DisableTFO controls whether TCP Fast Open is disabled when the Listen method is called.
	// TFO is enabled by default, unless [ListenConfig.Backlog] is negative.
	// Set to true to disable TFO and it will behave exactly the same as [net.ListenConfig].
	DisableTFO bool

	// Fallback controls whether to proceed without TFO when TFO is enabled but not supported
	// on the system.
	Fallback bool
}

ListenConfig wraps net.ListenConfig with TFO-related options.

func (*ListenConfig) Listen

func (lc *ListenConfig) Listen(ctx context.Context, network, address string) (net.Listener, error)

Listen is like net.ListenConfig.Listen but enables TFO whenever possible, unless [ListenConfig.Backlog] is negative or [ListenConfig.DisableTFO] is set to true.

type PlatformUnsupportedError

type PlatformUnsupportedError struct{}

PlatformUnsupportedError is returned when tfo-go does not support TCP Fast Open on the current platform.

var (
	ErrPlatformUnsupported PlatformUnsupportedError
)

func (PlatformUnsupportedError) Error

func (PlatformUnsupportedError) Error() string

func (PlatformUnsupportedError) Is

func (PlatformUnsupportedError) Is(target error) bool