proxy.onRequest

Syntax

browser.proxy.onRequest.addListener(
  listener,             //  function
  filter,               //  object
  extraInfoSpec         //  optional array of strings
)
browser.proxy.onRequest.removeListener(listener)
browser.proxy.onRequest.hasListener(listener)

Events have three functions:

addListener(listener, filter, extraInfoSpec)

Adds a listener to this event.

removeListener(listener)

Stops listening to this event. The listener argument is the listener to remove.

hasListener(listener)

Checks whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

listener

The function called when this event occurs. The function is passed one argument, which is a proxy.RequestDetails object containing details of the request.

The listener can return any of:

• a proxy.ProxyInfo object.
• an array of proxy.ProxyInfo objects.
• a Promise that resolves to a ProxyInfo object.
• a Promise that resolves to an array of ProxyInfo objects.

When the listener returns an array or a Promise that resolves to an array, the ProxyInfo objects after the first one represent failovers. If the proxy at position N in the array is not reachable when its ProxyInfo.failoverTimeout expires, the browser tries the proxy at position N+1.

By default, the request fails over to any browser-defined proxy unless a null object or an array ending in a null object ([{ ... proxy info ...} , null]) is returned.

If there is an error specifying the proxy.ProxyInfo objects, then proxy.onError is called.

filter

webRequest.RequestFilter. A set of filters that restricts the events sent to the listener.

extraInfoSpec Optional

array of string. Extra options for the event. Pass "requestHeaders" to include the request headers in the details object passed to the listener.

Examples

This code intercepts requests to <all_urls>, and proxies them if they are not for a top-level frame.

function shouldProxyRequest(requestInfo) {
  return requestInfo.parentFrameId !== -1;
}

function handleProxyRequest(requestInfo) {
  if (shouldProxyRequest(requestInfo)) {
    console.log(`Proxying: ${requestInfo.url}`);
    return { type: "http", host: "127.0.0.1", port: 65535 };
  }
  return { type: "direct" };
}

browser.proxy.onRequest.addListener(handleProxyRequest, {
  urls: ["<all_urls>"],
});

Example extensions

• proxy-blocker

Browser compatibility