browser.proxy

Описание

Разрешения

Чтобы использовать API настроек прокси-сервера, необходимо объявить разрешение "proxy" в манифесте расширения. Пример:

{
  "name": "My extension",
  ...
  "permissions": [
    "proxy"
  ],
  ...
}

Основные понятия и использование

Настройки прокси-сервера задаются в объекте proxy.ProxyConfig. В зависимости от настроек прокси-сервера Chrome в настройках может быть указан proxy.ProxyRules или proxy.PacScript.

Режимы прокси-сервера

Атрибут mode объекта ProxyConfig определяет общее поведение Chrome в отношении использования прокси-сервера. Возможные значения:

direct

В режиме direct все подключения создаются напрямую, без использования прокси-сервера. В этом режиме в объекте ProxyConfig нельзя использовать другие параметры.

auto_detect

В режиме auto_detect конфигурация прокси-сервера определяется скриптом PAC, который можно скачать по адресу http://wpad/wpad.dat. В этом режиме в объекте ProxyConfig нельзя использовать другие параметры.

pac_script

В режиме pac_script конфигурация прокси-сервера определяется PAC-скриптом, который извлекается из URL, указанного в объекте proxy.PacScript, или берется непосредственно из элемента data, указанного в объекте proxy.PacScript. Кроме того, в этом режиме в объекте ProxyConfig нельзя использовать другие параметры.

fixed_servers

В режиме fixed_servers конфигурация прокси-сервера кодируется в объекте proxy.ProxyRules. Его структура описана в разделе Правила прокси-сервера. Кроме того, в режиме fixed_servers в объекте ProxyConfig нельзя использовать другие параметры.

system

В режиме system конфигурация прокси-сервера берется из операционной системы. В этом режиме в объекте ProxyConfig нельзя использовать другие параметры. Обратите внимание, что режим system отличается от отсутствия конфигурации прокси-сервера. В последнем случае Chrome возвращается к системным настройкам, только если на конфигурацию прокси-сервера не влияют параметры командной строки.

Правила прокси-сервера

Объект proxy.ProxyRules может содержать атрибут singleProxy или подмножество атрибутов proxyForHttp, proxyForHttps, proxyForFtp и fallbackProxy.

В первом случае трафик HTTP, HTTPS и FTP передается через указанный прокси-сервер. Остальной трафик отправляется напрямую. В последнем случае поведение немного отличается: если для протокола HTTP, HTTPS или FTP настроен прокси-сервер, соответствующий трафик будет перенаправляться через указанный сервер. Если прокси-сервер не указан или трафик использует протокол, отличный от HTTP, HTTPS или FTP, используется fallbackProxy. Если формат (fallbackProxy) не задан, трафик отправляется напрямую без прокси-сервера.

Объекты прокси-сервера

Прокси-сервер настраивается в объекте proxy.ProxyServer. Подключение к прокси-серверу (определенному атрибутом host) использует протокол, заданный в атрибуте scheme. Если значение scheme не указано, по умолчанию используется http.

Если в объекте proxy.ProxyServer не определен параметр port, порт определяется на основе схемы. Порты по умолчанию:

Список обхода

Отдельные серверы можно исключить из прокси-сервера с помощью bypassList. В этом списке могут быть следующие записи:

[SCHEME://]HOST_PATTERN[:PORT]

Соответствует всем именам хостов, которые соответствуют шаблону HOST_PATTERN. Ведущий символ "." интерпретируется как "*.".

Примеры: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

Шаблон	Соответствует	Не соответствует
".foobar.com"	"www.foobar.com"	"foobar.com"
"*.foobar.com"	"www.foobar.com"	"foobar.com"
"foobar.com"	"foobar.com"	"www.foobar.com"
"*foobar.com"	"foobar.com", "www.foobar.com", "foofoobar.com"

[SCHEME://]IP_LITERAL[:PORT]

Сопоставлять URL, которые являются IP-адресами. По сути, это тот же случай, что и первый, но с особыми условиями для канонизации IP-адресов. Например, сопоставление с "[0:0:0::1]" аналогично сопоставлению с "[::1]", поскольку канонизация IPv6 выполняется внутри системы.

Примеры: 127.0.1, [0:0::1], [::1]:80, https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Поиск любого URL, содержащего IP-адрес (IP_LITERAL) в заданном диапазоне. Диапазон IP-адресов (PREFIX_LENGTH_IN_BITS) указывается в нотации CIDR.

Соответствует любому URL, содержащему IP-адрес в заданном диапазоне. Диапазон IP-адресов указывается в нотации CIDR. Примеры: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Строка <local> соответствует простым именам хостов. Простое имя хоста не содержит точек и не является IP-адресом. Например, example и localhost – простые имена хостов, а example.com, example. и [::1] – нет.

Пример: "<local>"

Примеры

В следующем коде для HTTP-подключений ко всем серверам, кроме foobar.com, задается прокси-сервер SOCKS 5, а для всех остальных протоколов используются прямые подключения. Настройки применяются к обычным окнам и окнам инкогнито, поскольку окна инкогнито наследуют настройки обычных окон. Также ознакомьтесь с документацией по Types API.

var config = {
  mode: "fixed_servers",
  rules: {
    proxyForHttp: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
browser.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

В приведенном ниже коде задан пользовательский PAC-скрипт.

var config = {
  mode: "pac_script",
  pacScript: {
    data: "function FindProxyForURL(url, host) {\n" +
          "  if (host == 'foobar.com')\n" +
          "    return 'PROXY blackhole:80';\n" +
          "  return 'DIRECT';\n" +
          "}"
  }
};
browser.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

В следующем фрагменте кода запрашиваются текущие действующие настройки прокси-сервера. Действующие настройки прокси-сервера могут быть заданы другим расширением или правилом. Подробная информация приведена в документации по Types API.

browser.proxy.settings.get(
  {'incognito': false},
  function(config) {
    console.log(JSON.stringify(config));
  }
);

Обратите внимание, что объект value, переданный в set(), не идентичен объекту value, переданному в функцию обратного вызова get(). Последний будет содержать элемент rules.proxyForHttp.port.

chrome.proxy.onProxyError.addListener(
  callback: function,
)