tcpip

package
v0.0.0-...-23e6066 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2018 License: Apache-2.0 Imports: 7 Imported by: 0

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. A stack can be created by calling the New() function of the tcpip/stack/stack package; configuring a stack involves creating NICs (via calls to Stack.CreateNIC()), adding network addresses (via calls to Stack.AddAddress()), and 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

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnknownProtocol       = &Error{"unknown protocol"}
	ErrUnknownNICID          = &Error{"unknown nic id"}
	ErrUnknownProtocolOption = &Error{"unknown option for protocol"}
	ErrDuplicateNICID        = &Error{"duplicate nic id"}
	ErrDuplicateAddress      = &Error{"duplicate address"}
	ErrNoRoute               = &Error{"no route"}
	ErrBadLinkEndpoint       = &Error{"bad link layer endpoint"}
	ErrAlreadyBound          = &Error{"endpoint already bound"}
	ErrInvalidEndpointState  = &Error{"endpoint is in invalid state"}
	ErrAlreadyConnecting     = &Error{"endpoint is already connecting"}
	ErrAlreadyConnected      = &Error{"endpoint is already connected"}
	ErrNoPortAvailable       = &Error{"no ports are available"}
	ErrPortInUse             = &Error{"port is in use"}
	ErrBadLocalAddress       = &Error{"bad local address"}
	ErrClosedForSend         = &Error{"endpoint is closed for send"}
	ErrClosedForReceive      = &Error{"endpoint is closed for receive"}
	ErrWouldBlock            = &Error{"operation would block"}
	ErrConnectionRefused     = &Error{"connection was refused"}
	ErrTimeout               = &Error{"operation timed out"}
	ErrAborted               = &Error{"operation aborted"}
	ErrConnectStarted        = &Error{"connection attempt started"}
	ErrDestinationRequired   = &Error{"destination address is required"}
	ErrNotSupported          = &Error{"operation not supported"}
	ErrQueueSizeNotSupported = &Error{"queue size querying not supported"}
	ErrNotConnected          = &Error{"endpoint not connected"}
	ErrConnectionReset       = &Error{"connection reset by peer"}
	ErrConnectionAborted     = &Error{"connection aborted"}
	ErrNoSuchFile            = &Error{"no such file"}
	ErrInvalidOptionValue    = &Error{"invalid option value specified"}
	ErrNoLinkAddress         = &Error{"no remote link address"}
	ErrBadAddress            = &Error{"bad address"}
)

Errors that can be returned by the network stack.

Functions

This section is empty.

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.

func (Address) To4 

func (a Address) To4() Address

To4 converts the IPv4 address to a 4-byte representation. If the address is not an IPv4 address, To4 returns "".

type AddressMask 

type AddressMask string

AddressMask is a bitmask for an address.

type Clock 

type Clock interface {
	// NowNanoseconds returns the current real time as a number of
	// nanoseconds since some epoch.
	NowNanoseconds() int64
}

A Clock provides the current time.

Times returned by a Clock should always be used for application-visible time, but never for netstack internal timekeeping.

type ControlMessages 

type ControlMessages struct {
	// HasTimestamp indicates whether Timestamp is valid/set.
	HasTimestamp bool

	// Timestamp is the time (in ns) that the last packed used to create
	// the read data was received.
	Timestamp int64
}

