proxy.register()

Registers a Proxy Auto-Configuration (PAC) file. The file is executed immediately, and its FindProxyForURL() function will be called for any HTTP, HTTPS, or FTP requests.

If PAC files are registered by more than one extension, then requests will be passed initially to the one that was registered first.

  • If the FindProxyForURL() function in the first PAC returns "DIRECT" for a request, then the request will be passed unchanged to the FindProxyForURL() function in the next PAC.
  • If the FindProxyForURL() function in the first PAC proxies the request by returning "PROXY" or some other proxying value, then the proxy URL will be passed to the FindProxyForURL() function in the next PAC.

Each extension can only register a single PAC file: if you call register() twice, the second PAC file will replace the first.

This is an asynchronous function that returns a Promise.

Communicating with PAC files

You can exchange messages between the PAC file and your extension's background page (or any other privileged pages, like popup pages) using runtime.sendMessage() and runtime.onMessage.

To send a message to the PAC file, you must set the toProxyScript option:

// background.js

// Log any messages from the proxy.
browser.runtime.onMessage.addListener((message, sender) => {
  if (sender.url === browser.extension.getURL(proxyScriptURL)) {
    console.log(message);
  }
});

let messageToProxy = {
  enabled: true,
  foo: "A string",
  bar: 1234
};

browser.runtime.sendMessage(messageToProxy, {toProxyScript: true});
// pac.js

browser.runtime.onMessage.addListener((message) => {
  if (message.enabled) {
    browser.runtime.sendMessage("I'm enabled!");
  }
});

PAC file specification

The basic PAC file syntax is described in the PAC documentation, but the implementation used by the proxy API differs from standard PAC design in several ways, which are described in this section.

FindProxyForURL() return value

The standard FindProxyForURL() returns a string. In Firefox 55 and 56, the PAC file used with the proxy API also returns a string. In Firefox 55 only, you must pass an argument to the "DIRECT" return value, even though it doesn't need an argument.

From Firefox 57 onwards, FindProxyForURL() may still return a string, but may alternatively (and preferably) return an array of proxy.ProxyInfo objects.

If the array contains more than one object, 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.

For example:

const proxySpecification = [
  {
    type: "socks",
    host: "foo.com",
    port: 1080,
    proxyDNS: true,
    failoverTimeout: 5
  },
  {
    type: "socks",
    host: "bar.com",
    port: 1060,
  }
];

The first proxy in the array will be tried first. If it does not respond in failoverTimeout seconds, the next will be tried, until the end of the array is reached.

PAC file environment

The global helper functions usually available for PAC files (isPlainHostName(), dnsDomainIs(), and so on) are not available.

Code running in the PAC file does not get access to:

//  pac.js

// send the log message to the background script
browser.runtime.sendMessage(`Proxy-blocker: blocked ${url}`);
// background-script.js

function handleMessage(message, sender) {
  // only handle messages from the proxy script
  if (sender.url != browser.extension.getURL(proxyScriptURL)) {
    return;
  }
  console.log(message);
}

browser.runtime.onMessage.addListener(handleMessage);

 

Syntax

var registering = browser.proxy.register(
  url   // string
)

Parameters

url
String. URL pointing to the PAC file to load. PAC files must be bundled with the extension, and url must be relative to the extension's manifest.json file.

Return value

A Promise that will be fulfilled with no arguments when the PAC file has been registered, or rejected if there was an error.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome No support NoEdge No support NoFirefox Full support 56
Full support 56
Full support 55
Alternate Name
Alternate Name Uses the non-standard name: registerProxyScript
Opera No support NoFirefox Android Full support 56
Full support 56
Full support 55
Alternate Name
Alternate Name Uses the non-standard name: registerProxyScript

Legend

Full support  
Full support
No support  
No support
Uses a non-standard name.
Uses a non-standard name.

Examples

const proxyScriptURL = "proxy/proxy-script.js";

browser.proxy.register(proxyScriptURL);

Example extensions

Acknowledgements

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

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