sysnetdebug

Documentation

Overview

Package sysnetdebug provides a channel-driven sysnet implementation for tests.

Index

• Variables
• type System
  • func (s *System) AddTunAddr(t tun.Tun, addr string) error
  • func (s *System) AddTunRoute(t tun.Tun, route string) error
  • func (s *System) AllocIP() subnet.IPAllocator
  • func (s *System) AllocSubnet() subnet.SubnetAllocator
  • func (s *System) BuildDefaultTun(opts sysnet.DefaultTunOpts) (sysnet.DefaultTun, error)
  • func (s *System) BuildMatcher(rule sysnet.Rule) (sysnet.Matcher, error)
  • func (s *System) BuildTun(opts sysnet.TunOpts) (tun.Tun, error)
  • func (s *System) Close() error
  • func (s *System) Features() sysnet.Features
  • func (s *System) GetDefaultTunPeer() (TunEntry, bool)
  • func (s *System) GetTunAddrs(t tun.Tun) ([]string, error)
  • func (s *System) GetTunPeer(name string) (TunEntry, bool)
  • func (s *System) GetTunRotue(t tun.Tun) ([]string, error)
  • func (s *System) ListRules() sysnet.RulesInfo
  • func (s *System) LocalNet() gonnect.Network
  • func (s *System) OutDNS() dns.Interface
  • func (s *System) OutNet() gonnect.Network
  • func (s *System) Requests() chan<- dns.Request
  • func (s *System) RuleCompl(rule sysnet.Rule) []string
  • func (s *System) RuleVerify(rule sysnet.Rule) bool
  • func (s *System) SetTunAddrs(t tun.Tun, addrs []string) error
  • func (s *System) SetTunMTU(t tun.Tun, mtu int) error
  • func (s *System) SetTunName(t tun.Tun, name string) ([]string, error)
  • func (s *System) SetTunRoutes(t tun.Tun, routes []string) error
  • func (s *System) TunNameVerify(name string) (valid bool, free bool)
  • func (s *System) VerifyDefaultTunOpts(opts sysnet.DefaultTunOpts) error
  • func (s *System) VerifyTunOpts(opts sysnet.TunOpts) error
• type TunConfig
• type TunEntry

Variables

var (
	// DefaultRules lists the process-owner rule types commonly exposed by
	// sysnet implementations.
	DefaultRules = []sysnet.RuleTypeInfo{
		{Type: "comm", Description: "Process command regexp matcher."},
		{Type: "exec", Description: "Process executable path matcher."},
		{Type: "cmd", Description: "Process command line regexp matcher."},
		{Type: "pid", Description: "Process PID."},
		{Type: "user", Description: "Name of user owning process."},
		{Type: "uid", Description: "UID owning process."},
		{Type: "group", Description: "Name of group owning process."},
		{Type: "gid", Description: "GID owning process."},
	}
)

Types

type System

type System struct {
	// DisableTun makes Features report regular tun creation as unsupported and
	// makes VerifyTunOpts and BuildTun return sysnet.ErrNotSupported.
	DisableTun bool

	// DisableDefaultTun makes Features report default tun creation as
	// unsupported and makes VerifyDefaultTunOpts and BuildDefaultTun return
	// sysnet.ErrNotSupported.
	DisableDefaultTun bool

	// DisableDynTun makes Features report dynamic regular tun updates as
	// unsupported. It is informational; setter methods still update the in-memory
	// state so tests can decide which behavior they need to assert.
	DisableDynTun bool

	// DisableDynDefaultTun makes Features report dynamic default tun updates as
	// unsupported.
	DisableDynDefaultTun bool

	// DisableTunNames makes Features report regular tun naming as unsupported
	// and makes SetTunName return sysnet.ErrNotSupported.
	DisableTunNames bool

	// DisableDefaultTunNames makes Features report default tun naming as
	// unsupported.
	DisableDefaultTunNames bool

	// DisableStrictMode makes Features report default tun strict mode as
	// unsupported.
	DisableStrictMode bool

	// Rules is the optional rule catalog returned by ListRules for both tun
	// rules and matcher rules. Leave it nil when the test does not care about
	// advertised rule types.
	Rules []sysnet.RuleTypeInfo

	// RuleMatcher is an optional hook used by matchers created with
	// BuildMatcher. When omitted, matchers return false, nil.
	RuleMatcher func(rule sysnet.Rule, flow sockowner.FlowTuple) (bool, error)

	// RuleVerifyer is an optional hook used by RuleVerify. When omitted, every
	// rule is considered valid.
	RuleVerifyer func(rule sysnet.Rule) bool

	// RuleCompletion is an optional hook used by RuleCompl. When omitted, no
	// completion suggestions are returned.
	RuleCompletion func(rule sysnet.Rule) []string

	// TunNameVerifyer is an optional hook used by TunNameVerify and SetTunName.
	// When omitted, any non-empty free name is valid.
	TunNameVerifyer func(name string) (valid bool)

	// OutDNSProvider is an optional DNS provider returned by OutDNS. When
	// omitted, OutDNS uses StaticDNS through an in-memory resolver.
	OutDNSProvider dns.Interface

	// StaticDNS maps host names to IP addresses for the default OutDNS resolver.
	// It can be omitted when DNS behavior is not relevant to the test.
	StaticDNS map[string]string

	// OutNetwork is an optional network returned by OutNet. When omitted, System
	// returns a loopback network that allows any host.
	OutNetwork gonnect.Network

	// LocalNetwork is an optional network returned by LocalNet. When omitted,
	// System returns a loopback network that allows any host.
	LocalNetwork gonnect.Network

	// DefaultTunOptsVerifyer is an optional hook used by VerifyDefaultTunOpts and
	// BuildDefaultTun. Use it in tests to assert or reject requested default tun
	// options.
	DefaultTunOptsVerifyer func(opts sysnet.DefaultTunOpts) error

	// DefaultTunBuilder is an optional hook used by BuildDefaultTun to provide a
	// custom tun implementation. When omitted, System creates an in-memory pipe
	// and exposes its peer through GetDefaultTunPeer.
	DefaultTunBuilder func(opts sysnet.DefaultTunOpts) (tun.Tun, error)

	// TunOptsVerifyer is an optional hook used by VerifyTunOpts and BuildTun. Use
	// it in tests to assert or reject requested regular tun options.
	TunOptsVerifyer func(opts sysnet.TunOpts) error

	// TunBuilder is an optional hook used by BuildTun to provide a custom tun
	// implementation. When omitted, System creates an in-memory pipe and exposes
	// its peer through GetTunPeer.
	TunBuilder func(opts sysnet.TunOpts) (tun.Tun, error)
	// contains filtered or unexported fields
}

