Rules Engine para Edge Application

O Rules Engine é uma funcionalidade do Edge Application controla a execução de comportamentos através de operadores lógicos. Através do Rules Engine, você pode construir uma arquitetura que proporciona melhor performance para seus usuários consumindo menos recursos e processando na origem.

Cada requisição de uma aplicação criada com o Azion Azion Console é processada numa sequência fixa de duas fases:

  1. Request Phase: ocorre quando um usuário submete uma requisição à edge application.
  2. Response Phase: ocorre quando um usuário recebe uma resposta da edge application.

Em cada fase de processamento, você pode definir um conjunto de regras para tratar a requisição de acordo com as necessidades da sua aplicação ou negócio. Uma vez selecionada a fase em que a sua regra será executada, você pode criar uma nova regra.

As regras são concebidas para seguir uma lógica condicional se-então. Cada regra é composta de Criteria (se), que são os critérios que definirão o conjunto de condições que devem ser cumpridas para a execução de Behaviors (então), ou comportamentos.

Para desencadear os comportamentos desejados para sua aplicação, você pode utilizar variáveis, operadores de comparação e operadores lógicos. Se as condições forem cumpridas, os comportamentos de cada regra são executados em sequência até que todas as regras sejam processadas.

EscopoRecurso
Primeiros passos de Edge ApplicationPrimeiros passos
Criar uma regraComo criar regras de Request e Response usando o Rules Engine para Edge Application
Criar uma configuração de cacheComo configurar políticas de cache para Edge Application
Mitigar HTTPoxy usando rulesComo mitigar a vulnerabilidade HTTPoxy

Ao criar uma regra, você será solicitado a selecionar uma das duas fases de processamento disponíveis: Request Phase ou Response Phase.

Durante a Request Phase, o edge node processa as requisições do usuário final. Para as regras da Request Phase, todas as variáveis associadas aos dados fornecidos pelo usuário na requisição podem ser utilizadas. No entanto, as variáveis relacionadas ao conteúdo que será entregue ao usuário nessa fase não são acessíveis, pois a resposta ainda não foi processada pela aplicação.

Além disso, é na Request Phase que você determina como a aplicação armazenará o conteúdo em cache. Se sua aplicação não permitir nenhuma forma de armazenamento em cache, você tem a opção de definir as condições sob as quais o armazenamento em cache deve ser desconsiderado.

Na Response Phase, sua aplicação trata do conteúdo que será entregue a seus usuários. Todo o processamento feito nessa fase é dinâmico e a entrega de cada usuário é realizada de forma independente com base em seus requisitos específicos.


Além do nome da regra, você pode adicionar uma descrição para ela usando o campo Description. Sua descrição ficará visível na lista de regras e pode ser usada para identificar o que a regra faz.


A seção Criteria do Rules Engine é onde você define os critérios para a execução da regra. Critérios são compostos de:

  • variáveis
  • operadores de comparação
  • argumentos, quando aplicável

A inclusão de argumentos em um critério depende dos operadores de comparação escolhidos, e seus formatos estão descritos nas seções variáveis e operadores de comparação. Operadores lógicos servem para incrementar a quantidade de comparações que a regra irá executar.

Por exemplo, o seguinte critério identifica se um usuário está usando um navegador web desktop para acessar sua aplicação através de uma expressão regular como argumento:

VariávelOperador de comparaçãoArgumento
If${http_user_agent}matches(Chrome|Mozilla)

Confira a lista completa de variáveis disponíveis e sua fase de processamento:

