filter

Documentation

Overview

Package filter contains the filter interface and its implementations along with types that combine them based on the settings in profile and filtering group.

Index

• Constants
• type BlockedServiceID
  • func NewBlockedServiceID(s string) (id BlockedServiceID, err error)
• type Config
• type ConfigClient
• type ConfigCustom
• type ConfigGroup
• type ConfigParental
• type ConfigRuleList
• type ConfigSafeBrowsing
• type ConfigSchedule
  • func (s *ConfigSchedule) Contains(t time.Time) (ok bool)
• type DayInterval
  • func (r *DayInterval) Validate() (err error)
• type Empty
• type EmptyMetrics
• type HashMatcher
• type ID
  • func NewID(s string) (id ID, err error)
• type Interface
• type Metrics
• type Request
• type Response
• type Result
• type ResultAllowed
• type ResultBlocked
• type ResultModifiedRequest
• type ResultModifiedResponse
• type RuleText
  • func NewRuleText(s string) (id RuleText, err error)
• type Storage
• type WeeklySchedule

Constants

const (
	IDNone = internal.IDNone

	IDAdGuardDNS        = internal.IDAdGuardDNS
	IDAdultBlocking     = internal.IDAdultBlocking
	IDBlockedService    = internal.IDBlockedService
	IDCustom            = internal.IDCustom
	IDGeneralSafeSearch = internal.IDGeneralSafeSearch
	IDNewRegDomains     = internal.IDNewRegDomains
	IDSafeBrowsing      = internal.IDSafeBrowsing
	IDYoutubeSafeSearch = internal.IDYoutubeSafeSearch
)

Special ID values shared across the AdGuard DNS system.

NOTE: DO NOT change these as other parts of the system depend on these values.

TODO(a.garipov): Consider removing those that aren't used outside of the filter subpackages.

const (
	GeneralTXTSuffix       = ".sb.dns.adguard.com"
	AdultBlockingTXTSuffix = ".pc.dns.adguard.com"
)

Default safe-browsing host suffixes.

const (
	// MaxDayIntervalStartMinutes is the maximum value for [DayInterval.Start].
	MaxDayIntervalStartMinutes = 24*60 - 1

	// MaxDayIntervalEndMinutes is the maximum value for [DayInterval.End].
	MaxDayIntervalEndMinutes = 24 * 60
)

const StoragePrefix = "filters/storage"

StoragePrefix is a common prefix for logging and refreshes of the filter storage.

TODO(a.garipov): Consider extracting these kinds of IDs to agdcache or some other package.

Types

type BlockedServiceID

type BlockedServiceID = internal.BlockedServiceID

BlockedServiceID is the ID of a blocked service. While these are usually human-readable, clients should treat them as opaque strings.

When a request is blocked by the service blocker, this ID is used as the text of the blocking rule.

func NewBlockedServiceID

func NewBlockedServiceID(s string) (id BlockedServiceID, err error)

NewBlockedServiceID converts a simple string into a BlockedServiceID and makes sure that it's valid. This should be preferred to a simple type conversion.

type Config

type Config interface {
	// contains filtered or unexported methods
}

Config is the sum type of [Storage.ForConfig] configurations.

Acceptable implementations are:

• nil
• *ConfigClient
• *ConfigGroup

type ConfigClient

type ConfigClient struct {
	// Custom is the configuration for identification or construction of a
	// custom filter for a client.  It must not be nil.
	Custom *ConfigCustom

	// Parental is the configuration for parental-control filtering.  It must
	// not be nil.
	Parental *ConfigParental

	// RuleList is the configuration for rule-list based filtering.  It must not
	// be nil.
	RuleList *ConfigRuleList

	// SafeBrowsing is the configuration for safe-browsing filtering.  It must
	// not be nil.
	SafeBrowsing *ConfigSafeBrowsing
}

ConfigClient is a Config for a client.

type ConfigCustom

type ConfigCustom = internal.ConfigCustom

ConfigCustom is the configuration for identification or construction of a custom filter for a client.

type ConfigGroup

type ConfigGroup struct {
	// Parental is the configuration for parental-control filtering.  It must
	// not be nil.
	Parental *ConfigParental

	// RuleList is the configuration for rule-list based filtering.  It must not
	// be nil.
	RuleList *ConfigRuleList

	// SafeBrowsing is the configuration for safe-browsing filtering.  It must
	// not be nil.
	SafeBrowsing *ConfigSafeBrowsing
}

ConfigGroup is a Config for a filtering group.

type ConfigParental

type ConfigParental struct {
	// PauseSchedule is the schedule for the pausing of the parental-control
	// filtering.  If it is nil, the parental-control filtering is never paused.
	// It is ignored if [ConfigParental.Enabled] is false.
	PauseSchedule *ConfigSchedule

	// BlockedServices are the IDs of the services blocked for this
	// parental-control configuration.  It is ignored if
	// [ConfigParental.Enabled] is false.
	BlockedServices []BlockedServiceID

	// Enabled shows whether the parental-control feature is enabled.
	Enabled bool

	// AdultBlockingEnabled shows whether the adult-blocking filtering should be
	// enforced.  It is ignored if [ConfigParental.Enabled] is false.
	AdultBlockingEnabled bool

	// SafeSearchGeneralEnabled shows whether the general safe-search filtering
	// should be enforced.  It is ignored if [ConfigParental.Enabled] is false.
	SafeSearchGeneralEnabled bool

	// SafeSearchYouTubeEnabled shows whether the YouTube safe-search filtering
	// should be enforced.  It is ignored if [ConfigParental.Enabled] is false.
	SafeSearchYouTubeEnabled bool
}

