filter

type BlockedServiceID string

type CategoryID string

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

type ConfigCategories struct {
	// IDs are the IDs of the filtering categories used for this filtering
	// configuration.  They are ignored if [ConfigRuleList.Enabled] is false.
	IDs []CategoryID

	// Enabled shows whether the category filtering is enabled.
	Enabled bool
}

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
}

type ConfigCustom struct {
	// Filter is the custom filter to use for this client, if any.  If
	// [ConfigCustom.Enabled] is true, Filter must not be nil.
	Filter Custom

	// Enabled shows whether the custom filters are applied at all.
	Enabled bool
}

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
}

type ConfigParental struct {
	// Categories is the configuration for category filtering.  It must not be
	// nil.  It is ignored if [ConfigParental.Enabled] is false.
	Categories *ConfigCategories

	// 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
}

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
}

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
}

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
}

type Custom interface {
	// Rules returns the rules used to create the filter.  rules must not be
	// modified.
	Rules() (rules []RuleText)

	// SetURLFilterResult applies the DNS filtering engine and sets the values
	// in res if any have matched.  ok must be true if there is a match.  req
	// and res must not be nil.
	SetURLFilterResult(
		ctx context.Context,
		req *urlfilter.DNSRequest,
		res *urlfilter.DNSResult,
	) (ok bool)
}

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
}

type Empty struct{}

type EmptyMetrics struct{}

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

type ID string

type Interface interface {
	// FilterRequest filters a DNS request based on the information provided
	// about the request.  req must be valid.
	FilterRequest(ctx context.Context, req *Request) (r Result, err error)

	// FilterResponse filters a DNS response based on the information provided
	// about the response.  resp must be valid.
	FilterResponse(ctx context.Context, resp *Response) (r Result, err error)
}

type Metrics interface {
	// SetFilterStatus sets the status of a filter by its id.  If err is not
	// nil, updTime and ruleCount are ignored.
	SetFilterStatus(
		ctx context.Context,
		id string,
		updTime time.Time,
		ruleCount int,
		err error,
	)
}

type Request struct {
	// DNS is the original DNS request used to create filtered responses.  It
	// must not be nil and must have exactly one question.
	DNS *dns.Msg

	// Messages is used to create filtered responses for this request.  It must
	// not be nil.
	Messages *dnsmsg.Constructor

	// RemoteIP is the remote IP address of the client.
	RemoteIP netip.Addr

	// ClientName is the client name for rule-list filtering.
	ClientName string

	// Host is the lowercased, non-FQDN version of the hostname from the
	// question of the request.
	Host string

	// QType is the type of question for this request.
	QType dnsmsg.RRType

	// QClass is the class of question for this request.
	QClass dnsmsg.Class
}

type Response struct {
	// DNS is the original DNS response used to create filtered responses.  It
	// must not be nil and must have exactly one question.
	DNS *dns.Msg

	// RemoteIP is the remote IP address of the client.
	RemoteIP netip.Addr

	// ClientName is the client name for rule-list filtering.
	ClientName string
}

type Result interface {
	// MatchedRule returns data about the matched rule and its rule list.
	MatchedRule() (id ID, text RuleText)
	// contains filtered or unexported methods
}

type ResultAllowed struct {
	List ID
	Rule RuleText
}

type ResultBlocked struct {
	List ID
	Rule RuleText
}

type ResultModifiedRequest struct {
	// Msg is the new, rewritten or modified request.
	Msg *dns.Msg

	// List is the ID of the filter list.
	List ID

	// Rule is the filtering rule that triggered the rewrite.
	Rule RuleText
}

type ResultModifiedResponse struct {
	// Msg is the new, rewritten or modified response.
	Msg *dns.Msg

	// List is the ID of the filter list.
	List ID

	// Rule is the filtering rule that triggered the rewrite.
	Rule RuleText
}

type RuleText string

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)
}

type WeeklySchedule [7]*DayInterval