tcpip

Documentation

Overview

Package tcpip provides the interfaces and related types that users of the tcpip stack will use in order to create endpoints used to send and receive data over the network stack.

The starting point is the creation and configuration of a stack. 1. A stack can be created by calling the New() function of the tcpip/stack package; 2. configuring a stack involves creating NICs (via calls to Stack.CreateNIC()), 3. adding network addresses (via calls to Stack.AddAddress()), and 4. setting a route table (via a call to Stack.SetRouteTable()).

Once a stack is configured, endpoints can be created by calling Stack.NewEndpoint(). Such endpoints can be used to send/receive data, connect to peers, listen for connections, accept connections, etc., depending on the transport protocol selected

Index

• Variables
• type Address
  • func (a Address) String() string
• type ControlMessages
• type Endpoint
• type ErrorOption
• type FullAddress
• type LinkEndpointID
• type NICID
• type NetworkProtocolNumber
• type NoDelayOption
• type PasscredOption
• type ReceiveBufferSizeOption
• type ReceiveQueueSizeOption
• type ReuseAddressOption
• type Route
  • func (r *Route) Match(addr Address) bool
• type SendBufferSizeOption
• type ShutdownFlags
• type Stack
• type Stats
• type TransportProtocolNumber

Variables

var (
	ErrUnknownProtocol      = errors.New("unknown protocol")
	ErrUnknownNICID         = errors.New("unknown nic id")
	ErrDuplicateNICID       = errors.New("duplicate nic id")
	ErrDuplicateAddress     = errors.New("duplicate address")
	ErrNoRoute              = errors.New("no route")
	ErrBadLinkEndpoint      = errors.New("bad link layer endpoint")
	ErrAlreadyBound         = errors.New("endpoint already bound")
	ErrInvalidEndpointState = errors.New("endpoint is in invalid state")
	ErrAlreadyConnecting    = errors.New("endpoint is already connecting")
	ErrAlreadyConnected     = errors.New("endpoint is already connected")
	ErrNoPortAvailable      = errors.New("no ports are available")
	ErrPortInUse            = errors.New("port is in use")
	ErrBadLocalAddress      = errors.New("bad local address")
	ErrClosedForSend        = errors.New("endpoint is closed for send")
	ErrClosedForReceive     = errors.New("endpoint is closed for receive")
	ErrWouldBlock           = errors.New("operation would block")
	ErrConnectionRefused    = errors.New("connection was refused")
	ErrTimeout              = errors.New("operation timed out")
	ErrAborted              = errors.New("operation aborted")
	ErrConnectStarted       = errors.New("connection attempt started")
	ErrDestinationRequired  = errors.New("destination address is required")
	ErrNotSupported         = errors.New("operation not supported")
	ErrNotConnected         = errors.New("endpoint not connected")
	ErrConnectionReset      = errors.New("connection reset by peer")
	ErrConnectionAborted    = errors.New("connection aborted")
)

Errors that can be returned by the network stack.

Types

type Address

type Address string

Address is a byte slice cast as a string that represents the address of a network node. Or, in the case of unix endpoints, it may represent a path

func (Address) String

func (a Address) String() string

String implements the fmt.Stringer interface.

type ControlMessages

type ControlMessages interface {
	// Release releases any resources owned by the control message.
	Release()

	// CloneCreds returns a copy of any credentials (if any) contained in the
	// ControlMessages.
	CloneCreds() ControlMessages
}

A ControlMessages represents a collection of socket control messages.

type Endpoint

type Endpoint interface {
	// Close puts the endpoint in a closed state and frees all resources
	// associated with it.
	Close()

	// Read reads data from the endpoint and optionally returns the sender.
	// This method does not block if there is no data pending.
	// It will also either return an error or data, never both.
	Read(*FullAddress) (buffer.View, error)

	// Write writes data to the endpoint's peer, or the provided address if
	// one is specified. This method does not block if the data cannot be
	// written.
	Write(buffer.View, *FullAddress) (uintptr, error)

	// RecvMsg reads data and a control message from the endpoint. This method
	// does not block if there is no data pending.
	RecvMsg(*FullAddress) (buffer.View, ControlMessages, error)

	// SendMsg writes data and a control message to the endpoint's peer.
	// This method does not block if the data cannot be written.
	//
	// SendMsg does not take ownership of any of its arguments on error.
	SendMsg(buffer.View, ControlMessages, *FullAddress) (uintptr, error)

	// Peek reads data without consuming it from the endpoint.
	//
	// This method does not block if there is no data pending.
	Peek(io.Writer) (uintptr, error)

	// Connect connects the endpoint to its peer. Specifying a NIC is
	// optional.
	//
	// There are three classes of return values:
	//	nil -- the attempt to connect succeeded.
	//	ErrConnectStarted -- the connect attempt started but hasn't
	//		completed yet. In this case, the actual result will
	//		become available via GetSockOpt(ErrorOption) when
	//		the endpoint becomes writable. (This mimics the
	//		connect(2) syscall behavior.)
	//	Anything else -- the attempt to connect failed.
	Connect(address FullAddress) error

	// ConnectEndpoint connects this endpoint directly to another.
	//
	// This should be called on the client endpoint, and the (bound)
	// endpoint passed in as a parameter.
	//
	// The error codes are the same as Connect.
	ConnectEndpoint(server Endpoint) error

	// Shutdown closes the read and/or write end of the endpoint connection
	// to its peer.
	Shutdown(flags ShutdownFlags) error

	// Listen puts the endpoint in "listen" mode, which allows it to accept
	// new connections.
	Listen(backlog int) error

	// Accept returns a new endpoint if a peer has established a connection
	// to an endpoint previously set to listen mode. This method does not
	// block if no new connections are available.
	//
	// The returned Queue is the wait queue for the newly created endpoint.
	Accept() (Endpoint, *waiter.Queue, error)

	// Bind binds the endpoint to a specific local address and port.
	// Specifying a NIC is optional.
	//
	// An optional commit function will be executed atomically with respect
	// to binding the endpoint. If this returns an error, the bind will not
	// occur and the error will be propagated back to the caller.
	Bind(address FullAddress, commit func() error) error

	// GetLocalAddress returns the address to which the endpoint is bound.
	GetLocalAddress() (FullAddress, error)

	// GetRemoteAddress returns the address to which the endpoint is
	// connected.
	GetRemoteAddress() (FullAddress, error)

	// Readiness returns the current readiness of the endpoint. For example,
	// if waiter.EventIn is set, the endpoint is immediately readable.
	Readiness(mask waiter.EventMask) waiter.EventMask

	// SetSockOpt sets a socket option.
	SetSockOpt(interface{}) error

	// GetSockOpt gets a socket option.
	GetSockOpt(interface{}) error
}

