chrome.declarativeNetRequest

Descrição

Permissões

As permissões "declarativeNetRequest" e "declarativeNetRequestWithHostAccess" oferecem os mesmos recursos. A diferença entre eles é quando as permissões são solicitadas ou concedidas.

"declarativeNetRequest"

Aciona um aviso de permissão no momento da instalação, mas fornece acesso implícito às regras allow, allowAllRequests e block. Use essa opção sempre que possível para evitar pedir acesso total aos organizadores.

"declarativeNetRequestFeedback"

Ativa recursos de depuração para extensões descompactadas, especificamente getMatchedRules() e onRuleMatchedDebug.

"declarativeNetRequestWithHostAccess"

Um aviso de permissão não é mostrado no momento da instalação, mas você precisa solicitar permissões de host antes de realizar qualquer ação em um host. Isso é adequado quando você quer usar regras declarativas de solicitação de rede em uma extensão que já tem permissões de host sem gerar avisos adicionais.

Disponibilidade

Manifesto

Além das permissões descritas anteriormente, alguns tipos de conjuntos de regras, especificamente os estáticos, exigem a declaração da chave de manifesto "declarative_net_request", que precisa ser um dicionário com uma única chave chamada "rule_resources". Essa chave é uma matriz que contém dicionários do tipo Ruleset, conforme mostrado abaixo. O nome "Ruleset" não aparece no JSON do manifesto porque é apenas uma matriz. Os conjuntos de regras estáticos são explicados mais adiante neste documento.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Regras e conjuntos de regras

Para usar essa API, especifique um ou mais conjuntos de regras. Um conjunto de regras contém uma matriz de regras. Uma única regra faz uma das seguintes ações:

• Bloqueie uma solicitação de rede.
• Faça upgrade do esquema (http para https).
• Impedir que uma solicitação seja bloqueada negando todas as regras bloqueadas correspondentes.
• Redirecionar uma solicitação de rede.
• Modificar cabeçalhos de solicitação ou resposta.

Há três tipos de conjuntos de regras, gerenciados de maneiras um pouco diferentes.

Dinâmico

Persistem em sessões do navegador e upgrades de extensão e são gerenciados usando JavaScript enquanto uma extensão está em uso.

Sessão

É limpo quando o navegador é fechado e quando uma nova versão da extensão é instalada. As regras de sessão são gerenciadas usando JavaScript enquanto uma extensão está em uso.

Estático

Empacotado, instalado e atualizado quando uma extensão é instalada ou atualizada. As regras estáticas são armazenadas em arquivos de regras formatados em JSON e listadas no arquivo de manifesto.

Conjuntos de regras dinâmicos e no escopo da sessão

Os conjuntos de regras dinâmicos e de sessão são gerenciados usando JavaScript enquanto uma extensão está em uso.

• As regras dinâmicas persistem nas sessões do navegador e nos upgrades de extensão.
• As regras de sessão são limpas quando o navegador é fechado e quando uma nova versão da extensão é instalada.

Há apenas um de cada tipo de conjunto de regras. Uma extensão pode adicionar ou remover regras de forma dinâmica chamando updateDynamicRules() e updateSessionRules(), desde que os limites de regras não sejam excedidos. Para informações sobre limites de regras, consulte Limites de regras. Confira um exemplo disso em exemplos de código.

Conjuntos de regras estáticos

Ao contrário das regras dinâmicas e de sessão, as regras estáticas são empacotadas, instaladas e atualizadas quando uma extensão é instalada ou atualizada. Eles são armazenados em arquivos de regras no formato JSON, que são indicados à extensão usando as chaves "declarative_net_request" e "rule_resources" conforme descrito acima, além de um ou mais dicionários Ruleset. Um dicionário Ruleset contém um caminho para o arquivo de regras, um ID para o conjunto de regras contido no arquivo e se o conjunto de regras está ativado ou desativado. Os dois últimos são importantes quando você ativa ou desativa um conjunto de regras de maneira programática.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Para testar arquivos de regras, carregue a extensão descompactada. Erros e avisos sobre regras estáticas inválidas só são mostrados para extensões descompactadas. Regras estáticas inválidas em extensões compactadas são ignoradas.

Análise acelerada

As mudanças em conjuntos de regras estáticas podem estar qualificadas para revisão acelerada. Consulte revisão acelerada para mudanças qualificadas.

Ativar e desativar regras e conjuntos de regras estáticos

Tanto regras estáticas individuais quanto conjuntos de regras estáticas completos podem ser ativados ou desativados durante a execução.

