WebRequest.jsm

The WebRequest module is new in Firefox 41.

The WebRequest module provides an API to add event listeners for the various stages of making an HTTP request. The event listener receives detailed information about the request, and can modify or cancel the request.

You can use this API to implement a content policy in an add-on (for example, an ad or script blocker), as you could using nsIContentPolicy. More generally, you can also use this API instead of HTTP request observers. You can use WebRequest.jsm in either the chrome or content processes.

The WebRequest API is modeled on Chrome's webRequest extension API, which makes it easier to write cross-browser add-on code. There are some differences between this API and Chrome's, though: see Chrome incompatibilities for the details.

Usage

To import WebRequest, use code like:

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});

The WebRequest object has the following properties, each of which corresponds to a specific stage in executing a web request:

Each of these objects defines two functions:

  • addListener(callback, filter, opt_extraInfoSpec)
  • removeListener(callback)

Adding listeners

Use addListener to add a listener to a particular event. It takes one mandatory argument and two optional arguments, as detailed below.

Name Type Description
callback Function

The callback argument is a function to be called when the event is triggered.

It's passed an object whose structure will vary depending on the event you're listening to: see the event-specific documentation for details.

filter Object The optional filter argument is used to restrict the requests for which the listener callback will be invoked. See Filtering.
opt_extraInfoSpec Array of String

The optional opt_extraInfoSpec argument lets you pass extra instructions for the handling of events.

The instructions you can pass here vary depending on the event you're listening to: see the event-specific documentation for details.

In particular, "blocking" may be passed to several event types, and will make the event dispatch synchronous, so the browser will wait for the event listener to return before continuing with the request. This then enables the event listener to modify or cancel the request. See Modifying & canceling requests.

Some examples of using addListener().

To remove a listener for an event, call removeListener on the event in question, passing it the listener to remove.

Filtering

The filter argument is the second argument to addListener(). If you don't pass filter, then the listener is invoked for every web request the browser makes that triggers that particular event.

filter is an object that may contain up to two properties: urls and types.

Name Type Description
urls MatchPattern Only invoke the listener for URLs that match one of the patterns.
types Array of Strings. An array of resource types. Only invoke the listener for resource types that match one of the types given.

To specify match patterns, first import the "MatchPattern.jsm" module, then construct a MatchPattern. The MatchPattern constructor accepts:

  • either: a string defining a single pattern
  • or: an array of such strings
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("https:/developer.mozilla.org/*");
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern(["https://mozorg.cdn.mozilla.net/*",
                                "https://mdn.mozillademos.org/*",
                                "https://developer.cdn.mozilla.net/*"]);

See the match patterns article for details on the syntax of the strings you supply. If you supply an array of strings, then a URL matches if it matches any of the strings.

See some examples of using filter.

Modifying & canceling requests

You can use the WebRequest API to modify and cancel network requests. What exactly you're able to do to a network request depends on the stage at which you have intercepted the request: that is, the WebRequest event that your listener is attached to. For example, it obviously doesn't make sense to cancel a network request after it has completed.

The general approach to modifying and canceling requests is this:

  • first, pass an array containing the string "blocking" as the third argument to your addListener() call. This tells the browser to wait for your event listener to return before continuing with the request.
  • next, return an object from the listener that contains instructions for what the browser should do with this request.

There are four things you can do with a request:

  • cancel it
  • redirect it
  • modify request headers
  • modify response headers.

To perform one of these operations, include a property with the appropriate name in the object returned from the listener, and assign it the desired value, as detailed in the table below:

Operation Available in Return property
Cancel onBeforeRequest

cancel

Boolean value set to true. See some examples of canceling requests.

Redirect onBeforeSendHeaders

redirectUrl

String set to the URL to redirect the request to. See some examples of redirection.

Modify request headers onBeforeSendHeaders

requestHeaders

Array of HTTP headers.

Modify response headers onHeadersReceived

responseHeaders

Array of HTTP headers.

See some examples of canceling, redirecting, and modifying request headers.

Events

The events exported by WebRequest.jsm are triggered at the various stages of making a request.

This section describes the stage corresponding to each event. It also documents two data structures that vary from one event to another:

  • the opt_extraInfoSpec argument to addListener()
  • the properties of the argument passed to the listener.

onBeforeRequest

This event is triggered when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel the request.

opt_extraInfoSpec values

Name Description
"blocking" Make the browser wait until the listener returns. Use this if you want to cancel the request. See some examples of canceling requests.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.

onBeforeSendHeaders

This event is triggered before sending any HTTP data, but after all HTTP headers are available. This is a good place to listen if you want to modify HTTP headers.

opt_extraInfoSpec values

Name Description
"blocking" Make the browser wait until the listener returns. Use this if you want to redirect the request or modify request headers. See examples of redirecting and modifying request headers.
"requestHeaders" Include request headers in the argument passed to the listener. See Modifying headers for an example using this.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.
method String The HTTP method to be used (GET, POST, etc).
requestHeaders Array of HTTP headers.

The HTTP request headers that will be sent.

This is only included if you set "requestHeaders" in the opt_extraInfoSpec argument.

onSendHeaders

Triggered just before sending headers. If you modified headers in onBeforeSendHeaders, you'll see the modified version here. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Name Description
"requestHeaders" Include request headers in the argument passed to the listener.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.
method String The HTTP method to be used (GET, POST, etc).
requestHeaders Array of HTTP headers.

The HTTP request headers that will be sent.

This is only included if you set "requestHeaders" in the opt_extraInfoSpec argument.

onHeadersReceived

