urlfilter

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2019 License: GPL-3.0 Imports: 21 Imported by: 7

README

Build Status Code Coverage Go Report Card GolangCI Go Doc

AdGuard content blocking library

Pure GO library that implements AdGuard filtering rules syntax.

You can learn more about AdGuard filtering rules syntax from this article.

TODO:
  • Basic filtering rules
  • Benchmark basic rules matching
  • Hosts matching rules
    • /etc/hosts matching
  • Memory optimization
  • Tech document
  • Cosmetic rules
    • Basic element hiding and CSS rules
      • Proper CSS rules validation
    • ExtCSS rules
    • Scriptlet rules
    • JS rules
  • Proxy implementation
    • Simple MITM proxy example
    • Add cosmetic filters to the proxy example
    • Handling cosmetic modifiers $elemhide, $generichide, $jsinject
    • (!) Server certificate verification - it should pass badssl.com/dashboard/
    • Unit tests coverage
    • Proxy - handle CSP (including tags with CSP)
    • Proxy - proper blocking page code
    • Proxy - unblocking via a temporary cookie
    • Proxy - content script caching
    • Content script - babel plugin
    • Content script - apply ExtCSS rules
    • Content script - styles protection
    • Content script - JS unit tests
    • Content script - GO unit tests
  • HTML filtering rules
  • Advanced modifiers
    • $important
    • $replace
    • $csp
    • $cookie
    • $redirect
    • $badfilter
How to use

TODO

Documentation

Index

Constants

View Source 
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

View Source 
var (
	// ErrUnsupportedRule signals that this might be a valid rule type,
	// but it is not yet supported by this library
	ErrUnsupportedRule = errors.New("this type of rules is unsupported")

	// ErrRuleRetrieval signals that the rule cannot be retrieved by RuleList
	// by the the specified index
	ErrRuleRetrieval = errors.New("cannot retrieve the rule")
)

Functions

This section is empty.

Types

type CosmeticEngine 

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

CosmeticEngine combines all the cosmetic rules and allows to quickly find all rules matching this or that hostname

func NewCosmeticEngine 

func NewCosmeticEngine(s *RuleStorage) *CosmeticEngine

NewCosmeticEngine builds a new cosmetic engine from the specified rule storage

func (*CosmeticEngine) Match 

func (e *CosmeticEngine) Match(hostname string, includeCSS bool, includeJS bool, includeGenericCSS bool) CosmeticResult

Match builds scripts and styles that needs to be injected into the specified page hostname is the page hostname includeCSS defines if we should inject any CSS and element hiding rules (see $elemhide) includeJS defines if we should inject JS into the page (see $jsinject) includeGenericCSS defines if we should inject generic CSS and element hiding rules (see $generichide) TODO: Additionally, we should provide a method that writes result to an io.Writer

type CosmeticOption added in v0.6.0 

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 CosmeticResult 

type CosmeticResult struct {
	ElementHiding StylesResult
	CSS           StylesResult
	JS            ScriptsResult
}

CosmeticResult represents all scripts and styles that needs to be injected into the page

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

type DNSEngine struct {
	RulesCount int // count of rules loaded to the engine
	// contains filtered or unexported fields
}

DNSEngine combines host rules and network rules and is supposed to quickly find matching rules for hostnames. First, it looks over network rules and returns first rule found. Then, if nothing found, it looks up the host rules.

func NewDNSEngine 

func NewDNSEngine(s *RuleStorage) *DNSEngine

NewDNSEngine parses the specified filter lists and returns a DNSEngine built from them. key of the map is the filter list ID, value is the raw content of the filter list.

func (*DNSEngine) Match 

func (d *DNSEngine) Match(hostname string) ([]Rule, bool)

Match finds a matching rule for the specified hostname. It returns true and the list of rules found or false and nil. The list of rules can be found when there're multiple host rules matching the same domain. For instance: 192.168.0.1 example.local 2000::1 example.local

type Engine 

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

Engine represents the filtering engine with all the loaded rules

func NewEngine 

func NewEngine(s *RuleStorage) *Engine