O conjunto de regras estáticas e conjuntos de regras ativados é mantido em todas as sessões do navegador. Nenhum dos dois é mantido nas atualizações de extensão. Isso significa que apenas as regras que você escolheu deixar nos arquivos de regras ficam disponíveis após uma atualização.

Por motivos de desempenho, também há limites para o número de regras e conjuntos de regras que podem ser ativados ao mesmo tempo. Chame getAvailableStaticRuleCount() para verificar o número de regras adicionais que podem ser ativadas. Para informações sobre limites de regras, consulte Limites de regras.

Para ativar ou desativar regras estáticas, chame updateStaticRules(). Esse método usa um objeto UpdateStaticRulesOptions, que contém matrizes de IDs de regras a serem ativadas ou desativadas. Os IDs são definidos usando a chave "id" do dicionário Ruleset. Há um limite máximo de 5.000 regras estáticas desativadas.

Para ativar ou desativar conjuntos de regras estáticos, chame updateEnabledRulesets(). Esse método usa um objeto UpdateRulesetOptions, que contém matrizes de IDs de conjuntos de regras a serem ativados ou desativados. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Regras de build

Independentemente do tipo, uma regra começa com quatro campos, conforme mostrado abaixo. Enquanto as chaves "id" e "priority" usam um número, as chaves "action" e "condition" podem fornecer várias condições de bloqueio e redirecionamento. A regra a seguir bloqueia todas as solicitações de script originadas de "foo.com" para qualquer URL com "abc" como uma substring.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

Correspondência de URL

A solicitação de rede declarativa permite corresponder URLs com uma sintaxe de correspondência de padrão ou expressões regulares.

Sintaxe do filtro de URL

A chave "condition" de uma regra permite uma chave "urlFilter" para agir em URLs de um domínio especificado. Você cria padrões usando tokens de correspondência de padrões. Confira alguns deles:

Expressões regulares

As condições também podem usar expressões regulares. Consulte a chave "regexFilter". Para saber mais sobre os limites aplicados a essas condições, consulte Regras que usam expressões regulares.

Escrever boas condições de URL

Tenha cuidado ao escrever regras para sempre corresponder a um domínio inteiro. Caso contrário, a regra pode corresponder em situações inesperadas. Por exemplo, ao usar a sintaxe de correspondência de padrões:

• google.com corresponde incorretamente a https://example.com/?param=google.com
• ||google.com corresponde incorretamente a https://google.company
• https://www.google.com corresponde incorretamente a https://example.com/?param=https://www.google.com

Considere usar:

• ||google.com/, que corresponde a todos os caminhos e subdomínios.
• |https://www.google.com/, que corresponde a todos os caminhos e nenhum subdomínio.

Da mesma forma, use os caracteres ^ e / para ancorar uma expressão regular. Por exemplo, ^https:\/\/www\.google\.com\/ corresponde a qualquer caminho em https://www.google.com.

Avaliação de regras

As regras de DNR são aplicadas pelo navegador em várias etapas do ciclo de vida da solicitação de rede.

Antes da solicitação

Antes de uma solicitação ser feita, uma extensão pode bloquear ou redirecionar (incluindo o upgrade do esquema de HTTP para HTTPS) com uma regra correspondente.

Para cada extensão, o navegador determina uma lista de regras correspondentes. As regras com uma ação modifyHeaders não estão incluídas aqui porque serão processadas mais tarde. Além disso, as regras com uma condição responseHeaders serão consideradas mais tarde (quando os cabeçalhos de resposta estiverem disponíveis) e não serão incluídas.

Em seguida, para cada extensão, o Chrome escolhe no máximo um candidato por solicitação. O Chrome encontra uma regra correspondente, ordenando todas as regras correspondentes por prioridade. Regras com a mesma prioridade são ordenadas por ação (allow ou allowAllRequests > block > upgradeScheme > redirect).

Se o candidato for uma regra allow ou allowAllRequests, ou se o frame em que a solicitação está sendo feita já tiver correspondido a uma regra allowAllRequests de prioridade maior ou igual desta extensão, a solicitação será "permitida" e a extensão não terá efeito sobre ela.

Se mais de uma extensão quiser bloquear ou redirecionar essa solicitação, uma única ação será escolhida. O Chrome faz isso classificando as regras na ordem block > redirect ou upgradeScheme > allow ou allowAllRequests. Se duas regras forem do mesmo tipo, o Chrome vai escolher a regra da extensão instalada mais recentemente.

