vclient

Documentation

Overview

Package vclient implements a virtual network client with a user-space TCP/IP stack. It operates at the IP packet level and can be connected to a slirp Stack for testing, or used on any IP-based network.

The client supports DNS, TCP (with retransmission), and UDP, and exposes standard Go interfaces such as Dial, net.Conn, and net.Resolver.

Index

• type Client
  • func New() *Client
  • func (c *Client) Addr() netip.Prefix
  • func (c *Client) Close() error
  • func (c *Client) Dial(network, address string) (net.Conn, error)
  • func (c *Client) DialContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) IP() net.IP
  • func (c *Client) Listen(network, address string) (net.Listener, error)
  • func (c *Client) LookupHost(ctx context.Context, host string) ([]string, error)
  • func (c *Client) Resolver() *net.Resolver
  • func (c *Client) Send(pkt pktkit.Packet) error
  • func (c *Client) SetAddr(p netip.Prefix) error
  • func (c *Client) SetDNS(servers []net.IP)
  • func (c *Client) SetDNS6(servers []net.IP)
  • func (c *Client) SetHandler(h func(pktkit.Packet) error)
  • func (c *Client) SetIP(ip net.IP, mask net.IPMask, gw net.IP)
  • func (c *Client) SetIPv6(ip net.IP)
• type Listener
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
• type TCPConn
  • func (tc *TCPConn) Close() error
  • func (tc *TCPConn) LocalAddr() net.Addr
  • func (tc *TCPConn) Read(b []byte) (int, error)
  • func (tc *TCPConn) RemoteAddr() net.Addr
  • func (tc *TCPConn) SetDeadline(t time.Time) error
  • func (tc *TCPConn) SetReadDeadline(t time.Time) error
  • func (tc *TCPConn) SetWriteDeadline(t time.Time) error
  • func (tc *TCPConn) Write(b []byte) (int, error)
• type UDPConn
  • func (u *UDPConn) Close() error
  • func (u *UDPConn) LocalAddr() net.Addr
  • func (u *UDPConn) Read(b []byte) (int, error)
  • func (u *UDPConn) RemoteAddr() net.Addr
  • func (u *UDPConn) SetDeadline(t time.Time) error
  • func (u *UDPConn) SetReadDeadline(t time.Time) error
  • func (u *UDPConn) SetWriteDeadline(t time.Time) error
  • func (u *UDPConn) Write(b []byte) (int, error)
• type UDPConn6
  • func (u *UDPConn6) Close() error
  • func (u *UDPConn6) LocalAddr() net.Addr
  • func (u *UDPConn6) Read(b []byte) (int, error)
  • func (u *UDPConn6) RemoteAddr() net.Addr
  • func (u *UDPConn6) SetDeadline(t time.Time) error
  • func (u *UDPConn6) SetReadDeadline(t time.Time) error
  • func (u *UDPConn6) SetWriteDeadline(t time.Time) error
  • func (u *UDPConn6) Write(b []byte) (int, error)

Types

type Client

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

Client is a virtual network client operating at the IP packet level. It implements pktkit.L3Device.

func New

func New() *Client

New creates a new virtual network client. Use SetHandler to wire it for packet delivery before use.

func (*Client) Addr

func (c *Client) Addr() netip.Prefix

Addr returns the client's current IP prefix. Implements pktkit.L3Device.

func (*Client) Close

func (c *Client) Close() error

Close shuts down the client and all active connections.

func (*Client) Dial

func (c *Client) Dial(network, address string) (net.Conn, error)

Dial connects to the address on the named network. Supported networks are "tcp", "tcp4", "udp", "udp4".

func (*Client) DialContext

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

DialContext connects to the address on the named network using the provided context.

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

HTTPClient returns an *http.Client configured to route all traffic through this virtual network client, including DNS resolution via DialContext which internally calls LookupHost.

func (*Client) IP

func (c *Client) IP() net.IP

IP returns the client's current IP address.

func (*Client) Listen

func (c *Client) Listen(network, address string) (net.Listener, error)

Listen announces on the virtual network address and returns a net.Listener. The network must be "tcp", "tcp4", or "tcp6". The address is "host:port" where host is the client's virtual IP (or empty/"0.0.0.0"/"::" for any).