VariávelDescriçãoExemploFase
${arg_name}Valor do nome do parâmetro na string de consulta da URL${arg_search} assume test para /path?search=testRequest
Response
${args}Todos os nomes de parâmetros e valores enviados na string de consulta da URL${args} assume search=test para /path?search=testRequest
Response
${cookie_name}Valor do cookie name${cookie_icl_current_language} assume pt-br para icl_current_language = pt-brRequest
Response
${device_group}Nome do device group. Você pode criar device groups na aba Device Groups de sua aplicação no Azion ConsoleMobileRequest
Response
${domain}Similar à variável ${host}. Armazena o host name ou o cabeçalho Host da requisição, removendo o último subdomínio após o domínio de segundo nível${domain} assume blog.dominio.com para az.blog.dominio.comRequest
Response
${geoip_city}Nome da cidade por extenso, utilizando a base de geolocalização geoip_citySao PauloRequest
Response
${geoip_city_continent_code}Código de continente com 2 letras, utilizando a base de geolocalização geoip_cityEU para EuropaRequest
Response
${geoip_city_country_code}Código de país com 2 letras, utilizando a base de geolocalização geoip_cityBR para BrasilRequest
Response
${geoip_city_country_name}Nome do país por extenso, utilizando a base de geolocalizaçãoUnited StatesRequest
Response
${geoip_continent_code}Código de continente com 2 letrasNA para América do NorteRequest
Response
${geoip_country_code}Código de país com 2 letras, utilizando a base de geolocalização geoip_countryRU para RússiaRequest
Response
${geoip_country_name}Nome do país por extenso, utilizando a base de geolocalização geoip_countryBrazilRequest
Response
${geoip_region}Código da região com 2 letrasRS para Rio Grande do SulRequest
Response
${geoip_region_name}Nome da região por extenso, utilizando a base de geolocalização geoip_regionOntarioRequest
Response
${host}Em ordem de precedência: o host name da linha de requisição, ou o valor do campo de cabeçalho Host da requisição, ou o nome do servidor atendendo a requisiçãoblog.domain.comRequest
Response
${http_name}O valor do campo de cabeçalho da requisição. name deve ser um cabeçalho HTTP válido convertido em letras minúsculas; hífens devem ser convertidos para underscore${http_accept} assume image/webp,image/apng para Accept: image/webp,image/apngRequest
Response
${remote_addr}O endereço IP do cliente que está realizando a requisição HTTP200.10.2.50Request
Response
${remote_port}A porta HTTP sendo usada na URL da requisição do cliente443Request
Response
${remote_user}O username fornecido pela autenticação básica, quando houverusernameRequest
Response
${request}A primeira linha da requisição original do request feito pelo cliente. É composta pelo método da requisição, o URI da requisição e a versão HTTPGET /path HTTP/2.0Request
Response
${request_method}O método HTTP da requisiçãoGETRequest
Response
${request_uri}O URI completo da requisição, com argumentos (query string). Caracteres UTF-8 especiais são codificados em URL encoding/path?var=value%20of%20varRequest
Response
${scheme}O scheme da requisiçãohttpsRequest
Response
${sent_http_name}O valor do campo de cabeçalho de resposta name. O argumento name deve ser convertido para letras minúsculas e os hífens devem ser convertidos para underscore (_)${sent_http_content_length} assume 9593 para Content-Length: 9593Response
${server_addr}O endereço IP do servidor que recebe a requisição HTTP200.0.0.0Request
${server_port}A porta HTTP do servidor que irá receber a requisição8080Request
${status}O status code da resposta200Response
${tcpinfo_rtt}Round-Trip Time (RTT) da conexão TCP do cliente, em microsegundos24763Response
${upstream_addr}O endereço IP e porta da origem consultada para obtenção da resposta. Caso múltiplas origens sejam consultadas durante o processamento da requisição, os endereços serão separados por vírgula (,). Se um redirect interno de um grupo de servidores para outro ocorrer, iniciado por um X-Accel-Redirect ou por uma página de erro, os endereços dos diferentes grupos serão separados por dois pontos (:)192.168.1.1:80, 192.168.1.2:80
192.168.1.1:80, 192.168.1.2:80 : 192.168.10.1:80, 192.168.10.2:80
Response
${upstream_cookie_name}Valor do cookie name enviado pela origem através do campo de cabeçalho Set-Cookie. Caso múltiplas origens sejam consultadas durante o processamento da requisição, apenas os cookies da última origem são armazenados${upstream_cookie_uuid} assume 12345 para Set-Cookie: uuid = 12345Response
${upstream_http_name}Valor do campo de cabeçalho name enviado pela origem. O argumento name deve ser convertido para letras minúsculas e os hífens devem ser convertidos para underscore. Caso múltiplas origens sejam consultadas durante o processamento da requisição, apenas os cabeçalhos da última origem são armazenados${upstream_http_server} assume UploadServer para Server: UploadServerResponse
${upstream_status}Status Code da resposta da origem enviada para o Azion Console. Caso múltiplas origens sejam consultadas durante o processamento da requisição, os status codes serão separados por vírgula (,). Se um redirect interno de um grupo de servidores para outro ocorrer, iniciado por um X-Accel-Redirect ou por uma página de erro, os status codes dos diferentes grupos serão separados por dois pontos (:)200, 201
500, 502 : 200, 200
Response
${uri}O URI normalizado (URL decoded) da solicitação.