Antes do envio dos cabeçalhos de solicitação

Antes de o Chrome enviar cabeçalhos de solicitação ao servidor, eles são atualizados com base nas regras modifyHeaders correspondentes.

Em uma única extensão, o Chrome cria a lista de modificações a serem realizadas encontrando todas as regras modifyHeaders correspondentes. Assim como antes, apenas as regras com uma prioridade maior do que qualquer regra allow ou allowAllRequests correspondente são incluídas.

Essas regras são aplicadas pelo Chrome em uma ordem em que as regras de uma extensão instalada mais recentemente são sempre avaliadas antes das regras de uma extensão mais antiga. Além disso, as regras de uma extensão com prioridade mais alta são sempre aplicadas antes das regras de uma extensão com prioridade mais baixa. Principalmente em todas as extensões:

• Se uma regra for adicionada a um cabeçalho, as regras de prioridade mais baixa só poderão ser adicionadas a esse cabeçalho. Não é permitido definir nem remover operações.
• Se uma regra definir um cabeçalho, somente as regras de menor prioridade da mesma extensão poderão anexar a ele. Nenhuma outra modificação é permitida.
• Se uma regra remover um cabeçalho, as regras de prioridade mais baixa não poderão modificar o cabeçalho.

Quando uma resposta é recebida

Depois que os cabeçalhos de resposta são recebidos, o Chrome avalia as regras com uma condição responseHeaders.

Depois de classificar essas regras por action e priority e excluir as regras que se tornaram redundantes por uma regra allow ou allowAllRequests correspondente (isso acontece de maneira idêntica às etapas em "Antes da solicitação"), o Chrome pode bloquear ou redirecionar a solicitação em nome de uma extensão.

Se uma solicitação chegar a essa etapa, ela já terá sido enviada ao servidor, e o servidor terá recebido dados como o corpo da solicitação. Uma regra de bloqueio ou redirecionamento com uma condição de cabeçalhos de resposta ainda será executada, mas não poderá bloquear ou redirecionar a solicitação.

No caso de uma regra de bloqueio, isso é processado pela página que fez a solicitação, recebendo uma resposta bloqueada e o Chrome encerrando a solicitação antecipadamente. No caso de uma regra de redirecionamento, o Chrome faz uma nova solicitação ao URL redirecionado. Considere se esses comportamentos atendem às expectativas de privacidade da sua extensão.

Se a solicitação não for bloqueada ou redirecionada, o Chrome vai aplicar as regras modifyHeaders. Aplicar modificações aos cabeçalhos de resposta funciona da mesma forma que descrito em "Antes do envio dos cabeçalhos de solicitação". Aplicar modificações aos cabeçalhos de solicitação não faz nada, já que a solicitação já foi feita.

Regras seguras

As regras seguras são definidas como regras com uma ação de block, allow, allowAllRequests ou upgradeScheme. Essas regras estão sujeitas a uma cota dinâmica maior.

Limites das regras

Há uma sobrecarga de desempenho ao carregar e avaliar regras no navegador. Por isso, alguns limites se aplicam ao usar a API. Os limites dependem do tipo de regra que você está usando.

Regras estáticas

As regras estáticas são aquelas especificadas em arquivos de regras declarados no arquivo de manifesto. Uma extensão pode especificar até 100 conjuntos de regras estáticos como parte da chave de manifesto "rule_resources", mas apenas 50 deles podem ser ativados por vez. O último é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. No total, esses conjuntos de regras têm pelo menos 30.000 regras. Isso é chamado de GUARANTEED_MINIMUM_STATIC_RULES.

O número de regras disponíveis depois disso depende de quantas regras são ativadas por todas as extensões instaladas no navegador de um usuário. Você pode encontrar esse número no tempo de execução chamando getAvailableStaticRuleCount(). Confira um exemplo disso em exemplos de código.

Regras de sessão

Uma extensão pode ter até 5.000 regras de sessão. Ele é exposto como o MAX_NUMBER_OF_SESSION_RULES.

Antes do Chrome 120, havia um limite de 5.000 regras dinâmicas e de sessão combinadas.

Regras dinâmicas

Uma extensão pode ter pelo menos 5.000 regras dinâmicas. Ele é exposto como o MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

A partir do Chrome 121, há um limite maior de 30.000 regras disponíveis para regras dinâmicas seguras, expostas como MAX_NUMBER_OF_DYNAMIC_RULES. Todas as regras não seguras adicionadas dentro do limite de 5.000 também contam para esse limite.

