urlfilter

package module
v0.23.1 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2026 License: GPL-3.0 Imports: 8 Imported by: 9

README

AdGuard content blocking library

Code Coverage Go Report Card GolangCI Go Doc

Pure GO library that implements AdGuard filtering rules syntax.

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

TODO

How to use

TODO

Documentation

Overview

Package urlfilter contains implementation of AdGuard content blocking engine.

Index

Constants

This section is empty.

Variables

This section is empty.

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 *filterlist.RuleStorage) *CosmeticEngine

NewCosmeticEngine builds a new cosmetic engine from the specified rule storage

func (*CosmeticEngine) Match 

func (e *CosmeticEngine) Match(hostname string, includeCSS, includeJS, 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 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 DNSEngine 

type DNSEngine struct {
	// 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 *filterlist.RuleStorage) (e *DNSEngine)

NewDNSEngine parses the specified filter lists and returns a *DNSEngine built from them. s must not be nil.

func (*DNSEngine) Match 

func (e *DNSEngine) Match(hostname string) (res *DNSResult, matched bool)

Match finds a matching rule for the specified hostname. It returns true and the list of rules found or false and nil. A list of rules is returned when there are multiple host rules matching the same domain, for example: 

192.168.0.1 example.local
2000::1 example.local

func (*DNSEngine) MatchRequest added in v0.11.0 

func (e *DNSEngine) MatchRequest(dReq *DNSRequest) (res *DNSResult, matched bool)

MatchRequest is like [MatchRequestInto] but returns a new result. req must not be nil.

func (*DNSEngine) MatchRequestInto added in v0.21.0 

func (e *DNSEngine) MatchRequestInto(req *DNSRequest, res *DNSResult) (matched bool)

MatchRequestInto matches the specified DNS request and puts the result into res. ok is true if the result has a basic network rule or some host rules. req and res must not be nil. res should be empty or reset using DNSResult.Reset.

NOTE: For compatibility reasons, it is also false when there are DNS rewrite and other kinds of special network rules, so users who need those will need to ignore the matched return parameter and instead inspect the results of the corresponding DNSResult getters.

TODO(a.garipov): Refactor the result and remove the exception above.

func (*DNSEngine) RulesCount 

func (e *DNSEngine) RulesCount() (n uint64)

RulesCount returns the number of rules added to the engine.

type DNSRequest added in v0.11.0 

type DNSRequest struct {
	// ClientTags is the list of tags to match against $ctag modifiers.
	ClientTags *container.SortedSliceSet[string]

	// ClientIdentifiers is the list of client IDs to match against $client
	// modifiers.
	ClientIdentifiers *container.SortedSliceSet[string]

	// ClientIP is the IP address to match against $client modifiers.  The
	// default zero value won't be considered.
	ClientIP netip.Addr

	// Hostname is the hostname to filter.
	Hostname string

	// DNSType is the type of the resource record (RR) of a DNS request, for
	// example "A" or "AAAA".  See [rules.RRValue] for all acceptable constants
	// and their corresponding values.
	DNSType rules.RRType

	// Answer if the filtering request is for filtering a DNS response.
	Answer bool
}

DNSRequest represents a DNS query with associated metadata.

func (*DNSRequest) Reset added in v0.21.0 

func (r *DNSRequest) Reset()

Reset makes r ready for reuse.

type DNSResult added in v0.9.0 

type DNSResult struct {
	// NetworkRule is the matched network rule, if any.  If it is nil,
	// HostRulesV4 and HostRulesV6 may still contain matched hosts-file style
	// rules.
	NetworkRule *rules.NetworkRule

	// HostRulesV4 are the host rules with IPv4 addresses.
	HostRulesV4 []*rules.HostRule

	// HostRulesV6 are the host rules with IPv6 addresses.
	HostRulesV6 []*rules.HostRule

	// NetworkRules are all matched network rules.  These include unprocessed
	// DNS rewrites, exception rules, and so on.
	NetworkRules []*rules.NetworkRule
}

DNSResult is the result of matching a DNS filtering request.

func (*DNSResult) DNSRewrites added in v0.14.0 

func (res *DNSResult) DNSRewrites() (nrules []*rules.NetworkRule)

DNSRewrites returns $dnsrewrite network rules applying exception logic. For example, rules like: 

||example.com^$dnsrewrite=127.0.0.1
||example.com^$dnsrewrite=127.0.0.2
@@||example.com^$dnsrewrite=127.0.0.1

Will result in example.com being rewritten to only return 127.0.0.2.

To get all DNS rewrite rules without applying any exception logic, use DNSResult.DNSRewritesAll.

func (*DNSResult) DNSRewritesAll added in v0.14.0 

func (res *DNSResult) DNSRewritesAll() (nrules []*rules.NetworkRule)

DNSRewritesAll returns all $dnsrewrite network rules. To get the rules with exception logic applied, use (*DNSResult).DNSRewrites.

func (*DNSResult) Reset added in v0.21.0 

func (res *DNSResult) Reset()

Reset makes res ready for reuse.

func (*DNSResult) ShallowCloneInto added in v0.22.0 

func (res *DNSResult) ShallowCloneInto(other *DNSResult)

ShallowCloneInto sets properties in other, as if making a shallow clone. other must not be nil and should be empty or reset using DNSResult.Reset.

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 *filterlist.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 rules.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 *rules.Request) (res *rules.MatchingResult)

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

type NetworkEngine 

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

NetworkEngine is the engine that supports quick search over network rules.

func NewNetworkEngine 

func NewNetworkEngine(s *filterlist.RuleStorage) (engine *NetworkEngine)

NewNetworkEngine builds an instance of the network engine. It scans the specified rule storage and adds all network rules found there to the internal indexes.

func NewNetworkEngineSkipStorageScan added in v0.15.0 

func NewNetworkEngineSkipStorageScan(s *filterlist.RuleStorage) (engine *NetworkEngine)

NewNetworkEngineSkipStorageScan creates a new instance of *NetworkEngine, but unlike NewNetworkEngine it does not scan the storage.

func (*NetworkEngine) AppendAllMatching added in v0.21.0 

func (e *NetworkEngine) AppendAllMatching(
	orig []*rules.NetworkRule,
	r *rules.Request,
) (res []*rules.NetworkRule)

AppendAllMatching appends all rules matching the specified request, regardless of the rule types, to orig. It will find both allowlist and blocklist rules. r must not be nil.

func (*NetworkEngine) Match 

func (e *NetworkEngine) Match(r *rules.Request) (rule *rules.NetworkRule, ok bool)

Match searches over all filtering rules loaded to the engine and returns true if a match was found alongside the matching rule. r must not be nil.

func (*NetworkEngine) MatchAll deprecated 

func (e *NetworkEngine) MatchAll(r *rules.Request) (res []*rules.NetworkRule)

MatchAll finds all rules matching the specified request regardless of the rule types. It will find both allowlist and blocklist rules. r must not be nil.

Deprecated: Use NetworkEngine.AppendAllMatching instead.

func (*NetworkEngine) RulesCount added in v0.4.0 

func (e *NetworkEngine) RulesCount() (n uint64)

RulesCount returns the number of rules added to the engine.

type ScriptsResult added in v0.6.0 

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

ScriptsResult contains scripts to be executed on a page

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
Package main is responsible for the command-line interface of the urlfilter content filtering proxy.
 Package main is responsible for the command-line interface of the urlfilter content filtering proxy.
examples
proxy command
Package filterlist provides methods to work with filter lists.
 Package filterlist provides methods to work with filter lists.
internal
lookup
Package lookup implements index structures that we use to improve matching speed in the engines.
 Package lookup implements index structures that we use to improve matching speed in the engines.
ufcbor
Package ufcbor provides utilities for fast and reflect-less [CBOR] decoding and encoding.
 Package ufcbor provides utilities for fast and reflect-less [CBOR] decoding and encoding.
ufencoding
Package ufencoding contains encoding-related utilities.
 Package ufencoding contains encoding-related utilities.
ufnet
Package ufnet contains utilities for domain and hostname parsing/validation.
 Package ufnet contains utilities for domain and hostname parsing/validation.
uftest
Package uftest contains common test data and utilities.
 Package uftest contains common test data and utilities.
tools module
Package proxy contains implementation of the filtering MITM proxy
 Package proxy contains implementation of the filtering MITM proxy
Package rules contains implementation of all kinds of blocking rules.
 Package rules contains implementation of all kinds of blocking rules.

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.