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 modeled on the events defined in the webRequest API. Like those events, its addListener() function takes three arguments:
- the listener that is called when the event is fired.
- a
RequestFilterobject controlling which requests cause the event to fire. - 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 proxy.ProxyInfo objects, enabling the browser to fail over if a proxy is unreachable). By default, the request fails over to any browser-defined proxy unless a null object or an array ending in a null object is returned.
To use proxy.onRequest, an extension must have the "proxy" API permission and the host permission for the URLs of the requests that it intercepts, which means 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)-
Stops listening to this event. The
listenerargument is the listener to remove. hasListener(listener)-
Checks whether
listeneris registered for this event. Returnstrueif it is listening,falseotherwise.
addListener syntax
Parameters
listener-
The function called when this event occurs. The function is passed one argument, which is a
proxy.RequestDetailsobject containing details of the request.The listener can return any of:
- a
proxy.ProxyInfoobject. - an array of
proxy.ProxyInfoobjects. - a
Promisethat resolves to aProxyInfoobject. - a
Promisethat resolves to an array ofProxyInfoobjects.
When the listener returns an array or a Promise that resolves to an array, the
ProxyInfoobjects after the first one represent failovers. If the proxy at position N in the array is not reachable when itsProxyInfo.failoverTimeoutexpires, the browser tries the proxy at position N+1.By default, the request fails over to any browser-defined proxy unless a
nullobject or an array ending in anullobject ([{ ... proxy info ...} , null]) is returned.If there is an error specifying the
proxy.ProxyInfoobjects, thenproxy.onErroris called. - a
filter-
webRequest.RequestFilter. A set of filters that restricts the events sent to the listener. extraInfoSpecOptional-
arrayofstring. Extra options for the event. Pass"requestHeaders"to include the request headers in thedetailsobject 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
Browser compatibility
Loading…