NewEngine parses the filtering rules and creates a filtering engine of them

func (*Engine) GetCosmeticResult added in v0.6.0 

func (e *Engine) GetCosmeticResult(hostname string, option CosmeticOption) CosmeticResult

GetCosmeticResult gets cosmetic result for the specified hostname and cosmetic options

func (*Engine) MatchRequest added in v0.6.0 

func (e *Engine) MatchRequest(r *Request) MatchingResult

MatchRequest - matches the specified request against the filtering engine and returns the matching result.

type FileRuleList added in v0.4.0 

type FileRuleList struct {
	ID             int      // Rule list ID
	IgnoreCosmetic bool     // Whether to ignore cosmetic rules or not
	File           *os.File // File with rules

	sync.Mutex
	// contains filtered or unexported fields
}

FileRuleList represents a file-based rule list

func NewFileRuleList added in v0.4.0 

func NewFileRuleList(id int, path string, ignoreCosmetic bool) (*FileRuleList, error)

NewFileRuleList initializes a new file-based rule list

func (*FileRuleList) Close added in v0.4.0 

func (l *FileRuleList) Close() error

Close closes the underlying file

func (*FileRuleList) GetID added in v0.4.0 

func (l *FileRuleList) GetID() int

GetID returns the rule list identifier

func (*FileRuleList) NewScanner added in v0.4.0 

func (l *FileRuleList) NewScanner() *RuleScanner

NewScanner creates a new rules scanner that reads the list contents

func (*FileRuleList) RetrieveRule added in v0.4.0 

func (l *FileRuleList) RetrieveRule(ruleIdx int) (Rule, error)

RetrieveRule finds and deserializes rule by its index. If there's no rule by that index or rule is invalid, it will return an error.

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 

func NewHostRule(ruleText string, filterListID int) (*HostRule, error)

NewHostRule parses the rule and creates a new HostRule instance The format is: IP_address canonical_hostname [aliases...]

func (*HostRule) GetFilterListID 

func (f *HostRule) GetFilterListID() int

GetFilterListID returns ID of the filter list this rule belongs to

func (*HostRule) Match 

func (f *HostRule) Match(hostname string) bool

Match checks if this filtering rule matches the specified hostname

func (*HostRule) String 

func (f *HostRule) String() string

String returns original rule text

func (*HostRule) Text 

func (f *HostRule) Text() string

Text returns the original rule text Implements the `Rule` interface

type MatchingResult added in v0.6.0 

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

func NewMatchingResult(rules []*NetworkRule, 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 added in v0.6.0 

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

func (m *MatchingResult) GetCosmeticOption() CosmeticOption

GetCosmeticOption returns a bit-flag with the list of cosmetic options

type NetworkEngine 

type NetworkEngine struct {
	RulesCount int // RulesCount -- count of rules added to the engine
	// contains filtered or unexported fields
}

NetworkEngine is the engine that supports quick search over network rules

func NewNetworkEngine 

func NewNetworkEngine(s *RuleStorage) *NetworkEngine

NewNetworkEngine builds an instance of the network engine

func (*NetworkEngine) Match 

func (n *NetworkEngine) Match(r *Request) (*NetworkRule, bool)

Match searches over all filtering rules loaded to the engine It returns true if a match was found alongside the matching rule

func (*NetworkEngine) MatchAll 

func (n *NetworkEngine) MatchAll(r *Request) []*NetworkRule

MatchAll finds all rules matching the specified request regardless of the rule types It will find both whitelist and blacklist rules

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

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

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

NetworkRuleOption enumeration

func (NetworkRuleOption) Count added in v0.6.0 

func (o NetworkRuleOption) Count() int

Count returns the count of enabled options

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)

	SourceURL      string // Source URL
	SourceHostname string // Source hostname
	SourceDomain   string // Source domain (eTLD+1)
}

Request represents a web request with all it's necessary properties

func NewRequest 

func NewRequest(url string, sourceURL string, requestType RequestType) *Request

NewRequest creates a new instance of "Request" and populates it's fields

func NewRequestForHostname 

