network

package module
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2024 License: MPL-2.0 Imports: 45 Imported by: 6

README

Network

Network is a Go package that provides a host independent abstraction for network operations. It is designed to be used as a drop-in replacement for the Go net package, allowing it to be used with existing networking code.

This is implemented using a userspace TCP/IP stack based on Netstack from the gVisor project.

Part of the Noisy Sockets project.

Usage

Example usage of the package can be found in the examples directory.

Documentation

Overview

Package network provides a host independent abstraction for network operations.

Index

Constants

View Source 
const MaxPacketSize = 65535

MaxPacketSize is the maximum size of an IP packet.

Variables

View Source 
var (
	ErrInvalidPort           = errors.New("invalid port")
	ErrMissingAddress        = errors.New("missing address")
	ErrNoSuitableAddress     = errors.New("no suitable address found")
	ErrUnexpectedAddressType = errors.New("unexpected address type")
)

Functions

func IsStackClosed added in v0.4.1 

func IsStackClosed(err error) bool

IsStackClosed checks if the error is due to the network stack being closed. This is relevant to errors returned by the userspace network stack.

func Pipe 

func Pipe(conf *PipeConfiguration) (Interface, Interface)

Pipe creates a pair of connected interfaces that can be used to simulate a network connection. This is similar to a linux veth device.

func Splice added in v0.18.0 

func Splice(ctx context.Context, nicA, nicB Interface, conf *SpliceConfiguration) error

Splice splices (bidirectional copy) two network interfaces together.

Types

type DialContextFunc added in v0.3.0 

type DialContextFunc func(ctx context.Context, network, address string) (stdnet.Conn, error)

DialContextFunc is a function that dials a network address using a context.

type Forwarder added in v0.6.0 

type Forwarder interface {
	// TCPProtocolHandler forwards a TCP session.
	TCPProtocolHandler(id stack.TransportEndpointID, pkt *stack.PacketBuffer) bool
	// UDPProtocolHandler forwards a UDP session.
	UDPProtocolHandler(id stack.TransportEndpointID, pkt *stack.PacketBuffer) bool
	// ICMPProtocolHandler forwards an ICMP session.
	ICMPv4ProtocolHandler(id stack.TransportEndpointID, pkt *stack.PacketBuffer) bool
	// ICMPv6ProtocolHandler forwards an ICMPv6 session.
	ICMPv6ProtocolHandler(id stack.TransportEndpointID, pkt *stack.PacketBuffer) bool
	// ValidDestination checks if the destination address is valid for forwarding.
	ValidDestination(addr netip.Addr) bool
}

Forwarders can be used to forward sessions between networks.

type HostNetwork 

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

func Host 

func Host() *HostNetwork

Host returns a Network implementation that uses the standard library's network operations.

func (*HostNetwork) Close 

func (net *HostNetwork) Close() error

func (*HostNetwork) Dial 

func (net *HostNetwork) Dial(network, address string) (stdnet.Conn, error)

func (*HostNetwork) DialContext 

func (net *HostNetwork) DialContext(ctx context.Context, network, address string) (stdnet.Conn, error)

func (*HostNetwork) Domain added in v0.5.0 

func (net *HostNetwork) Domain() (string, error)

func (*HostNetwork) Hostname 

func (net *HostNetwork) Hostname() (string, error)

func (*HostNetwork) InterfaceAddrs 

func (net *HostNetwork) InterfaceAddrs() ([]stdnet.Addr, error)

func (*HostNetwork) Listen 

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

func (*HostNetwork) ListenPacket 

func (net *HostNetwork) ListenPacket(network, address string) (stdnet.PacketConn, error)

func (*HostNetwork) LookupHost 

func (net *HostNetwork) LookupHost(host string) ([]string, error)

func (*HostNetwork) LookupHostContext 

func (net *HostNetwork) LookupHostContext(ctx context.Context, host string) ([]string, error)

func (*HostNetwork) Ping added in v0.9.0 

func (net *HostNetwork) Ping(ctx context.Context, network, host string) error

type Interface 