Triggered once response headers have been received. You can use this event to modify HTTP response headers.

opt_extraInfoSpec values

Name Description
"blocking" Make the browser wait until the listener returns. Use this if you want to modify response headers. See Modifying and canceling requests.
"responseHeaders" Include response headers in the argument passed to the listener.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.
method String The HTTP method to be used (GET, POST, etc).
responseHeaders Array of HTTP headers.

The HTTP response headers that were received.

This is only included if you set "responseHeaders" in the opt_extraInfoSpec argument.

statusCode Number HTTP response code.

onResponseStarted

Triggered once the browser has started to receive the response body. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Name Description
"responseHeaders" Include response headers in the argument passed to the listener.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.
method String The HTTP method used (GET, POST, etc).
responseHeaders Array of HTTP headers.

The HTTP response headers that were received.

This is only included if you set "responseHeaders" in the opt_extraInfoSpec argument.

statusCode Number HTTP response code.

onCompleted

Triggered when the response has been received. Note that you can't pass "blocking" for this event, so you can't modify or cancel the request from this event: it's informational only.

opt_extraInfoSpec values

Name Description
"responseHeaders" Include response headers in the argument passed to the listener.

Listener argument

Name Type Description
url String Target of the request.
windowId Number The ID of the window making the request, as an outerWindowID.
parentWindowId Number
type String The resource type.
browser Object The XUL browser into which the resource will be loaded, or null if the resource will not be loaded into a XUL browser.
method String The HTTP method used (GET, POST, etc).
responseHeaders Array of HTTP headers.

The HTTP response headers that were received.

This is only included if you set "responseHeaders" in the opt_extraInfoSpec argument.

statusCode Number HTTP response code.

Types

Resource types

The resource type string identifies the kind of resource being fetched. It's used in two places: filtering requests by type, and as the type property of the argument passed to the listener.

The following types are supported:

"main_frame"
"sub_frame"
"stylesheet"
"script"
"image"
"object"
"xmlhttprequest"

HTTP headers

HTTPs headers are represented as objects with two properties, name and value:

Name Type Description
name String Header name, for example "Content-Type"
value String Header value, for example "image/png"

Chrome incompatibilities

Although this API is modeled on Chrome's webRequest extension API, there are some differences. We're working on addressing them, though.

  • filtering by windowId and tabId is not supported.
  • the onAuthRequired, onBeforeRedirect, and onErrorOccurred events are not supported.
  • the "requestBody" instruction in opt_extraInfoSpec is not supported.
  • redirection is not allowed in onBeforeRequest or onHeadersReceived, but is allowed in onBeforeSendHeaders. See bug 1176092.
  • handlerBehaviorChanged() is not supported.
  • requestId is not included in the argument passed to the listener.

Examples

Basic examples

This example just logs the URL for every request initiated:

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});

WebRequest.onBeforeRequest.addListener(logURL);

function logURL(e) {
  console.log("Loading: " + e.url);
}

Filtering

This example logs URLs for requests under "https://developer.mozilla.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("https:/developer.mozilla.org/*");


WebRequest.onBeforeRequest.addListener(logURL, {urls: pattern});

function logURL(e) {
  console.log("Loading: " + e.url);
}

This listener will be invoked for requests matching any of the three patterns, where the resource type is "stylesheet" or "image":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern(["https://mozorg.cdn.mozilla.net/*",
                                "https://mdn.mozillademos.org/*",
                                "https://developer.cdn.mozilla.net/*"]);

WebRequest.onBeforeRequest.addListener(listener, {
                                         urls: pattern,
                                         types: ["image", "stylesheet"]
                                       });

function listener(e) {
  console.log("Matched: " + e.url);
}

Canceling

This example cancels requests to load content from "http://example.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("http://example.org/*");

WebRequest.onBeforeRequest.addListener(cancelRequest,
                                       {urls: pattern},
                                       ["blocking"]);

function cancelRequest(e) {
  console.log("Canceling: " + e.url);
  return {cancel: true};
}

This code cancels requests for images that are made to URLs under "https://mdn.mozillademos.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("https://mdn.mozillademos.org/*");

WebRequest.onBeforeRequest.addListener(cancelImages,
                                       {
                                         urls: pattern,
                                         types: ["image"]
                                       },
                                       ["blocking"]);

function cancelImages(e) {
  console.log("Canceling: " + e.url);
  return {cancel: true};
}

Redirecting

This code replaces, by redirection, all network requests for images that are made to URLs under "https://mdn.mozillademos.org/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("https://mdn.mozillademos.org/*");

WebRequest.onBeforeSendHeaders.addListener(redirect,
                                           {
                                             urls: pattern,
                                             types: ["image"]
                                           },
                                           ["blocking"]);

function redirect(e) {
  console.log("Redirecting: " + e.url);
  return {redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif"}; }

Modifying headers

This code changes the User Agent header so the browser identifies itself as IE 11, but only when visiting pages under "http://useragentstring.com/":

let {WebRequest} = Cu.import("resource://gre/modules/WebRequest.jsm", {});
Cu.import("resource://gre/modules/MatchPattern.jsm");

let pattern = new MatchPattern("http://useragentstring.com/*");

let ua = "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko";

WebRequest.onBeforeSendHeaders.addListener(changeUserAgent,
                                           {
                                             urls: pattern
                                           },
                                           ["blocking", "requestHeaders"]);

function changeUserAgent(e) {
  for (let header of e.requestHeaders) {
    if (header.name == "User-Agent") {
      header.value = ua;
    }
  }
  return {requestHeaders: e.requestHeaders};
}