chrome.declarativeWebRequest

Description:

Note: this API is currently on hold, without concrete plans to move to stable. Use the chrome.declarativeWebRequest API to intercept, block, or modify requests in-flight. It is significantly faster than the chrome.webRequest API because you can register rules that are evaluated in the browser rather than the JavaScript engine with reduces roundtrip latencies and allows higher efficiency.

Note that certain types of non-sensitive actions do not require host
permissions:

CancelRequest

IgnoreRules

RedirectToEmptyDocument

RedirectToTransparentImage

The SendMessageToExtension action requires host permissions
for any hosts whose network requests you want to trigger a message.

All other actions require host permissions to all URLs.

As an example, if "*://*.google.com/*" is the only host permission
an extension has, than such an extension may set up a rule to

cancel a request to "http://www.google.com" or "http://anything.else.com"

send a message when navigating to "http://www.google.com" but not to
"http://something.else.com"

The extension cannot set up a rule to redirect "http://www.google.com" to
"http://mail.google.com".

Rules

The Declarative Web Request API follows the concepts of the Declarative API. You can register rules to
the chrome.declarativeWebRequest.onRequest event object.

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

Note: 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. The
Performance section of the
Events API provides further performance tips.

Evaluation of conditions and actions

The Declarative Web Request API follows the
Life cycle model for web requests of
the Web Request API. 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.

Request stages during which condition attributes can be processed.

Condition attribute

onBeforeRequest

onBeforeSendHeaders

onHeadersReceived

onAuthRequired

url

✓

✓

✓

✓

resourceType

✓

✓

✓

✓

contentType

✓

excludeContentType

✓

responseHeaders

✓

excludeResponseHeaders

✓

requestHeaders

✓

excludeRequestHeaders

✓

thirdPartyForCookies

✓

✓

✓

✓

Request stages during which actions can be executed.

Event

onBeforeRequest

onBeforeSendHeaders

onHeadersReceived

onAuthRequired

AddRequestCookie

✓

AddResponseCookie

✓

AddResponseHeader

✓

CancelRequest

✓

✓

✓

✓

EditRequestCookie

✓

EditResponseCookie

✓

IgnoreRules

✓

✓

✓

✓

RedirectByRegEx

✓

✓

RedirectRequest

✓

✓

RedirectToEmptyDocument

✓

✓

RedirectToTransparentImage

✓

✓

RemoveRequestCookie

✓

RemoveRequestHeader

✓

RemoveResponseCookie

✓

RemoveResponseHeader

✓

SendMessageToExtension

✓

✓

✓

✓

SetRequestHeader

✓

Note: Applicable stages can be further constrained by using the
"stages" attribute.

Note: Redirects initiated by a redirect action use the original
request method for the redirect, with one exception: If the redirect is
initiated at the onHeadersReceived stage, then the redirect will be issued using
the GET method.

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

Using priorities to override rules

Rules can be associated with priorities as described in the
Events API. 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".

It is important to recognize that the IgnoreRules action is not
persisted across request stages. All conditions of
all rules are evaluated at each stage of a web request. If an
IgnoreRules action is executed, it applies only to other actions
that are executed for the same web request in the same stage.

Types

Stage

HeaderFilter

Filters request headers for various criteria. Multiple criteria are evaluated as a conjunction.

properties

string

(optional)
namePrefix

Matches if the header name starts with the specified string.

string

(optional)
nameSuffix

Matches if the header name ends with the specified string.

array of string or string

(optional)
nameContains

Matches if the header name contains all of the specified strings.

string

(optional)
nameEquals

Matches if the header name is equal to the specified string.

string

(optional)
valuePrefix

Matches if the header value starts with the specified string.

string

(optional)
valueSuffix

Matches if the header value ends with the specified string.

array of string or string

(optional)
valueContains

Matches if the header value contains all of the specified strings.

string

(optional)
valueEquals

Matches if the header value is equal to the specified string.

RequestMatcher

Matches network events by various criteria.

properties

object

(optional)
url

