proxy.onRequest

Fired when a web request is about to be made, to give the extension an opportunity to proxy it.

This event is closely modelled on the events defined in the webRequest API. Like those events, its addListener() function takes three arguments:

  • the listener which will be called when the event is fired.
  • a RequestFilter object controlling which requests cause the event to be fired.
  • an array of strings to control other aspects of the event's behavior.

The event is fired before any of the webRequest events for the same request.

When the event is fired, the listener is called with an object containing information about the request. The listener returns a proxy.ProxyInfo object representing a proxy to use (or an array of such objects, enabling the browser to fail over if a proxy is unreachable).

To use proxy.onRequest, an extension must have the "proxy" API permission, and also  the host permission for the URLs of the requests that it intercepts - this means essentially that the match patterns in the filter argument must be a subset of the extension's host permissions.

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)
Stop listening to this event. The listener argument is the listener to remove.
hasListener(listener)
Check whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

listener

Function that will be called when this event occurs. The function will be passed a single argument, which is a proxy.RequestDetails object containing details of the request.

The listener can return any one 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.

If the listener returns an array, or a Promise that resolves to an array, then all 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, then the browser will try the proxy at position N+1.

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

filter
webRequest.RequestFilter. A set of filters that restricts the events that will be sent to this listener.
extraInfoSpecOptional
array of string. Extra options for the event. You can pass a single value, "requestHeaders", to include the request headers in the details object passed to the listener.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome No support NoEdge No support NoFirefox Full support 60Opera No support NoFirefox Android Full support 60

Legend

Full support  
Full support
No support  
No support

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>"]});

Document Tags and Contributors

Contributors to this page: wbamberg
Last updated by: wbamberg,