aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/UrlFilter.md91
1 files changed, 91 insertions, 0 deletions
diff --git a/doc/UrlFilter.md b/doc/UrlFilter.md
new file mode 100644
index 0000000..cea2397
--- /dev/null
+++ b/doc/UrlFilter.md
@@ -0,0 +1,91 @@
+## FilterDomain
+Filter Domains are groups of domains that can point to one or more filter
+rules.
+
+### Types
+There are 4 Filter Domain types:
+- AllowOnDomains - only match specified domains
+- BlockOnDomains - match all but specified domains
+- AllowOnAllDomains - match all domains
+- BlockOnAllDomains - match no domains
+
+### JSON
+ {
+ "type" : "AllowOnDomains",
+ "domains" : [ "example.com", "test.example.com" ],
+ "rules" : []
+ }
+
+## FilterRule
+Filter rules contain information on how a request should be modified.
+
+### "action"
+- Whitelist - allow this request
+- Blacklist - block this request
+- Redirect - redirect this request
+- SetHeader - apply a list of headers
+
+### "regexp", "contains", "endswith"
+
+### JSON
+Allow all URLs that contain "waifu.png"
+ {
+ "action" : "Whitelist"
+ "contains" : "waifu.png"
+ }
+
+Block specific URL
+ {
+ "action" : "Blacklist"
+ "equals" : "example.com/annoying-ad/masquerade/waifu.png"
+ }
+
+Block all URLs that contain "banner.gif"
+ {
+ "action" : "Blacklist",
+ "contains" : "banner.gif"
+ }
+
+Redirect URLs containing "ads/annoying-spam.gif" to "waifu.tld/waifu.gif"
+ {
+ "action" : "Redirect"
+ "contains" : "ads/annoying-spam.gif"
+ "url" : "waifu.tld/waifu.gif"
+ }
+
+Set some headers
+ {
+ "action" : "SetHeader"
+ "header" : [ "DNT" : "1" ]
+ }
+
+## QWebEngineUrlRequestInterceptor
+
+All network requests pass through the request interceptor. It gives the
+following information:
+
+- firstPartyUrl - the page on which the request is made
+- requestUrl - the url of the request
+- requestMethod
+- resourceType
+- navigationType
+
+And provides the following methods:
+
+- block (bool shouldBlock) - can block the request
+- redirect (const QUrl) - can redirect the requestUrl
+- setHttpHeader - can set HTTP headers (such as user agent and do not track)
+
+### Example
+This is a sample request made when loading DuckDuckGo:
+
+ firstPartyUrl=https://duckduckgo.com/
+ requestUrl=https://duckduckgo.com/o1635.css
+
+## How the filter works
+When a requst comes in, the interceptor extracts the host of the request and
+matches it against the list of FilterDomains.
+
+ firstPartyHost=duckduckgo.com
+ requestHost=duckduckgo.com
+