netif

README

netif

Networking interfaces. For now I'm adding a TAP interface I can understand

Debugging with VSCode

To run with an ethernet interface you'll need to open VSCode as sudo with --no-sandbox option:

sudo code --user-data-dir ~/.config/Code --no-sandbox .

You may need to install the Go extension and Delve as sudo since you are opening VSCode as a different user.

Creating a launch.json maps directly to using VSCode normally. Here's an example:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Package",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/examples/mqtt/",
        }
    ]
}

Documentation

Index

• func DefaultInterface() (*net.Interface, error)
• type AddrMethod
• type Engine
  • func NewEngine(nic InterfaceEthPoller, cfg EngineConfig) (*Engine, error)
  • func (e *Engine) Addr() netip.Addr
  • func (e *Engine) DialTCP(localport uint16, establishDeadline time.Time, raddr netip.AddrPort) (net.Conn, error)
  • func (e *Engine) HandlePoll() (received, sent int, err error)
  • func (e *Engine) Interface() InterfaceEthPoller
  • func (e *Engine) NewResolver(localport uint16, timeout time.Duration) Resolver
  • func (e *Engine) ResolveHardwareAddr(ip netip.Addr, timeout time.Duration) ([6]byte, error)
  • func (e *Engine) WaitForDHCP(timeout time.Duration) error
• type EngineConfig
• type EthSocket
  • func NewEthSocket(interfaceName string) (*EthSocket, error)
  • func (e *EthSocket) Close() error
  • func (e *EthSocket) HardwareAddr6() ([6]byte, error)
  • func (e *EthSocket) MTU() int
  • func (e *EthSocket) NetFlags() net.Flags
  • func (e *EthSocket) NetNotify(cb func(Event)) error
  • func (e *EthSocket) PollOne() (bool, error)
  • func (e *EthSocket) RecvEthHandle(fn func(b []byte) error)
  • func (e *EthSocket) SendEth(data []byte) error
  • func (e *EthSocket) SetPollBuffer(buf []byte)
• type Event
• type Interface
• type InterfaceEthPoller
• type Resolver
• type Tap
  • func OpenTap(name string) (_ *Tap, err error)
  • func (t *Tap) Addr() (netip.Addr, error)
  • func (t *Tap) Close() error
  • func (t *Tap) GetMTU() (uint32, error)
  • func (t *Tap) Read(data []byte) (int, error)
  • func (t *Tap) SetAddr(addr netip.Addr) error
  • func (t *Tap) SetMTU(mtu uint32) error
  • func (t *Tap) Write(data []byte) (int, error)

Functions

func DefaultInterface

func DefaultInterface() (*net.Interface, error)

Default interface returns the default network interface over which traffic is routed.

Types

type AddrMethod

type AddrMethod uint8

const (
	AddrMethodDHCP AddrMethod
	AddrMethodManual
)

type Engine

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

func NewEngine

func NewEngine(nic InterfaceEthPoller, cfg EngineConfig) (*Engine, error)

NewEngine returns a networking engine that uses the given network interface controller. Engine facilitates:

• DHCP handling for address, router, DNS servers, and other network parameters.
• DNS resolution.
• TCP connection handling.
• ARP resolution (handled automatically)

func (*Engine) Addr

func (e *Engine) Addr() netip.Addr

Addr returns the IP address of the stack.

func (*Engine) DialTCP

func (e *Engine) DialTCP(localport uint16, establishDeadline time.Time, raddr netip.AddrPort) (net.Conn, error)

DialTCP creates a new TCP connection to the remote address raddr.

func (*Engine) HandlePoll

func (e *Engine) HandlePoll() (received, sent int, err error)

HandlePoll polls the network interface for incoming packets and sends queued packets.

func (*Engine) Interface

func (e *Engine) Interface() InterfaceEthPoller

Interface returns the underlying network interface controller.

func (*Engine) NewResolver

func (e *Engine) NewResolver(localport uint16, timeout time.Duration) Resolver

NewResolver returns a DNS client that uses the Engine's ARP and network stack.

func (*Engine) ResolveHardwareAddr

func (e *Engine) ResolveHardwareAddr(ip netip.Addr, timeout time.Duration) ([6]byte, error)

ResolveHardwareAddr resolves the hardware address of an IP address:

• If the IP address is in the cache, it is returned.
• If the IP address is not on the local network, the router's hardware address is returned.
• If the IP address is on the local network, an ARP request is sent and the resulting hardware address is returned.