System is an in-memory sysnet.System implementation intended for tests.

The zero value is ready to use. By default it reports every sysnet feature as supported, creates pipe-backed tun devices, exposes loopback networks for OutNet and LocalNet, accepts every rule, and matches no flows. Tests can provide only the public fields that matter for the behavior under test and leave all other fields omitted.

This makes System useful as a focused test double for code that requires a sysnet.System implementation. For example, pass &sysnetdebug.System{} to the code under test, set Disable* fields to exercise unsupported-feature paths, install verifier or builder functions to assert requested options, or inspect GetTunPeer and GetDefaultTunPeer to observe created virtual tun devices.

func (*System) AddTunAddr

func (s *System) AddTunAddr(t tun.Tun, addr string) error

AddTunAddr appends addr to the recorded addresses for a tun created by this System.

func (*System) AddTunRoute

func (s *System) AddTunRoute(t tun.Tun, route string) error

AddTunRoute appends route to the recorded routes for a tun created by this System.

func (*System) AllocIP

func (s *System) AllocIP() subnet.IPAllocator

AllocIP returns the shared in-memory IP allocator for this System.

func (*System) AllocSubnet

func (s *System) AllocSubnet() subnet.SubnetAllocator

AllocSubnet returns the shared in-memory subnet allocator for this System.

func (*System) BuildDefaultTun

func (s *System) BuildDefaultTun(
	opts sysnet.DefaultTunOpts,
) (sysnet.DefaultTun, error)

BuildDefaultTun creates or reconfigures the default tun for this System.

With the default configuration it creates an in-memory pipe-backed tun and exposes the peer through GetDefaultTunPeer so tests can inspect packets. When DefaultTunBuilder is set, the custom builder supplies the tun and no peer is recorded.

func (*System) BuildMatcher

func (s *System) BuildMatcher(rule sysnet.Rule) (sysnet.Matcher, error)

BuildMatcher builds a matcher for rule. The matcher delegates to RuleMatcher, or matches nothing when RuleMatcher is omitted.

func (*System) BuildTun

func (s *System) BuildTun(opts sysnet.TunOpts) (tun.Tun, error)

BuildTun creates a regular tun for this System.

With the default configuration it creates an in-memory pipe-backed tun and exposes the peer through GetTunPeer so tests can inspect packets. When TunBuilder is set, the custom builder supplies the tun and no peer is recorded.

func (*System) Close

func (s *System) Close() error

Close closes every tun created by System and stops DNS request routing. It is safe to call more than once.

func (*System) Features

func (s *System) Features() sysnet.Features

Features reports the sysnet feature set described by the Disable* fields.

func (*System) GetDefaultTunPeer

func (s *System) GetDefaultTunPeer() (TunEntry, bool)

GetDefaultTunPeer returns a snapshot of the current default tun entry.

This helper is not part of sysnet.System. Tests can use it to inspect the peer side and recorded configuration of the tun created by BuildDefaultTun.

