client

Documentation

Overview

Package client contains types and logic dealing with AdGuard Home's DNS clients.

TODO(a.garipov): Expand.

Index

• Constants
• func ValidateClientID(id string) (err error)
• type AddressProcessor
• type AddressUpdater
• type DefaultAddrProc
  • func NewDefaultAddrProc(c *DefaultAddrProcConfig) (p *DefaultAddrProc)
  • func (p *DefaultAddrProc) Close() (err error)
  • func (p *DefaultAddrProc) Process(ip netip.Addr)
• type DefaultAddrProcConfig
• type EmptyAddrProc
  • func (EmptyAddrProc) Close() (_ error)
  • func (EmptyAddrProc) Process(_ netip.Addr)
• type Index
  • func NewIndex() (ci *Index)
  • func (ci *Index) Add(c *Persistent)
  • func (ci *Index) Clashes(c *Persistent) (err error)
  • func (ci *Index) Delete(c *Persistent)
  • func (ci *Index) Find(id string) (c *Persistent, ok bool)
• type Persistent
  • func (c *Persistent) CloseUpstreams() (err error)
  • func (c *Persistent) EqualIDs(prev *Persistent) (equal bool)
  • func (c *Persistent) IDs() (ids []string)
  • func (c *Persistent) IDsLen() (n int)
  • func (c *Persistent) SetIDs(ids []string) (err error)
  • func (c *Persistent) SetSafeSearch(conf filtering.SafeSearchConfig, cacheSize uint, cacheTTL time.Duration) (err error)
  • func (c *Persistent) SetTags(tags []string, known *stringutil.Set)
  • func (c *Persistent) ShallowClone() (clone *Persistent)
• type Runtime
  • func (r *Runtime) Info() (cs Source, host string)
  • func (r *Runtime) IsEmpty() (ok bool)
  • func (r *Runtime) SetInfo(cs Source, hosts []string)
  • func (r *Runtime) SetWHOIS(info *whois.Info)
  • func (r *Runtime) Unset(cs Source)
  • func (r *Runtime) WHOIS() (info *whois.Info)
• type Source
  • func (cs Source) MarshalText() (text []byte, err error)
  • func (cs Source) String() (s string)
• type UID
  • func MustNewUID() (uid UID)
  • func NewUID() (uid UID, err error)
  • func (uid UID) MarshalText() ([]byte, error)
  • func (uid *UID) UnmarshalText(data []byte) error

Constants

const ErrClosed errors.Error = "use of closed address processor"

ErrClosed is returned from [AddressProcessor.Close] if it's closed more than once.

Functions

func ValidateClientID

func ValidateClientID(id string) (err error)

ValidateClientID returns an error if id is not a valid ClientID.

TODO(s.chzhen): It's an exact copy of the [dnsforward.ValidateClientID] to avoid the import cycle. Remove it.

Types

type AddressProcessor

type AddressProcessor interface {
	Process(ip netip.Addr)
	Close() (err error)
}

AddressProcessor is the interface for types that can process clients.

type AddressUpdater

type AddressUpdater interface {
	// UpdateAddress updates information about an IP address, setting host (if
	// not empty) and WHOIS information (if not nil).
	UpdateAddress(ip netip.Addr, host string, info *whois.Info)
}

AddressUpdater is the interface for storages of DNS clients that can update information about them.

TODO(a.garipov): Consider using the actual client storage once it is moved into this package.

type DefaultAddrProc

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

DefaultAddrProc processes incoming client addresses with rDNS and WHOIS, if configured, and updates that information in a client storage.

func NewDefaultAddrProc

func NewDefaultAddrProc(c *DefaultAddrProcConfig) (p *DefaultAddrProc)

NewDefaultAddrProc returns a new running client address processor. c must not be nil.

func (*DefaultAddrProc) Close

func (p *DefaultAddrProc) Close() (err error)

