Rules overview
When globally enabled, HIN works by applying a sequence
of
rules, each with a
match criterion, to every
incoming request it receives. Each rule has associated with
it an optional set of
actions (see below) which are
performed on the request when that rule matches. For purposes here,
the term "request" refers, as in the
chrome.webRequest
documentation, collectively to the HTTP request sent by the browser together
with the HTTP response that comes back. If multiple rules match,
all their enabled actions are performed. The match criterion is a logical
composition of tests, usually string operations, applied against the
content of the HTTP request, specifically the request method
(GET, POST, etc), and the URL (e.g.,
"http://www.foobar.com/baz"). There is not (yet) an ability for
a rule to match on other request information such as the
headers, nor any part of the response such as the HTTP status
or response headers.
Actions are referenced in a rule by name and described in the next section.
Rules Syntax
The rules in place are given by the key
rules: in the HIN
Options JSON data. The value of this key is an array of JSON objects,
each of which is a named rule and has the following required components:
- name: Rule name. This name will appear in the debug page when the rule matches.
- description: Rule description. Describes the purpose and operation of the rule. This will appear in the tooltip of the rule where it appears on the HIN toolbar icon popup.
- enabled: Boolean flag, true if the rule is enabled for matching and execution of actions.
- match: A match condition, see Match Syntax, below.
- action: A single named action string, or array of zero or more action names, each of which will be performed (if enabled) when the rule matches. An empty list of actions will cause the rule to do nothing, however its match will still be captured as a debug event if debug capture is enabled. This can be useful for debugging match expressions. The named actions must all appear in the action list given in the action section (see below).
Match Syntax
A match condition is a JSON value that is evaluated by the HIN matching engine to yield "true" or "false" value that decides if the rules is a match for the request (in which case the rule's enabled actions are performed). The condition can take the following forms:
-
A JSON boolean, true or false. The built-in
rule "Default" has match of true and so will always
match and perform, on every request, whatever enabled actions are
given there. The value false by itself is not
useful as it will cause the rule never to match, but can
be useful in conjunction with logical operators (see
below) to disable a portion of a rule for debugging.
-
A JSON array representing a logical expression: [
"and", conditions ], or [ "or", conditions ],
where conditions is a sequence of
zero or more conditions, or [ "not", condition ] where condition
(which must be given) is a single condition. Examples:
- "match": ["and", ["url", "contains", "foobar.com"], ["url", "starts", "https://"]]
- "match": ["not", ["or", ["url", "matches", "https?://"], ["url", "ends", ".jpg"]]
The "and" operator together with the false literal can be used to disable a portion of a complex expression:
["and", ["url", "contains", "this-matches"], ["and", false, ["url", "contains", "this-part-disabled-for-now"]]]
-
A JSON array representing a string match operation on a field:
[field, op, arg], where:
- field is a request field
to be tested, one of "method" or "url".
- op is a string comparison operator, one of
"contains",
"starts",
"ends",
"equals", or
"matches". The first four operators function case-insensitively on a single string argument, while
"matches" takes as argument a string to be compiled into a regular expression
using the JavaScript RegExp syntax (and with the "i" and "g" options given for case-insensitivity and global, respectively).
- arg is a string
argument to the operator, either a literal string or
RegExp string as appropriate. Note that where the
string is to be compiled into a RegExp, all appropriate escaping
must be done. For example, to match on a single backslash the RegExp string must be given
two backslashes, while also the JSON string syntax requires both those
to be escaped, so that you need to give four (!) backslashes "\\\\" in the argument.
To see numerous examples, open the HIN Options page and study the default rules.