Related discussion/issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2917
- https://github.com/uBlockOrigin/uAssets/discussions/30124
The "list of selectors" parameter is now a "list of steps". A step
can be:
- A selector, which tells the scriptlet to click a matching element. If
no matching element is found, the scriptlet will wait for a matching
element to become available.
- An integer, which tells the scriptlet to wait n ms before processing
the next step
- A directive, which is a string starting with `!` (not implemented yet)
If the last item in the list is an integer, this tells the scriplet to
override the built-in timeout value of 10s, such that the life time of
the scriptlet can now be extended beyond 10s.
Example:
..##+js(trusted-click-element, '1000, a, 500, b, c, 15000')
The scriptlet filter above will perform the following steps, in order:
- Prepare the scriptlet to timeout at 15s from now
- Wait 1000 ms
- Wait for element `a` to become available then click on it
- Wait 500 ms
- Wait for element `b` to become available then click on it
- Wait for element `c` to become available then click on it
- Abort if all the steps cannot be completed before 15s
The changes keep compatiblity with older syntax or with AdGuard
syntax.
Related issue:
https://github.com/uBlockOrigin/uBlock-issues/issues/3799
An infinite loop in the network filter parser was triggered when
the following conditions were fulfilled:
- There was a network option `$` anchor
- There were only whitespace character(s) preceding the anchor
- There was an invalid filter option following the anchor
Add vararg `throttle, n` where `n` is the time to wait in ms before
returning a response from proxied `fetch()`.
As discussed with filter list maintainers.
The `uritransform=` option will now be converted to a proper DNR
rule when the following condition are fulfilled:
- The value of the `uritransform` option matches `//[replacement]/`,
i.e. the pattern to match is empty, and only the replacement part is
provided.
- The filter pattern is a regex.
Is such case, the DNR rule will be a `redirect` making use of the
`regexSubstitution` property.
In case the above conditions are not fulfilled, the filter will
be discarded as incompatible with DNR syntax (as was the case
before).
This is potentially a breaking change, in cases where a filter
assumed that the part to match was the start of the path part of
a URL.
A reminder that `uritransform` is an option which requires a
trusted source, otherwise it is rejected.
As discussed with filter list maintainers.
Examples of usage:
$ => result is `null`
$+={"modifyOrCreate": "..."}
These expressions were not working with previous version.
As discussed with filter list maintainers.
Examples of JSON path expression to replace a pattern within a string
value:
..book.*.author=repl({"pattern": "Melville", "replacement": "Toto"})
..book.*.author=repl({"regex": "e", "replacement": "o"})
..book.*.author=repl({"regex": "e", "flags": "g", "replacement": "o"})
If the target value is not a string, no modification will occur.
Related issue:
https://github.com/uBlockOrigin/uBOL-home/issues/325
This is a first version, with support only for custom filters which are
plain CSS selectors. Future versions will extend support to style-based
and procedural cosmetic filters.
Manually text-editing existing custom filters is currently not supported,
this will be added in a future version in the Develop pane. To remove
existing custom filters, the "Remove a custom filter" tool can be used.
As discussed with filter list maintainers.
@scriptlet edit-inbound-object.js
@description
Prune properties from an object passed as argument to a specific method.
Properties can only be removed.
@param propChain
Property chain of the method to trap.
@param argPos
0-based position of the argument. Use negative integer for position relative
to the end.
@param jsonq
A uBO-flavored JSONPath query.
@scriptlet trusted-edit-inbound-object.js
@description
Edit properties of an object passed as argument to a specific method.
Properties can be assigned new values.
@param propChain
Property chain of the method to trap.
@param argPos
0-based position of the argument. Use negative integer for position relative
to the end.
@param jsonq
A uBO-flavored JSONPath query.
edit-outbound-object-.js
@description
Prune properties from an object returned by a specific method.
Properties can only be removed.
@param jsonq
A uBO-flavored JSONPath query.
trusted-edit-outbound-object.js
@description
Edit properties from an object returned by a specific method.
Properties can be assigned new values.
@param jsonq
A uBO-flavored JSONPath query.
json-edit-xhr-request.js
@description
Edit the object sent as the body in a XHR instance.
Properties can only be removed.
@param jsonq
A uBO-flavored JSONPath query.
@param [propsToMatch, value]
An optional vararg detailing the arguments to match when xhr.open() is
called.
trusted-json-edit-xhr-request.js
@description
Edit the object sent as the body in a XHR instance.
Properties can be assigned new values.
@param jsonq
A uBO-flavored JSONPath query.
@param [propsToMatch, value]
An optional vararg detailing the arguments to match when xhr.open() is
called.
json-edit-fetch-request.js
@description
Edit the request body sent through the fetch API.
Properties can only be removed.
@param jsonq
A uBO-flavored JSONPath query.
@param [propsToMatch, value]
An optional vararg detailing the arguments to match when fetch() is
called.
trusted-json-edit-fetch-request.js
@description
Edit the request body sent through the fetch API.
Properties can be assigned new values.
@param jsonq
A uBO-flavored JSONPath query.
@param [propsToMatch, value]
An optional vararg detailing the arguments to match when fetch() is
called.
This feature is hidden behind the "Developer mode" setting in
the dashboard. When "Developer mode" is enabled, a tab named
"Develop" will become available in the dashboard. This tab is
meant to contain tools for technical users.
At the moment, the "Develop" pane allows to create custom DNR
rules through a (CodeMirror-based) editor.
For the sake of convenience, the DNR rule must be entered in
YAML-like format. The format is not really full compliant YAML,
just YAML-like, and very strict in order to ensure the parser
stays simple enough.
Lines starting with `#` are comments and will be ignored by the
parser.
Any line which do not match the parser's expectation will be
marked as invalid, and the whole DNR rule containing such invalid
lines will be discarded.
There must not be empty lines inside a rule definition.
Each DNR rule must be separated with a `---` line, which is
known as a YAML document separator.
String values must not be quoted, otherwise the quotes will be
considered part of the value. There is one exception: `''` will
be parsed as "an empty string".
The editor will attempt to auto-complete known DNR keywords. That
feature will improve over time.
Though the parser will identify some errors, not all invalid DNR
rules are currently identified by the parser, and these will be
reported when the rules are registered through the DNR API. Better
identifying invalid DNR rules at edit time will improve over time.
The editor will report `regexFilter` values which are not
supported by the DNR engine on the current platform.
The editor reacts to instances of `regexFilter: ...` to report
whether a regex value is supported. This means you can test for
a regex value by using `# regexFilter: ...` so that you do not
have to create an actual DNR rules just for the sake of testing.
Custom DNR rules can be exported into a JSON file (a format
known by the DNR API as a "static ruleset").
JSON-based ruleset can be imported, the content will be converted
to YAML-like syntax.
The editor will attempt to convert to YAML pasted content which
can be JSON-parsed. It's possible to paste partially or wholly
JSON-based rulesets.
When disabling "Developer mode", all custom DNR rules will be
unregistered from the DNR API. The DNR rules content will be left
intact in such case. Existing DNR rules will be registered into
the DNR API when re-enabling "Developer mode".
Administrators can prevent "Developer mode" from being enabled
by adding `develop` token to `disabledFeatures` setting.
Related discussion:
https://github.com/uBlockOrigin/uBOL-home/discussions/323
The main motivation is to give list maintainers a tool to assist
with resolving filter issues. Custom DNR rules can assist in
crafting and validating filters meant to work with uBOL.
A secondary motivation is to provide technical users the ability
to further customize their content blocker.
More conveniences will be added over time, this is a first version.
Related issue:
https://github.com/uBlockOrigin/uBOL-home/issues/157
The `header=` option will be converted into DNR's `responseHeaders`
condition.
There will be an attempt to convert regex-based values into DNR-
compatible syntax. Not all regex-based patterns can be converted to
use DNR's patterns with `*` and `?` special characters.
The implementation of `header=` option in uBO has been revisited to
improve compatibility with DNR syntax to minimize burden for list
maintainers when creating `header=` filters compatible with both
uBO and uBOL.
The changes:
- Header names are now case-insensitive by default
- Occurrences of `*` in non-regex-based header values now mean
"matches any number of characters"
- Occurrences of `?` in non-regex-based header values now mean
"matches zero or one character"
At time of commit, and as per MDN, only Chromium-based browsers
currently support filtering on repsonse headers:
https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/declarativeNetRequest/HeaderInfo
Also as per MDN, Chromium 121-127 silently ignore the `responseHeaders`
condition, potentially causing undue blocking of network requests.
Currently uBOL support Chromium 122 and later, meaning we need to mind
potential false positives in Chromium 122-127 for filters using
`header=` option.