type Interface interface {
	io.Closer

	// MTU returns the Maximum Transmission Unit of the interface.
	MTU() (int, error)

	// BatchSize returns the preferred/max number of packets that can be read or
	// written in a single read/write call.
	BatchSize() int

	// Read one or more packets from the interface (without any additional headers).
	// On a successful read it returns a slice of packets of up-to length batchSize.
	// The caller is responsible for releasing the packets back to the pool. The
	// caller can optionally supply an unallocated packets slice (eg. from a
	// previous call to Read()) that will be used to store the read packets.
	// This allows avoiding allocating a new packets slice on each read.
	Read(ctx context.Context, packets []*Packet, offset int) ([]*Packet, error)

	// Write one or more packets to the interface (without any additional headers).
	// Ownership of the packets is transferred to the interface and must not be
	// accessed after a write operation.
	Write(ctx context.Context, packets []*Packet) error
}

Interface is a network interface.

type Network 

type Network interface {
	io.Closer
	// Hostname returns the hostname of the local machine.
	Hostname() (string, error)
	// Domain returns the domain of the local machine.
	Domain() (string, error)
	// InterfaceAddrs returns a list of the network interfaces addresses.
	InterfaceAddrs() ([]stdnet.Addr, error)
	// LookupHost looks up the IP addresses for the given host.
	LookupHost(host string) ([]string, error)
	// LookupHostContext looks up the IP addresses for the given host.
	LookupHostContext(ctx context.Context, host string) ([]string, error)
	// Dial connects to the address on the named network.
	// Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only), "udp", "udp4" (IPv4-only), "udp6" (IPv6-only).
	Dial(network, address string) (stdnet.Conn, error)
	// DialContext connects to the address on the named network using the provided context.
	DialContext(ctx context.Context, network, address string) (stdnet.Conn, error)
	// Listen listens for incoming connections on the network address.
	// Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only).
	// If the address is an empty string, Listen listens on all available addresses.
	Listen(network, address string) (stdnet.Listener, error)
	// ListenPacket listens for incoming packets addressed to the local address.
	// Known networks are "udp", "udp4" (IPv4-only), "udp6" (IPv6-only).
	ListenPacket(network, address string) (stdnet.PacketConn, error)
	// Ping sends an ICMP echo request to the given host.
	// Network must be "ip", "ip4" (IPv4-only), "ip6" (IPv6-only).
	Ping(ctx context.Context, network, host string) error
}

Network is an interface that abstracts a superset of the standard library's network operations.

type Packet added in v0.13.0 

type Packet struct {
	// Buf is the buffer containing the packet data.
	Buf [MaxPacketSize]byte
	// Offset is the offset inside the buffer where the packet data starts.
	Offset int
	// Size is the size of the packet data.
	Size int
	// contains filtered or unexported fields
}

Packet represents an IP packet.

func (*Packet) Bytes added in v0.15.0 

func (p *Packet) Bytes() []byte

Bytes returns the packet data as a byte slice.

func (*Packet) MoveOffset added in v0.17.0 

func (p *Packet) MoveOffset(offset int)

MoveOffset moves the packet data to a new offset inside the buffer. This can be a potentially expensive operation.

func (*Packet) Release added in v0.13.0 

func (p *Packet) Release()

Release returns the packet to its pool.

func (*Packet) Reset added in v0.13.0 

func (p *Packet) Reset()

Reset resets the packet.

type PacketPool added in v0.16.0 

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

func NewPacketPool added in v0.16.0 

func NewPacketPool(max int, debug bool) *PacketPool

NewPacketPool creates a new packet pool with the given maximum number of packets.

func (*PacketPool) Borrow added in v0.16.0 

func (p *PacketPool) Borrow() *Packet

func (*PacketPool) Count added in v0.16.0 

func (p *PacketPool) Count() int

func (*PacketPool) Release added in v0.16.0 

func (p *PacketPool) Release(pkt *Packet)

type PipeConfiguration added in v0.16.0 

type PipeConfiguration struct {
	// MTU is the maximum transmission unit of the pipe.
	// If not specified, a default MTU of 1500 will be used.
	MTU *int
	// BatchSize is the maximum number of packets that can be read or written at
	// once. If not specified, a default batch size of 16 will be used.
	BatchSize *int
	// PacketPool is the pool from which packets are borrowed.
	// If not specified, an unbounded pool will be created.
	PacketPool *PacketPool
}

PipeConfiguration is the configuration for a pipe.