A ControlMessages contains socket control messages for IP sockets.

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.
	//
	// A timestamp (in ns) is optionally returned. A zero value indicates
	// that no timestamp was available.
	Read(*FullAddress) (buffer.View, ControlMessages, *Error)

	// Write writes data to the endpoint's peer. This method does not block if
	// the data cannot be written.
	//
	// Unlike io.Writer.Write, Endpoint.Write transfers ownership of any bytes
	// successfully written to the Endpoint. That is, if a call to
	// Write(SlicePayload{data}) returns (n, err), it may retain data[:n], and
	// the caller should not use data[:n] after Write returns.
	//
	// Note that unlike io.Writer.Write, it is not an error for Write to
	// perform a partial write.
	Write(Payload, WriteOptions) (uintptr, *Error)

	// Peek reads data without consuming it from the endpoint.
	//
	// This method does not block if there is no data pending.
	//
	// A timestamp (in ns) is optionally returned. A zero value indicates
	// that no timestamp was available.
	Peek([][]byte) (uintptr, ControlMessages, *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/ErrAlreadyConnecting -- the connect attempt started
	//		but hasn't completed yet. In this case, the caller must call Connect
	//		or GetSockOpt(ErrorOption) when the endpoint becomes writable to
	//		get the actual result. The first call to Connect after the socket has
	//		connected returns nil. Calling connect again results in ErrAlreadyConnected.
	//	Anything else -- the attempt to connect failed.
	Connect(address FullAddress) *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. opt should be one of the *Option types.
	SetSockOpt(opt interface{}) *Error

	// GetSockOpt gets a socket option. opt should be a pointer to one of the
	// *Option types.
	GetSockOpt(opt 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 Error 

type Error struct {
	// contains filtered or unexported fields
}

Error represents an error in the netstack error space. Using a special type ensures that errors outside of this space are not accidentally introduced.

func (*Error) String 

func (e *Error) String() string

String implements fmt.Stringer.String.

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 LinkAddress 

type LinkAddress string

LinkAddress is a byte slice cast as a string that represents a link address. It is typically a 6-byte MAC address.

func ParseMACAddress 

func ParseMACAddress(s string) (LinkAddress, error)

ParseMACAddress parses an IEEE 802 address.

It must be in the format aa:bb:cc:dd:ee:ff or aa-bb-cc-dd-ee-ff.

func (LinkAddress) String 

func (a LinkAddress) String() string

String implements the fmt.Stringer interface.

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 int

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

Only supported on Unix sockets.

type Payload 

type Payload interface {
	// Get returns a slice containing exactly 'min(size, p.Size())' bytes.
	Get(size int) ([]byte, *Error)

	// Size returns the payload size.
	Size() int
}

Payload provides an interface around data that is being sent to an endpoint. This allows the endpoint to request the amount of data it needs based on internal buffers without exposing them. 'p.Get(p.Size())' reads all the data.

type ProtocolAddress 

type ProtocolAddress struct {
	// Protocol is the protocol of the address.
	Protocol NetworkProtocolNumber

	// Address is a network address.
	Address Address
}

ProtocolAddress is an address and the network protocol it is associated with.

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 SendQueueSizeOption 

type SendQueueSizeOption int

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

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 SlicePayload 

type SlicePayload []byte

SlicePayload implements Payload on top of slices for convenience.

func (SlicePayload) Get 

func (s SlicePayload) Get(size int) ([]byte, *Error)

Get implements Payload.

func (SlicePayload) Size 

func (s SlicePayload) Size() int

Size implements Payload.

type Stats 

type Stats struct {
	// UnknownProtocolRcvdPackets 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

	// DroppedPackets is the number of packets dropped due to full queues.
	DroppedPackets uint64
}

Stats holds statistics about the networking stack.

type StdClock 

type StdClock struct{}

StdClock implements Clock with the time package.

func (*StdClock) NowNanoseconds 

func (*StdClock) NowNanoseconds() int64

NowNanoseconds implements Clock.NowNanoseconds.

type Subnet 

type Subnet struct {
	// contains filtered or unexported fields
}

Subnet is a subnet defined by its address and mask.

func NewSubnet 

func NewSubnet(a Address, m AddressMask) (Subnet, error)

NewSubnet creates a new Subnet, checking that the address and mask are the same length.

func (*Subnet) Bits 

func (s *Subnet) Bits() (ones int, zeros int)

Bits returns the number of ones (network bits) and zeros (host bits) in the subnet mask.

func (*Subnet) Contains 

func (s *Subnet) Contains(a Address) bool

Contains returns true iff the address is of the same length and matches the subnet address and mask.

func (*Subnet) ID 

func (s *Subnet) ID() Address

ID returns the subnet ID.

func (*Subnet) Prefix 

func (s *Subnet) Prefix() int

Prefix returns the number of bits before the first host bit.

type TCPInfoOption 

type TCPInfoOption struct{}

TCPInfoOption is used by GetSockOpt to expose TCP statistics.

TODO: Add and populate stat fields.

type TimestampOption 

type TimestampOption int

TimestampOption is used by SetSockOpt/GetSockOpt to specify whether SO_TIMESTAMP socket control messages are enabled.

type TransportProtocolNumber 

type TransportProtocolNumber uint32

TransportProtocolNumber is the number of a transport protocol.

type V6OnlyOption 

type V6OnlyOption int

V6OnlyOption is used by SetSockOpt/GetSockOpt to specify whether an IPv6 socket is to be restricted to sending and receiving IPv6 packets only.

type WriteOptions 

type WriteOptions struct {
	// If To is not nil, write to the given address instead of the endpoint's
	// peer.
	To *FullAddress

	// More has the same semantics as Linux's MSG_MORE.
	More bool

	// EndOfRecord has the same semantics as Linux's MSG_EOR.
	EndOfRecord bool
}

WriteOptions contains options for Endpoint.Write.

Source Files

View all Source files

Directories

Path Synopsis
adapters
gonet
Package gonet provides a Go net package compatible wrapper for a tcpip stack.
 Package gonet provides a Go net package compatible wrapper for a tcpip stack.
Package buffer provides the implementation of a buffer view.
 Package buffer provides the implementation of a buffer view.
Package checker provides helper functions to check networking packets for validity.
 Package checker provides helper functions to check networking packets for validity.
Package header provides the implementation of the encoding and decoding of network protocol headers.
 Package header provides the implementation of the encoding and decoding of network protocol headers.
link
channel
Package channel provides the implemention of channel-based data-link layer endpoints.
 Package channel provides the implemention of channel-based data-link layer endpoints.
fdbased
Package fdbased provides the implemention of data-link layer endpoints backed by boundary-preserving file descriptors (e.g., TUN devices, seqpacket/datagram sockets).
 Package fdbased provides the implemention of data-link layer endpoints backed by boundary-preserving file descriptors (e.g., TUN devices, seqpacket/datagram sockets).
loopback
Package loopback provides the implemention of loopback data-link layer endpoints.
 Package loopback provides the implemention of loopback data-link layer endpoints.
rawfile
Package rawfile contains utilities for using the netstack with raw host files on Linux hosts.
 Package rawfile contains utilities for using the netstack with raw host files on Linux hosts.
sharedmem
Package sharedmem provides the implemention of data-link layer endpoints backed by shared memory.
 Package sharedmem provides the implemention of data-link layer endpoints backed by shared memory.
sharedmem/pipe
Package pipe implements a shared memory ring buffer on which a single reader and a single writer can operate (read/write) concurrently.
 Package pipe implements a shared memory ring buffer on which a single reader and a single writer can operate (read/write) concurrently.
sharedmem/queue
Package queue provides the implementation of transmit and receive queues based on shared memory ring buffers.
 Package queue provides the implementation of transmit and receive queues based on shared memory ring buffers.
sniffer
Package sniffer provides the implementation of data-link layer endpoints that wrap another endpoint and logs inbound and outbound packets.
 Package sniffer provides the implementation of data-link layer endpoints that wrap another endpoint and logs inbound and outbound packets.
tun
Package tun contains methods to open TAP and TUN devices.
 Package tun contains methods to open TAP and TUN devices.
waitable
Package waitable provides the implementation of data-link layer endpoints that wrap other endpoints, and can wait for inflight calls to WritePacket or DeliverNetworkPacket to finish (and new ones to be prevented).
 Package waitable provides the implementation of data-link layer endpoints that wrap other endpoints, and can wait for inflight calls to WritePacket or DeliverNetworkPacket to finish (and new ones to be prevented).
network
arp
Package arp implements the ARP network protocol.
 Package arp implements the ARP network protocol.
fragmentation
Package fragmentation contains the implementation of IP fragmentation.
 Package fragmentation contains the implementation of IP fragmentation.
hash
Package hash contains utility functions for hashing.
 Package hash contains utility functions for hashing.
ipv4
Package ipv4 contains the implementation of the ipv4 network protocol.
 Package ipv4 contains the implementation of the ipv4 network protocol.
ipv6
Package ipv6 contains the implementation of the ipv6 network protocol.
 Package ipv6 contains the implementation of the ipv6 network protocol.
Package ports provides PortManager that manages allocating, reserving and releasing ports.
 Package ports provides PortManager that manages allocating, reserving and releasing ports.
sample
tun_tcp_connect
This sample creates a stack with TCP and IPv4 protocols on top of a TUN device, and connects to a peer.
 This sample creates a stack with TCP and IPv4 protocols on top of a TUN device, and connects to a peer.
tun_tcp_echo
This sample creates a stack with TCP and IPv4 protocols on top of a TUN device, and listens on a port.
 This sample creates a stack with TCP and IPv4 protocols on top of a TUN device, and listens on a port.
Package seqnum defines the types and methods for TCP sequence numbers such that they fit in 32-bit words and work properly when overflows occur.
 Package seqnum defines the types and methods for TCP sequence numbers such that they fit in 32-bit words and work properly when overflows occur.
Package stack provides the glue between networking protocols and the consumers of the networking stack.
 Package stack provides the glue between networking protocols and the consumers of the networking stack.
transport
ping
Package ping contains the implementation of the ICMP and IPv6-ICMP transport protocols for use in ping.
 Package ping contains the implementation of the ICMP and IPv6-ICMP transport protocols for use in ping.
queue
Package queue provides the implementation of buffer queue and interface of queue entry with Length method.
 Package queue provides the implementation of buffer queue and interface of queue entry with Length method.
tcp
Package tcp contains the implementation of the TCP transport protocol.
 Package tcp contains the implementation of the TCP transport protocol.
tcp/testing/context
Package context provides a test context for use in tcp tests.
 Package context provides a test context for use in tcp tests.
tcpconntrack
Package tcpconntrack implements a TCP connection tracking object.
 Package tcpconntrack implements a TCP connection tracking object.
udp
Package udp contains the implementation of the UDP transport protocol.
 Package udp contains the implementation of the UDP transport protocol.
unix
Package unix contains the implementation of Unix endpoints.
 Package unix contains the implementation of Unix endpoints.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.