chrome/common/extensions/docs/templates/intros/declarativeWebRequest.html

<h2 id="notes">Notes</h2>

<p>
Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or
modify requests in-flight. It is significantly faster than the <a
  href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can
register rules that are evaluated in the browser rather than the
JavaScript engine which reduces roundtrip latencies and allows for very high
efficiency.
</p>

<h2 id="manifest">Manifest</h2>

<p>
You must declare the "declarativeWebRequest" permission in the
<a href="manifest.html">extension manifest</a> to use this API,
along with <a href="manifest.html#permissions">host permissions</a> for any
hosts whose network requests you want to access.
</p>

<pre>{
  "name": "My extension",
  ...
<b>  "permissions": [
    "declarativeWebRequest",
    "*://*.google.com"
  ]</b>,
  ...
}</pre>

<h2 id="rules">Rules</h2>

<p>
The Declarative Web Request API follows the concepts of the <a
  href="events.html#declarative">Declarative API</a>. You can register rules to
the <code>chrome.declarativeWebRequest.onRequest</code> event object.
</p>

<p>
The Declarative Web Request API supports a single type of match criteria, the
<code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network
requests if and only if all listed criteria are met. The following
<code>RequestMatcher</code> would match a network request when the user enters
"http://www.example.com" in the URL bar:
</p>

<pre>
var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
  });
</pre>

<p>
Requests to "https://www.example.com" would be rejected by the
<code>RequestMatcher</code> due to the scheme. Also all requests for an embedded
iframe would be rejected due to the <code>resourceType</code>.
</p>

<p class="note">
<strong>Note:</strong> All conditions and actions are created via a constructor
as shown in the example above.
<p>

<p>
In order to cancel all requests to "example.com", you can define a rule as
follows:
</p>
<pre>
var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]};
</pre>

<p>
In order to cancel all requests to "example.com" and "foobar.com", you can add a
second condition, as each condition is sufficient to trigger all specified
actions:
</p>
<pre>
var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]};
</pre>

<p>
Register rules as follows:
</p>
<pre>
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
</pre>

<p class="note">
<strong>Note:</strong> You should always register or unregister rules in bulk rather than
individually because each of these operations recreates internal data
structures.  This re-creation is computationally expensive but facilitates a
very fast URL matching algorithm for hundreds of thousands of URLs.
</p>


<h2 id="evaluation">Evaluation of conditions and actions</h2>

<p>
The Declarative Web Request API follows the
<a href="webRequest.html#life_cycle">Life cycle model for web requests</a> of
the <a href="webRequest.html">Web Request API</a>. This means that conditions
can only be tested at specific stages of a web request and, likewise, actions
can also only be executed at specific stages. The following tables list the
request stages that are compatible with conditions and actions.
</p>

<p>
<table>
  <tr>
    <th colspan="5">Request stages during which condition attributes can be processed.
  </tr>
  <tr>
    <th>Condition attribute
    <th>onBeforeRequest
    <th>onBeforeSendHeaders
    <th>onHeadersReceived
    <th>onAuthRequired
  </tr>
  <tr><td>url<td>✓<td>✓<td>✓<td>✓
  <tr><td>resourceType<td>✓<td>✓<td>✓<td>✓
  <tr><td>contentType<td><td><td>✓<td>
  <tr><td>excludeContentType<td><td><td>✓<td>
  <tr><td>responseHeaders<td><td><td>✓<td>
  <tr><td>excludeResponseHeaders<td><td><td>✓<td>
  <tr>
    <th colspan="5" style="padding-top:2em">Request stages during which actions can be executed.
  </tr>
  <tr>
    <th>Event
    <th>onBeforeRequest
    <th>onBeforeSendHeaders
    <th>onHeadersReceived
    <th>onAuthRequired
  </tr>
  <tr><td>AddRequestCookie<td><td>✓<td><td>
  <tr><td>AddResponseCookie<td><td><td>✓<td>
  <tr><td>AddResponseHeader<td><td><td>✓<td>
  <tr><td>CancelRequest<td>✓<td>✓<td>✓<td>✓
  <tr><td>EditRequestCookie<td><td>✓<td><td>
  <tr><td>EditResponseCookie<td><td><td>✓<td>
  <tr><td>IgnoreRules<td>✓<td>✓<td>✓<td>✓
  <tr><td>RedirectByRegEx<td>✓<td><td><td>
  <tr><td>RedirectRequest<td>✓<td><td><td>
  <tr><td>RedirectToEmptyDocument<td>✓<td><td><td>
  <tr><td>RedirectToTransparentImage<td>✓<td><td><td>
  <tr><td>RemoveRequestCookie<td><td>✓<td><td>
  <tr><td>RemoveRequestHeader<td><td>✓<td><td>
  <tr><td>RemoveResponseCookie<td><td><td>✓<td>
  <tr><td>RemoveResponseHeader<td><td><td>✓<td>
  <tr><td>SetRequestHeader<td><td>✓<td><td>
</table>
</p>

<p>
<strong>Example:</strong> It is possible to combine a
<code>new chrome.declarativeWebRequest.RequestMatcher({contentType: ["image/jpeg"]})</code>
condition with a <code>new chrome.declarativeWebRequest.CancelRequest()</code>
action because both of them can be evaluated in the onHeadersReceived stage.
It is, however, impossible to combine the request matcher with a
<code>new chrome.declarativeWebRequest.RedirectToTransparentImage()</code>
because redirects cannot be executed any more by the time the content
type has been determined.
</p>

<h2 id="precedences">Using priorities to override rules</h2>

<p>
Rules can be associated with priorities as described in the
<a href="events.html#declarative">Events API</a>. This mechanism can be used
to express exceptions. The following example will block all requests to
images named "evil.jpg" except on the server "myserver.com".
</p>

<pre>
var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
</pre>

<p>
It is important to recognize that the <code>IgnoreRules</code> action is not
persisted across <a href="#evaluation">request stages</a>. All conditions of
all rules are evaluated at each stage of a web request. If an
<code>IgnoreRules</code> action is executed, it applies only to other actions
that are executed for the same web request in the same stage.
</p>