O valor de ${uri} pode mudar durante o processamento de uma solicitação, por exemplo, quando ocorre um redirecionamento interno ou quando arquivos de índice são usados. Para parâmetros de query string e caracteres URL encoded, use ${request_uri}
/path/my file.txtRequest
Response

Variáveis para Mutual Transport Layer Security (mTLS)

Seção intitulada Variaveis para Mutual Transport Layer Security (mTLS)

Utilize essas variáveis no Rules Engine da sua edge application para configurar Mutual Transport Layer Security (mTLS). Variáveis para mTLS estão disponíveis apenas para a Request Phase.

VariávelDescriçãoExemplo
${ssl_client_fingerprint}O Secure Hash Algorithm 1 (SHA-1) do client certificate2fd4e1c67a2d28fced849
${ssl_client_escaped_cert}O client certificate no formato Private Enhanced Mail (PEM), formatado como uma string URL encoded-----BEGIN%20CERTIFICATE-----%0AMIICnz...%0A-----END%20CERTIFICATE-----
${ssl_client_s_dn}Retorna o subject DN do client certificate como string/C=US/ST=California/L=San Francisco/O=Example CA/CN=example.com
${ssl_client_s_dn_parsed}Retorna o subject CN (extraído do subject DN) do client certificate como stringexample.com
${ssl_client_cert}Esta é uma variável descontinuada. Use ${ssl_client_escaped_cert}

Retorna o client certificate no formato PEM
-----BEGIN CERTIFICATE-----
MIICnz...
-----END CERTIFICATE-----
${ssl_client_i_dn}Retorna o issuer DN do client certificate como string/C=US/ST=California/L=San Francisco/O=Example CA/CN=issuer.com
${ssl_client_serial}Retorna o número de série do client certificate6C:0A:83:7E:92:3B:D6:C6:E3:56:50:E7
${ssl_client_v_end}Retorna a data de expiração do client certificate em formato YYYYMMDDHHmmSS20230115120000
${ssl_client_v_remain}Retorna o tempo, em dias, que falta para o client certificate expirar100
${ssl_client_v_start}Retorna a data de emissão do client certificate em formato YYYYMMDDHHmmSS20230115120000
${ssl_client_verify}Retorna o resultado da verificação do client certificateSUCCESS
FAILED:reason
NONE

A maioria dos serviços mTLS depende do recebimento do certificado do usuário. Usando o Azion Console, você pode enviar a variável ${ssl_client_escaped_cert} no cabeçalho X-Forward-Client-Cert (XFCC) na requisição para a origem e, em seguida, configurar sua edge application para usar esse header com os dados do certificado. :::

Saiba mais sobre suporte para mTLS

Para behaviors que requerem um argumento, você pode utilizar as mesmas variáveis que estão disponíveis na fase de processamento. Dessa forma você pode, por exemplo, compor cookies ou cabeçalhos HTTP de requisição utilizando dados coletados durante a Request Phase, tais como o device group a qual o usuário pertence ou sua geolocalização.

Por exemplo, para a regra na Response Phase:

VariávelOperador de comparaçãoArgumento
If${host}is equalhost.com
ComportamentoArgumento
ThenAdd Response Cookiecookie-host-value=${host}

Quando esta regra for ativada, se a requisição for feita do host determinado no criteria, a resposta retornará o cabeçalho com o seguinte valor: Set-Cookie: cookie-host-value=host.com.

A Azion também disponibiliza variáveis especiais que agem como funções e levam argumentos. As seguintes variáveis podem ser usadas para compor argumentos de Behaviors:

VariávelDescrição
${cookie_time_offset(number)}Retorna a data atual acrescida de um offset em segundos, informado como argumento, para ser utilizado na definição do tempo de expiração de um cookie
${encode_base64(string)}Retorna o argumento codificado em base64

