Skip to content

Latest commit

 

History

History
391 lines (311 loc) · 12.2 KB

manual.wiki

File metadata and controls

391 lines (311 loc) · 12.2 KB
Raw

Table of Contents

Request Control Manual

Request Control Rule

Request Control Rule consists of Pattern, Types and Action.

Requests that match a pattern and types of an active rule will be intercepted taking the action of the rule.

Pattern

Pattern filters matched requests by Scheme, Host and Path.

Scheme

Supported schemes are http and https.

http Match a http scheme.
https Match a https scheme.
http/https Match both http and https schemes.

Host

Host pattern may match the host of the request URL in following ways:

www.example.com Matches a complete host.
*.example.com Matches the given host and any of its subdomains. Will match example.com and all subdomains of example.com e.g. www.example.com , good.example.com
www.example.* Matches the given host and manually listed top-level domains. (can be combined with the subdomain matching) Write the top-level domains to the top-level domain name list (e.g. com, org).
* Matches any host.

Path

Path pattern may subsequently contain any combination of "*" wildcard and any of the characters that are allowed in URL path. The "*" wildcard matches any portion of path and it may appear more than once.

Below are examples of using path patterns.

* Matches any path.
path/a/b/ Matches the exact path "path/a/b/".
*b* Matches a path that contains a component "b" somewhere in the middle.
Matches an empty path.

Types

Filter matched requests by the type of request. The type indicates the requested resource. All supported types are listed below.

Type Details
Document Indicates a DOM document at the top-level that is retrieved directly within a browser tab. (main frame)
Sub document Indicates a DOM document that is retrieved inside another DOM document (<iframe> and <frame> elements).
Stylesheet Indicates a stylesheet (for example, <style> elements).
Script Indicates an executable script (such as JavaScript) loaded with <script> element or the Worker API.
Image Indicates an image (for example, <img> elements).
Object Indicates a generic object (<object> and <embed> elements).
Plugin Indicates a request made by a plugin. (object_subrequest)
XMLHttpRequest Indicates a request made by an XMLHttpRequest (xhr) or by Fetch API.
XSLT Indicates an XSLT style sheet transformation for an XML document.
Ping Indicates a ping request triggered by an <a> element using the ping attribute. Only in use if browser.send_pings is enabled.
Speculative Indicates a predictive TCP and/or TLS handsake for a request that browser has determined to be coming soon. Only in use if network.http.speculative-parallel-limit is greater than 0.
Beacon Indicates a Beacon request.
XML DTD Indicates a DTD loaded by an XML document.
Font Indicates a font loaded via @font-face rule.
Media Indicates a video or audio load (<video> and <audio> elements).
WebSocket Indicates a WebSocket load.
CSP Report Indicates a Content Security Policy report.
Imageset Indicates a request to load an <img> (with the srcset attribute) or <picture> element.
Web Manifest Indicates a request to load a Web App Manifest.
Other Indicates a request that is not classified as being any of the above types.

Action

Filter
Skip URL redirection and/or remove URL query parameters.
Redirect
Redirect requests to manually configured redirect URL.
Secure
Upgrade non-secure HTTP requests to secure HTTPS.
Block
Cancel requests before they are made.
Whitelist
Whitelist and optionally log requests.

Extra URL Matchers

Following matchers extend the matching capabilities of WebRequest API.

Includes and Excludes

Filter matched requests by patterns that can be defined as a string with support for wildcards "?" and "*" (where "?" matches any single character and "*" matches zero or more characters), or as a regular expression pattern.

Include and exclude pattern matching is case insensitive as opposed to Host and Path which are case sensitive.

Below are examples of using include and exclude patterns:

login Matches URLs containing "login".
log?n Matches for example URLs containing "login" and "logon".
a*b Matches URLs where "a" is followed by "b"
/[?&]a=\d+(&|$)/ Matches URLs containing parameter "a" with digits as value.

Match by origin

Filter matched requests by origin of request.

Any Matches requests with any origin
Same domain Matches requests on same domain
Same origin Matches requests on same origin. Adheres to the Same-origin policy.
Third party domain Matches requests to third party domain
Third party origin Matches requests to third party origin

Rule priorities

  1. Whitelist rule
  2. Block rule
  3. Secure rule
  4. Redirect rule
  5. Filter rule

