NGINX JavaScript, também conhecido como NJS, é um módulo dinâmico para NGINX que permite a extensão da funcionalidade integrada usando a sintaxe JavaScript familiar. A linguagem NJS é um subconjunto de JavaScript, compatível com ES5 (ECMAScript 5.1 Strict Variant) com algumas extensões ES6 (ECMAScript 6) e mais recentes. Consulte compatibilidade para obter mais detalhes.
NGINX JavaScript é fornecido como dois módulos dinâmicos para NGINX (ngx_http_js_module e ngx_stream_js_module) e pode ser adicionado a qualquer instalação NGINX Open Source ou NGINX Plus compatível sem recompilação.
O módulo NJS permite que os administradores NGINX:
Veja exemplos e nossos diversos projetos desenvolvidos com a NJS:
Estende a funcionalidade do NGINX Plus para se comunicar diretamente com provedores de identidade compatíveis com OIDC, autenticando usuários e autorizando conteúdo entregue pelo NGINX Plus.
Implementação de referência do NGINX Plus como provedor de serviços para autenticação SAML.
Expõe o endpoint de métricas do Prometheus diretamente do NGINX Plus.
Dica
O NJS também pode ser usado com o servidor de aplicativos NGINX Unit. Saiba mais sobre a API de controle da unidade NGINX e como definir chamadas de função com NJS.
Siga estas etapas para baixar e instalar binários NGINX e NGINX JavaScript Linux pré-compilados. Você também pode optar por construir o módulo localmente a partir do código-fonte.
Siga este guia para adicionar o repositório oficial do pacote NGINX ao seu sistema e instalar o NGINX Open Source. Se você já possui o NGINX Open Source ou o NGINX Plus instalado, pule a parte de instalação do NGINX na última etapa.
Depois que o repositório for provisionado, você poderá instalar o NJS emitindo o seguinte comando:
sudo apt install nginx-module-njssudo yum install nginx-module-njssudo apk add nginx-module-njs@nginxsudo zypper install nginx-module-njsDica
O repositório de pacotes inclui um módulo alternativo que permite símbolos de depuração. Embora não seja recomendado para ambientes de produção, este módulo pode ser útil no desenvolvimento de configurações baseadas em NJS. Para baixar e instalar a versão de depuração do módulo, substitua o nome do módulo no comando anterior por nginx-module-njs-dbg .
Os scripts de instalação do pacote instalam dois módulos, suportando contextos NGINX http e stream .
ngx_http_js_module
Este módulo NJS permite a manipulação de dados transmitidos por HTTP.
ngx_stream_js_module
Este módulo NJS permite a manipulação de dados transmitidos através de protocolos de fluxo como TCP e UDP.
Por padrão, ambos os módulos são instalados no diretório /etc/nginx/modules .
O uso de NJS envolve habilitar o módulo, adicionar arquivos JavaScript com funções definidas e invocar funções exportadas em arquivos de configuração NGINX.
NGINX JavaScript é um módulo para NGINX Open Source ou NGINX Plus. Caso ainda não tenha feito isso, siga estas etapas para instalar o NGINX Open Source ou o NGINX Plus. Depois de instalado, certifique-se de que a instância NGINX esteja em execução e seja capaz de responder às solicitações HTTP.
Emita o seguinte comando para iniciar o NGINX:
sudo nginxcurl -I 127.0.0.1Você deverá ver a seguinte resposta:
HTTP/1.1 200 OK
Server: nginx/1.25.5 Depois de instalados, um (ou ambos) módulo(s) NJS devem ser incluídos no arquivo de configuração NGINX. Na maioria dos sistemas, o arquivo de configuração NGINX está localizado em /etc/nginx/nginx.conf por padrão.
sudo vi /etc/nginx/nginx.confUse a diretiva load_module no contexto de nível superior (“principal”) para ativar um (ou ambos) módulo(s).
load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so; Os arquivos de script NJS normalmente são nomeados com uma extensão .js e colocados no diretório /etc/nginx/njs/ . Geralmente são compostos por funções que são exportadas, disponibilizando-as nos arquivos de configuração do NGINX.
NJS fornece uma coleção de objetos com métodos e propriedades associados que não fazem parte das definições do ECMAScript. Veja a referência completa a esses objetos e como eles podem ser usados para estender e personalizar ainda mais o NGINX.
Aqui está um exemplo básico de "Hello World".
A função hello neste arquivo retorna um código de resposta de status HTTP 200 OK junto com a string "Hello World!", seguida por um feed de linha. A função é então exportada para uso em um arquivo de configuração NGINX.
Adicione este arquivo ao diretório /etc/nginx/njs :
function hello ( r ) {
r . return ( 200 , "Hello world!n" ) ;
}
export default { hello } Modificamos nossa configuração NGINX ( /etc/nginx/nginx.conf ) para importar o arquivo JavaScript e executar a função em circunstâncias específicas.
# Load the ngx_http_js_module module
load_module modules/ngx_http_js_module.so;
events {}
http {
# Set the path to our njs JavaScript files
js_path "/etc/nginx/njs/" ;
# Import our JavaScript file into the variable "main"
js_import main from http/hello.js;
server {
listen 80 ;
location / {
# Execute the "hello" function defined in our JavaScript file on all HTTP requests
# and respond with the contents of our function.
js_content main.hello;
}
}
}Para obter uma lista completa das diretivas njs, consulte as páginas de documentação dos módulos ngx_http_js_module e ngx_stream_js_module.
Dica
Uma versão mais detalhada deste e de outros exemplos pode ser encontrada no repositório oficial njs-examples.
O NGINX JavaScript é instalado com um utilitário de interface de linha de comando. A interface pode ser aberta como um shell interativo ou usada para processar sintaxe JavaScript a partir de arquivos predefinidos ou entrada padrão. Como o utilitário é executado de forma independente, objetos específicos do NGINX, como HTTP e Stream, não estão disponíveis em seu tempo de execução.
$ njs
>> globalThis
global {
njs: njs {
version : '0.8.4'
} ,
global : [ Circular ] ,
process : process {
argv : [ '/usr/bin/njs' ] ,
env : {
PATH : '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' ,
HOSTNAME : 'f777c149d4f8' ,
TERM : 'xterm' ,
NGINX_VERSION : '1.25.5' ,
NJS_VERSION : '0.8.4' ,
PKG_RELEASE : '1~buster' ,
HOME : '/root'
}
} ,
console : {
log : [ Function : native ] ,
dump : [ Function : native ] ,
time : [ Function : native ] ,
timeEnd : [ Function : native ]
} ,
print : [ Function : native ]
}
>>$ echo " 2**3 " | njs -q
8As etapas a seguir podem ser usadas para construir o NGINX JavaScript como um módulo dinâmico a ser integrado ao NGINX ou um binário independente para uso como um utilitário de interface de linha de comando.
Importante
Para construir o módulo para uso com o NGINX, você também precisará clonar, configurar e construir o NGINX seguindo as etapas descritas neste documento.
A maioria das distribuições Linux exigirá a instalação de várias dependências para construir NGINX e NGINX JavaScript. As instruções a seguir são específicas para o gerenciador de pacotes apt , amplamente disponível na maioria das distribuições Ubuntu/Debian e seus derivados.
sudo apt install gcc makesudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-devPara construir com QuickJS, você também precisará construir a biblioteca QuickJS:
git clone https://github.com/bellard/quickjs
cd quickjs
CFLAGS= ' -fPIC ' make libquickjs.aAviso
Este é o conjunto mínimo de bibliotecas de dependência necessárias para construir NGINX e NJS. Outras dependências podem ser necessárias se você optar por construir o NGINX com módulos adicionais. Monitore a saída do comando configure discutido nas seções a seguir para obter informações sobre quais módulos podem estar faltando.
Usando seu método preferido, clone o repositório JavaScript NGINX em seu diretório de desenvolvimento. Consulte Clonando um repositório GitHub para obter ajuda adicional.
https://github.com/nginx/njs.gitAs etapas a seguir são opcionais e necessárias apenas se você optar por construir o NJS como um utilitário independente.
Para usar o shell interativo NJS, você precisará instalar a biblioteca libedit-dev
sudo apt install libedit-devExecute os seguintes comandos no diretório raiz do seu repositório clonado:
./configureConstrua JavaScript NGINX:
make O utilitário agora deve estar disponível em
Clone o repositório de código-fonte NGINX em um diretório fora do repositório de origem NJS clonado anteriormente.
https://github.com/nginx/nginx.gitPara construir o NGINX JavaScript como um módulo dinâmico, execute os seguintes comandos no diretório raiz do repositório de código-fonte NGINX:
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx Para construir com suporte QuickJS, forneça o caminho de inclusão e da biblioteca usando as opções --with-cc-opt= e --with-ld-opt= :
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx --with-cc-opt= " -I" --with-ld-opt= " -L"
Aviso
Por padrão, este método construirá apenas o módulo ngx_http_js_module . Para usar NJS com o módulo NGINX Stream, você precisará habilitá-lo durante a etapa configure para que ele seja compilado com o binário NGINX. Fazer isso compilará automaticamente o módulo ngx_stream_js_module quando NJS for adicionado à compilação. Uma maneira de fazer isso é alterar a etapa configure para:
auto/configure --with-stream --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginxCompilar o módulo
makeDica
Para construir o NGINX com JavaScript NGINX incorporado em um único binário, altere a etapa configure para o seguinte:
auto/configure --add-module= < NJS_SRC_ROOT_DIR > /nginx Se construído como módulo(s) dinâmico(s), o(s) módulo(s) JavaScript NGINX estarão disponíveis no diretório
Como alternativa, você pode optar por instalar os binários NGINX e NGINX JavaScript criados emitindo o seguinte comando:
Importante
Se integrado ao binário NGINX como um módulo padrão (não dinâmico), este será o método mais fácil de instalação
make install Por padrão, o binário NGINX será instalado em /usr/local/nginx/sbin/nginx . Os módulos JavaScript NGINX serão copiados para /usr/local/nginx/modules/ .
As especificações técnicas do NJS são idênticas às do NGINX.
Consulte Sistemas operacionais e plataformas testados para obter uma lista completa de distribuições suportadas.
O NGINX JavaScript é compatível com todas as versões de código aberto do NGINX começando com nginx-1.14 e todas as versões do NGINX Plus começando com NGINX Plus R15.
Nós encorajamos você a se envolver conosco. Consulte o guia de contribuição para obter informações sobre como fazer perguntas, relatar problemas e contribuir com código.
Consulte nossa página de lançamento para acompanhar as atualizações.
Licença tipo BSD de 2 cláusulas
Documentação adicional disponível em: https://nginx.org/en/docs/njs/
©2024 F5, Inc. Todos os direitos reservados. https://www.f5.com/products/nginx