func NewRequestForHostname(hostname string) *Request

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

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

func NewRule added in v0.4.0 

func NewRule(line string, filterListID int) (Rule, error)

NewRule creates a new filtering rule from the specified line It returns nil if the line is empty or if it is a comment

type RuleList added in v0.4.0 

type RuleList interface {
	GetID() int                             // GetID returns the rule list identifier
	NewScanner() *RuleScanner               // Creates a new scanner that reads the list contents
	RetrieveRule(ruleIdx int) (Rule, error) // Retrieves a rule by its index
	io.Closer                               // Closes the rules list
}

RuleList represents a set of filtering rules

type RuleScanner added in v0.4.0 

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

RuleScanner implements an interface for reading filtering rules.

func NewRuleScanner added in v0.4.0 

func NewRuleScanner(r io.Reader, listID int, ignoreCosmetic bool) *RuleScanner

NewRuleScanner returns a new RuleScanner to read from r. r -- source of the filtering rules listID -- filter list ID IgnoreCosmetic -- if true, cosmetic rules will be ignored

func (*RuleScanner) Rule added in v0.4.0 

func (s *RuleScanner) Rule() (Rule, int)

Rule returns the most recent rule generated by a call to Scan, and the index of this rule's text.

func (*RuleScanner) Scan added in v0.4.0 

func (s *RuleScanner) Scan() bool

Scan advances the RuleScanner to the next rule, which will then be available through the Rule method. It returns false when the scan stops, either by reaching the end of the input or an error.

type RuleStorage added in v0.4.0 

type RuleStorage struct {
	// Lists is an array of rules lists which can be accessed
	// using this RuleStorage
	Lists []RuleList

	sync.Mutex
	// contains filtered or unexported fields
}

RuleStorage is an abstraction that combines several rule lists It can be scanned using RuleStorageScanner, and also it allows retrieving rules by its index

The idea is to keep rules in a serialized format (even original format in the case of FileRuleList) and create them in a lazy manner only when we really need them. When the filtering engine is being initialized, we need to scan the rule lists once in order to fill up the lookup tables. We use rule indexes as a unique rule identifier instead of the rule itself. The rule is created (see RetrieveRule) only when there's a chance that it's needed.

Rule index is an int64 value that actually consists of two int32 values: One is the rule list identifier, and the second is the index of the rule inside of that list.

func NewRuleStorage 

func NewRuleStorage(lists []RuleList) (*RuleStorage, error)

NewRuleStorage creates a new instance of the RuleStorage and validates the list of rules specified

func (*RuleStorage) Close added in v0.4.0 

func (s *RuleStorage) Close() error

Close closes the storage instance

func (*RuleStorage) NewRuleStorageScanner added in v0.4.0 

func (s *RuleStorage) NewRuleStorageScanner() *RuleStorageScanner

NewRuleStorageScanner creates a new instance of RuleStorageScanner. It can be used to read and parse all the storage contents.

func (*RuleStorage) RetrieveHostRule added in v0.4.0 

func (s *RuleStorage) RetrieveHostRule(idx int64) *HostRule

RetrieveHostRule is a helper method that retrieves a host rule from the storage It returns a pointer to the rule or nil in any other case (not found or error)

func (*RuleStorage) RetrieveNetworkRule added in v0.4.0 

func (s *RuleStorage) RetrieveNetworkRule(idx int64) *NetworkRule

RetrieveNetworkRule is a helper method that retrieves a network rule from the storage It returns a pointer to the rule or nil in any other case (not found or error)

func (*RuleStorage) RetrieveRule added in v0.4.0 

func (s *RuleStorage) RetrieveRule(storageIdx int64) (Rule, error)

RetrieveRule looks for the filtering rule in this storage storageIdx is the lookup index that you can get from the rule storage scanner

type RuleStorageScanner added in v0.4.0 

type RuleStorageScanner struct {
	// Scanners is the list of list scanners backing this combined scanner
	Scanners []*RuleScanner
	// contains filtered or unexported fields
}