Matches if the conditions of the UrlFilter are fulfilled for the URL of the request.

string

(optional)
hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string

(optional)
hostEquals

Matches if the host name of the URL is equal to a specified string.

string

(optional)
hostPrefix

Matches if the host name of the URL starts with a specified string.

string

(optional)
hostSuffix

Matches if the host name of the URL ends with a specified string.

string

(optional)
pathContains

Matches if the path segment of the URL contains a specified string.

string

(optional)
pathEquals

Matches if the path segment of the URL is equal to a specified string.

string

(optional)
pathPrefix

Matches if the path segment of the URL starts with a specified string.

string

(optional)
pathSuffix

Matches if the path segment of the URL ends with a specified string.

string

(optional)
queryContains

Matches if the query segment of the URL contains a specified string.

string

(optional)
queryEquals

Matches if the query segment of the URL is equal to a specified string.

string

(optional)
queryPrefix

Matches if the query segment of the URL starts with a specified string.

string

(optional)
querySuffix

Matches if the query segment of the URL ends with a specified string.

string

(optional)
urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string

(optional)
schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer

(optional)
ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

object

(optional)
firstPartyForCookiesUrl

Matches if the conditions of the UrlFilter are fulfilled for the 'first party' URL of the request. The 'first party' URL of a request, when present, can be different from the request's target URL, and describes what is considered 'first party' for the sake of third-party checks for cookies.

string

(optional)
hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string

(optional)
hostEquals

Matches if the host name of the URL is equal to a specified string.

string

(optional)
hostPrefix

Matches if the host name of the URL starts with a specified string.

string

(optional)
hostSuffix

Matches if the host name of the URL ends with a specified string.

string

(optional)
pathContains

Matches if the path segment of the URL contains a specified string.

string

(optional)
pathEquals

Matches if the path segment of the URL is equal to a specified string.

string

(optional)
pathPrefix

Matches if the path segment of the URL starts with a specified string.

string

(optional)
pathSuffix

Matches if the path segment of the URL ends with a specified string.

string

(optional)
queryContains

Matches if the query segment of the URL contains a specified string.

string

(optional)
queryEquals

Matches if the query segment of the URL is equal to a specified string.

string

(optional)
queryPrefix

Matches if the query segment of the URL starts with a specified string.

string

(optional)
querySuffix

Matches if the query segment of the URL ends with a specified string.

string

(optional)
urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string

(optional)
schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer

(optional)
ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

Contains a list of strings describing stages. Allowed values are 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'. If this attribute is present, then it limits the applicable stages to those listed. Note that the whole condition is only applicable in stages compatible with all attributes.

CancelRequest

Declarative event action that cancels a network request.

RedirectRequest

Declarative event action that redirects a network request.

properties

string

redirectUrl

Destination to where the request is redirected.

RedirectToTransparentImage

Declarative event action that redirects a network request to a transparent image.

RedirectToEmptyDocument

Declarative event action that redirects a network request to an empty document.

RedirectByRegEx

Redirects a request by applying a regular expression on the URL. The regular expressions use the RE2 syntax.

properties

string

from

A match pattern that may contain capture groups. Capture groups are referenced in the Perl syntax ($1, $2, ...) instead of the RE2 syntax (\1, \2, ...) in order to be closer to JavaScript Regular Expressions.

string

to

Destination pattern.

SetRequestHeader

Sets the request header of the specified name to the specified value. If a header with the specified name did not exist before, a new one is created. Header name comparison is always case-insensitive. Each request header name occurs only once in each request.

properties

string

name

HTTP request header name.

string

value

HTTP request header value.

RemoveRequestHeader

Removes the request header of the specified name. Do not use SetRequestHeader and RemoveRequestHeader with the same header name on the same request. Each request header name occurs only once in each request.

properties

string

name

HTTP request header name (case-insensitive).

AddResponseHeader

Adds the response header to the response of this web request. As multiple response headers may share the same name, you need to first remove and then add a new response header in order to replace one.

properties

string

name

HTTP response header name.

string

value

HTTP response header value.