Antes do Chrome 120, havia um limite de 5.000 regras dinâmicas e de sessão combinadas.

Regras que usam expressões regulares

Todos os tipos de regras podem usar expressões regulares, mas o número total de regras de expressão regular de cada tipo não pode exceder 1.000. Isso é chamado de MAX_NUMBER_OF_REGEX_RULES.

Além disso, cada regra precisa ter menos de 2 KB depois de compilada. Isso se correlaciona aproximadamente com a complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, vai aparecer um aviso como este, e a regra será ignorada.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Interações com service workers

Uma declarativeNetRequest só se aplica a solicitações que chegam à pilha de rede. Isso inclui respostas do cache HTTP, mas não as que passam pelo manipulador onfetch de um service worker. O declarativeNetRequest não afeta as respostas geradas pelo service worker ou recuperadas de CacheStorage, mas afeta as chamadas para fetch() feitas em um service worker.

Recursos acessíveis da Web

Uma regra declarativeNetRequest não pode redirecionar de uma solicitação de recurso público para um recurso que não seja acessível pela Web. Isso aciona um erro. Isso é válido mesmo que o recurso acessível da Web especificado seja de propriedade da extensão de redirecionamento. Para declarar recursos para declarativeNetRequest, use a matriz "web_accessible_resources" do manifesto.

Modificação de cabeçalho

A operação de adição só é compatível com os seguintes cabeçalhos: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Exemplos

Exemplos de código

Atualizar regras dinâmicas

O exemplo a seguir mostra como chamar updateDynamicRules(). O procedimento para updateSessionRules() é o mesmo.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Atualizar conjuntos de regras estáticos

O exemplo a seguir mostra como ativar e desativar conjuntos de regras considerando o número de conjuntos estáticos disponíveis e o número máximo de conjuntos ativados. Isso é feito quando o número de regras estáticas necessárias excede o permitido. Para que isso funcione, alguns conjuntos de regras precisam ser instalados com outros desativados (definindo "Enabled" como false no arquivo de manifesto).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemplos de regras

Os exemplos a seguir ilustram como o Chrome prioriza regras em uma extensão. Ao analisar, abra as regras de priorização em uma janela separada.

A chave "priority"

Esses exemplos exigem permissão de host para *://*.example.com/*.

Para determinar a prioridade de um URL específico, consulte as chaves "priority", "action" e "urlFilter" (definidas pelo desenvolvedor). Esses exemplos se referem ao arquivo de regra de exemplo mostrado abaixo deles.

Navegação para https://google.com

Duas regras abrangem este URL: as regras com IDs 1 e 4. A regra com ID 1 é aplicada porque as ações "block" têm uma prioridade maior do que as ações "redirect". As regras restantes não se aplicam porque são para URLs mais longos.

Navegação para https://google.com/1234

Devido ao URL mais longo, a regra com ID 2 agora também corresponde às regras com IDs 1 e 4. A regra com ID 2 é aplicada porque "allow" tem uma prioridade maior que "block" e "redirect".

Navegação para https://google.com/12345

Todas as quatro regras correspondem a este URL. A regra com ID 3 é aplicada porque a prioridade definida pelo desenvolvedor é a mais alta do grupo.

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

Redirecionamentos

O exemplo abaixo exige permissão de host para *://*.example.com/*.

O exemplo a seguir mostra como redirecionar uma solicitação de example.com para uma página na própria extensão. O caminho da extensão /a.jpg é resolvido como chrome-extension://EXTENSION_ID/a.jpg, em que EXTENSION_ID é o ID da extensão. Para que isso funcione, o manifesto precisa declarar /a.jpg como um recurso acessível à Web.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

O exemplo a seguir usa a chave "transform" para redirecionar para um subdomínio de example.com. Ele usa uma âncora de nome de domínio ("||") para interceptar solicitações com qualquer esquema de example.com. A chave "scheme" em "transform" especifica que os redirecionamentos para o subdomínio sempre usarão "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

O exemplo a seguir usa expressões regulares para redirecionar de https://www.abc.xyz.com/path para https://abc.xyz.com/path. Na chave "regexFilter", observe como os pontos são escapados e que o grupo de captura seleciona "abc" ou "def". A chave "regexSubstitution" especifica a primeira correspondência retornada da expressão regular usando "\1". Nesse caso, "abc" é capturado do URL redirecionado e colocado na substituição.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Cabeçalhos

O exemplo a seguir remove todos os cookies de um frame principal e de todos os subframes.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}