OperadorDescriçãoTipo de argumento
is equalO valor da variável é igual ao argumento, comparado caractere a caracterestring
is not equalO valor da variável não é exatamente igual ao argumentostring
starts withO valor da variável inicia pelo argumentostring
does not start withO valor da variável não inicia pelo argumentostring
matchesO valor da variável coincide com a expressão regular informada como argumentoregular expression
does not matchO valor da variável não coincide com a expressão regular informada como argumentoregular expression
existsA variável tem valor definido. Exemplo: ${arg_search} existe se foi enviado um argumento search na query string da requisição-
does not existA variável não tem valor definido. Exemplo: ${arg_search} não existe se não foi enviado um argumento search na query string da requisição-

Múltiplos critérios podem ser adicionados por meio dos operadores lógicos AND e OR. Com isso, cada regra pode conter até 10 critérios.

O operador AND tem precedência implícita sobre o operador OR. Se for necessária precedência explícita, você pode adicionar múltiplos grupos de critérios apenas sob a lógica AND.


Na seção de Behaviors da Rules Engine, você adiciona os comportamentos que deseja executar, caso as condições da regra sejam atendidas.

Por exemplo, esse comportamento redireciona o usuário para uma versão em inglês de um path de FAQ:

ComportamentoArgumento
Redirect To (302 Found)/en-us/faq

Cada regra pode carregar até 10 comportamentos.

Em cada fase de processamento, comportamentos distintos estão disponíveis.

Request Phase Response Phase Requer Application Accelerator

Adiciona um cookie no cabeçalho Set-Cookie da requisição ou da resposta. O valor do cookie deve ser informado como argumento no formato cookie-name=cookie-value.

Para cookies de resposta, você pode adicionar as seguintes políticas de Set-Cookie ao argumento, separadas do valor do cookie por ponto e vírgula (;):

  • Expires=date (EEE, d MMM yyyy HH:mm
    Z)
  • Domain=domain-value
  • Path=path-value
  • Max-age=number (TTL in seconds, takes precedence over Expires)
  • SameSite=value; Secure
  • HttpOnly

Múltiplas políticas também são permitidas se separadas por ponto e vírgula (;). Por exemplo: cookie-name=cookie-value; Domain=domain-value; Path=path-value; SameSite=value.

Você também pode usar variáveis no lugar de valores. Por exemplo: Path=${uri}; Domain=${host}.

Request Phase Response Phase

Adiciona um campo de cabeçalho na requisição que será enviada a origem ou na resposta que será enviada para o usuário. O campo de cabeçalho deve ser informado como argumento no formato Field: value.

Request Phase Requer Application Accelerator

Define que a Azion não deverá armazenar em cache a resposta de sua origem. A execução desta regra não tem impacto sobre o cache no browser dos usuários, o qual deve ser definido utilizando o behavior Set Cache Policy.

Através do Bypass Cache, você configura o serviço da Azion para repassar todas as requisições a um path diretamente para sua origem. Contudo, você contará com importantes otimizações de protocolo para acelerar sua aplicação e conexão keep-alive entre os edge nodes da Azion e sua origem sempre que possível.

Diferença entre Bypass Cache e TTL 0

Seção intitulada Diferenca entre Bypass Cache e TTL 0

Tanto o comportamento Bypass Cache quanto o Maximum TTL em zero segundos permitem otimizar a entrega de conteúdo e reduzir os tempos de carregamento na origem, mas seus efeitos são levemente diferentes.

Ao usar o comportamento Bypass Cache, todas as solicitações HTTP e HTTPS recebidas pelos edge nodes da Azion serão enviadas para a origem, sem armazenar nenhum conteúdo em cache. Utilize o Bypass Cache se você quiser fornecer conteúdo diferente para cada solicitação de usuário.

No entanto, ao definir o TTL em 0 (zero) segundos, várias solicitações em paralelo aos edge nodes da Azion serão enviadas como uma única solicitação à origem. Nesse caso, os edge nodes da Azion também validam as alterações no conteúdo com sua origem usando o parâmetro If-Modified-Since. Se o objeto não tiver sido alterado desde a última solicitação, o conteúdo não precisará ser transferido novamente, o que pode resultar em uma resposta 304 Not Modified muito mais rápida. Além disso, o TTL máximo de cache em 0 ainda irá gerar um objeto de cache que vive por 999 milissegundos.

Request Phase Requer Application Accelerator

