client

package
v0.107.52 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 4, 2024 License: GPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

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

TODO(a.garipov): Expand.

Index

Constants

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

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

Variables

This section is empty.

Functions

func ValidateClientID added in v0.107.46 

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 Config added in v0.107.52 

type Config struct {
	// AllowedTags is a list of all allowed client tags.
	AllowedTags []string
}

Config is the client storage configuration structure.

TODO(s.chzhen): Expand.

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 Persistent added in v0.107.46 

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

	// SafeSearch handles search engine hosts rewrites.
	SafeSearch filtering.SafeSearch

	// BlockedServices is the configuration of blocked services of a client.  It
	// must not be nil after initialization.
	BlockedServices *filtering.BlockedServices

	// Name of the persistent client.  Must not be empty.
	Name string

	// Tags is a list of client tags that categorize the client.
	Tags []string

	// Upstreams is a list of custom upstream DNS servers for the client.
	Upstreams []string

	// IPs is a list of IP addresses that identify the client.  The client must
	// have at least one ID (IP, subnet, MAC, or ClientID).
	IPs []netip.Addr

	// Subnets identifying the client.  The client must have at least one ID
	// (IP, subnet, MAC, or ClientID).
	//
	// TODO(s.chzhen):  Use netutil.Prefix.
	Subnets []netip.Prefix

	// MACs identifying the client.  The client must have at least one ID (IP,
	// subnet, MAC, or ClientID).
	MACs []net.HardwareAddr

	// ClientIDs identifying the client.  The client must have at least one ID
	// (IP, subnet, MAC, or ClientID).
	ClientIDs []string

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

	// UpstreamsCacheSize is the cache size for custom upstreams.
	UpstreamsCacheSize uint32

	// UpstreamsCacheEnabled specifies whether custom upstreams are used.
	UpstreamsCacheEnabled bool

	// UseOwnSettings specifies whether custom filtering settings are used.
	UseOwnSettings bool

	// FilteringEnabled specifies whether filtering is enabled.
	FilteringEnabled bool

	// SafeBrowsingEnabled specifies whether safe browsing is enabled.
	SafeBrowsingEnabled bool

	// ParentalEnabled specifies whether parental control is enabled.
	ParentalEnabled bool

	// UseOwnBlockedServices specifies whether custom services are blocked.
	UseOwnBlockedServices bool

	// IgnoreQueryLog specifies whether the client requests are logged.
	IgnoreQueryLog bool

	// IgnoreStatistics  specifies whether the client requests are counted.
	IgnoreStatistics bool

	// SafeSearchConf is the safe search filtering configuration.
	//
	// TODO(d.kolyshev): Make SafeSearchConf a pointer.
	SafeSearchConf filtering.SafeSearchConfig
}

Persistent contains information about persistent clients.

func (*Persistent) CloseUpstreams added in v0.107.46 

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

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

func (*Persistent) EqualIDs added in v0.107.46 

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 added in v0.107.46 

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

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

func (*Persistent) IDsLen added in v0.107.46 

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

IDsLen returns a length of client ids.

func (*Persistent) SetIDs added in v0.107.46 

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 added in v0.107.46 

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) ShallowClone added in v0.107.46 

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 added in v0.107.44 

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

Runtime is a client information from different sources.

func NewRuntime added in v0.107.49 

func NewRuntime(ip netip.Addr) (r *Runtime)

NewRuntime constructs a new runtime client. ip must be valid IP address.

TODO(s.chzhen): Validate IP address.

func (*Runtime) Addr added in v0.107.49 

func (r *Runtime) Addr() (ip netip.Addr)

Addr returns an IP address of the client.

func (*Runtime) Info added in v0.107.44 

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

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

func (*Runtime) SetInfo added in v0.107.44 

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

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

func (*Runtime) SetWHOIS added in v0.107.44 

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

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

func (*Runtime) WHOIS added in v0.107.44 

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

WHOIS returns a WHOIS client information.

type RuntimeIndex added in v0.107.49 

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

RuntimeIndex stores information about runtime clients.

func NewRuntimeIndex added in v0.107.49 

func NewRuntimeIndex() (ri *RuntimeIndex)

NewRuntimeIndex returns initialized runtime index.

func (*RuntimeIndex) Add added in v0.107.49 

func (ri *RuntimeIndex) Add(rc *Runtime)

Add saves the runtime client in the index. IP address of a client must be unique. See [Runtime.Client]. rc must not be nil.

func (*RuntimeIndex) Client added in v0.107.49 

func (ri *RuntimeIndex) Client(ip netip.Addr) (rc *Runtime)

Client returns the saved runtime client by ip. If no such client exists, returns nil.

func (*RuntimeIndex) Delete added in v0.107.49 

func (ri *RuntimeIndex) Delete(ip netip.Addr)

Delete removes the runtime client by ip.

func (*RuntimeIndex) DeleteBySource added in v0.107.49 

