helpers

package
v0.3.15 Latest Latest
Warning

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

 Go to latest Published: May 3, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package helpers provides utility functions and types for working with gVisor's netstack. It includes helpers for creating and managing network interfaces, converting between address formats, wrapping netstack errors to implement the error interface, and managing NIC (Network Interface Card) creation.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSack is returned when setting TCP SACK (Selective Acknowledgment) fails.
	ErrSack = errors.New("set tcp sack")
	// ErrNIC is returned when creating a network interface card fails.
	ErrNIC = errors.New("create nic")
	// ErrNewAddr is returned when adding a protocol address fails.
	ErrNewAddr = errors.New("add protocol address")
	// ErrProm is returned when setting promiscuous mode fails.
	ErrProm = errors.New("set promiscuous mode")
	// ErrNotTCP is returned when a connection is expected to be TCP but is not.
	ErrNotTCP = errors.New("not a tcp conn")
	// ErrNotUDP is returned when a connection is expected to be UDP but is not.
	ErrNotUDP = errors.New("not a udp conn")
	// ErrUp is returned when bringing the stack up fails.
	ErrUp = errors.New("bring stack up")
	// ErrDown is returned when bringing the stack down fails.
	ErrDown = errors.New("bring stack down")
)

Functions

func AddrPortFromString 

func AddrPortFromString(hostport string) (netip.AddrPort, error)

func ConvertToFullAddr 

func ConvertToFullAddr(endpoint netip.AddrPort) (tcpip.FullAddress, tcpip.NetworkProtocolNumber)

ConvertToFullAddr converts a netip.AddrPort to a tcpip.FullAddress and the corresponding network protocol number (IPv4 or IPv6).

func CreateNIC 

func CreateNIC(st *stack.Stack, id *tcpip.NICID, ep stack.LinkEndpoint) (tcpip.NICID, error)

CreateNIC creates a network interface card (NIC) on the given stack. If id is nil, it generates a new NIC ID automatically. Returns the NIC ID and any error that occurred during creation.

func NIC2Iface 

func NIC2Iface(id tcpip.NICID, info stack.NICInfo) gonnect.NetworkInterface

NIC2Iface converts a gVisor NIC ID and its associated information into a gonnect.NetworkInterface implementation. It extracts protocol addresses (IPv4/IPv6) and populates the interface with standard network properties.

func WrapErr 

func WrapErr(err error, ne NetstackErr) error

WrapErr wraps a netstack error with a standard error to create a joined error. If either err or ne is nil, it returns nil.

Types

type NetstackErr 

type NetstackErr interface {
	String() string
}

NetstackErr is an interface for netstack error types that do not implement the standard error interface. It provides a String() method to retrieve the error message.

type Opts 

type Opts struct {
	// MTU specifies the maximum transmission unit size. Defaults to 1500 if not set.
	MTU int

	// DisableSACK disables TCP Selective Acknowledgment when set to true.
	DisableSACK bool

	// IPAlloc provides IP address allocation for the network interfaces.
	IPAlloc subnet.IPAllocator
}

Opts contains configuration options for building a gVisor netstack.

func (*Opts) BuildStack 

func (o *Opts) BuildStack(local bool) (*stack.Stack, error)

BuildStack creates and configures a new gVisor network stack with IPv4, IPv6, TCP, UDP, and ICMP protocols enabled. It applies the configured options for TCP SACK and returns the initialized stack.

func (*Opts) GetIPAlloc 

func (o *Opts) GetIPAlloc() subnet.IPAllocator

GetIPAlloc returns the configured IP allocator, or creates a new random one if not set.

func (*Opts) GetMTU 

func (o *Opts) GetMTU() int

GetMTU returns the configured MTU value, or the default value of 1500 if not set.

type TCPConn 

type TCPConn struct {
	*gonet.TCPConn
	Laddr, Raddr net.Addr
}

TCPConn wraps a gonet.TCPConn and implements the gonnect.TCPConn interface. It provides methods for reading, writing, and configuring TCP connection parameters (though most configuration methods are no-ops for this implementation).

func (*TCPConn) LocalAddr added in v0.3.7 

func (t *TCPConn) LocalAddr() net.Addr

func (*TCPConn) ReadFrom 

func (t *TCPConn) ReadFrom(r io.Reader) (int64, error)

ReadFrom copies data from the provided reader to the TCP connection.

func (*TCPConn) RemoteAddr added in v0.3.7 

func (t *TCPConn) RemoteAddr() net.Addr

func (*TCPConn) SetKeepAlive 

func (t *TCPConn) SetKeepAlive(keepalive bool) error

SetKeepAlive enables or disables TCP keep-alive (no-op for this implementation).

func (*TCPConn) SetKeepAliveConfig 

func (t *TCPConn) SetKeepAliveConfig(config net.KeepAliveConfig) error

