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

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

Google Chrome では 同じく"proxy"という拡張機能API が提供されていて、その機能はこの API と似ていて、拡張機能はプロキシポリシーを使うことができます。しかし、Chrome API の設計はこの API とまったく違います。Chrome の API では拡張機能は PAC ファイルを定義できて、明示的なプロキシルールも定義できます。このため拡張機能 PAC ファイルも使用できて、この API は PAC ファイルアプローチのみをサポートします。この API は Chrome proxy API と互換性がないため、この API は browser 名前空間のみで利用できます。

この API を使うには、"proxy" パーミッションが必要です。

PAC ファイルと通信する

PAC ファイルと拡張機能のバックグラウンドページ(やその他の権限つきページ、ポップアップページのようなもの)とでメッセージを交換できて、その手段は runtime.sendMessage()runtime.onMessage

PAC ファイルにメッセージを送るには、toProxyScript オプションをセットしなければなりません:

// 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.

例えば、:

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()
所与のプロキシスクリプトを登録する
proxy.unregister()
プロキシスクリプトの登録を取り消す。

イベント

proxy.onProxyError
プロキシスクリプト実行している際にシステムがエラーに遭遇した時に発火します。

ブラウザ実装状況

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxOperaAndroid 版 Firefox
onErrorChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 60
完全対応 60
完全対応 55
代替名
代替名 非標準の名前 onProxyError を使用しています。
Opera 未対応 なしFirefox Android 完全対応 60
完全対応 60
完全対応 55
代替名
代替名 非標準の名前 onProxyError を使用しています。
onRequestChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 60Opera 未対応 なしFirefox Android 完全対応 60
ProxyInfoChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 60Opera 未対応 なしFirefox Android 完全対応 60
RequestDetailsChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 60Opera 未対応 なしFirefox Android 完全対応 60
registerChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 56
完全対応 56
完全対応 55
代替名
代替名 非標準の名前 registerProxyScript を使用しています。
Opera 未対応 なしFirefox Android 完全対応 56
完全対応 56
完全対応 55
代替名
代替名 非標準の名前 registerProxyScript を使用しています。
settingsChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 60
補足
完全対応 60
補足
補足 In version 59, this property was listed as proxyConfig in the browserSettings namespace, but had a bug that made it mostly unusable.
Opera 未対応 なしFirefox Android 未対応 なし
unregisterChrome 未対応 なしEdge 未対応 なしFirefox 完全対応 56Opera 未対応 なしFirefox Android 完全対応 56

凡例

完全対応  
完全対応
未対応  
未対応
実装ノートを参照してください。
実装ノートを参照してください。
非標準の名前を使用しています。
非標準の名前を使用しています。

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,