func (*Engine) WaitForDHCP

func (e *Engine) WaitForDHCP(timeout time.Duration) error

WaitForDHCP waits for DHCP to complete. This should always be called after creating the engine with AddrMethodDHCP.

type EngineConfig

type EngineConfig struct {
	MaxOpenPortsUDP uint16
	MaxOpenPortsTCP uint16
	// AddrMethod selects the mode in which the stack address is chosen or obtained.
	AddrMethod AddrMethod
	// Netmask is the bit prefix length of addresses on the physical network.
	// It is used if AddrMethod is set to Manual.
	Netmask uint8
	// Address is used to request a specific DHCP address
	// or set the address of the stack manually.
	Address netip.Addr
	// Router manually sets the IP address of the default gateway, which allows
	// sending packets out of the physical network and omits getting
	// the Router over DHCP.
	Router netip.Addr
	// DNSServers manually sets the DNS servers and omits getting them over DHCP.
	DNSServers []netip.Addr
	Logger     *slog.Logger
	// Hostname is the hostname to request over DHCP.
	Hostname string
	// TCPBufferSize is the size of the buffer for TCP connections for both
	// send and receive buffers, in bytes. If zero a sensible value is used.
	TCPBuffersize int
}

type EthSocket

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

func NewEthSocket

func NewEthSocket(interfaceName string) (*EthSocket, error)

func (*EthSocket) Close

func (e *EthSocket) Close() error

func (*EthSocket) HardwareAddr6

func (e *EthSocket) HardwareAddr6() ([6]byte, error)

func (*EthSocket) MTU

func (e *EthSocket) MTU() int

func (*EthSocket) NetFlags

func (e *EthSocket) NetFlags() net.Flags

func (*EthSocket) NetNotify

func (e *EthSocket) NetNotify(cb func(Event)) error

func (*EthSocket) PollOne

func (e *EthSocket) PollOne() (bool, error)

func (*EthSocket) RecvEthHandle

func (e *EthSocket) RecvEthHandle(fn func(b []byte) error)

func (*EthSocket) SendEth

func (e *EthSocket) SendEth(data []byte) error

func (*EthSocket) SetPollBuffer

func (e *EthSocket) SetPollBuffer(buf []byte)

type Event

type Event uint8

const (
	// The device's network connection is now UP
	EventNetUp Event = iota
	// The device's network connection is now DOWN
	EventNetDown
)

Network events

type Interface

type Interface interface {
	// HardwareAddr6 returns the device's 6-byte [MAC address].
	//
	// [MAC address]: https://en.wikipedia.org/wiki/MAC_address
	HardwareAddr6() ([6]byte, error)
	// NetFlags returns the net.Flag values for the interface. It includes state of connection.
	NetFlags() net.Flags
	// MTU returns the maximum transmission unit size.
	MTU() int
}

Interface is the minimum interface that need be implemented by any network device driver and is based on net.Interface.

type InterfaceEthPoller

type InterfaceEthPoller interface {
	Interface
	// SendEth sends an Ethernet packet
	SendEth(pkt []byte) error
	// RecvEthHandle sets recieve Ethernet packet callback function
	RecvEthHandle(func(pkt []byte) error)
	// PollOne tries to receive one Ethernet packet and returns true if
	// a packet was received by the stack callback.
	PollOne() (bool, error)
}

InterfaceEthPoller is implemented by devices that send/receive ethernet packets.

type Resolver

type Resolver interface {
	// LookupNetIP returns the IP addresses of a host.
	LookupNetIP(host string) ([]netip.Addr, error)
}

Resolver is the interface for DNS resolution, as implemented by the `net` package.

type Tap

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

Tap implements Unix TAP interface.

func OpenTap

func OpenTap(name string) (_ *Tap, err error)

OpenTap opens an existing TAP device by name. See ./make-tap.sh script.

func (*Tap) Addr

func (t *Tap) Addr() (netip.Addr, error)

func (*Tap) Close

func (t *Tap) Close() error

func (*Tap) GetMTU

func (t *Tap) GetMTU() (uint32, error)

func (*Tap) Read

func (t *Tap) Read(data []byte) (int, error)

func (*Tap) SetAddr

func (t *Tap) SetAddr(addr netip.Addr) error

func (*Tap) SetMTU

func (t *Tap) SetMTU(mtu uint32) error

func (*Tap) Write

func (t *Tap) Write(data []byte) (int, error)