Documentation
¶
Overview ¶
Package rulelist contains the implementation of the standard rule-list filter that wraps an urlfilter filtering-engine.
TODO(a.garipov): Add a new update worker.
Index ¶
Constants ¶
const ( EngineNameAllow = "allow" EngineNameBlock = "block" EngineNameCustom = "custom" )
Common engine names.
const DefaultMaxRuleListSize = 64 * datasize.MB
DefaultMaxRuleListSize is the default maximum filtering-rule list size.
const DefaultRuleBufSize = 1024
DefaultRuleBufSize is the default length of a buffer used to read a line with a filtering rule, in bytes.
TODO(a.garipov): Consider using datasize.ByteSize. It is currently only used as an int.
const ErrHTML errors.Error = "data is HTML, not plain text"
ErrHTML is returned by Parser.Parse if the data is likely to be HTML.
TODO(a.garipov): This error is currently returned to the UI. Stop that and make it all-lowercase.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is a single DNS filter based on one or more rule lists. This structure contains the filtering engine combining several rule lists.
TODO(a.garipov): Merge with TextEngine in some way?
func NewEngine ¶
func NewEngine(c *EngineConfig) (e *Engine)
NewEngine returns a new rule-list filtering engine. The engine is not refreshed, so a refresh should be performed before use.
func (*Engine) FilterRequest ¶
func (e *Engine) FilterRequest( req *urlfilter.DNSRequest, ) (res *urlfilter.DNSResult, hasMatched bool)
FilterRequest returns the result of filtering req using the DNS filtering engine.
func (*Engine) Refresh ¶
func (e *Engine) Refresh( ctx context.Context, parseBuf []byte, cli *http.Client, cacheDir string, maxSize datasize.ByteSize, ) (err error)
Refresh updates all rule lists in e. ctx is used for cancellation. parseBuf, cli, cacheDir, and maxSize are used for updates of rule-list filters; see Filter.Refresh.
TODO(a.garipov): Unexport and test in an internal test or through engine tests.
type EngineConfig ¶
type EngineConfig struct {
// Logger is used to log the operation of the engine. It must not be nil.
Logger *slog.Logger
// name is the human-readable name of the engine; see [EngineNameAllow] and
// similar constants.
Name string
// Filters is the data about rule lists in this engine. There must be no
// other references to the items of this slice. Each item must not be nil.
Filters []*Filter
}
EngineConfig is the configuration for rule-list filtering engines created by combining refreshable filters.
type Filter ¶
type Filter struct {
// contains filtered or unexported fields
}
Filter contains information about a single rule-list filter.
TODO(a.garipov): Use.
func NewFilter ¶
func NewFilter(c *FilterConfig) (f *Filter, err error)
NewFilter creates a new rule-list filter. The filter is not refreshed, so a refresh should be performed before use.
func (*Filter) Refresh ¶
func (f *Filter) Refresh( ctx context.Context, parseBuf []byte, cli *http.Client, cacheDir string, maxSize datasize.ByteSize, ) (parseRes *ParseResult, err error)
Refresh updates the data in the rule-list filter. parseBuf is the initial buffer used to parse information from the data. cli and maxSize are only used when f is a URL-based list.
TODO(a.garipov): Unexport and test in an internal test or through engine tests.
TODO(a.garipov): Consider not returning parseRes.
type FilterConfig ¶
type FilterConfig struct {
// URL is the URL of this rule-list filter. Supported schemes are:
// - http
// - https
// - file
URL *url.URL
// Name is the human-readable name of this rule-list filter. If not set, it
// is either taken from the rule-list data or generated synthetically from
// the UID.
Name string
// UID is the unique ID of this rule-list filter.
UID UID
// URLFilterID is used for working with package urlfilter.
URLFilterID URLFilterID
// Enabled, if true, means that this rule-list filter is used for filtering.
Enabled bool
}
FilterConfig contains the configuration for a Filter.
type ParseResult ¶
type ParseResult struct {
// Title is the title contained within the filtering-rule list, if any.
Title string
// RulesCount is the number of rules in the list. It excludes empty lines
// and comments.
RulesCount int
// BytesWritten is the number of bytes written to dst.
BytesWritten int
// Checksum is the CRC-32 checksum of the rules content. That is, excluding
// empty lines and comments.
Checksum uint32
}
ParseResult contains information about the results of parsing a filtering-rule list by Parser.Parse.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser is a filtering-rule parser that collects data, such as the checksum and the title, as well as counts rules and removes comments.
type Storage ¶
type Storage struct {
// contains filtered or unexported fields
}
Storage contains the main filtering engines, including the allowlist, the blocklist, and the user's custom filtering rules.
func NewStorage ¶
func NewStorage(c *StorageConfig) (s *Storage, err error)
NewStorage creates a new filtering-engine storage. The engines are not refreshed, so a refresh should be performed before use.
type StorageConfig ¶
type StorageConfig struct {
// Logger is used to log the operation of the storage. It must not be nil.
Logger *slog.Logger
// HTTPClient is the HTTP client used to perform updates of rule lists.
// It must not be nil.
HTTPClient *http.Client
// CacheDir is the path to the directory used to cache rule-list files.
// It must be set.
CacheDir string
// AllowFilters are the filtering-rule lists used to exclude domain names
// from the filtering. Each item must not be nil.
AllowFilters []*Filter
// BlockFilters are the filtering-rule lists used to block domain names.
// Each item must not be nil.
BlockFilters []*Filter
// CustomRules contains custom rules of the user. They have priority over
// both allow- and blacklist rules.
CustomRules []string
// MaxRuleListTextSize is the maximum size of a rule-list file. It must be
// greater than zero.
MaxRuleListTextSize datasize.ByteSize
}
StorageConfig is the configuration for the filtering-engine storage.
type TextEngine ¶
type TextEngine struct {
// contains filtered or unexported fields
}
TextEngine is a single DNS filter based on a list of rules in text form.
func NewTextEngine ¶
func NewTextEngine(c *TextEngineConfig) (e *TextEngine, err error)
NewTextEngine returns a new rule-list filtering engine that uses rules directly. The engine is ready to use and should not be refreshed.
func (*TextEngine) Close ¶
func (e *TextEngine) Close() (err error)
Close closes the underlying rule list engine as well as the rule lists.
func (*TextEngine) FilterRequest ¶
func (e *TextEngine) FilterRequest( req *urlfilter.DNSRequest, ) (res *urlfilter.DNSResult, hasMatched bool)
FilterRequest returns the result of filtering req using the DNS filtering engine.
type TextEngineConfig ¶
type TextEngineConfig struct {
// name is the human-readable name of the engine; see [EngineNameAllow] and
// similar constants.
Name string
// Rules is the text of the filtering rules for this engine.
Rules []string
// ID is the ID to use inside a URL-filter engine.
ID URLFilterID
}
TextEngineConfig is the configuration for a rule-list filtering engine created from a filtering rule text.
type UID ¶
UID is the type for the unique IDs of filtering-rule lists.
func MustNewUID ¶
func MustNewUID() (uid UID)
MustNewUID is a wrapper around NewUID that panics if there is an error.
func NewUID ¶
NewUID returns a new filtering-rule list UID. Any error returned is an error from the cryptographic randomness reader.
func (UID) String ¶
String implements the fmt.Stringer interface for UID.
type URLFilterID ¶
type URLFilterID = int
URLFilterID is a semantic type-alias for IDs used for working with package urlfilter.
const ( URLFilterIDCustom URLFilterID = 0 URLFilterIDEtcHosts URLFilterID = -1 URLFilterIDBlockedService URLFilterID = -2 URLFilterIDParentalControl URLFilterID = -3 URLFilterIDSafeBrowsing URLFilterID = -4 URLFilterIDSafeSearch URLFilterID = -5 )
The IDs of built-in filter lists.
NOTE: Do not change without the need for it and keep in sync with client/src/helpers/constants.ts.
TODO(a.garipov): Add type URLFilterID once it is used consistently in package filtering.
TODO(d.kolyshev): Add URLFilterIDLegacyRewrite here and to the UI.
Source Files