Close implements the AddressProcessor interface for *DefaultAddrProc.

func (*DefaultAddrProc) Process

func (p *DefaultAddrProc) Process(ip netip.Addr)

Process implements the AddressProcessor interface for *DefaultAddrProc.

type DefaultAddrProcConfig

type DefaultAddrProcConfig struct {
	// DialContext is used to create TCP connections to WHOIS servers.
	// DialContext must not be nil if [DefaultAddrProcConfig.UseWHOIS] is true.
	DialContext aghnet.DialContextFunc

	// Exchanger is used to perform rDNS queries.  Exchanger must not be nil if
	// [DefaultAddrProcConfig.UseRDNS] is true.
	Exchanger rdns.Exchanger

	// PrivateSubnets are used to determine if an incoming IP address is
	// private.  It must not be nil.
	PrivateSubnets netutil.SubnetSet

	// AddressUpdater is used to update the information about a client's IP
	// address.  It must not be nil.
	AddressUpdater AddressUpdater

	// InitialAddresses are the addresses that are queued for processing
	// immediately by [NewDefaultAddrProc].
	InitialAddresses []netip.Addr

	// CatchPanics, if true, makes the address processor catch and log panics.
	//
	// TODO(a.garipov): Consider better ways to do this or apply this method to
	// other parts of the codebase.
	CatchPanics bool

	// UseRDNS, if true, enables resolving of client IP addresses using reverse
	// DNS.
	UseRDNS bool

	// UsePrivateRDNS, if true, enables resolving of private client IP addresses
	// using reverse DNS.  See [DefaultAddrProcConfig.PrivateSubnets].
	UsePrivateRDNS bool

	// UseWHOIS, if true, enables resolving of client IP addresses using WHOIS.
	UseWHOIS bool
}

DefaultAddrProcConfig is the configuration structure for address processors.

type EmptyAddrProc

type EmptyAddrProc struct{}

EmptyAddrProc is an AddressProcessor that does nothing.

func (EmptyAddrProc) Close

func (EmptyAddrProc) Close() (_ error)

Close implements the AddressProcessor interface for EmptyAddrProc.

func (EmptyAddrProc) Process

func (EmptyAddrProc) Process(_ netip.Addr)

Process implements the AddressProcessor interface for EmptyAddrProc.

type Index

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

Index stores all information about persistent clients.

func NewIndex

func NewIndex() (ci *Index)

NewIndex initializes the new instance of client index.

func (*Index) Add

func (ci *Index) Add(c *Persistent)

Add stores information about a persistent client in the index. c must be non-nil and contain UID.

func (*Index) Clashes

func (ci *Index) Clashes(c *Persistent) (err error)

Clashes returns an error if the index contains a different persistent client with at least a single identifier contained by c. c must be non-nil.

func (*Index) Delete

func (ci *Index) Delete(c *Persistent)

Delete removes information about persistent client from the index. c must be non-nil.

func (*Index) Find

func (ci *Index) Find(id string) (c *Persistent, ok bool)

Find finds persistent client by string representation of the client ID, IP address, or MAC.

type Persistent

type Persistent struct {
	// UpstreamConfig is the custom upstream configuration for this client.  If
	// it's nil, it has not been initialized yet.  If it's non-nil and empty,
	// there are no valid upstreams.  If it's non-nil and non-empty, these
	// upstream must be used.
	UpstreamConfig *proxy.CustomUpstreamConfig

	// TODO(d.kolyshev): Make SafeSearchConf a pointer.
	SafeSearchConf filtering.SafeSearchConfig
	SafeSearch     filtering.SafeSearch

	// BlockedServices is the configuration of blocked services of a client.
	BlockedServices *filtering.BlockedServices

	Name string

	Tags      []string
	Upstreams []string

	IPs []netip.Addr
	// TODO(s.chzhen):  Use netutil.Prefix.
	Subnets   []netip.Prefix
	MACs      []net.HardwareAddr
	ClientIDs []string

	// UID is the unique identifier of the persistent client.
	UID UID

	UpstreamsCacheSize    uint32
	UpstreamsCacheEnabled bool

	UseOwnSettings        bool
	FilteringEnabled      bool
	SafeBrowsingEnabled   bool
	ParentalEnabled       bool
	UseOwnBlockedServices bool
	IgnoreQueryLog        bool
	IgnoreStatistics      bool
}

