diff --git a/Dynamic-filtering:-rule-syntax.md b/Dynamic-filtering:-rule-syntax.md new file mode 100644 index 0000000..8577117 --- /dev/null +++ b/Dynamic-filtering:-rule-syntax.md @@ -0,0 +1,69 @@ +[Back to "Dynamic-filtering"](https://github.com/gorhill/uBlock/wiki/Dynamic-filtering) + +*** + +### Rule syntax + +A dynamic filtering rule is made of four components: a source, a destination, a request type, and then a keyword which tells what to do with a request which happens to match the three former components. + +| rule type | source | destination | request type | action | +|---|---|---|---|---| +| **Type-based** | `*`
_hostname_ | `*`
  | `*`
`image`
`inline-script`
`1p-script`
`3p`
`3p-script`
`3p-frame` | `block`
`noop`
`allow` | +| **Hostname-based** | `*`
_hostname_ |
_hostname_ |
`*` | `block`
`noop`
`allow` | + +Source hostname always corresponds to the hostname extracted from the URL of the web page in the browser. + +The destination hostname corresponds to the hostname extracted from the URL of a remote resource which the web page is fetching (or trying to). + +The rule always automatically propagates to all subdomains of the source hostname and all subdomains of the destination hostname -- unless the rule is overridden by a narrower rule in one of the subodmains. + +The type is the type of the fetched resource. + +A request can be blocked (`block`), allowed (`allow`), or ignored (`noop`). A `noop` rule will cause matching network requests to be ignored by the dynamic filtering engine, but those ignored network requests will still be subjected to static filtering (filter lists). + +*** + +### Type-based rules + +Type-based rules are used to filter specific types of request on a web page. There currently exists seven types of request which can be dynamically filtered: + +- `*`: any type of request +- `image`: images +- `3p`: any request which 3rd-party to the web page +- `inline-script`: inline script tags, i.e. scripts embedded in the main document +- `1p-script`: 1st-party scripts, i.e. scripts which are pulled from the same domain name of the current web page +- `3p-script`: 3rd-party scripts, i.e. scripts which are pulled from a different domain name than that of the current web page +- `3p-frame`: 3rd-party frames, i.e. frames elements which are pulled from a different domain name than that of current web page + +These rules can apply everywhere, or be specific to a web site. For instance blocking 3rd-party frames is a very good habit security-wise: `* * 3p-frame block`. This rule translates into "globally block 3rd-party frames". + +Another example: `wired.com * image block`, which means "block images from all origins when visiting a web page on wired.com". + +Note that with type-based rules, the destination hostname is **always** `*`, meaning "from anywhere". + +*** + +### Hostname-based rules + +Hostname-based rules are used to filter network resources according to their origin, i.e. according to which remote server a resource is pulled. Hostname-based rules have a higher specificity than type-based rules, and thus hostname-based rules always override type-based rules whenever a network request end up matching both a type- and a hostname-based rule. + +With hostname-based rule, the request type is always `*`, meaning the rule will apply to any type of request. + +For example, `* disqus.com * block` means "globally block all net requests to `disqus.com`". + +Just like type-based rules, a hostname-based rule can apply only when visiting a specific web site, for example: `wired.com disqus.com * noop`, which means "do not apply dynamic filtering to network requests to `disqus.com` when visiting a web page on `wired.com`. Since this last rule is more specific than the previous one, it will override the global blocking of `disqus.com` everywhere. + +*** + +### Actions + +A matching rule can do one of three things: + +- `block`: matching network request will be blocked. + - `block` dynamic filter rules override any existing [static exception filters](https://adblockplus.org/en/filters#whitelist). + - Thus you can use them to block with 100% certainty (unless you set another overriding dynamic filter rule). +- `allow`: matching network request will be allowed. + - `allow` dynamic filters rules override any existing static and dynamic block filters. + - Thus they are most useful to create finer-grained exceptions, and to un-break web sites broken by some static filters somewhere. +- `noop`: exclude network requests from being subjected to dynamic filtering. + - It cancels dynamic filtering, but it does not cancel static filtering. \ No newline at end of file