RemoveResponseHeader

Removes all response headers of the specified names and values.

properties

string

name

HTTP request header name (case-insensitive).

string

(optional)
value

HTTP request header value (case-insensitive).

IgnoreRules

Masks all rules that match the specified criteria.

properties

integer

(optional)
lowerPriorityThan

If set, rules with a lower priority than the specified value are ignored. This boundary is not persisted, it affects only rules and their actions of the same network request stage.

string

(optional)
hasTag

If set, rules with the specified tag are ignored. This ignoring is not persisted, it affects only rules and their actions of the same network request stage. Note that rules are executed in descending order of their priorities. This action affects rules of lower priority than the current rule. Rules with the same priority may or may not be ignored.

SendMessageToExtension

The value that will be passed in the message attribute of the dictionary that is passed to the event handler.

RequestCookie

A filter or specification of a cookie in HTTP Requests.

properties

string

(optional)
name

Name of a cookie.

string

(optional)
value

Value of a cookie, may be padded in double-quotes.

ResponseCookie

A specification of a cookie in HTTP Responses.

properties

string

(optional)
name

Name of a cookie.

string

(optional)
value

Value of a cookie, may be padded in double-quotes.

string

(optional)
expires

Value of the Expires cookie attribute.

double

(optional)
maxAge

Value of the Max-Age cookie attribute

string

(optional)
domain

Value of the Domain cookie attribute.

string

(optional)
path

Value of the Path cookie attribute.

string

(optional)
secure

Existence of the Secure cookie attribute.

string

(optional)
httpOnly

Existence of the HttpOnly cookie attribute.

FilterResponseCookie

A filter of a cookie in HTTP Responses.

properties

string

(optional)
name

Name of a cookie.

string

(optional)
value

Value of a cookie, may be padded in double-quotes.

string

(optional)
expires

Value of the Expires cookie attribute.

double

(optional)
maxAge

Value of the Max-Age cookie attribute

string

(optional)
domain

Value of the Domain cookie attribute.

string

(optional)
path

Value of the Path cookie attribute.

string

(optional)
secure

Existence of the Secure cookie attribute.

string

(optional)
httpOnly

Existence of the HttpOnly cookie attribute.

integer

(optional)
ageUpperBound

Inclusive upper bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is in the interval [now, now + ageUpperBound] fulfill this criterion. Session cookies and cookies whose expiration date-time is in the past do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime.

integer

(optional)
ageLowerBound

Inclusive lower bound on the cookie lifetime (specified in seconds after current time). Only cookies whose expiration date-time is set to 'now + ageLowerBound' or later fulfill this criterion. Session cookies do not meet the criterion of this filter. The cookie lifetime is calculated from either 'max-age' or 'expires' cookie attributes. If both are specified, 'max-age' is used to calculate the cookie lifetime.

boolean

(optional)
sessionCookie

Filters session cookies. Session cookies have no lifetime specified in any of 'max-age' or 'expires' attributes.

AddRequestCookie

Adds a cookie to the request or overrides a cookie, in case another cookie of the same name exists already. Note that it is preferred to use the Cookies API because this is computationally less expensive.

AddResponseCookie

Adds a cookie to the response or overrides a cookie, in case another cookie of the same name exists already. Note that it is preferred to use the Cookies API because this is computationally less expensive.

The stage of the network request during which the event was triggered.

string

requestId

The ID of the request. Request IDs are unique within a browser session. As a result, they could be used to relate different events of the same request.

string

url

string

method

Standard HTTP method.

integer

frameId

The value 0 indicates that the request happens in the main frame; a positive value indicates the ID of a subframe in which the request happens. If the document of a (sub-)frame is loaded (type is main_frame or sub_frame), frameId indicates the ID of this frame, not the ID of the outer frame. Frame IDs are unique within a tab.

integer

parentFrameId

ID of frame that wraps the frame which sent the request. Set to -1 if no parent frame exists.

integer

tabId

The ID of the tab in which the request takes place. Set to -1 if the request isn't related to a tab.