Persistent contains information about persistent clients.

func (*Persistent) CloseUpstreams

func (c *Persistent) CloseUpstreams() (err error)

CloseUpstreams closes the client-specific upstream config of c if any.

func (*Persistent) EqualIDs

func (c *Persistent) EqualIDs(prev *Persistent) (equal bool)

EqualIDs returns true if the ids of the current and previous clients are the same.

func (*Persistent) IDs

func (c *Persistent) IDs() (ids []string)

IDs returns a list of client IDs containing at least one element.

func (*Persistent) IDsLen

func (c *Persistent) IDsLen() (n int)

IDsLen returns a length of client ids.

func (*Persistent) SetIDs

func (c *Persistent) SetIDs(ids []string) (err error)

SetIDs parses a list of strings into typed fields and returns an error if there is one.

func (*Persistent) SetSafeSearch

func (c *Persistent) SetSafeSearch(
	conf filtering.SafeSearchConfig,
	cacheSize uint,
	cacheTTL time.Duration,
) (err error)

SetSafeSearch initializes and sets the safe search filter for this client.

func (*Persistent) SetTags

func (c *Persistent) SetTags(tags []string, known *stringutil.Set)

SetTags sets the tags if they are known, otherwise logs an unknown tag.

func (*Persistent) ShallowClone

func (c *Persistent) ShallowClone() (clone *Persistent)

ShallowClone returns a deep copy of the client, except upstreamConfig, safeSearchConf, SafeSearch fields, because it's difficult to copy them.

type Runtime

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

Runtime is a client information from different sources.

func (*Runtime) Info

func (r *Runtime) Info() (cs Source, host string)

Info returns a client information from the highest-priority source.

func (*Runtime) IsEmpty

func (r *Runtime) IsEmpty() (ok bool)

IsEmpty returns true if there is no information from any source.

func (*Runtime) SetInfo

func (r *Runtime) SetInfo(cs Source, hosts []string)

SetInfo sets a host as a client information from the cs.

func (*Runtime) SetWHOIS

func (r *Runtime) SetWHOIS(info *whois.Info)

SetWHOIS sets a WHOIS client information. info must be non-nil.

func (*Runtime) Unset

func (r *Runtime) Unset(cs Source)

Unset clears a cs information.

func (*Runtime) WHOIS

func (r *Runtime) WHOIS() (info *whois.Info)

WHOIS returns a WHOIS client information.

type Source

type Source uint8

Source represents the source from which the information about the client has been obtained.

const (
	SourceWHOIS Source = iota + 1
	SourceARP
	SourceRDNS
	SourceDHCP
	SourceHostsFile
	SourcePersistent
)

Clients information sources. The order determines the priority.

func (Source) MarshalText

func (cs Source) MarshalText() (text []byte, err error)

MarshalText implements encoding.TextMarshaler for the Source.

func (Source) String

func (cs Source) String() (s string)

String returns a human-readable name of cs.

type UID

type UID uuid.UUID

UID is the type for the unique IDs of persistent clients.

func MustNewUID

func MustNewUID() (uid UID)

MustNewUID is a wrapper around NewUID that panics if there is an error.

func NewUID

func NewUID() (uid UID, err error)

NewUID returns a new persistent client UID. Any error returned is an error from the cryptographic randomness reader.

func (UID) MarshalText

func (uid UID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler for UID.

func (*UID) UnmarshalText

func (uid *UID) UnmarshalText(data []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface for UID.