Um testador de expressões regulares para NGINX e NGINX Plus

Rick NelsonVice-presidente regional de Engenharia de Soluções

Enquanto trabalhava em uma expressão regular (regex) para usar com o NGINX, tive uma ideia de como testar facilmente uma regex em uma configuração real do NGINX. (O testador de regex funciona da mesma forma para o NGINX Open Source e o NGINX Plus, e, para facilitar a leitura, vou me referir simplesmente ao NGINX neste post.)

O suporte a expressões regulares é um dos recursos avançados do NGINX, mas elas podem ser complexas e difíceis de configurar corretamente, especialmente se você não trabalha com elas com frequência. O NGINX permite o uso de expressões regulares em várias partes de uma configuração, como locais, mapas, reescritas e nomes de servidor. O testador descrito aqui destina-se a expressões regulares usadas em locais e mapas.

Existem outros testadores de expressões regulares gratuitos e online que funcionam bem para a maioria das expressões, mas o NGINX usa alguns atalhos não padronizados e otimizados para aplicações web. Por exemplo, não é necessário usar um caractere de escape para a barra (/) em um URI, como seria em uma expressão regular padrão. Além disso, ao usar uma expressão regular em um mapa, você especifica qual valor deve ser definido quando houver uma correspondência. Com outros testadores de expressões regulares, talvez seja necessário modificar a expressão ou, no caso de um mapa, deduzir qual valor será definido. Além disso, é sempre bom poder testar uma expressão regular usando o mecanismo de expressões regulares real no ambiente real.

Observações:

• O NGINX usa Expressões Regulares Compatíveis com Perl (PCRE), e este artigo pressupõe um conhecimento básico tanto do NGINX quanto de expressões regulares. Explicar como criar expressões regulares está fora do escopo deste artigo e, infelizmente, não podemos responder a outras perguntas na seção de comentários sobre como fazer isso. Há vários sites que oferecem ferramentas ou documentação para a criação de expressões regulares. Dois que consideramos úteis são:
  • regex101.com
  • Regular-expressions.info
• O testador processa expressões regulares em dois contextos – blocos map{} e blocos HTTP location{} – e, abaixo, há uma breve explicação de como as expressões regulares funcionam em cada caso. Explicar como o NGINX processa expressões regulares em todos os contextos está fora do escopo deste post; consulte nossa documentação:
  • Verificações de integridade:
    • HTTP – nginx.org e Guia de Administração do NGINX Plus
    • TCP – nginx.org e Guia de Administração do NGINX Plus
    • UDP – nginx.org e Guia de Administração do NGINX Plus
  • location{} blocos – nginx.org e Guia de Administração do NGINX Plus
  • map{} blocos – nginx.org
  • Reescritas de URI – nginx.org e Guia do administrador do NGINX Plus
  • Nomes de servidores virtuais – nginx.org e Guia do administrador do NGINX Plus
• O testador foi intencionalmente projetado para ser o mais simples possível e cumprir um único propósito: testar expressões regulares conforme escritas pelo usuário, usando o mecanismo de expressões regulares real do NGINX para mapas e locais HTTP. Por isso, você precisa fornecer apenas o mínimo de informações necessário para criar uma configuração funcional do NGINX. Não temos planos de adicionar recursos (como validar a expressão regular antes do teste), pois isso violaria o princípio norteador da simplicidade. É claro que teremos prazer em corrigir bugs; envie-os pela aba Issues do nosso repositório no GitHub.

Visão geral

Antes de entrarmos nos detalhes do testador de expressões regulares, vamos primeiro discutir como elas podem ser usadas em blocos location e mapas do NGINX.

Locais

As expressões regulares nos blocos location{} do NGINX têm o seguinte formato:

location regex {
    #...
}

Por exemplo, um bloco location{} com a seguinte expressão regular processa todas as solicitações PHP com um URI que termina em myapp/nome_do_arquivo.php, como /test/myapp/hello.php e /myapp/hello.php. O asterisco após o til (~*) faz com que a correspondência não diferencie maiúsculas de minúsculas.

location ~* /myapp/.+\.php$ {
    #...
}

O NGINX e o testador de expressões regulares oferecem suporte a grupos de captura posicionais em blocos location{}. No exemplo a seguir, o primeiro grupo captura tudo o que vem antes do nome do arquivo PHP, e o segundo captura o nome do arquivo PHP:

location ~* (.*/myapp)/(.+\.php)$ {
    #...
}

Para o URI /myapp/hello.php, a variável $1 é definida como /myapp e $2 é definida como hello.php.

O NGINX também oferece suporte a grupos de captura nomeados:

location ~* (?<begin>.*myapp)/(?<end>.+\.php)$ {
    #...
}

Nesse caso, a variável $begin é definida como /myapp e $end é definida como hello.php.