func (*System) GetTunAddrs

func (s *System) GetTunAddrs(t tun.Tun) ([]string, error)

GetTunAddrs returns the recorded addresses for a tun created by this System.

func (*System) GetTunPeer

func (s *System) GetTunPeer(name string) (TunEntry, bool)

GetTunPeer returns a snapshot of a regular tun entry by name.

This helper is not part of sysnet.System. Tests can use it to inspect the peer side and recorded configuration of tuns created by BuildTun.

func (*System) GetTunRotue

func (s *System) GetTunRotue(t tun.Tun) ([]string, error)

GetTunRotue returns the recorded routes for a tun created by this System.

The method name follows the sysnet.System interface spelling.

func (*System) ListRules

func (s *System) ListRules() sysnet.RulesInfo

ListRules returns Rules for both tun rule and matcher rule support.

func (*System) LocalNet

func (s *System) LocalNet() gonnect.Network

LocalNet returns the loopback network configured by LocalNetwork, or a permissive loopback network when LocalNetwork is omitted.

func (*System) OutDNS

func (s *System) OutDNS() dns.Interface

OutDNS returns the DNS provider used for traffic that should bypass a default tun.

func (*System) OutNet

func (s *System) OutNet() gonnect.Network

OutNet returns the outbound network configured by OutNetwork, or a permissive loopback network when OutNetwork is omitted.

func (*System) Requests

func (s *System) Requests() chan<- dns.Request

Requests returns the DNS request channel for the System dns.Interface implementation.

Requests sent here are forwarded to the resolver most recently installed by the current default tun's SetDns method. Requests are dropped while no default tun DNS resolver is configured.

func (*System) RuleCompl

func (s *System) RuleCompl(rule sysnet.Rule) []string

RuleCompl returns completion suggestions from RuleCompletion, or nil when no hook is configured.

func (*System) RuleVerify

func (s *System) RuleVerify(rule sysnet.Rule) bool

RuleVerify validates rule using RuleVerifyer, or accepts it when no hook is configured.

func (*System) SetTunAddrs

func (s *System) SetTunAddrs(t tun.Tun, addrs []string) error

SetTunAddrs replaces the recorded addresses for a tun created by this System.

func (*System) SetTunMTU

func (s *System) SetTunMTU(t tun.Tun, mtu int) error

SetTunMTU records mtu for a tun created by this System.

func (*System) SetTunName

func (s *System) SetTunName(t tun.Tun, name string) ([]string, error)

SetTunName renames a regular tun created by this System.

Default tun handles and unknown tun handles return sysnet.ErrUnknownTun. DisableTunNames makes this method return sysnet.ErrNotSupported.

func (*System) SetTunRoutes

func (s *System) SetTunRoutes(t tun.Tun, routes []string) error

SetTunRoutes replaces the recorded routes for a tun created by this System.

func (*System) TunNameVerify

func (s *System) TunNameVerify(name string) (valid bool, free bool)

TunNameVerify reports whether name is valid and not already used by this System.

func (*System) VerifyDefaultTunOpts

func (s *System) VerifyDefaultTunOpts(opts sysnet.DefaultTunOpts) error

VerifyDefaultTunOpts validates opts for BuildDefaultTun. It returns sysnet.ErrNotSupported when DisableDefaultTun is set, delegates to DefaultTunOptsVerifyer when provided, and otherwise accepts opts.

func (*System) VerifyTunOpts

func (s *System) VerifyTunOpts(opts sysnet.TunOpts) error

VerifyTunOpts validates opts for BuildTun. It returns sysnet.ErrNotSupported when DisableTun is set, delegates to TunOptsVerifyer when provided, and otherwise accepts opts.

type TunConfig

type TunConfig struct {
	// MTU is the tun MTU after System defaulting has been applied.
	MTU int

	// TunAddrs are the addresses assigned to the tun.
	TunAddrs []string

	// TunRoutes are the routes assigned to the tun.
	TunRoutes []string

	// DnsIP is the DNS endpoint address requested for a default tun.
	DnsIP string

	// Strict records whether strict routing was requested for a default tun.
	Strict bool

	// Exclude records rules that should bypass a default tun.
	Exclude []sysnet.Rule

	// Include records rules that should use a default tun.
	Include []sysnet.Rule
}

TunConfig is a snapshot of the tun options recorded by System.

type TunEntry

type TunEntry struct {
	// Name is the current System name for the tun.
	Name string

	// Tun is the handle returned by BuildTun or BuildDefaultTun.
	Tun tun.Tun

	// Peer is the other end of the in-memory pipe when System built the tun
	// itself. It is nil when a custom builder supplied the tun.
	Peer tun.Tun

	// Default reports whether this entry was created by BuildDefaultTun.
	Default bool

	// Config is the last configuration recorded for this tun.
	Config TunConfig
}

TunEntry describes a tun created by System.