Trimming URL parameters

Filter rule supports URL query parameter trimming. Trimmed URL parameters are defined either as literal strings with support for "*" and "?" wildcards or using regular expression.

Below are examples of using query parameter trimming patterns.

utm_source Trims any "utm_source" parameter
utm_* Trims any parameter starting with "utm_"
/[0-9]+/ Trims any parameter containing only digits

Invert Trim Option

Keeps only parameters that are defined in trimmed parameters list. All other parameters will be removed.

Trim All Option

Removes all URL query parameters from matched request.

Redirect using pattern capturing

Redirect rule supports redirecting requests to a manually configured URL. The redirect URL may be parametrized using parameter expansion and redirect instructions. Parameter expansion allows to access and manipulate a set of named parameters of the original URL. Redirect instructions can be used to replace named parameters of original request URL (e.g. by instructing requests to redirect to a different port).

Both methods may be combined. Redirect instructions will be parsed and applied first before parameter expansions.

Parameter expansion may also be used within a redirect instruction.

Parameter expansion

{parameter}
Access a named parameter of the original request URL. Available named parameters are listed at the end of this section.

Parameter expansion supports the following string manipulation formats:

Substring replacing

{parameter/pattern/replacement}

Replaces the first matched substring in expanded parameter. 

{parameter//pattern/replacement}

Replaces all occurrences of matched substring in expanded parameter.

The pattern is written in regular expression. A number of special replacement patterns are supported, including referencing of capture groups which are described below.

$n Inserts the n-th captured group counting from 1.
$` Inserts the portion of the string that precedes the matched substring.
$' Inserts the portion of the string that follows the matched substring.
$& Inserts the matched substring.
$$ Inserts a "$".

Substring extraction

{parameter:offset:length}
Extract a part of the expanded parameter. Offset determines the starting position. It begins from 0 and can be a negative value counting from the end of the string.

Decoding and encoding

{parameter|encodingRule}
Decode or encode an expanded pattern.

encodeURI Encodes a pattern as URI. It does not encode the following characters: ":", "/", ";", and "?".
decodeURI Decodes an encoded URI.
encodeURIComponent Encodes a pattern as a component of URI. Encodes all special characters reserved for URI.
decodeURIComponent Decodes an encoded URI component.
encodeBase64 Encode a pattern as Base64 string.
decodeBase64 Decodes an encoded Base64 string.

Combining manipulation rules

{parameter(manipulation1)|(manipulation2)...|(manipulationN)}
String manipulation rules can be chained using a "|" pipe character. The output is the result of manipulations chain.

Examples

https://{hostname}/new/path
Uses the hostname of the original request. 

https://{hostname/([a-z]{2}).*/$1}/new/path
Captures a part of the hostname of the original request. 

https://{hostname::-3|/\.co/\.com}/new/path
Uses the hostname of the original request but manipulate its length by three cutting it from the end and replace ".co" with ".com". 

{search.url|decodeURIComponent}
Captures "url" search parameter and decodes it.

Redirect instruction

[parameter=value]
Replace a certain part of the original request. Available named URL parameters are listed at the end of this section. 

[parameter={parameter<manipulations>}]

The value of a redirect instruction can be parametrized using the parameter expansion described above.

Examples

[port=8080]
Redirects the original request to a port 8080. 

[port=8080][hostname=localhost]
Redirects the original request to a port 8080 of localhost. 

[port=8080][hostname=localhost][hash={pathname}]
Redirects the original request to a port 8080 of localhost where hash is the original request's path.

List of named parameters

Names of the supported parameters and their example outputs are listed in the table below.

Example address used as input: 

https://www.example.com:8080/some/path?query=value#hash
Name Output
protocol https:
hostname www.example.com
port :8080
pathname /some/path
search ?query=value
search.query value
hash #hash
host www.example.com:8080
origin https://www.example.com:8080
href https://www.example.com:8080/some/path?query=value#hash

This manual page is build upon the material of the following MDN wiki documents and is licenced under CC-BY-SA 2.5.

  1. Match patterns by Mozilla Contributors is licensed under CC-BY-SA 2.5.
  2. webRequest.ResourceType by Mozilla Contributors is licensed under CC-BY-SA 2.5.
  3. URL by Mozilla Contributors is licensed under CC-BY-SA 2.5.