O testador de expressões regulares oferece suporte a grupos de captura nomeados, mas os trata como grupos de captura posicionais na saída, exibindo seus números ordinais em vez dos nomes.

Mapas

Os blocos map{} do NGINX que usam expressões regulares têm o seguinte formato:

map variable-to-test variable-to-set {
    regex1 value-to-set-if-match;
    regex2 value-to-set-if-match;
    #...
    regexN value-to-set-if-match;
    default value-to-set-if-no-match;
}

Por exemplo, este bloco map{} define a variável $isphp como 1 se o URI (conforme registrado na variável $uri) terminar em .php, e como 0 caso contrário (a correspondência diferencia maiúsculas de minúsculas):

map $uri $isphp {
    ~\.php$ 1;
    default 0;
}

Para mapas, tanto o NGINX quanto o testador de expressões regulares oferecem suporte a grupos de captura posicionais e nomeados.

Por exemplo, os dois mapeamentos a seguir definem a variável $fileext com o valor da extensão do arquivo, que, neste exemplo, também é capturado como $1:

map $uri $fileext {
    ~*.+\.(.+)$  $1;
    default      '';
}

E como $ext neste exemplo:

map $uri $fileext {
    ~*.+\.(?<ext>.+)$  $ext;
    default            '';
}

Você pode usar o testador de expressões regulares para blocos map{} nos contextos http{} e stream{} porque a sintaxe e o comportamento dos mapas são os mesmos em ambos os contextos. No entanto, se o seu mapa estiver no contexto stream{} você poderá usar apenas o bloco map{} da saída do testador. Consulte a observação abaixo para obter mais detalhes.

O testador de expressões regulares

O testador de expressões regulares é implementado em um contêiner Docker com o NGINX e o NGINX Unit instalados. O NGINX Unit disponibiliza duas versões de uma página PHP: uma para expressões regulares em blocos location{} e outra para expressões regulares em blocos map{}. As duas páginas solicitam diferentes entradas ao usuário:

• Página de localização:
  • A expressão regular
  • Diferenciação entre maiúsculas e minúsculas
  • O URI
• Página do mapa:
  • A expressão regular
  • Diferenciação entre maiúsculas e minúsculas
  • O valor a ser testado (o valor da variável que é o primeiro parâmetro da diretiva map)
  • O valor a ser definido na variável especificada como o segundo parâmetro da diretiva map directive

Depois de fornecer as informações, clique no botão Testar. O testador gera o arquivo de configuração do NGINX necessário, a configuração é recarregada e uma solicitação é enviada para testar a expressão regular. Em seguida, os resultados são exibidos e indicam se houve uma correspondência. Em caso afirmativo, na página Testador de localização, os valores dos grupos de captura são exibidos e, na página Testador de mapa, é informado o valor definido pelo mapa.

Exemplo da página de localização

Este exemplo mostra os resultados de um teste sem diferenciação entre maiúsculas e minúsculas da expressão regular (.*myapp)/(.+\.php)$ em relação ao URI /myapp/hello.php:

Exemplo de página de mapa

Este exemplo mostra os resultados de um teste sem diferenciação entre maiúsculas e minúsculas da expressão regular .+\.(?<ext>.*)$ em relação ao valor /myapp/hello.php, usando o grupo de captura nomeado $ext como o valor a ser definido:

Observação: Se o seu mapa estiver no contexto stream{}، você poderá usar apenas o bloco map{} da saída na sua configuração. O bloco server{} não é válido porque inclui um bloco location{}، que não é compatível com o contexto stream{}.

Conclusão

Como você pode ver, a configuração do NGINX é bastante curta e simples. O trabalho pesado é feito pela página PHP, que gera o arquivo de configuração necessário do NGINX com base nos valores inseridos pelo usuário, recarrega o NGINX, envia uma solicitação ao NGINX e exibe os resultados.

Você pode experimentar o testador de expressões regulares: todo o código está disponível em nosso repositório no GitHub (https://github.com/nginxinc/NGINX-Demos/tree/master/nginx-regex-tester).

Para facilitar a configuração e a execução do testador de expressões regulares, todos os arquivos necessários estão incluídos. Para criar a imagem do Docker e o contêiner, basta executar:

$ docker-compose up -d

Em seguida, acesse http://Docker-host/regextester.php no seu navegador.

Espero que você considere o tester útil ao trabalhar com expressões regulares e que ele lhe dê uma ideia do poder, da flexibilidade e da simplicidade do NGINX.

Para experimentar o testador de expressões regulares com o NGINX Plus, comece hoje mesmo sua avaliação gratuita de 30 dias ou entre em contato conosco para conversar sobre seus casos de uso.

Sobre o autor

Rick NelsonVice-presidente regional de Engenharia de Soluções

Mais publicações de Rick Nelson