Comportamento de apoio para manipulação de strings. Armazena em uma variável temporária o resultado da captura de grupos de correspondência definidos por uma regex aplicada a um dos campos da requisição HTTP disponibilizados. Essa variável temporária pode ser posteriormente referenciada no behavior Rewrite Request para montar a string de reescrita.

Este behavior requer três argumentos:

  • captured array name: o nome que você deseja dar à variável temporária onde será armazenado o array de strings capturadas.
  • subject: o campo da requisição HTTP de onde você deseja capturar alguma string.
  • regex: a expressão regular usada para capturar as strings. Cada grupo capturado deve ser representado entre parênteses.

Por exemplo, para capturar o caminho e o nome de um arquivo em uma requisição HTTP, você pode utilizar:

  • captured array name: capture
  • subject: ${uri}
  • regex: ^(./)([^/])$

É possível referenciar a variável de captura como um array utilizando a notação %{*variable[index]*}. Por se tratar de uma variável local, você só poderá utilizá-la dentro da mesma regra que estiver configurando. Neste exemplo, se o URI for /path/image.jpg, a variável de captura apresentará os seguintes valores:

  • %{capture[0]} = "/path/image.jpg"
  • %{capture[1]} = "/path/"
  • %{capture[2]} = "image.jpg"

Você também pode nomear os índices para referenciá-los usando nomes em vez de um índice numérico. Para tanto, utilize a notação ?<name>, como no exemplo:

  • captured array name: capture
  • subject: ${uri}
  • regex: ^(?<path>.*/)(?<filename>[^/]*)$
Request Phase Response Phase

Encerra o processamento da requisição e entrega o conteúdo para o usuário, sem executar nenhuma das regras seguintes. Ao utilizar o behavior Deliver, você estará forçando o término do processamento imediatamente.

Request Phase

Entrega um 403 Forbidden para o usuário. Por se tratar de uma regra finalizadora, esse behavior encerra o processamento da requisição.

Request Phase Response Phase

Ativa a compressão de dados em gzip, caso suportada pelo browser do usuário. Consulte o guia de Como habilitar compressão gzip para mais informações.

Request Phase Requer Edge Cache

Ativa segmentação de objetos grandes em fragmentos, caso sua origem tenha suporte a requisições HTTP byte-range. Utilize este behavior se você entrega objetos com mais de 1MB através da Azion para que a entrega do conteúdo para seus usuários seja iniciada da edge, mesmo antes de ter recebido todo o objeto de sua origem.

Ao ativar esta funcionalidade, a Azion irá requisitar os objetos para sua origem via range requests e os mesmos serão cacheados na Azion com Advanced Cache Key.

Caso sua origem não tenha suporte a range requests, a Azion só poderá iniciar a entrega de seu conteúdo para seus usuários após sua origem finalizar o envio completo do objeto.

Request Phase Requer Live Ingest

Este behavior é incluído automaticamente pela Azion toda vez que você selecionar uma origem do tipo Live Ingest. Duas ações são executadas nessa situação: o bypass de todas suas regras da Cache Phase e a imposição da política de cache definida pela Azion para transmissões live em HLS.

A política de cache da Azion para transmissões live em HLS é de 5 segundos de cache para playlists (.m3u8) e 60 segundos de cache para chunks (.ts).

consulte o guia para implementar cache HLS

Request Phase Response Phase Requer Application Accelerator

Remove um cookie do cabeçalho da requisição que será enviada para a origem ou da requisição que será enviada para o usuário. Como argumento, você pode informar o nome do cookie que deseja remover no formato cookie-name.

Para remover apenas valores específicos, você deve informar o nome e valor do cookie no formato cookie-name=cookie-value.

Request Phase Response Phase

Remove um campo do cabeçalho da requisição que será enviada para a origem ou da resposta que será enviada para o usuário. O nome do cabeçalho deve ser informado como argumento, por exemplo: Header-Name.

Request Phase

Finaliza a fase de requisição. Qualquer comportamento ou regra abaixo desse comportamento não será executada.

Request Phase Requer Application Accelerator

Ao utilizar o comportamento Forward Cookies, você está determinando que a Azion encaminhe aos seus usuários o cabeçalho Set-Cookie recebido da origem, mesmo quando for identificado conteúdo em cache (HIT).

Para evitar que um usuário receba o cabeçalho Set-Cookie da sessão de outro usuário, consulte o guia sobre políticas de cache.