ConfigParental is the configuration for parental-control filtering.

type ConfigRuleList

type ConfigRuleList struct {
	// IDs are the IDs of the filtering rule lists used for this filtering
	// configuration.  They are ignored if [ConfigRuleList.Enabled] is false.
	IDs []ID

	// Enabled shows whether the rule-list based filtering is enabled.
	Enabled bool
}

ConfigRuleList is the configuration for rule-list based filtering.

type ConfigSafeBrowsing

type ConfigSafeBrowsing struct {
	// Enabled shows whether the safe-browsing hashprefix-based filtering should
	// is enabled.
	Enabled bool

	// DangerousDomainsEnabled shows whether the dangerous-domains safe-browsing
	// filtering should be enforced.  It is ignored if
	// [ConfigSafeBrowsing.Enabled] is false.
	DangerousDomainsEnabled bool

	// NewlyRegisteredDomainsEnabled shows whether the newly-registered domains
	// safe-browsing filtering should be enforced.  It is ignored if
	// [ConfigSafeBrowsing.Enabled] is false.
	NewlyRegisteredDomainsEnabled bool
}

ConfigSafeBrowsing is the configuration for safe-browsing filtering.

type ConfigSchedule

type ConfigSchedule struct {
	// Week is the parental protection schedule for every day of the week.  It
	// must not be nil.
	Week *WeeklySchedule

	// TimeZone is the profile's time zone.  It must not be nil.
	TimeZone *agdtime.Location
}

ConfigSchedule is the schedule of a client's parental protection. All fields must not be nil.

func (*ConfigSchedule) Contains

func (s *ConfigSchedule) Contains(t time.Time) (ok bool)

Contains returns true if t is within the allowed schedule.

type DayInterval

type DayInterval struct {
	// Start is the inclusive start of the interval in minutes.  It must be
	// within the range from 00:00:00 (0) to 23:59:59
	// ([MaxDayIntervalStartMinutes]).
	Start uint16

	// End is the exclusive end of the interval in minutes.  It must be within
	// the range from 00:00:00 (0) to 00:00:00 of the next day
	// ([MaxDayIntervalEndMinutes]).
	End uint16
}

DayInterval is an interval within a single day. The interval is exclusive at the end. An empty DayInterval is zero-length.

func (*DayInterval) Validate

func (r *DayInterval) Validate() (err error)

Validate returns the day range validation errors, if any. A nil DayInterval is considered valid.

type Empty

type Empty = internal.Empty

Empty is an Interface implementation that always returns nil.

type EmptyMetrics

type EmptyMetrics = internal.EmptyMetrics

EmptyMetrics is the implementation of the Metrics interface that does nothing.

type HashMatcher

type HashMatcher interface {
	MatchByPrefix(ctx context.Context, host string) (hashes []string, matched bool, err error)
}

HashMatcher is the interface for a safe-browsing and adult-blocking hash matcher, which is used to respond to a TXT query based on the domain name.

type ID

type ID = internal.ID

ID is the ID of a filter list. It is an opaque string.

func NewID

func NewID(s string) (id ID, err error)

NewID converts a simple string into an ID and makes sure that it's valid. This should be preferred to a simple type conversion.

type Interface

type Interface = internal.Interface

Interface is the DNS request and response filter interface.

type Metrics

type Metrics = internal.Metrics

Metrics is the interface for metrics of filters.

type Request

type Request = internal.Request

Request contains information about a request being filtered.

type Response

type Response = internal.Response

Response contains information about a response being filtered.

type Result

type Result = internal.Result

Result is a sum type of all possible filtering actions. See the following types as implementations:

• *ResultAllowed
• *ResultBlocked
• *ResultModifiedResponse
• *ResultModifiedRequest

type ResultAllowed

type ResultAllowed = internal.ResultAllowed

ResultAllowed means that this request or response was allowed by an allowlist rule within the given filter list.

type ResultBlocked

type ResultBlocked = internal.ResultBlocked

ResultBlocked means that this request or response was blocked by a blocklist rule within the given filter list.

type ResultModifiedRequest

type ResultModifiedRequest = internal.ResultModifiedRequest

ResultModifiedRequest means that this request was modified by a rewrite rule within the given filter list.

type ResultModifiedResponse

type ResultModifiedResponse = internal.ResultModifiedResponse

ResultModifiedResponse means that this response was rewritten or modified by a rewrite rule within the given filter list.

type RuleText

type RuleText = internal.RuleText

RuleText is the text of a single rule within a rule-list filter.

func NewRuleText

func NewRuleText(s string) (id RuleText, err error)

NewRuleText converts a simple string into an RuleText and makes sure that it's valid. This should be preferred to a simple type conversion.

type Storage

type Storage interface {
	// ForConfig returns a filter created from the configuration.  If c is nil,
	// f is [filter.Empty].
	ForConfig(ctx context.Context, c Config) (f Interface)

	// HasListID returns true if id is known to the storage.
	HasListID(id ID) (ok bool)
}

Storage is the interface for filter storages that can build a filter based on a configuration.

type WeeklySchedule

type WeeklySchedule [7]*DayInterval

WeeklySchedule is a schedule for one week. The index is the same as time.Weekday values. That is, 0 is Sunday, 1 is Monday, etc. A nil DayInterval means that there is no schedule for this day.