Documentation ¶
Overview ¶
Package network provides a host independent abstraction for network operations.
Index ¶
- Constants
- Variables
- func IsStackClosed(err error) bool
- func Pipe(conf *PipeConfiguration) (Interface, Interface)
- func Splice(ctx context.Context, nicA, nicB Interface, conf *SpliceConfiguration) error
- type DialContextFunc
- type Forwarder
- type HostNetwork
- func (net *HostNetwork) Close() error
- func (net *HostNetwork) Dial(network, address string) (stdnet.Conn, error)
- func (net *HostNetwork) DialContext(ctx context.Context, network, address string) (stdnet.Conn, error)
- func (net *HostNetwork) Domain() (string, error)
- func (net *HostNetwork) Hostname() (string, error)
- func (net *HostNetwork) InterfaceAddrs() ([]stdnet.Addr, error)
- func (net *HostNetwork) Listen(network, address string) (stdnet.Listener, error)
- func (net *HostNetwork) ListenPacket(network, address string) (stdnet.PacketConn, error)
- func (net *HostNetwork) LookupHost(host string) ([]string, error)
- func (net *HostNetwork) LookupHostContext(ctx context.Context, host string) ([]string, error)
- func (net *HostNetwork) Ping(ctx context.Context, network, host string) error
- type Interface
- type Network
- type Packet
- type PacketPool
- type PipeConfiguration
- type ResolverFactory
- type SpliceConfiguration
- type UserspaceNetwork
- func (net *UserspaceNetwork) Close() error
- func (net *UserspaceNetwork) Dial(network, address string) (stdnet.Conn, error)
- func (net *UserspaceNetwork) DialContext(ctx context.Context, network, address string) (stdnet.Conn, error)
- func (net *UserspaceNetwork) Domain() (string, error)
- func (net *UserspaceNetwork) EnableForwarding(fwd Forwarder) error
- func (net *UserspaceNetwork) Hostname() (string, error)
- func (net *UserspaceNetwork) InterfaceAddrs() (addrs []stdnet.Addr, err error)
- func (net *UserspaceNetwork) Listen(network, address string) (stdnet.Listener, error)
- func (net *UserspaceNetwork) ListenPacket(network, address string) (stdnet.PacketConn, error)
- func (net *UserspaceNetwork) LookupHost(host string) ([]string, error)
- func (net *UserspaceNetwork) LookupHostContext(ctx context.Context, host string) ([]string, error)
- func (net *UserspaceNetwork) Ping(ctx context.Context, network, host string) error
- func (net *UserspaceNetwork) Stack() *stack.Stack
- func (net *UserspaceNetwork) WriteNotify()
- type UserspaceNetworkConfig
Constants ¶
const MaxPacketSize = 65535
MaxPacketSize is the maximum size of an IP packet.
Variables ¶
Functions ¶
func IsStackClosed ¶ added in v0.4.1
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.
Types ¶
type DialContextFunc ¶ added in v0.3.0
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 (*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 ¶
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) MoveOffset ¶ added in v0.17.0
MoveOffset moves the packet data to a new offset inside the buffer. This can be a potentially expensive operation.
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 (*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 (*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 ¶
Directories ¶
Path | Synopsis |
---|---|
examples
module
|
|
Package forwarder provides a network session forwarder.
|
Package forwarder provides a network session forwarder. |
internal
|
|
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. |
Package tun provides a TUN device implementation for noisysockets.
|
Package tun provides a TUN device implementation for noisysockets. |