Documentation ¶
Overview ¶
Package rules contains implementation of all kinds of blocking rules
Index ¶
- Constants
- Variables
- type CosmeticOption
- type CosmeticRule
- type CosmeticRuleType
- type DNSRewrite
- type HostRule
- type MatchingResult
- type NetworkRule
- func (f *NetworkRule) GetFilterListID() int
- func (f *NetworkRule) GetPermittedDomains() []string
- func (f *NetworkRule) IsGeneric() bool
- func (f *NetworkRule) IsHigherPriority(r *NetworkRule) bool
- func (f *NetworkRule) IsHostLevelNetworkRule() bool
- func (f *NetworkRule) IsOptionDisabled(option NetworkRuleOption) bool
- func (f *NetworkRule) IsOptionEnabled(option NetworkRuleOption) bool
- func (f *NetworkRule) IsRegexRule() bool
- func (f *NetworkRule) Match(r *Request) bool
- func (f *NetworkRule) String() string
- func (f *NetworkRule) Text() string
- type NetworkRuleOption
- type RCode
- type RRType
- type RRValue
- type Request
- type RequestType
- type Rule
- type RuleSyntaxError
Constants ¶
const ( // MaskStartURL definition: // Matching the beginning of an address. With this character you don't // have to specify a particular protocol and subdomain in address mask. // It means, || stands for http://*., https://*., ws://*., wss://*. at once. MaskStartURL = "||" // MaskPipe definition: // A pointer to the beginning or the end of address. The value depends on the // character placement in the mask. For example, a rule swf| corresponds // to http://example.com/annoyingflash.swf , but not to http://example.com/swf/index.html. // |http://example.org corresponds to http://example.org, but not to http://domain.com?url=http://example.org. MaskPipe = "|" // MaskSeparator definition: // Separator character mark. Separator character is any character, // but a letter, a digit, or one of the following: _ - . % MaskSeparator = "^" // MaskAnyCharacter is a wildcard character. It is used to represent "any set of characters". // This can also be an empty string or a string of any length. MaskAnyCharacter = "*" // RegexAnyCharacter corresponds to MaskAnyCharacter. RegexAnyCharacter = ".*" // RegexSeparator corresponds to MaskSeparator. RegexSeparator = "([^ a-zA-Z0-9.%_-]|$)" // RegexStartURL corresponds to MaskStartURL. RegexStartURL = "^(http|https|ws|wss)://([a-z0-9-_.]+\\.)?" // RegexEndString corresponds to MaskPipe if it is in the end of a pattern. RegexEndString = "$" // RegexStartString corresponds to MaskPipe if it is in the beginning of a pattern. RegexStartString = "^" )
Variables ¶
var ErrTooWideRule = errors.New("the rule is too wide, add domain, client or ctag restrictions or make it more specific")
ErrTooWideRule - returned if the rule matches all urls but has no domain, client or ctag restrictions
var ErrUnsupportedRule = errors.New("this type of rules is unsupported")
ErrUnsupportedRule signals that this might be a valid rule type, but it is not yet supported by this library
Functions ¶
This section is empty.
Types ¶
type CosmeticOption ¶
type CosmeticOption uint32
CosmeticOption is the enumeration of various content script options. Depending on the set of enabled flags the content script will contain different set of settings.
const ( // CosmeticOptionGenericCSS - if generic elemhide and CSS rules are enabled. // Can be disabled by a $generichide rule. CosmeticOptionGenericCSS CosmeticOption = 1 << iota // CosmeticOptionCSS - if elemhide and CSS rules are enabled. // Can be disabled by an $elemhide rule. CosmeticOptionCSS // CosmeticOptionJS - if JS rules and scriptlets are enabled. // Can be disabled by a $jsinject rule. CosmeticOptionJS // TODO: Add support for these flags // They are useful when content script is injected into an iframe // In this case we can check what flags were applied to the top-level frame CosmeticOptionSourceGenericCSS CosmeticOptionSourceCSS CosmeticOptionSourceJS // CosmeticOptionAll - everything is enabled CosmeticOptionAll = CosmeticOptionGenericCSS | CosmeticOptionCSS | CosmeticOptionJS // CosmeticOptionNone - everything is disabled CosmeticOptionNone = CosmeticOption(0) )
CosmeticOption enumeration
type CosmeticRule ¶
type CosmeticRule struct { RuleText string // RuleText is the original rule text FilterListID int // Filter list identifier Type CosmeticRuleType // Type of the rule // Content meaning depends on the rule type. // Element hiding: content is just a selector // CSS: content is a selector + style definition // JS: text of the script to be injected Content string // Whitelist means that this rule is meant to disable rules with the same content on the specified domains // For instance, https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#elemhide-exceptions Whitelist bool // ExtendedCSS means that this rule is supposed to be applied by the javascript library // https://github.com/AdguardTeam/ExtendedCss ExtendedCSS bool // contains filtered or unexported fields }
CosmeticRule represents a cosmetic rule (element hiding, CSS, scriptlet)
func NewCosmeticRule ¶
func NewCosmeticRule(ruleText string, filterListID int) (*CosmeticRule, error)
NewCosmeticRule parses the rule text and creates a
func (*CosmeticRule) GetFilterListID ¶
func (f *CosmeticRule) GetFilterListID() int
GetFilterListID returns ID of the filter list this rule belongs to
func (*CosmeticRule) GetPermittedDomains ¶
func (f *CosmeticRule) GetPermittedDomains() []string
GetPermittedDomains returns a list of permitted domains
func (*CosmeticRule) IsGeneric ¶
func (f *CosmeticRule) IsGeneric() bool
IsGeneric returns true if rule can be considered generic (is not limited to a specific domain)
func (*CosmeticRule) Match ¶
func (f *CosmeticRule) Match(hostname string) bool
Match returns true if this rule can be used on the specified hostname
func (*CosmeticRule) String ¶
func (f *CosmeticRule) String() string
String returns original rule text
func (*CosmeticRule) Text ¶
func (f *CosmeticRule) Text() string
Text returns the original rule text Implements the `Rule` interface
type CosmeticRuleType ¶
type CosmeticRuleType uint
CosmeticRuleType is the enumeration of different cosmetic rules
const ( CosmeticElementHiding CosmeticRuleType = iota // ## rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-elemhide-rules) CosmeticCSS // #$# rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#cosmetic-css-rules) CosmeticJS // #%# rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#javascript-rules) // TODO: Move HTML filtering rules to a different file/structure CosmeticHTML // $$ rules (https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#html-filtering-rules) )
CosmeticRuleType enumeration
type DNSRewrite ¶ added in v0.14.0
type DNSRewrite struct { // RCode is the new DNS RCODE. RCode RCode // RRType is the new DNS resource record (RR) type. It is only non-zero // if RCode is dns.RCodeSuccess. RRType RRType // Value is the value for the record. See the RRValue documentation for // more details. Value RRValue // NewCNAME is the new CNAME. If set, clients must ignore other fields, // resolve the CNAME, and set the new A and AAAA records accordingly. NewCNAME string }
DNSRewrite is a DNS rewrite ($dnsrewrite) rule.
type HostRule ¶
type HostRule struct { RuleText string // RuleText is the original rule text FilterListID int // Filter list identifier Hostnames []string // Hostnames is the list of hostnames that is configured IP net.IP // ip address }
HostRule is a structure for simple host-level rules (i.e. /etc/hosts syntax). http://man7.org/linux/man-pages/man5/hosts.5.html It also supports "just domain" syntax. In this case, the IP will be set to 0.0.0.0.
func NewHostRule ¶
NewHostRule parses the rule and creates a new HostRule instance The format is: IP_address canonical_hostname [aliases...]
func (*HostRule) GetFilterListID ¶
GetFilterListID returns ID of the filter list this rule belongs to
type MatchingResult ¶
type MatchingResult struct { // BasicRule - a rule matching the request. // It could lead to one of the following: // * block the request // * unblock the request (a regular whitelist rule or a document-level whitelist rule) // * modify the way cosmetic rules work for this request // * modify the response (see $redirect rules) BasicRule *NetworkRule // DocumentRule - a rule matching the request's referrer and having on of the following modifiers: // * $document -- this one basically disables everything // * $urlblock -- disables network-level rules (not cosmetic) // * $genericblock -- disables generic network-level rules // // Other document-level modifiers like $jsinject or $content will be ignored here // as they don't do anything DocumentRule *NetworkRule // CspRules - a set of rules modifying the response's content-security-policy // See $csp modifier CspRules []*NetworkRule // CookieRules - a set of rules modifying the request's and response's cookies // See $cookie modifier CookieRules []*NetworkRule // ReplaceRules -- a set of rules modifying the response's content // See $replace modifier ReplaceRules []*NetworkRule // StealthRule - this is a whitelist rule that negates stealth mode features // Note that the stealth rule can be be received from both rules and sourceRules // https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#stealth-modifier StealthRule *NetworkRule }
MatchingResult contains all the rules matching a web request, and provides methods that define how a web request should be processed
func NewMatchingResult ¶
func NewMatchingResult(rules, sourceRules []*NetworkRule) MatchingResult
NewMatchingResult creates an instance of the MatchingResult struct and fills it with the rules. rules - a set of rules matching the request URL sourceRules - a set of rules matching the referrer nolint:gocyclo
func (*MatchingResult) GetBasicResult ¶
func (m *MatchingResult) GetBasicResult() *NetworkRule
GetBasicResult returns a rule that should be applied to the web request.
Possible outcomes are: * returns nil -- bypass the request. * returns a whitelist rule -- bypass the request. * returns a blocking rule -- block the request.
func (*MatchingResult) GetCosmeticOption ¶
func (m *MatchingResult) GetCosmeticOption() CosmeticOption
GetCosmeticOption returns a bit-flag with the list of cosmetic options
type NetworkRule ¶
type NetworkRule struct { RuleText string // RuleText is the original rule text Whitelist bool // true if this is an exception rule FilterListID int // Filter list identifier Shortcut string // the longest substring of the rule pattern with no special characters // DNSRewrite is the DNS rewrite rule, if any. DNSRewrite *DNSRewrite sync.Mutex // contains filtered or unexported fields }
NetworkRule is a basic filtering rule https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#basic-rules
func NewNetworkRule ¶
func NewNetworkRule(ruleText string, filterListID int) (*NetworkRule, error)
NewNetworkRule parses the rule text and returns a filter rule
func (*NetworkRule) GetFilterListID ¶
func (f *NetworkRule) GetFilterListID() int
GetFilterListID returns ID of the filter list this rule belongs to
func (*NetworkRule) GetPermittedDomains ¶
func (f *NetworkRule) GetPermittedDomains() []string
GetPermittedDomains - returns an array of domains this rule is allowed on
func (*NetworkRule) IsGeneric ¶
func (f *NetworkRule) IsGeneric() bool
IsGeneric returns true if the rule is considered "generic" "generic" means that the rule is not restricted to a limited set of domains Please note that it might be forbidden on some domains, though.
func (*NetworkRule) IsHigherPriority ¶
func (f *NetworkRule) IsHigherPriority(r *NetworkRule) bool
IsHigherPriority checks if the rule has higher priority that the specified rule whitelist + $important > $important > whitelist > basic rules nolint: gocyclo
func (*NetworkRule) IsHostLevelNetworkRule ¶
func (f *NetworkRule) IsHostLevelNetworkRule() bool
IsHostLevelNetworkRule checks if this rule can be used for hosts-level blocking
func (*NetworkRule) IsOptionDisabled ¶
func (f *NetworkRule) IsOptionDisabled(option NetworkRuleOption) bool
IsOptionDisabled returns true if the specified option is disabled
func (*NetworkRule) IsOptionEnabled ¶
func (f *NetworkRule) IsOptionEnabled(option NetworkRuleOption) bool
IsOptionEnabled returns true if the specified option is enabled
func (*NetworkRule) IsRegexRule ¶
func (f *NetworkRule) IsRegexRule() bool
IsRegexRule returns true if rule's pattern is a regular expression
func (*NetworkRule) Match ¶
func (f *NetworkRule) Match(r *Request) bool
Match checks if this filtering rule matches the specified request
func (*NetworkRule) String ¶
func (f *NetworkRule) String() string
String returns original rule text
func (*NetworkRule) Text ¶
func (f *NetworkRule) Text() string
Text returns the original rule text Implements the `Rule` interface
type NetworkRuleOption ¶
type NetworkRuleOption uint64
NetworkRuleOption is the enumeration of various rule options In order to save memory, we store some options as a flag
const ( OptionThirdParty NetworkRuleOption = 1 << iota // $third-party modifier OptionMatchCase // $match-case modifier OptionImportant // $important modifier OptionBadfilter // $badfilter modifier OptionElemhide // $elemhide modifier OptionGenerichide // $generichide modifier OptionGenericblock // $genericblock modifier OptionJsinject // $jsinject modifier OptionUrlblock // $urlblock modifier OptionContent // $content modifier OptionExtension // $extension modifier // Whitelist -- specific to Stealth mode OptionStealth // $stealth // Content-modifying (TODO: get rid of, deprecated in favor of $redirect) OptionEmpty // $empty OptionMp4 // $mp4 // Blocking OptionPopup // $popup // Advanced (TODO: Implement) OptionCsp // $csp OptionReplace // $replace OptionCookie // $cookie OptionRedirect // $redirect // Blacklist-only options OptionBlacklistOnly = OptionPopup | OptionEmpty | OptionMp4 // Whitelist-only options OptionWhitelistOnly = OptionElemhide | OptionGenericblock | OptionGenerichide | OptionJsinject | OptionUrlblock | OptionContent | OptionExtension | OptionStealth // Options supported by host-level network rules OptionHostLevelRulesOnly = OptionImportant | OptionBadfilter )
NetworkRuleOption enumeration
func (NetworkRuleOption) Count ¶
func (o NetworkRuleOption) Count() int
Count returns the count of enabled options
type RCode ¶ added in v0.14.0
type RCode = int
RCode is a semantic alias for int when used as a DNS response code RCODE.
type RRType ¶ added in v0.14.0
type RRType = uint16
RRType is a semantic alias for uint16 when used as a DNS resource record (RR) type.
type RRValue ¶ added in v0.14.0
type RRValue = interface{}
RRValue is the value of a resource record. If the coresponding RR is either dns.TypeA or dns.TypeAAAA, the underlying type of RRValue is net.IP. If the RR is dns.TypeTXT, the underlying type of Value is string. Otherwise, currently, it is nil. New types may be added in the future.
type Request ¶
type Request struct { RequestType RequestType // request type ThirdParty bool // true if request is third-party // IsHostnameRequest means that the request is for a given Hostname, // and not for a URL, and we don't really know what protocol it is. // This can be true for DNS requests, or for HTTP CONNECT, or SNI matching. IsHostnameRequest bool URL string // Request URL URLLowerCase string // Request URL in lower case Hostname string // Request hostname Domain string // Request domain (eTLD+1) // DNSType is the type of the resource record (RR) of a DNS request. // See package github.com/miekg/dns for all acceptable constants. DNSType uint16 SourceURL string // Source URL SourceHostname string // Source hostname SourceDomain string // Source domain (eTLD+1) SortedClientTags []string // Sorted list of client tags ($ctag) ClientIP string // Client IP address ClientName string // Client name }
Request represents a web request with all it's necessary properties
func NewRequest ¶
func NewRequest(url, sourceURL string, requestType RequestType) *Request
NewRequest creates a new instance of "Request" and populates it's fields
func NewRequestForHostname ¶
NewRequestForHostname creates a new instance of "Request" for matching hostname. It uses "http://" as a protocol and TypeDocument as a request type.
type RequestType ¶
type RequestType uint32
RequestType is the request types enumeration
const ( // TypeDocument (main frame) TypeDocument RequestType = 1 << iota // TypeSubdocument (iframe) $subdocument TypeSubdocument // TypeScript (javascript, etc) $script TypeScript // TypeStylesheet (css) $stylesheet TypeStylesheet // TypeObject (flash, etc) $object TypeObject // TypeImage (any image) $image TypeImage // TypeXmlhttprequest (ajax/fetch) $xmlhttprequest TypeXmlhttprequest // TypeMedia (video/music) $media TypeMedia // TypeFont (any custom font) $font TypeFont // TypeWebsocket (a websocket connection) $websocket TypeWebsocket // TypeOther - any other request type TypeOther )
func (RequestType) Count ¶
func (t RequestType) Count() int
Count returns count of the enabled flags
type Rule ¶
type Rule interface { // Text returns the original rule text Text() string // GetFilterListID returns ID of the filter list this rule belongs to GetFilterListID() int }
Rule is a base interface for all filtering rules
type RuleSyntaxError ¶
type RuleSyntaxError struct {
// contains filtered or unexported fields
}
RuleSyntaxError represents an error while parsing a filtering rule
func (*RuleSyntaxError) Error ¶
func (e *RuleSyntaxError) Error() string