SetKeepAliveConfig configures TCP keep-alive parameters (no-op for this implementation).

func (*TCPConn) SetKeepAlivePeriod 

func (t *TCPConn) SetKeepAlivePeriod(d time.Duration) error

SetKeepAlivePeriod sets the TCP keep-alive period (no-op for this implementation).

func (*TCPConn) SetLinger 

func (t *TCPConn) SetLinger(sec int) error

SetLinger sets the linger behavior for socket close (no-op for this implementation).

func (*TCPConn) SetNoDelay 

func (t *TCPConn) SetNoDelay(noDelay bool) error

SetNoDelay enables or disables Nagle's algorithm (no-op for this implementation).

func (*TCPConn) WriteTo 

func (t *TCPConn) WriteTo(w io.Writer) (int64, error)

WriteTo copies data from the TCP connection to the provided writer.

type TCPListener 

type TCPListener struct {
	*gonet.TCPListener
	Address net.Addr
}

TCPListener wraps a gonet.TCPListener and implements the gonnect.TCPListener interface. It provides methods for accepting TCP connections.

func (*TCPListener) Accept 

func (l *TCPListener) Accept() (net.Conn, error)

Accept accepts the next incoming connection and returns it wrapped as a TCPConn.

func (*TCPListener) AcceptTCP 

func (l *TCPListener) AcceptTCP() (gonnect.TCPConn, error)

AcceptTCP accepts the next incoming TCP connection and returns it.

func (*TCPListener) Addr added in v0.3.7 

func (l *TCPListener) Addr() net.Addr

func (*TCPListener) SetDeadline 

func (l *TCPListener) SetDeadline(t time.Time) error

type UDPConn 

type UDPConn struct {
	*gonet.UDPConn
	Laddr, Raddr net.Addr
}

UDPConn wraps a gonet.UDPConn and implements the gonnect.UDPConn interface. It provides methods for reading and writing UDP packets with various address formats (net.UDPAddr and netip.AddrPort).

func (*UDPConn) LocalAddr added in v0.3.7 

func (u *UDPConn) LocalAddr() net.Addr

func (*UDPConn) ReadFromUDP 

func (u *UDPConn) ReadFromUDP(b []byte) (n int, addr *net.UDPAddr, err error)

ReadFromUDP reads a UDP packet and returns the number of bytes read, the remote address, and any error that occurred.

func (*UDPConn) ReadFromUDPAddrPort 

func (u *UDPConn) ReadFromUDPAddrPort(b []byte) (n int, addr netip.AddrPort, err error)

ReadFromUDPAddrPort reads a UDP packet and returns the number of bytes read, the remote address as a netip.AddrPort, and any error that occurred.

func (*UDPConn) ReadMsgUDP 

func (u *UDPConn) ReadMsgUDP(b, oob []byte) (n, oobn, flags int, addr *net.UDPAddr, err error)

ReadMsgUDP reads a UDP packet with out-of-band data and returns the number of bytes read, out-of-band bytes read, flags, remote address, and any error. Note: Out-of-band data is not supported.

func (*UDPConn) ReadMsgUDPAddrPort 

func (u *UDPConn) ReadMsgUDPAddrPort(
	b, oob []byte,
) (n, oobn, flags int, addr netip.AddrPort, err error)

ReadMsgUDPAddrPort reads a UDP packet with out-of-band data and returns the number of bytes read, out-of-band bytes read, flags, remote address as netip.AddrPort, and any error. Note: Out-of-band data is not supported.

func (*UDPConn) RemoteAddr added in v0.3.7 

func (u *UDPConn) RemoteAddr() net.Addr

func (*UDPConn) WriteMsgUDP 

func (u *UDPConn) WriteMsgUDP(b, oob []byte, addr *net.UDPAddr) (n, oobn int, err error)

WriteMsgUDP writes a UDP packet with optional out-of-band data to the specified remote address. Note: Out-of-band data is not supported and will return an error if provided.

func (*UDPConn) WriteMsgUDPAddrPort 

func (u *UDPConn) WriteMsgUDPAddrPort(
	b, oob []byte,
	addr netip.AddrPort,
) (n, oobn int, err error)

WriteMsgUDPAddrPort writes a UDP packet with optional out-of-band data to the specified remote address given as netip.AddrPort. Note: Out-of-band data is not supported and will return an error if provided.

func (*UDPConn) WriteToUDP 

func (u *UDPConn) WriteToUDP(b []byte, addr *net.UDPAddr) (int, error)

WriteToUDP writes a UDP packet to the specified remote address.

func (*UDPConn) WriteToUDPAddrPort 

func (u *UDPConn) WriteToUDPAddrPort(b []byte, addr netip.AddrPort) (int, error)

WriteToUDPAddrPort writes a UDP packet to the specified remote address given as a netip.AddrPort.

Source Files

View all Source files

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.