type ResolverFactory added in v0.3.0 

type ResolverFactory func(dialContext DialContextFunc) (resolver.Resolver, error)

ResolverFactory is a function that creates a DNS resolver from the given dial function.

type SpliceConfiguration added in v0.19.0 

type SpliceConfiguration struct {
	// PacketWriteOffset is an optional hint to write outbound packet data at a
	// specific offset inside the buffer. This is a performance hint for
	// WireGuard (and other protocols that need to add their own headers).
	PacketWriteOffset int
}

type UserspaceNetwork 

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

func Userspace 

func Userspace(ctx context.Context, logger *slog.Logger, nic Interface, conf UserspaceNetworkConfig) (*UserspaceNetwork, error)

Userspace returns a userspace Network implementation based on Netstack from the gVisor project.

func (*UserspaceNetwork) Close 

func (net *UserspaceNetwork) Close() error

func (*UserspaceNetwork) Dial 

func (net *UserspaceNetwork) Dial(network, address string) (stdnet.Conn, error)

func (*UserspaceNetwork) DialContext 

func (net *UserspaceNetwork) DialContext(ctx context.Context, network, address string) (stdnet.Conn, error)

func (*UserspaceNetwork) Domain added in v0.5.0 

func (net *UserspaceNetwork) Domain() (string, error)

func (*UserspaceNetwork) EnableForwarding added in v0.6.0 

func (net *UserspaceNetwork) EnableForwarding(fwd Forwarder) error

EnableForwarding enables forwarding of network sessions using the provided Forwarder implementation.

func (*UserspaceNetwork) Hostname 

func (net *UserspaceNetwork) Hostname() (string, error)

func (*UserspaceNetwork) InterfaceAddrs 

func (net *UserspaceNetwork) InterfaceAddrs() (addrs []stdnet.Addr, err error)

func (*UserspaceNetwork) Listen 

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

func (*UserspaceNetwork) ListenPacket 

func (net *UserspaceNetwork) ListenPacket(network, address string) (stdnet.PacketConn, error)

func (*UserspaceNetwork) LookupHost 

func (net *UserspaceNetwork) LookupHost(host string) ([]string, error)

func (*UserspaceNetwork) LookupHostContext 

func (net *UserspaceNetwork) LookupHostContext(ctx context.Context, host string) ([]string, error)

func (*UserspaceNetwork) Ping added in v0.9.0 

func (net *UserspaceNetwork) Ping(ctx context.Context, network, host string) error

func (*UserspaceNetwork) Stack added in v0.9.0 

func (net *UserspaceNetwork) Stack() *stack.Stack

Stack returns the underlying netstack stack.

func (*UserspaceNetwork) WriteNotify 

func (net *UserspaceNetwork) WriteNotify()

type UserspaceNetworkConfig added in v0.3.0 

type UserspaceNetworkConfig struct {
	// Hostname is the hostname of the local process.
	Hostname string
	// Domain is the local domain of the network.
	Domain string
	// Addresses is a list of IP addresses/IP prefixes to add.
	Addresses []netip.Prefix
	// ResolverFactory is an optional factory to create a DNS resolver.
	ResolverFactory ResolverFactory
	// PacketCaptureWriter is an optional writer to write a packet capture file to.
	// If nil, no packet capture file will be written.
	// This is useful for debugging network issues.
	PacketCaptureWriter io.Writer
	// PacketPool is the pool from which packets are borrowed.
	// If not specified, an unbounded pool will be created.
	PacketPool *PacketPool
	// PacketWriteOffset is an optional hint to write outbound packet data at a
	// specific offset inside the buffer. This is a performance hint for
	// WireGuard (and other protocols that need to add their own headers).
	PacketWriteOffset int
}

Source Files

View all Source files

Directories

Path Synopsis
examples module
Package forwarder provides a network session forwarder.
 Package forwarder provides a network session forwarder.
internal
iptables/matcher
iptables/target
multilistener
Package multilistener provides a net.Listener that multiplexes connections from multiple listeners.
 Package multilistener provides a net.Listener that multiplexes connections from multiple listeners.
packetmux
protocol
testutil
util
Package tun provides a TUN device implementation for noisysockets.
 Package tun provides a TUN device implementation for noisysockets.

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.