Endpoint is the interface implemented by transport protocols (e.g., tcp, udp) that exposes functionality like read, write, connect, etc. to users of the networking stack.

type ErrorOption

type ErrorOption struct{}

ErrorOption is used in GetSockOpt to specify that the last error reported by the endpoint should be cleared and returned

type FullAddress

type FullAddress struct {
	// NIC is the ID of the NIC this address refers to.
	//
	// This may not be used by all endpoint types.
	NIC NICID

	// Addr is the network address.
	Addr Address

	// Port is the transport port.
	//
	// This may not be used by all endpoint types.
	Port uint16
}

FullAddress represents a full transport node address, as required by the Connect() and Bind() methods

type LinkEndpointID

type LinkEndpointID uint64

LinkEndpointID represents a data link layer endpoint.

type NICID

type NICID int32

NICID is a number that uniquely identifies a NIC

type NetworkProtocolNumber

type NetworkProtocolNumber uint32

NetworkProtocolNumber is the number of a network protocol.

type NoDelayOption

type NoDelayOption int

NoDelayOption is used by SetSockOpt/GetSockOpt to specify if data should be sent out immediately by the transport protocol. For TCP, it determines if the Nagle algorithm is on or off.

type PasscredOption

type PasscredOption int32

PasscredOption is used by SetSockOpt/GetSockOpt to specify whether SCM_CREDENTIALS socket control messages are enabled.

Only supported on Unix sockets.

type ReceiveBufferSizeOption

type ReceiveBufferSizeOption int

ReceiveBufferSizeOption is used by SetSockOpt/GetSockOpt to specify the receive buffer size option.

type ReceiveQueueSizeOption

type ReceiveQueueSizeOption int

ReceiveQueueSizeOption is used in GetSockOpt to specify that the number of unread bytes in the input buffer should be returned.

type ReuseAddressOption

type ReuseAddressOption int

ReuseAddressOption is used by SetSockOpt/GetSockOpt to specify whether Bind() should allow reuse of local address.

type Route

type Route struct {
	// Destination is the address that must be matched against the masked
	// target address to check if this row is viable.
	Destination Address

	// Mask specifies which bits of the Destination and the target address
	// must match for this row to be viable.
	Mask Address

	// Gateway is the gateway to be used if this row is viable.
	Gateway Address

	// NIC is the id of the nic to be used if this row is viable.
	NIC NICID
}

Route is a row in the routing table. It specifies through which NIC (and gateway) sets of packets should be routed. A row is considered viable if the masked target address matches the destination adddress in the row.

func (*Route) Match

func (r *Route) Match(addr Address) bool

Match determines if r is viable for the given destination address.

type SendBufferSizeOption

type SendBufferSizeOption int

SendBufferSizeOption is used by SetSockOpt/GetSockOpt to specify the send buffer size option

type ShutdownFlags

type ShutdownFlags int

ShutdownFlags represents flags that can be passed to the Shutdown() method of the Endpoint interface

const (
	ShutdownRead ShutdownFlags = 1 << iota
	ShutdownWrite
)

Values of the flags that can be passed to the Shutdown() method. They can be OR'ed together

type Stack

type Stack interface {
	// NewEndpoint creates a new transport layer endpoint of the given
	// protocol.
	NewEndpoint(transport TransportProtocolNumber, network NetworkProtocolNumber, waiterQueue *waiter.Queue) (Endpoint, error)

	// SetRouteTable assigns the route table to be used by this stack. It
	// specifies which NICs to use for given destination address ranges.
	SetRouteTable(table []Route)

	// CreateNIC creates a NIC with the provided id and link-layer sender.
	CreateNIC(id NICID, linkEndpoint LinkEndpointID) error

	// AddAddress adds a new network-layer address to the specified NIC.
	AddAddress(id NICID, protocol NetworkProtocolNumber, addr Address) error

	// Stats returns a snapshot of the current stats.
	Stats() Stats
}

Stack represents a networking stack, with all supported protocols, NICs, and route table.

type Stats

type Stats struct {
	// UnkownProtocolRcvdPackets is the number of packets received by the
	// stack that were for an unknown or unsupported protocol.
	UnknownProtocolRcvdPackets uint64

	// UnknownNetworkEndpointRcvdPackets is the number of packets received
	// by the stack that were for a supported network protocol, but whose
	// destination address didn't having a matching endpoint.
	UnknownNetworkEndpointRcvdPackets uint64

	// MalformedRcvPackets is the number of packets received by the stack
	// that were deemed malformed.
	MalformedRcvdPackets uint64
}

Stats holds statistics about the networking stack.

type TransportProtocolNumber

type TransportProtocolNumber uint32

TransportProtocolNumber is the number of a transport protocol.