Uma alternativa ao envio do cabeçalho de resposta Set-Cookie é a criação de cookies por JavaScript, que permite criar, ler e expirar cookies através da propriedade document.cookie.

O JavaScript cookie deve possuir o seguinte formato:

document.cookie = "username=John Doe; expires=Thu, 18 Dec 2013 12:00:00 UTC; path=/";

Por padrão, a Azion não irá filtrar o Request Header Cookie, independentemente de sua configuração de Forward Cookies. Sendo assim, JavaScript Cookies poderão ser enviados para sua origem para viabilizar o gerenciamento de sua aplicação.

Request Phase

Retorna um código 204 quando se faz um request à aplicação ao invés do código recebido da origem.

Request Phase Requer Image Processor

Ativa a otimização de imagens.

Request Phase Requer aplicação HTTPS

Redireciona a requisição HTTP para a respectiva URL em HTTPS. Caso a requisição já seja HTTPS, não executa nenhum comportamento.

Request Phase Response Phase

Redirect to (301 Moved Permanently) e Redirect To (302 Found) redirecionam o usuário para uma outra URL informada como argumento, retornando o status code 301 Moved Permanently ou 302 Found.

É recomendado que estes comportamentos sejam utilizados para mudanças de caminhos: 301 Moved Permanently para mudanças permanentes e 302 Found para mudanças mudanças temporárias.

Por se tratarem de regras finalizadoras, esses behaviors encerram o processamento da requisição.

Request Phase Requer Application Accelerator

Modifica o path do recurso que será requisitado para a origem. Você pode reescrever o path do recurso utilizando:

  • Uma string.
  • As variáveis da requisição (as mesmas que podem ser utilizadas em Criteria).
  • As variáveis locais, no formato %{name[index]}, com o resultado de captura de strings, ao utilizar o behavior Capture Match Groups.

Por exemplo, se você deseja que a requisição de um usuário para o recurso /original/image.jpg seja enviada para sua origem como /new/image.jpg, você pode:

  1. Utilizar o behavior Capture Match Groups com os argumentos:
  • captured array name: capture
  • subject: ${uri}
  • regex: /original/(.*)
  1. Utilizar o behavior Rewrite Request com o argumento /new/%{capture[1]}

Request Phase Response Phase Requer Application Accelerator Requer Edge Functions

Executa uma função criada no Edge Functions e instanciada pela aba Edge Functions da edge application. Consulte o guia de Como executar funções serverless para mais informações.

Request Phase

Atribui a política de cache que deve ser utilizada para a requisição. As políticas de cache devem ser previamente configuradas na Cache Settings.

Na política de cache você configura o tempo que o objeto deve ser armazenado em cache e as regras para variação dos objetos em cache com a Advanced Cache Key.

Request Phase

Atribui a origem que deve ser consultada pelo edge node para a requisição.

As origens devem ser previamente configuradas usando Origins.


Execução e lógica de behaviors

Seção intitulada Execucao e logica de behaviors

Enquanto behaviors e regras são executados na ordem em que são distribuidos, alguns tipos de behaviors não podem ser encadeados.

Se um behavior do tipo Set, como Set Custom Response no Edge Firewall ou Set Origin no Edge Application, for adicionado múltiplas vezes a regras no Rules Engine, apenas o último behavior da última regra na qual o criteria foi atendido será executado.

Behaviors do tipo Add são cumulativos e podem ser adicionados várias vezes às regras. Isso significa que se Add Cookie e Add Header forem executados várias vezes para os mesmos pares key-value, múltiplas entradas idênticas serão adicionadas.

No entanto, para cabeçalhos únicos como Host, o último behavior do tipo Add Header que é executado sobrescreverá o valor anterior, já que não pode haver mais de um cabeçalho Host em uma requisição.

Alguns behaviors, como Deny, podem finalizar a execução das regras. Se uma sequência de regras inclui tal behavior, quaisquer regras ou behaviors que sigam este tipo de comportamento finalizador não serão executados.


Você pode executar o fazer o debug de regras criadas com Rules Engine usando GraphQL API, Data Stream ou Real-Time Events.


Estes são os limites default:

EscopoLimites
Criteria por regra5
Behaviors por regra10
Variables por criteria10

Contribuidores