Torne sua configuração NGINX ainda mais modular e reutilizável com njs 0.7.7

Desde a introdução do módulo NGINX JavaScript (njs) em2015 (sob seu nome original, nginScript) e tornando-o disponível para o público em geral em 2017<.htmla>, continuamos adicionando novos recursos e refinando nossa implementação em dezenas de atualizações de versão . Normalmente esperamos o lançamento do NGINX Plus para discutir os recursos de uma nova versão do NGINX JavaScript, mas estamos tão animados com a versão 0.7.7 que desta vez mal podemos esperar!

As melhorias significativas no njs 0.7.7 ajudam a tornar sua configuração NGINX ainda mais modular, organizada e reutilizável:

• Agora você pode declarar o código njs nos contextos em que ele se aplica, em vez de globalmente, aproximando seu código personalizado do ponto de uso.
• Ganchos no próprio código njs permitem que você modifique o comportamento dependendo do contexto de execução .
• O novo objeto fs.FileHandle torna as operações de arquivo mais eficientes .

Para saber mais sobre njs e revisar a lista de casos de uso para os quais fornecemos código de exemplo, leia Aproveitando o poder e a conveniência do JavaScript para cada solicitação com o módulo JavaScript NGINX em nosso blog.

Para uma lista completa de todos os novos recursos e correções de bugs no njs 0.7.7, consulte a documentação de Alterações .

Declarando código JavaScript e variáveis em contextos locais

Em versões anteriores do njs, você tinha que importar seu código JavaScript e declarar as variáveis relevantes – com as diretivas js_import , js_path , js_set e js_var – no contexto http ou stream de nível superior, o equivalente a declarar variáveis globais no topo de um arquivo principal. Mas as diretivas que realmente invocam as funções e variáveis JavaScript aparecem em um contexto filho – por exemplo, com a diretiva js_content em um bloco HTTP location{} e a diretiva js_access em um bloco Stream server{} . Isso cria dois problemas:

1. Para alguém que lê a configuração, as declarações nos contextos http e stream são essencialmente ruído, porque não há indicação de onde o código e as variáveis associados são realmente usados.
2. Não é óbvio no contexto filho onde o código e as variáveis foram importados e declarados. Embora recomendemos incluir os blocos http{} e stream{} somente no arquivo de configuração principal ( nginx.conf ) e usar a diretiva include para ler arquivos de configuração menores específicos de função dos diretórios /etc/nginx/conf.d e /etc/nginx/stream.d , a configuração do NGINX é flexível – você pode incluir blocos http{} e stream{} em vários arquivos. Isso pode ser especialmente problemático em ambientes onde várias pessoas trabalham na configuração do NGINX e nem sempre seguem as convenções estabelecidas.

No njs 0.7.7 e posteriores, você pode importar código e declarar variáveis nos contextos onde elas são usadas:

• HTTP –

  • Essas diretivas podem aparecer nos contextos de servidor e localização , bem como no contexto http :

    • js_import
    • caminho_js
    • js_conjunto
    • js_var

  • Essas diretivas podem aparecer no contexto if, bem como nos contextos location e limit_except :

    • js_body_filter
    • js_conteúdo
    • js_header_filter

• Stream – Essas diretivas podem aparecer no contexto do servidor e também no contexto do fluxo :

  • js_import
  • caminho_js
  • js_conjunto
  • js_var

Ter todas as configurações do njs para um caso de uso específico em um único arquivo também torna seu código mais modular e portátil.

Por exemplo, em versões anteriores do njs, quando você adicionava um novo script, era preciso alterar tanto o nginx.conf (adicionando js_import e possivelmente js_path , js_set e js_var ) quanto o arquivo onde a função JavaScript é invocada (aqui, jscode_local.conf ).

No njs 0.7.7 e posteriores, toda a configuração relacionada à função util está em um arquivo, jscode_integrated.conf :

Modificando o comportamento dependendo do contexto de execução

Vários novos recursos no njs 0.7.7 permitem que você modifique o comportamento do seu código JavaScript dependendo do contexto (fase de processamento) em que ele está sendo executado.

A propriedade HTTP r.internal

A propriedade HTTP r.internal é um sinalizador booleano definido como “true” para solicitações internas (que são manipuladas por blocos location{} que incluem a diretiva internal ). Você pode usar o sinalizador r.internal para bifurcar a lógica quando um script usa um manipulador de eventos geral que pode ser chamado em contextos internos e não internos.

Classificam-se como solicitações internas:

• Solicitações redirecionadas pelas diretivas error_page , index , random_index e try_files
• Solicitações redirecionadas pelo cabeçalho de resposta X-Accel-Redirect de um servidor upstream
• Sub-solicitações invocadas pelas diretivas auth_request e mirror , as diretivas no módulo ngx_http_addition_module ou o comando virtual Server Side Include (SSI) include (com suporte pelo módulo ngx_http_ssi_module )
• Solicitações alteradas pela diretiva rewrite

Método de fluxo s.send() aprimorado

Em versões anteriores do njs, o método Stream s.send() é dependente do contexto, porque a direção na qual ele envia dados é determinada pela localização (upstream ou downstream) do retorno de chamada onde o método é chamado. Isso funciona bem para retornos de chamada síncronos – para os quais s.send() foi originalmente projetado – mas falha com funções assíncronas como ngx.fetch() .

No njs 0.7.7 e posteriores, a direção é armazenada em um sinalizador interno separado, que s.send() pode então usar.

Operações de arquivo mais eficientes com o novo objeto fs.FileHandle()

O módulo do sistema de arquivos ( fs ) implementa operações em arquivos. O novo objeto FileHandle no módulo fs é um wrapper de objeto para um descritor de arquivo numérico. Instâncias do objeto FileHandle são criadas pelo método fs.promises.open() .

Use o objeto FileHandle para obter um descritor de arquivo, que pode ser usado posteriormente para:

• Executar funções como read() e write() no arquivo
• Abra um arquivo e execute leituras e gravações em um local especificado sem ler o arquivo inteiro

As seguintes propriedades de FileHandle foram implementadas (para obter informações sobre os argumentos obrigatórios e opcionais para cada propriedade, consulte a documentação ):

• arquivohandle.fd
• filehandle.read()
• filehandle.stat()
• filehandle.write()
• filehandle.write()
• filehandle.close()

Esses métodos foram atualizados para oferecer suporte a FileHandle (consulte a documentação vinculada para obter informações sobre os argumentos de cada método):

• fs.openSync()
• fs.promessas.abrir()
• fs.fstatSync()
• fs.readSync()
• fs.writeSync() (buffer)
• fs.writeSync() (sequência de caracteres)

Use njs para aprimorar sua configuração

Com o njs 0.7.7, facilitamos o trabalho e o compartilhamento do código njs para suas equipes. Os contextos estendidos para diretivas njs tornam ainda mais simples aprimorar a configuração do NGINX com código JavaScript personalizado. Você pode dar o primeiro passo em direção a um gateway de API, proxy reverso ou servidor web – e um que seja mais do que apenas outro middleware ou componente de ponta. Você pode torná-lo parte do seu aplicativo por meio de JavaScript, TypeScript ou módulos de nó de terceiros sem adicionar outro componente à sua pilha. Tudo o que você precisa é do NGINX!

Tem alguma dúvida?Participe do Slack da Comunidade NGINX e confira o canal #njs-code-review para saber mais, fazer perguntas e obter feedback sobre seu código njs.