func (*Client) LookupHost

func (c *Client) LookupHost(ctx context.Context, host string) ([]string, error)

LookupHost resolves a hostname to IP addresses using the configured DNS servers.

func (*Client) Resolver

func (c *Client) Resolver() *net.Resolver

Resolver returns a *net.Resolver that uses this client's DNS resolution.

func (*Client) Send

func (c *Client) Send(pkt pktkit.Packet) error

Send delivers an IP packet to the client for processing. Implements pktkit.L3Device.

func (*Client) SetAddr

func (c *Client) SetAddr(p netip.Prefix) error

SetAddr configures the client's IP prefix (updates IP and mask). Implements pktkit.L3Device.

func (*Client) SetDNS

func (c *Client) SetDNS(servers []net.IP)

SetDNS configures the DNS server addresses (IPv4).

func (*Client) SetDNS6

func (c *Client) SetDNS6(servers []net.IP)

SetDNS6 configures the IPv6 DNS server addresses.

func (*Client) SetHandler

func (c *Client) SetHandler(h func(pktkit.Packet) error)

SetHandler sets the callback for packets produced by this client. Implements pktkit.L3Device.

func (*Client) SetIP

func (c *Client) SetIP(ip net.IP, mask net.IPMask, gw net.IP)

SetIP configures a static IP address, subnet mask, and default gateway.

func (*Client) SetIPv6

func (c *Client) SetIPv6(ip net.IP)

SetIPv6 configures the client's IPv6 address.

type Listener

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

Listener is a virtual TCP listener that accepts connections from the virtual network. It implements net.Listener.

func (*Listener) Accept

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

Accept waits for and returns the next connection to the listener.

func (*Listener) Addr

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

Addr returns the listener's network address.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the listener.

type TCPConn

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

TCPConn is a virtual TCP connection implementing net.Conn. It wraps a vtcp.Conn and handles registration/unregistration with the parent Client.

func (*TCPConn) Close

func (tc *TCPConn) Close() error

func (*TCPConn) LocalAddr

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

func (*TCPConn) Read

func (tc *TCPConn) Read(b []byte) (int, error)

func (*TCPConn) RemoteAddr

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

func (*TCPConn) SetDeadline

func (tc *TCPConn) SetDeadline(t time.Time) error

func (*TCPConn) SetReadDeadline

func (tc *TCPConn) SetReadDeadline(t time.Time) error

func (*TCPConn) SetWriteDeadline

func (tc *TCPConn) SetWriteDeadline(t time.Time) error

func (*TCPConn) Write

func (tc *TCPConn) Write(b []byte) (int, error)

type UDPConn

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

UDPConn is a virtual UDP connection implementing net.Conn.

func (*UDPConn) Close

func (u *UDPConn) Close() error

func (*UDPConn) LocalAddr

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

func (*UDPConn) Read

func (u *UDPConn) Read(b []byte) (int, error)

func (*UDPConn) RemoteAddr

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

func (*UDPConn) SetDeadline

func (u *UDPConn) SetDeadline(t time.Time) error

func (*UDPConn) SetReadDeadline

func (u *UDPConn) SetReadDeadline(t time.Time) error

func (*UDPConn) SetWriteDeadline

func (u *UDPConn) SetWriteDeadline(t time.Time) error

func (*UDPConn) Write

func (u *UDPConn) Write(b []byte) (int, error)

type UDPConn6

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

UDPConn6 is a virtual IPv6 UDP connection implementing net.Conn.

func (*UDPConn6) Close

func (u *UDPConn6) Close() error

func (*UDPConn6) LocalAddr

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

func (*UDPConn6) Read

func (u *UDPConn6) Read(b []byte) (int, error)

func (*UDPConn6) RemoteAddr

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

func (*UDPConn6) SetDeadline

func (u *UDPConn6) SetDeadline(t time.Time) error

func (*UDPConn6) SetReadDeadline

func (u *UDPConn6) SetReadDeadline(t time.Time) error

func (*UDPConn6) SetWriteDeadline

func (u *UDPConn6) SetWriteDeadline(t time.Time) error

func (*UDPConn6) Write

func (u *UDPConn6) Write(b []byte) (int, error)