### Example: startProxy function Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Shows how to create and start a proxy server with filter lists and MITM configuration. Uses proxy.NewServer and server.Start(). ```go import ( "github.com/AdguardTeam/gomitmproxy" "github.com/AdguardTeam/gomitmproxy/mitm" "github.com/AdguardTeam/urlfilter/proxy" "github.com/AdguardTeam/urlfilter/rules" ) func startProxy(m *mitm.Config, tlsCfg *tls.Config) (*proxy.Server, error) { addr := &net.TCPAddr{IP: net.IPv4(0, 0, 0, 0), Port: 3333} config := proxy.Config{ FiltersPaths: map[rules.ListID]string{ 1: "adguard_base_filter.txt", 2: "adguard_russian_filter.txt", }, CompressContentScript: true, } config.ProxyConfig = gomitmproxy.Config{ ListenAddr: addr, TLSConfig: tlsCfg, Username: "user", Password: "pass", APIHost: "adguard", MITMConfig: m, MITMExceptions: []string{"example.com"}, } server, err := proxy.NewServer(config) if err != nil { return nil, err } return server, server.Start() } ``` -------------------------------- ### Start method signature Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Starts the proxy server. Returns an error from s.proxyServer.Start(). ```go // Start starts the proxy server func (s *Server) Start() error ``` -------------------------------- ### Complete bootstrap example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-interface.md Example showing how to create rule lists, build a RuleStorage, and create engines for network and DNS filtering. ```APIDOC ## Complete bootstrap example ### Description This example demonstrates how to create rule lists using `filterlist.NewString` and `filterlist.NewBytes`, build a `RuleStorage` with `filterlist.NewRuleStorage`, and create engines for network and DNS filtering. ### Code ```go import ( "github.com/AdguardTeam/urlfilter" "github.com/AdguardTeam/urlfilter/filterlist" "github.com/AdguardTeam/urlfilter/rules" ) lists := []filterlist.Interface{ filterlist.NewString(&filterlist.StringConfig{ ID: rules.ListID(1), RulesText: "||example.org^\n##.ad\n", }), filterlist.NewBytes(&filterlist.BytesConfig{ ID: rules.ListID(2), RulesText: []byte("0.0.0.0 track.example\n"), }), } storage, err := filterlist.NewRuleStorage(lists) if err != nil { log.Fatal(err) // duplicate ListID } defer storage.Close() engine := urlfilter.NewEngine(storage) // network + cosmetic engineDNS := urlfilter.NewDNSEngine(storage) // host rules + host-level network rules _ = engine _ = engineDNS ``` ``` -------------------------------- ### Example: using query methods Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-network-rule.md Example showing how to create a NetworkRule and use query methods like Whitelist, IsOptionEnabled, IsGeneric, and IsHostLevelNetworkRule. The comments show expected outputs. ```go rule, _ := rules.NewNetworkRule("@@||example.org^$important", rules.ListID(1)) fmt.Println("whitelist:", rule.Whitelist) // true fmt.Println("important:", rule.IsOptionEnabled(rules.OptionImportant)) // true fmt.Println("generic: ", rule.IsGeneric()) // true fmt.Println("host-level:", rule.IsHostLevelNetworkRule()) // true ($important is in OptionHostLevelRulesOnly) ``` -------------------------------- ### Start() error Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Starts the proxy server. Returns an error if the underlying proxy server fails to start. ```APIDOC ## Start() error ### Description Starts the proxy server. Returns an error if the underlying proxy server fails to start. ### Method Start ### Signature func (s *Server) Start() error ### Returns - **error** (error) - Error from s.proxyServer.Start(). ### Example ```go server, err := proxy.NewServer(config) if err != nil { return nil, err } return server, server.Start() ``` ``` -------------------------------- ### Example: using Match Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-network-rule.md Example showing how to construct a Request and call Match on a rule. The output is a boolean indicating whether the rule matches. ```go req := &rules.Request{ URL: "https://sub.example.org/analytics?x=1", URLLowerCase: "https://sub.example.org/analytics?x=1", Hostname: "sub.example.org", SourceURL: "https://example.org/", RequestType: rules.TypeScript, } fmt.Println(rule.Match(req)) // true/false ``` -------------------------------- ### Session usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-session.md Example usage of NewSession and SetResponse. It prints the hostname and request type before setting the response, then prints the media type after. ```go session := proxy.NewSession("abc123", httpReq) fmt.Println(session.Request.Hostname) fmt.Println(session.Request.RequestType) // e.g. rules.TypeScript session.SetResponse(httpResp) fmt.Println(session.MediaType) // e.g. "text/html" ``` -------------------------------- ### Example: matching a request with NetworkEngine Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/network-engine.md Shows how to create a NetworkEngine, build a request, and use Match to determine if it is blocked or allowed. The example prints whether the request was blocked or allowed based on the rule's Whitelist field. ```go engine := urlfilter.NewNetworkEngine(storage) req := rules.NewRequest("https://ads.example.org/x.js", "https://example.org/", rules.TypeScript) rule, matched := engine.Match(req) if matched { if rule.Whitelist { fmt.Printf("allowed by: %s\n", rule.Text()) } else { fmt.Printf("blocked by: %s\n", rule.Text()) } } ``` -------------------------------- ### HTTP request/response example for GET /content-script.js Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/endpoints.md Shows a raw HTTP request to the content-script endpoint with required query parameters and the corresponding 200 OK response with headers and a sample content-script body. The response includes Cache-Control, Last-Modified, and Expires headers. ```http GET /content-script.js?hostname=example.org&option=7&ts=1580000000 HTTP/1.1 Host: injections.adguard.org HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 Cache-Control: public, max-age=3600 Last-Modified: Wed, 01 Jan 2010 01:00:00 GMT Expires: /* content-script v1.0.0 ... */ (function (configuration) { ... }) ({"elementHiding":{...}}) ``` -------------------------------- ### NetworkRuleOption usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-network-rule.md Shows how to check if options are enabled or disabled on a network rule created with the $third-party and ~script modifiers. The example prints true, false, and false respectively. ```go rule, _ := rules.NewNetworkRule("||example.org^$third-party,~script", rules.ListID(1)) fmt.Println(rule.IsOptionEnabled(rules.OptionThirdParty)) // true fmt.Println(rule.IsOptionDisabled(rules.OptionThirdParty)) // false fmt.Println(rule.IsOptionEnabled(rules.OptionMatchCase)) // false ``` -------------------------------- ### Example: Creating a StorageID Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-storage-id.md Shows how to create a StorageID with list ID 3 and rule index 42, then print it with %+v. ```go id := filterlist.NewStorageID(rules.ListID(3), 42) fmt.Printf("%+v\n", id) ``` -------------------------------- ### Match usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-engine.md Example of calling Match with a hostname and iterating over the returned host rules and network rule. Prints the hostnames and IPs for host rules, and the network rule text if present. ```go res, matched := engine.Match("doubleclick.net") if matched { for _, h := range append(res.HostRulesV4, res.HostRulesV6...) { fmt.Printf("%s -> %s\n", h.Hostnames, h.IP) } if res.NetworkRule != nil { fmt.Printf("network rule: %s\n", res.NetworkRule.Text()) } } ``` -------------------------------- ### DNSRequest usage and reset example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-request.md Shows how to create a DNSRequest, use it with engine.MatchRequest, then reset it for reuse with a new hostname. The example demonstrates the Reset method and reusing the request for a subsequent lookup. ```go req := &urlfilter.DNSRequest{Hostname: "example.org", DNSType: dns.TypeA} res, _ := engine.MatchRequest(req) // Reuse the request for the next lookup: req.Reset() req.Hostname = "doubleclick.net" res2, _ := engine.MatchRequest(req) ``` -------------------------------- ### Example: creating and using a HostRule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-host-rule.md Shows how to create a host rule, access its fields, and match a hostname. Also demonstrates multiple hostnames and IPv6 support. ```go h, err := rules.NewHostRule("0.0.0.0 doubleclick.net", rules.ListID(1)) if err != nil { log.Fatal(err) } fmt.Println(h.IP) // 0.0.0.0 fmt.Println(h.Hostnames) // [doubleclick.net] fmt.Println(h.Match("doubleclick.net")) // true // Multiple hostnames + IPv6: m, _ := rules.NewHostRule("::1 localhost localhost.localdomain", rules.ListID(1)) fmt.Println(m.Hostnames) // [localhost localhost.localdomain] ``` -------------------------------- ### Buffer reuse example with AppendAllMatching Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/network-engine.md Shows how to reuse a buffer across multiple calls to AppendAllMatching to avoid allocations. The example iterates over the results and prints rules with DNS rewrites. ```go buf := make([]*rules.NetworkRule, 0, 32) buf = engine.AppendAllMatching(buf[:0], request1) buf = engine.AppendAllMatching(buf[:0], request2) for _, nr := range buf { if nr.DNSRewrite != nil { // e.g. $dnsrewrite rules fmt.Println(nr.Text()) } } ``` -------------------------------- ### Full lifecycle example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-storage.md Shows creating a RuleStorage, deferring Close, creating an engine, scanning rules, and resolving storage IDs lazily with RetrieveNetworkRule. ```go storage, _ := filterlist.NewRuleStorage(lists) defer func() { _ = storage.Close() }() engine := urlfilter.NewEngine(storage) scanner := storage.NewRuleStorageScanner() for scanner.Scan() { f, id := scanner.Rule() fmt.Printf("rule %v from list %d\n", f.Text(), id.ListID()) // Storage IDs can be resolved lazily: if nr := storage.RetrieveNetworkRule(id); nr != nil { fmt.Println("network rule:", nr.Text()) } } ``` -------------------------------- ### MatchRequest usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-engine.md Example of constructing a DNSRequest with hostname, client IP, DNSType, and client tags, then calling MatchRequest. Prints the network rule if matched. ```go req := &urlfilter.DNSRequest{ Hostname: "example.org", ClientIP: netip.MustParseAddr("192.168.0.1"), DNSType: dns.TypeA, ClientTags: container.NewSortedSliceSet("device_phone"), } res, matched := engine.MatchRequest(req) if matched { fmt.Printf("network rule: %v\n", res.NetworkRule) } ``` -------------------------------- ### NewDNSEngine usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-engine.md Shows how to create a DNSEngine from a rule storage containing a string filter list with host and network rules. ```go list := filterlist.NewString(&filterlist.StringConfig{ RulesText: "0.0.0.0 doubleclick.net\n||example.org^\n", ID: rules.ListID(7), }) storage, _ := filterlist.NewRuleStorage([]filterlist.Interface{list}) defer storage.Close() engine := urlfilter.NewDNSEngine(storage) ``` -------------------------------- ### Example: using HostRule with DNSEngine Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-host-rule.md Shows how to use a HostRule in a DNSEngine match, iterating over matched host rules and printing their hostnames and IPs. ```go engine := urlfilter.NewDNSEngine(storage) res, matched := engine.Match("doubleclick.net") if matched { for _, hr := range append(res.HostRulesV4, res.HostRulesV6...) { fmt.Printf("%s resolves to %s\n", hr.Hostnames, hr.IP) } } ``` -------------------------------- ### Usage Example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-dnsrewrite.md Example of creating a network rule with a DNS rewrite and accessing the DNSRewrite value. ```APIDOC ## Usage Example ### Description Demonstrates how to create a network rule with a DNS rewrite and access the DNSRewrite value. ### Code ```go rule, err := rules.NewNetworkRule("||example.org^$dnsrewrite=192.0.2.1", rules.ListID(1)) if err != nil { log.Fatal(err) } dr := rule.DNSRewrite fmt.Println(dr.RCode) // 0 (dns.RcodeSuccess) fmt.Println(dr.RRType) // 1 (dns.TypeA) fmt.Println(dr.Value) // 192.0.2.1 (netip.Addr) ``` ``` -------------------------------- ### Complete bootstrap example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-interface.md Shows how to create a rule storage from multiple rule lists and initialize both a standard engine and a DNS engine. It demonstrates the use of String and Bytes list types and handles potential duplicate ListID errors. ```go import ( "github.com/AdguardTeam/urlfilter" "github.com/AdguardTeam/urlfilter/filterlist" "github.com/AdguardTeam/urlfilter/rules" ) lists := []filterlist.Interface{ filterlist.NewString(&filterlist.StringConfig{ ID: rules.ListID(1), RulesText: "||example.org^\n##.ad\n", }), filterlist.NewBytes(&filterlist.BytesConfig{ ID: rules.ListID(2), RulesText: []byte("0.0.0.0 track.example\n"), }), } storage, err := filterlist.NewRuleStorage(lists) if err != nil { log.Fatal(err) // duplicate ListID } defer storage.Close() engine := urlfilter.NewEngine(storage) // network + cosmetic engineDNS := urlfilter.NewDNSEngine(storage) // host rules + host-level network rules _ = engine _ = engineDNS ``` -------------------------------- ### Example: Creating a file-based rule list with NewFile Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-lists.md Shows how to create a file-based rule list using filterlist.NewFile with a FileConfig. The example sets Path to "base_filter.txt", ID to 1, and IgnoreCosmetic to false. It handles the error with log.Fatal and defers list.Close(). ```go list, err := filterlist.NewFile(&filterlist.FileConfig{ Path: "base_filter.txt", ID: rules.ListID(1), IgnoreCosmetic: false, }) if err != nil { log.Fatal(err) } defer list.Close() ``` -------------------------------- ### CosmeticRule Match example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-cosmetic-rule.md Example usage of the Match method. For a rule with a specific domain, subdomains match but supersites do not. For a wildcard rule like example.*, the TLD is replaced by any ICANN public suffix, but subdomains of the wildcard domain do not match. ```go rule, _ := rules.NewCosmeticRule("sub.example.org##.x", rules.ListID(1)) fmt.Println(rule.Match("sub.example.org")) // true fmt.Println(rule.Match("example.org")) // false (supersite not matched) fmt.Println(rule.Match("a.sub.example.org")) // true (subdomain) w, _ := rules.NewCosmeticRule("example.*##.x", rules.ListID(1)) fmt.Println(w.Match("example.com")) // true fmt.Println(w.Match("example.org")) // true fmt.Println(w.Match("example.sub.com")) // false ``` -------------------------------- ### Example usage of NewCosmeticRule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-cosmetic-rule.md Example demonstrating how to create cosmetic rules with NewCosmeticRule, including element hiding, generic, and whitelist rules. It shows the resulting fields and methods. ```go r, err := rules.NewCosmeticRule("example.org##.ad-banner", rules.ListID(1)) if err != nil { log.Fatal(err) } fmt.Println(r.Type) // CosmeticElementHiding fmt.Println(r.Content) // .ad-banner fmt.Println(r.IsGeneric()) // false fmt.Println(r.GetPermittedDomains()) // [example.org] generic, _ := rules.NewCosmeticRule("##.ad", rules.ListID(1)) fmt.Println(generic.IsGeneric()) // true fmt.Println(generic.Match("anywhere.org")) // true unhide, _ := rules.NewCosmeticRule("example.org#@#.ad", rules.ListID(1)) fmt.Println(unhide.Whitelist) // true ``` -------------------------------- ### Example: using NewCosmeticEngine and Match Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/cosmetic-engine.md Shows how to create an engine and call Match, then print counts of generic and specific element hiding rules. ```go engine := urlfilter.NewCosmeticEngine(storage) res := engine.Match("example.org", true, true, true) fmt.Printf("generic styles: %d\n", len(res.ElementHiding.Generic)) fmt.Printf("specific styles: %d\n", len(res.ElementHiding.Specific)) fmt.Printf("generic extcss: %d\n", len(res.ElementHiding.GenericExtCSS)) ``` -------------------------------- ### Example: error handling on startup Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Shows how to handle a startup error from proxy.NewServer when a filter list file does not exist. The error message is "failed to create rule list 1: open ...: no such file or directory". ```go server, err := proxy.NewServer(proxy.Config{ FiltersPaths: map[rules.ListID]string{1: "/nonexistent/rules.txt"}, }) if err != nil { fmt.Println(err) // "failed to create rule list 1: open ...: no such file or directory" return } defer server.Close() ``` -------------------------------- ### Example: create and match a network rule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-network-rule.md Creates a rule from text with modifiers, builds a request, and checks if it matches. Prints the rule text on match. ```go rule, err := rules.NewNetworkRule("||example.org^$third-party,image", rules.ListID(1)) if err != nil { log.Fatal(err) } req := rules.NewRequest("https://cdn.example.org/a.png", "https://example.org/", rules.TypeImage) if rule.Match(req) { fmt.Println("matched:", rule.Text()) } ``` -------------------------------- ### Example: building an Engine from a rule storage Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/engine.md Shows how to create a rule storage from a string with network and cosmetic rules, then build an Engine. The storage is scanned once; the engine remains usable until Close is called on the storage. ```go import ( "github.com/AdguardTeam/urlfilter" "github.com/AdguardTeam/urlfilter/filterlist" "github.com/AdguardTeam/urlfilter/rules" ) func buildEngine() *urlfilter.Engine { rulesText := "||example.org^$third-party\n##.ad-banner\n" list := filterlist.NewString(&filterlist.StringConfig{ RulesText: rulesText, ID: rules.ListID(1), }) storage, err := filterlist.NewRuleStorage([]filterlist.Interface{list}) if err != nil { panic(err) // e.g. duplicated list IDs } engine := urlfilter.NewEngine(storage) // The engine can be used until Close is called on the storage. return engine } ``` -------------------------------- ### Run the proxy with basic flags Source: https://github.com/adguardteam/urlfilter/blob/master/cmd/README.md Starts the proxy listening on all interfaces on port 8080, using the generated root certificate and key, and loads the three filter lists. ```bash ./adguard -l 0.0.0.0 -p 8080\ -c root.crt\ -k root.key\ -f adguard_base.txt\ -f adguard_tracking_protection.txt\ -f adguard_social.txt ``` -------------------------------- ### GetCosmeticOption usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-matching-result.md Shows how to use GetCosmeticOption to retrieve cosmetic options and check if element-hiding styles are enabled. The example then passes the options to GetCosmeticResult to obtain cosmetic results for a domain. ```go options := result.GetCosmeticOption() if options&rules.CosmeticOptionCSS != 0 { // html can include element-hiding styles } cosmetic := engine.GetCosmeticResult("example.org", options) ``` -------------------------------- ### Example: creating a request Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-request.md Shows how to create a Request for an image resource and print its fields. Outputs: ads.example.org, 32 (TypeImage), true, false. ```go req := rules.NewRequest( "https://ads.example.org/banner.png", "https://example.org/page.html", rules.TypeImage, ) fmt.Println(req.Hostname) // ads.example.org fmt.Println(req.RequestType) // 32 (TypeImage) fmt.Println(req.ThirdParty) // true fmt.Println(req.IsHostnameRequest) // false ``` -------------------------------- ### Usage Example — Full Form with Typed Values Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-dnsrewrite.md Example of using the full form of DNS rewrite with typed values, including error handling. ```APIDOC ## Usage Example — Full Form with Typed Values ### Description Demonstrates how to use the full form of DNS rewrite with typed values and handle parse errors. ### Code ```go // $dnsrewrite=NOERROR;SVCB;1 . alpn=h3 rule, err := rules.NewNetworkRule(`||example.org^$dnsrewrite=NOERROR;SVCB;1 . alpn=h3`, rules.ListID(1)) if err != nil { log.Fatal(err) } if svcb, ok := rule.DNSRewrite.Value.(*rules.DNSSVCB); ok { fmt.Println(svcb.Priority) // 1 fmt.Println(svcb.Target) // . fmt.Println(svcb.Params) // map[alpn:h3] } // Error handling: invalid keywords/values are rejected at parse time. if _, err := rules.NewNetworkRule("||example.org^$dnsrewrite=NOERROR;AAAA;not-an-ip", rules.ListID(1)); err != nil { fmt.Println("parse error:", err) } ``` ``` -------------------------------- ### Example: using MatchRequest to block or allow a request Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/engine.md Shows how to build an engine, create a request, match it, and check the result. Also demonstrates a document-type request for whitelist checks. ```go engine := buildEngine() req := rules.NewRequest( "https://ads.example.org/banner.png", "https://example.org/", rules.TypeImage, ) result := engine.MatchRequest(req) if rule := result.GetBasicResult(); rule != nil && !rule.Whitelist { fmt.Printf("blocked by: %s\n", rule.Text()) } else { fmt.Println("allowed") } // Whitelist check via the document page: docResult := engine.MatchRequest(rules.NewRequest("https://example.org/", "", rules.TypeDocument)) if docResult.DocumentRule != nil { fmt.Printf("document rule: %s\n", docResult.DocumentRule.Text()) } ``` -------------------------------- ### Example usage of RulesCount Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/network-engine.md Prints the number of loaded network rules using fmt.Printf. ```go fmt.Printf("loaded %d network rules\n", engine.RulesCount()) ``` -------------------------------- ### Reset usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-result.md Shows how to reuse a DNSResult across multiple requests by calling Reset before each match. ```go var res urlfilter.DNSResult for _, h := range hostnames { res.Reset() engine.MatchRequestInto(&urlfilter.DNSRequest{Hostname: h}, &res) handle(res) } ``` -------------------------------- ### Example usage of RulesCount Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-engine.md Prints the number of rules in the DNS engine using fmt.Printf. ```go fmt.Printf("DNS engine has %d rules\n", engine.RulesCount()) ``` -------------------------------- ### GetDNSBasicRule usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-matching-result.md Shows how to obtain the DNS basic rule from matched rules and print the verdict. Uses engine.AppendAllMatching and checks if the result is non-nil. ```go rules := engine.AppendAllMatching(nil, req) if basic := rules.GetDNSBasicRule(rules); basic != nil { fmt.Println("DNS verdict:", basic.Text(), "whitelist:", basic.Whitelist) } ``` -------------------------------- ### Example: Per-list lazy retrieval with RetrieveRule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-lists.md Demonstrates lazy retrieval of rules by index using RetrieveRule. The example creates a String list with two rules and retrieves them by offset. It also shows that retrieving an out-of-range index returns ErrRuleRetrieval, which is checked with errors.Is. ```go list := filterlist.NewString(&filterlist.StringConfig{ RulesText: "||example.org^\n||example.net^\n", ID: 1, }) r0, err := list.RetrieveRule(0) // ||example.org^ r1, err := list.RetrieveRule(15) // ||example.net^ (offset of second line) _, err = list.RetrieveRule(999) if errors.Is(err, filterlist.ErrRuleRetrieval) { fmt.Println("not found") } ``` -------------------------------- ### DNS rewrite rule example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-dnsrewrite.md Creates a DNS rewrite rule for an A record and prints the parsed RCode, RRType, and Value. ```go rule, err := rules.NewNetworkRule("||example.org^$dnsrewrite=192.0.2.1", rules.ListID(1)) if err != nil { log.Fatal(err) } dr := rule.DNSRewrite fmt.Println(dr.RCode) // 0 (dns.RcodeSuccess) fmt.Println(dr.RRType) // 1 (dns.TypeA) fmt.Println(dr.Value) // 192.0.2.1 (netip.Addr) ``` -------------------------------- ### DNSRewrites usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-result.md Shows how to iterate over DNS rewrite rules and handle different value types (IP address, MX, SVCB, or RCODE/CNAME). ```go res, matched := engine.MatchRequest(&urlfilter.DNSRequest{ Hostname: "example.com", DNSType: dns.TypeA, }) for _, nr := range res.DNSRewrites() { dr := nr.DNSRewrite switch v := dr.Value.(type) { case netip.Addr: fmt.Printf("rewrite to %s (RR type %d)\n", v, dr.RRType) case *rules.DNSMX: fmt.Printf("MX %d %s\n", v.Preference, v.Exchange) case *rules.DNSSVCB: fmt.Printf("SVCB priority=%d target=%s\n", v.Priority, v.Target) default: fmt.Printf("rcode=%d cname=%q\n", dr.RCode, dr.NewCNAME) } } ``` -------------------------------- ### String rule list example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-lists.md Creates a string-based rule list with rules text, ID 1, and IgnoreCosmetic false. ```go list := filterlist.NewString(&filterlist.StringConfig{ RulesText: "||example.org^\n##.ad-banner\n", ID: rules.ListID(1), IgnoreCosmetic: false, }) ``` -------------------------------- ### GetBasicResult usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-matching-result.md Shows how to use GetBasicResult to determine whether to bypass or block a request. The example checks if the rule is nil or a whitelist rule to bypass, otherwise blocks. It prints the rule text for allowed and blocked cases. ```go result := engine.MatchRequest(request) rule := result.GetBasicResult() if rule == nil { // bypass } else if rule.Whitelist { // bypass, but this rule (e.g. @@||example.org^$elemhide) affects cosmetics fmt.Println("allowed via:", rule.Text()) } else { // block fmt.Println("blocked via:", rule.Text()) } ``` -------------------------------- ### Example: scanning like the engines do Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-storage-scanner.md Shows the iteration pattern used by the engines (NewNetworkEngine, NewDNSEngine, NewCosmeticEngine) to deduplicate rules using a set and print rule details. ```go set := container.NewMapSet[string]() scanner := storage.NewRuleStorageScanner() for scanner.Scan() { f, id := scanner.Rule() if nr, ok := f.(*rules.NetworkRule); ok { if !set.Has(nr.String()) { set.Add(nr.String()) fmt.Printf("network rule id=%v text=%s\n", id, nr.Text()) } } } ``` -------------------------------- ### Example: scanning a RuleStorage Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-storage-scanner.md Shows how to create a RuleStorage with two string rules and iterate over them using RuleStorageScanner, printing the rule type and list ID. ```go storage, _ := filterlist.NewRuleStorage([]filterlist.Interface{ filterlist.NewString(&filterlist.StringConfig{ID: 1, RulesText: "||a.org^\n"}), filterlist.NewString(&filterlist.StringConfig{ID: 2, RulesText: "0.0.0.0 b.org\n"}), }) sc := storage.NewRuleStorageScanner() for sc.Scan() { f, id := sc.Rule() switch f.(type) { case *rules.NetworkRule: fmt.Println("network rule from list", id.ListID()) case *rules.HostRule: fmt.Println("host rule from list", id.ListID()) } } ``` -------------------------------- ### Example: error handling for NewRule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-rule.md Shows how to handle errors from NewRule, including unknown modifiers and the ErrTooWideRule error for bare patterns. ```go _, err := rules.NewRule("||example.org^$unknownmod", rules.ListID(1)) if err != nil { fmt.Printf("parse error: %v\n", err) // "unknown filter modifier: ..." } // "the rule is too wide" for a bare pattern with no restrictions: _, err = rules.NewRule("||", rules.ListID(1)) if err == rules.ErrTooWideRule { fmt.Println("rule rejected as too wide") } ``` -------------------------------- ### Bytes rule list example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-lists.md Reads rules from a file and creates a bytes-based rule list with ID 2 and IgnoreCosmetic true. ```go data, _ := os.ReadFile("rules.txt") list := filterlist.NewBytes(&filterlist.BytesConfig{ RulesText: data, ID: rules.ListID(2), IgnoreCosmetic: true, }) ``` -------------------------------- ### RequestType usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-request.md Shows how to combine request types with OR, count them, and check for a specific type. Also demonstrates creating a request with a specific type and verifying it. ```go rt := rules.TypeScript | rules.TypeImage fmt.Println(rt.Count()) // 2 fmt.Println(rt&rules.TypeImage != 0) // true req := rules.NewRequest("https://example.org/style.css", "", rules.TypeStylesheet) fmt.Println(req.RequestType == rules.TypeStylesheet) // true ``` -------------------------------- ### Example: Binary serialization round-trip Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-storage-id.md Creates a StorageID, serializes it with AppendBinary, then deserializes with UnmarshalBinary. The decoded value equals the original. ```go id := filterlist.NewStorageID(rules.ListID(7), 1024) buf, err := id.AppendBinary(nil) if err != nil { log.Fatal(err) } var decoded filterlist.StorageID if err := decoded.UnmarshalBinary(buf); err != nil { log.Fatal(err) } // decoded == id ``` -------------------------------- ### Example: error handling for invalid host rule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-host-rule.md Shows how to handle a *RuleSyntaxError when creating a host rule with an invalid IP address. ```go _, err := rules.NewHostRule("999.999.1.1 bad.example", rules.ListID(1)) if err != nil { var syntaxErr *rules.RuleSyntaxError if errors.As(err, &syntaxErr) { fmt.Println(syntaxErr.Error()) // rule "...": invalid syntax / parse error } } ``` -------------------------------- ### Run the proxy with authentication and HTTPS Source: https://github.com/adguardteam/urlfilter/blob/master/cmd/README.md Starts the proxy with username/password authentication and as an HTTPS proxy using the specified server name. The -t flag enables HTTPS, and -n sets the server name. ```bash ./adguard -l 0.0.0.0 -p 8080\ -c root.crt\ -k root.key\ -f adguard_base.txt\ -f adguard_tracking_protection.txt\ -f adguard_social.txt\ -u user\ -a password\ -t -n yourdomainname ``` -------------------------------- ### ShallowCloneInto usage example Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-result.md Shows how to call ShallowCloneInto on a DNSResult to copy its data into another DNSResult variable. ```go var other urlfilter.DNSResult res.ShallowCloneInto(&other) ``` -------------------------------- ### Example: Using GetCosmeticResult to inject cosmetic rules Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/engine.md Shows how to match a request, compute allowed cosmetic options, fetch the cosmetic result, and print the generic and specific element hiding styles to inject. ```go result := engine.MatchRequest(rules.NewRequestForHostname("example.org")) // Compute the cosmetic options that are currently allowed: options := result.GetCosmeticOption() // Fetch the styles/scripts to inject into the page: cosmetic := engine.GetCosmeticResult("example.org", options) inject := cosmetic.ElementHiding.Generic inject = append(inject, cosmetic.ElementHiding.Specific...) for _, style := range inject { fmt.Printf("inject style: %s\n", style) } ``` -------------------------------- ### Example: scanning rules from a string Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-scanner.md Creates a RuleScanner over a string containing three rules, scans them, and prints each rule's index and text. The output shows byte offsets 0, 12, and 20. ```go scanner := filterlist.NewRuleScanner( strings.NewReader("||example.org^\n##.ad\n0.0.0.0 host.example\n"), rules.ListID(5), false, ) for scanner.Scan() { rule, idx := scanner.Rule() fmt.Printf("idx=%d rule=%s\n", idx, rule.Text()) } // Output: // idx=0 rule=||example.org^ // idx=12 rule=##.ad // idx=20 rule=0.0.0.0 host.example ``` -------------------------------- ### Example: parsing multiple rule lines Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-rule.md Shows how to parse a multi-line rules text using NewRule and handle different rule types. Demonstrates the dispatch order and error handling for invalid lines. ```go rulesText := "||example.org^\n##.ad-banner\n0.0.0.0 tracker.example\n! a comment\n" for _, line := range strings.Split(rulesText, "\n") { rule, err := rules.NewRule(line, rules.ListID(42)) if err != nil { log.Printf("invalid rule %q: %v", line, err) continue } if rule == nil { continue // empty or comment } switch v := rule.(type) { case *rules.NetworkRule: fmt.Println("network:", v.Text()) case *rules.HostRule: fmt.Println("host:", v.Hostnames, v.IP) case *rules.CosmeticRule: fmt.Println("cosmetic:", v.Content, v.Type) } } ``` -------------------------------- ### Example: Toggle CosmeticOptionGenericCSS Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-matching-result.md Shows how to disable the generic CSS option using XOR and check if the CSS option is still set. The output is true. ```go o := rules.CosmeticOptionAll o ^= rules.CosmeticOptionGenericCSS // disable generic CSS fmt.Println(o&rules.CosmeticOptionCSS == rules.CosmeticOptionCSS) // true ``` -------------------------------- ### Example: ignoring cosmetic rules Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-scanner.md Creates a RuleScanner with ignoreCosmetic set to true, so only host rules survive. The loop prints only rules that are of type *rules.HostRule. ```go scanner := filterlist.NewRuleScanner(r, rules.ListID(5), true) for scanner.Scan() { f, _ := scanner.Rule() if _, ok := f.(*rules.HostRule); ok { // only hosts-file rules survive fmt.Println(f.Text()) } } ``` -------------------------------- ### Example: using MatchRequestInto with pooled results Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/dns-engine.md Shows how to use MatchRequestInto in a loop with a pooled DNSResult to avoid allocations. The result is reset before each call, and shallow copies are appended to a pool. Note the comment about shallow copies and ShallowCloneInto. ```go pool := make([]*urlfilter.DNSResult, 0, 4) var res urlfilter.DNSResult defer res.Reset() for _, h := range []string{"doubleclick.net", "example.org"} { res.Reset() matched := engine.MatchRequestInto(&urlfilter.DNSRequest{Hostname: h}, &res) pool = append(pool, &res) // shallow copies; see ShallowCloneInto _ = matched } ``` -------------------------------- ### Example — producing injectable HTML Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/cosmetic-engine.md Shows how to flatten the element-hiding rules from a CosmeticResult into a slice of strings for injection. It concatenates generic, specific, and extended CSS rules. ```go func injectableStyles(res urlfilter.CosmeticResult) []string { var out []string out = append(out, res.ElementHiding.Generic...) out = append(out, res.ElementHiding.Specific...) out = append(out, res.ElementHiding.GenericExtCSS...) out = append(out, res.ElementHiding.SpecificExtCSS...) return out } ``` -------------------------------- ### Example CLI invocation Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/cmd-cli.md Shows a typical command-line usage of the urlfilter CLI, specifying CA certificate and key, two filter lists, port 8080, and verbose mode. ```bash urlfilter \ -c ca.crt -k ca.key \ -f adguard_base_filter.txt -f adguard_russian_filter.txt \ -p 8080 -v ``` -------------------------------- ### GET /content-script.js Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/endpoints.md Serves a generated content-script that applies cosmetic rules for a given hostname and option bitmask. Requires the hostname, option, and ts query parameters; returns 404 if any are missing or zero, and 304 if the ts matches the server creation timestamp with an If-Modified-Since header. ```APIDOC ## GET /content-script.js ### Description Serves a generated content-script that applies cosmetic rules for a given hostname and option bitmask. Requires the hostname, option, and ts query parameters; returns 404 if any are missing or zero, and 304 if the ts matches the server creation timestamp with an If-Modified-Since header. ### Method GET ### Endpoint /content-script.js ### Parameters #### Query Parameters - **hostname** (string) - Required - Page hostname to build cosmetic rules for. Absent/empty ⇒ 404. - **option** (uint64) - Required - `rules.CosmeticOption` bitmask; `0` ⇒ 404. - **ts** (uint64) - Required - Server creation timestamp (used for cache busting); `0` ⇒ 404. ### Request Example ``` GET /content-script.js?hostname=example.org&option=7&ts=1580000000 HTTP/1.1 Host: injections.adguard.org ``` ### Response #### Success Response (200) - **Content-Type**: text/javascript; charset=utf-8 - **Body**: Generated content-script invoking the cosmetic rules for `hostname`/`option` - **Headers**: `Cache-Control: public, max-age=3600`, `Expires`, `Last-Modified: Wed, 01 Jan 2010 01:00:00 GMT`; `Content-Encoding: gzip` when `CompressContentScript` is true. #### Response Example ``` HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 Cache-Control: public, max-age=3600 Last-Modified: Wed, 01 Jan 2010 01:00:00 GMT Expires: /* content-script v1.0.0 ... */ (function (configuration) { ... }) ({"elementHiding":{...}}) ``` #### 304 Not Modified - **Content-Type**: text/javascript; charset=utf-8 - **Body**: empty - **Condition**: `ts` equals the server's `createdAt.Unix()` **and** request has a non-empty `If-Modified-Since` header. Cache headers re-enabled. #### 404 Not Found - **Content-Type**: text/html - **Body**: empty HTML - **Condition**: Request method is not `GET`, or any of `hostname`/`option`/`ts` is missing/zero. ``` -------------------------------- ### FileConfig struct and NewFile function Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-lists.md Defines the configuration for a file-based rule list and the constructor function. The Path is cleaned with filepath.Clean before opening. The file is kept open for the list's lifetime; SizeEstimate uses the file size. Returns (*File, error). Errors: os.Open error (not wrapped) if file cannot be opened, and 'getting fileinfo for size estimation: %w' if os.File.Stat fails. ```go // FileConfig represents configuration for a file-based rule list. type FileConfig struct { // Path is the path to the file with rules. Path string // ID is the rule list identifier. ID rules.ListID // IgnoreCosmetic tells whether to ignore cosmetic rules or not. IgnoreCosmetic bool } // NewFile creates a new file-based rule list with the given configuration. func NewFile(conf *FileConfig) (f *File, err error) ``` -------------------------------- ### Example: creating RuleStorage with duplicate IDs Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/filterlist-rule-storage.md This example creates a RuleStorage with two string rule lists that both have ID 1, causing an error. The error message is printed as "at index 1: id: duplicated: 1". ```go storage, err := filterlist.NewRuleStorage([]filterlist.Interface{ filterlist.NewString(&filterlist.StringConfig{ID: 1, RulesText: "||a.org^"}), filterlist.NewString(&filterlist.StringConfig{ID: 1, RulesText: "||b.org^"}), }) if err != nil { fmt.Println(err) // "at index 1: id: duplicated: 1" } ``` -------------------------------- ### Build the proxy with go build Source: https://github.com/adguardteam/urlfilter/blob/master/cmd/README.md Clones the repository, changes to the cmd directory, and builds the adguard binary. ```bash git clone https://github.com/AdguardTeam/urlfilter cd urlfilter/cmd go build -o adguard ``` -------------------------------- ### Catching filterlist.ErrRuleRetrieval Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/errors.md Example of using errors.Is to check for ErrRuleRetrieval when retrieving a rule with an out-of-range index. ```go _, err := list.RetrieveRule(99999) if errors.Is(err, filterlist.ErrRuleRetrieval) { // index out of range or empty line } ``` -------------------------------- ### Catching rules.ErrTooWideRule Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/errors.md Example of checking for the ErrTooWideRule sentinel error after calling rules.NewNetworkRule with a too-generic pattern. Works with errors.Is if wrapped. ```go _, err := rules.NewNetworkRule("||", rules.ListID(1)) if err == rules.ErrTooWideRule { fmt.Println("rejected as too wide") } ``` -------------------------------- ### Config.String method signature Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Returns a human-readable multi-line description of the server configuration, including listen address, MITM status, HTTPS-proxy status, proxy auth, API host, and filter-list paths. ```go // String - server's configuration description func (c *Config) String() string ``` -------------------------------- ### Command-line help output Source: https://github.com/adguardteam/urlfilter/blob/master/cmd/README.md Shows the full usage and options for the adguard binary, including verbose output, log file, listen address/port, CA certificate/key, filter lists, authentication, and HTTPS settings. ```bash $ ./adguard -h Usage: adguard [OPTIONS] Application Options: -v, --verbose Verbose output (optional). -o, --output= Path to the log file. If not set, it writes to stderr. -l, --listen= Listen address. (default: 0.0.0.0) -p, --port= Listen port. Zero value disables TCP and UDP listeners. (default: 8080) -c, --ca-cert= Path to a file with the root certificate. -k, --ca-key= Path to a file with the CA private key. -f, --filter= Path to the filter list. Can be specified multiple times. -u, --username= Proxy auth username. If specified, proxy authorization is required. -a, --password= Proxy auth password. If specified, proxy authorization is required. -t, --https Run an HTTPS proxy (otherwise, it runs plain HTTP proxy). -n, --https-name= Server name for the HTTPS proxy. Help Options: -h, --help Show this help message ``` -------------------------------- ### Rule interface Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/rules-rule.md The Rule interface is the base abstraction for all filtering rules. It provides methods to get the original rule text and the filter list ID. ```APIDOC ## Rule interface ### Description The Rule interface is the base abstraction for all filtering rules. It provides methods to get the original rule text and the filter list ID. ### Methods - **Text()** (string) - Returns the original rule text. - **GetFilterListID()** (ListID) - Returns the ID of the filter list this rule belongs to. ### Implemented By - *NetworkRule - *HostRule - *CosmeticRule ``` -------------------------------- ### NewServer function signature Source: https://github.com/adguardteam/urlfilter/blob/master/_autodocs/api-reference/proxy-server.md Constructor for the MITM server. Takes a Config and returns a *Server and error. Wires the engine from FiltersPaths and registers handlers. ```go // NewServer creates a new instance of the MITM server func NewServer(config Config) (*Server, error) ```