この翻訳は不完全です。英語から この記事を翻訳 してください。

拡張された Proxy Auto-Configuration (PAC) file (これはウェブのリクエストをプロキシー化するポリシーを実装します) を実装するのにプロキシー API を使います。この実装は標準の PAC 設計といくつかそれていて、なぜなら PAC ファイルのデファクト仕様は1995年頃の初期実装から変えられてないためです。仕様を維持している標準化団体はありません。

Note that Google Chrome provides an extension API also called "proxy" which is functionally similar to this API, in that extensions can use it to implement a proxying policy. However, the design of the Chrome API is completely different to this API. With Chrome's API an extension can register a PAC file, but can also define explicit proxying rules. Since this is also possible using the extended PAC files, this API only supports the PAC file approach. Because this API is incompatible with the Chrome proxy API, this API is only available through the browser namespace.

To use this API you need to have the "proxy" permission.

PAC ファイルと通信する

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 ファイル仕様

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 objects. Each object has the following properties:

type
String. This must be one of: "http"|"https|"socks4"|"socks"|"direct". "socks" refers to the SOCKS5 protocol.
host
String. Hostname for the proxy to use.
port
String. Port for the proxy.
username Optional
String. Username for the proxy. This is usable with "socks". For HTTP proxy authorizations, use webRequest.onAuthRequired.
password Optional
String. Password for the proxy. This is usable with "socks". For HTTP proxy authorizations, use webRequest.onAuthRequired.
proxyDNS Optional
Boolean. If true, the proxy server is used to resolve certain DNS queries (only usable with "socks4" and "socks"). Defaults to false.
failoverTimeout Optional
Integer. Number of seconds before timing out and trying the next proxy in the array. Defaults to 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 ファイル環境

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);

関数

proxy.register()
Registers the given proxy script.
proxy.unregister()
Unregisters the proxy script.

イベント

proxy.onProxyError
Fired when the system encounters an error running the proxy script.

ブラウザ実装状況

ChromeEdgeFirefoxFirefox for AndroidOpera
onProxyError 無し 無し5555 無し
register 無し 無し

56

55 *

55 無し
unregister 無し 無し5656 無し

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.

ドキュメントのタグと貢献者

 このページの貢献者: Uemmra3
 最終更新者: Uemmra3,