func (ri *RuntimeIndex) DeleteBySource(src Source) (n int)

DeleteBySource removes all runtime clients that have information only from the specified source and returns the number of removed clients.

func (*RuntimeIndex) Range added in v0.107.49 

func (ri *RuntimeIndex) Range(f func(rc *Runtime) (cont bool))

Range calls f for each runtime client in an undefined order.

func (*RuntimeIndex) Size added in v0.107.49 

func (ri *RuntimeIndex) Size() (n int)

Size returns the number of the runtime clients.

type Source added in v0.107.37 

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 added in v0.107.37 

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

MarshalText implements encoding.TextMarshaler for the Source.

func (Source) String added in v0.107.37 

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

String returns a human-readable name of cs.

type Storage added in v0.107.52 

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

Storage contains information about persistent and runtime clients.

func NewStorage added in v0.107.52 

func NewStorage(conf *Config) (s *Storage)

NewStorage returns initialized client storage. conf must not be nil.

func (*Storage) Add added in v0.107.52 

func (s *Storage) Add(p *Persistent) (err error)

Add stores persistent client information or returns an error.

func (*Storage) AddRuntime added in v0.107.52 

func (s *Storage) AddRuntime(rc *Runtime)

AddRuntime saves the runtime client information in the storage. IP address of a client must be unique. rc must not be nil.

TODO(s.chzhen): Use it.

func (*Storage) ClientRuntime added in v0.107.52 

func (s *Storage) ClientRuntime(ip netip.Addr) (rc *Runtime)

ClientRuntime returns a copy of the saved runtime client by ip. If no such client exists, returns nil.

TODO(s.chzhen): Use it.

func (*Storage) CloseUpstreams added in v0.107.52 

func (s *Storage) CloseUpstreams() (err error)

CloseUpstreams closes upstream configurations of persistent clients.

func (*Storage) DeleteBySource added in v0.107.52 

func (s *Storage) DeleteBySource(src Source) (n int)

DeleteBySource removes all runtime clients that have information only from the specified source and returns the number of removed clients.

TODO(s.chzhen): Use it.

func (*Storage) DeleteRuntime added in v0.107.52 

func (s *Storage) DeleteRuntime(ip netip.Addr)

DeleteRuntime removes the runtime client by ip.

TODO(s.chzhen): Use it.

func (*Storage) Find added in v0.107.52 

func (s *Storage) Find(id string) (p *Persistent, ok bool)

Find finds persistent client by string representation of the client ID, IP address, or MAC. And returns its shallow copy.

func (*Storage) FindByMAC added in v0.107.52 

func (s *Storage) FindByMAC(mac net.HardwareAddr) (p *Persistent, ok bool)

FindByMAC finds persistent client by MAC and returns its shallow copy.

func (*Storage) FindByName added in v0.107.52 

func (s *Storage) FindByName(name string) (p *Persistent, ok bool)

FindByName finds persistent client by name. And returns its shallow copy.

func (*Storage) FindLoose added in v0.107.52 

func (s *Storage) FindLoose(ip netip.Addr, id string) (p *Persistent, ok bool)

FindLoose is like Storage.Find but it also tries to find a persistent client by IP address without zone. It strips the IPv6 zone index from the stored IP addresses before comparing, because querylog entries don't have it. See TODO on [querylog.logEntry.IP].

Note that multiple clients can have the same IP address with different zones. Therefore, the result of this method is indeterminate.

func (*Storage) RangeByName added in v0.107.52 

func (s *Storage) RangeByName(f func(c *Persistent) (cont bool))

RangeByName calls f for each persistent client sorted by name, unless cont is false.

func (*Storage) RangeRuntime added in v0.107.52 

func (s *Storage) RangeRuntime(f func(rc *Runtime) (cont bool))

RangeRuntime calls f for each runtime client in an undefined order.

TODO(s.chzhen): Use it.

func (*Storage) RemoveByName added in v0.107.52 

func (s *Storage) RemoveByName(name string) (ok bool)

RemoveByName removes persistent client information. ok is false if no such client exists by that name.

func (*Storage) Size added in v0.107.52 

func (s *Storage) Size() (n int)

Size returns the number of persistent clients.

func (*Storage) SizeRuntime added in v0.107.52 

func (s *Storage) SizeRuntime() (n int)

SizeRuntime returns the number of the runtime clients.

TODO(s.chzhen): Use it.

func (*Storage) Update added in v0.107.52 

func (s *Storage) Update(name string, p *Persistent) (err error)

Update finds the stored persistent client by its name and updates its information from p.

type UID added in v0.107.46 

type UID uuid.UUID

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

func MustNewUID added in v0.107.46 

func MustNewUID() (uid UID)

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

func NewUID added in v0.107.46 

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 added in v0.107.46 

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

MarshalText implements the encoding.TextMarshaler for UID.

func (*UID) UnmarshalText added in v0.107.46 

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

UnmarshalText implements the encoding.TextUnmarshaler interface for UID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.