RuleStorageScanner scans multiple RuleScanner instances The rule index is built from the rule index in the list + the list ID First 4 bytes is the rule index in the list Second 4 bytes is the list ID

func (*RuleStorageScanner) Rule added in v0.4.0 

func (s *RuleStorageScanner) Rule() (Rule, int64)

Rule returns the most recent rule generated by a call to Scan, and the index of this rule. See ruleListIdxToStorageIdx for more information on what this index is.

func (*RuleStorageScanner) Scan added in v0.4.0 

func (s *RuleStorageScanner) Scan() bool

Scan advances the RuleStorageScanner to the next rule, which will then be available through the Rule method. It returns false when the scan stops, either by reaching the end of the input or an error.

type RuleSyntaxError added in v0.4.0 

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

RuleSyntaxError represents an error while parsing a filtering rule

func (*RuleSyntaxError) Error added in v0.4.0 

func (e *RuleSyntaxError) Error() string

type ScriptsResult added in v0.6.0 

type ScriptsResult struct {
	Generic  []string
	Specific []string
}

ScriptsResult contains scripts to be executed on a page

type Session added in v0.6.0 

type Session struct {
	ID      int64    // Session identifier
	Request *Request // Request data

	HTTPRequest  *http.Request  // HTTP request data
	HTTPResponse *http.Response // HTTP response data

	MediaType string // Mime media type
	Charset   string // Response charset (if it's possible to parse it from content-type)

	Result MatchingResult // Filtering engine result
}

Session contains all the necessary data to filter requests and responses. It also contains the current state of the request. Throughout the HTTP request lifetime, session data is updated with new information.

There are two main stages of the HTTP request lifetime:

  1. Received the HTTP request headers. At this point, we can find all the rules matching the request using what we know. We assume the resource type by URL and "Accept" headers and look for matching rules. If there's a match, and the request should be blocked, we simply block it. Otherwise, we continue the HTTP request execution.
  2. Received the HTTP response headers. At this point we've got the content-type header so we know for sure what type of resource we're dealing with. We are looking for matching rules again, and update them. The possible outcomes are:

2.1. The request must be blocked. 2.2. The response must be modified (with a $replace or a $csp rule, for instance). 2.3. This is an HTML response so we need to filter the response body and apply cosmetic filters. 2.4. We should continue execution and do nothing with the response.

func NewSession added in v0.6.0 

func NewSession(id int64, req *http.Request) *Session

NewSession creates a new instance of the Session struct and initializes it. id -- unique session identifier req -- HTTP request data

func (*Session) SetResponse added in v0.6.0 

func (s *Session) SetResponse(res *http.Response)

SetResponse sets the response of this session This can also end in changing the request type

type StringRuleList added in v0.4.0 

type StringRuleList struct {
	ID             int    // Rule list ID
	RulesText      string // String with filtering rules (one per line)
	IgnoreCosmetic bool   // Whether to ignore cosmetic rules or not
}

StringRuleList represents a string-based rule list

func (*StringRuleList) Close added in v0.4.0 

func (l *StringRuleList) Close() error

Close does nothing as there's nothing to close in the StringRuleList

func (*StringRuleList) GetID added in v0.4.0 

func (l *StringRuleList) GetID() int

GetID returns the rule list identifier

func (*StringRuleList) NewScanner added in v0.4.0 

func (l *StringRuleList) NewScanner() *RuleScanner

NewScanner creates a new rules scanner that reads the list contents

func (*StringRuleList) RetrieveRule added in v0.4.0 

func (l *StringRuleList) RetrieveRule(ruleIdx int) (Rule, error)

RetrieveRule finds and deserializes rule by its index. If there's no rule by that index or rule is invalid, it will return an error.

type StylesResult added in v0.6.0 

type StylesResult struct {
	Generic        []string `json:"generic"`
	Specific       []string `json:"specific"`
	GenericExtCSS  []string `json:"genericExtCss"`
	SpecificExtCSS []string `json:"specificExtCss"`
}

StylesResult contains either element hiding or CSS rules

Source Files

View all Source files

Directories

Path Synopsis
examples
proxy

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.