Rules overview
When globally enabled, HIN works by intercepting each HTTP request
from the browser and applying a sequence of
rules,
each with a
match condition
and optional sequence of
actions (see below) to be
performed on requests matching the condition. 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 a request,
all their enabled actions are performed. The match condition is a logical
composition of tests, usually string comparisons, 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: An action name 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 options' actions: 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 its enabled actions, for every request.
The value false by itself is not
generally useful here, 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
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 temporarily a portion of a complex expression for debugging:
["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 compare case-insensitively the value of
field to arg, while
"matches" treats arg as a string to be compiled into a regular expression
using the JavaScript RegExp syntax (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.
