README
¶
Package tcplisten provides a customizable TCP net.Listener with various
performance-related options:
-
SO_REUSEPORT: This option allows linear scaling of server performance on multi-CPU servers. See https://www.nginx.com/blog/socket-sharding-nginx-release-1-9-1/ for details. -
TCP_DEFER_ACCEPT: This option expects the server read from the accepted connection before writing to them. -
TCP_FASTOPEN: See https://lwn.net/Articles/508865/ for details.
UNIX Socket Attributes
CreateListener(address) keeps the operating system defaults for socket permissions and ownership. Use CreateListenerWithOptions to set attributes on a filesystem UNIX socket:
gid := 33
listener, err := tcplisten.CreateListenerWithOptions(
"unix:///run/roadrunner/fcgi.sock",
&tcplisten.UnixSocketOptions{Mode: "0660", GID: &gid},
)
Modemust be an octal string from"0000"through"0777". An empty string keeps the default mode.UIDandGIDare optional numeric IDs. Nil keeps the default. Zero is a valid ID. Each ID must fit in anintand be less than4294967295.- A nil options pointer preserves the existing address behavior. A non-nil pointer, including an empty options struct, requires a filesystem UNIX socket on Linux, macOS, or FreeBSD.
- TCP, Linux abstract sockets, and Windows reject non-nil options. Windows can still create listeners without these options.
Validate(address)checks options without filesystem access. A nil receiver is valid.- The caller must close the returned listener. The library closes it if an attribute change fails.
The library sets pathname ownership before mode. It does not change the process umask, worker credentials, or parent directories. The process must have permission to perform the requested operations. An unprivileged owner can change the group only to one of its groups.
Attributes are set after the socket starts listening. A client can connect before these changes finish. Successful return guarantees the requested final attributes, not access control during setup. Existing directory permissions and umask must restrict initial access. Parent directories must prevent untrusted path replacement throughout the listener lifetime. Clients also need search permission on every parent directory.
An existing filesystem socket is removed before bind. Regular files, directories, and symlinks are not removed. Socket replacement does not check whether another process still uses the socket. On Linux, addresses that start with @ or NUL use the abstract namespace and cause no filesystem changes.
On macOS and FreeBSD, a relative name such as @socket is a filesystem path. Go leaves this pathname after a successful listener close. Use unix://./@socket for automatic removal, or remove the pathname after closing the listener. On Windows, leading @ and NUL retain Go's address encoding without filesystem operations; this does not add abstract-socket support to Windows.
The package is derived from tcplisten with modifications.
Documentation
¶
Overview ¶
Package tcplisten provides customizable TCP net.Listener with various performance-related options:
SO_REUSEPORT. This option allows linear scaling server performance on multi-CPU servers. See https://www.nginx.com/blog/socket-sharding-nginx-release-1-9-1/ for details.
TCP_DEFER_ACCEPT. This option expects the server reads from the accepted connection before writing to them.
TCP_FASTOPEN. See https://lwn.net/Articles/508865/ for details.
The package is derived from https://github.com/kavu/go_reuseport .
Index ¶
Constants ¶
const ( IPV4 string = "tcp4" IPV6 string = "tcp6" )
Variables ¶
This section is empty.
Functions ¶
func CreateListener ¶ added in v1.5.0
CreateListener creates a TCP or UNIX listener from an address. A TCP address can omit the tcp:// prefix. UNIX addresses require unix://. Filesystem socket permissions and ownership use the operating system defaults.
func CreateListenerWithOptions ¶ added in v1.6.0
func CreateListenerWithOptions(address string, options *UnixSocketOptions) (net.Listener, error)
CreateListenerWithOptions creates a listener with optional UNIX socket attributes. It validates the options before it changes the filesystem. It closes the listener if an attribute change fails. Attributes are set after listen, so clients can connect before setup completes. Parent directories must restrict initial access and prevent path replacement.
Types ¶
type Config ¶
type Config struct {
// ReusePort enables SO_REUSEPORT.
ReusePort bool
// DeferAccept enables TCP_DEFER_ACCEPT.
DeferAccept bool
// FastOpen enables TCP_FASTOPEN.
FastOpen bool
// Backlog is the maximum number of pending TCP connections the listener
// may queue before passing them to Accept.
// See man 2 listen for details.
//
// By default system-level backlog value is used.
Backlog int
}
Config provides options to enable on the returned listener.
func (*Config) NewListener ¶
NewListener returns TCP listener with options set in the Config.
The function may be called many times for creating distinct listeners with the given config.
Only tcp4 and tcp6 networks are supported.
type UnixSocketOptions ¶ added in v1.6.0
type UnixSocketOptions struct {
// Mode is an octal string from "0000" through "0777". Empty means no change.
Mode string `mapstructure:"mode"`
// UID sets the socket owner. Nil means no change. Zero is a valid ID.
UID *int `mapstructure:"uid"`
// GID sets the socket group. Nil means no change. Zero is a valid ID.
GID *int `mapstructure:"gid"`
}
UnixSocketOptions sets attributes on a filesystem UNIX socket. Omitted attributes keep their operating system defaults.
func (*UnixSocketOptions) Validate ¶ added in v1.6.0
func (o *UnixSocketOptions) Validate(address string) error
Validate checks the options and address without filesystem access. A nil receiver is valid for every address. Non-nil options require a filesystem UNIX socket on Linux, macOS, or FreeBSD.
Source Files