<!-- review: finished -->

<a id="external-njs"></a>

# NJS

O módulo fornece integração da linguagem de programação JavaScript no
modelo de processamento de eventos do Angie e permite estender a funcionalidade do servidor usando
scripts JavaScript. Ele consiste em dois módulos:

- [HTTP JS](https://pt.angie.software//angie/docs/installation/external-modules/http_js.md#http-js) — para processamento de tráfego HTTP;
- [Stream JS](https://pt.angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js) — para processamento de tráfego TCP/UDP.

<a id="installation-19"></a>

## Instalação

Para [instalar](https://pt.angie.software//angie/docs/installation/index.md#install-packages) o módulo, use um dos
seguintes pacotes:

- Angie: `angie-module-njs` ou `angie-module-njs-light`;
- Angie PRO: `angie-pro-module-njs` ou `angie-pro-module-njs-light`.

<a id="features-1"></a>

## Recursos

O módulo estende a funcionalidade do servidor usando scripts escritos em njs,
um subconjunto de JavaScript, permitindo a implementação de lógica personalizada do lado do servidor
e muito mais:

- Controle de acesso complexo e verificações de segurança antes
  que a requisição chegue ao servidor com proxy.
- Manipulação de cabeçalhos de resposta.
- Escrita de manipuladores assíncronos flexíveis e filtros de conteúdo.

Também está disponível um utilitário de linha de comando independente que pode ser usado
independentemente do servidor para desenvolver e depurar scripts njs.

<a id="loading-the-module-19"></a>

## Carregando o Módulo

Carregando módulos no contexto `main{}`:

```nginx
load_module modules/ngx_http_js_module.so;    # para HTTP
load_module modules/ngx_stream_js_module.so;  # para Stream
```

<a id="usage"></a>

## Uso

A documentação detalhada está disponível nas seções para módulos individuais:

- [HTTP JS](https://pt.angie.software//angie/docs/installation/external-modules/http_js.md#http-js)
- [Stream JS](https://pt.angie.software//angie/docs/installation/external-modules/stream_js.md#stream-js)

<a id="security"></a>

## Segurança

O módulo não executa código dinâmico, especialmente código recebido da rede.
A única maneira de executar tal código usando njs é configurar a
diretiva `js_import` na configuração do servidor. O código JavaScript é carregado uma vez
na inicialização do servidor.

No modelo de ameaças do módulo, o código JavaScript é considerado uma fonte confiável assim como
o arquivo de configuração e os certificados do site. Na prática, isso significa o seguinte:

- divulgação de conteúdo de memória e outros problemas de segurança causados por
  modificação do código JavaScript não são considerados problemas de segurança,
  mas são tratados como bugs regulares;
- medidas devem ser tomadas para proteger o código JavaScript usado pelo módulo;
- se não houver diretivas `js_import` no arquivo de configuração,
  o servidor está protegido contra vulnerabilidades relacionadas ao JavaScript.

<a id="command-line-utility"></a>

## Utilitário de Linha de Comando

O utilitário de linha de comando **njs** ajuda a desenvolver e depurar scripts njs
e é instalado junto com os módulos. Diferentemente de quando o módulo é executado
como parte do Angie, os objetos Angie (`HTTP` e
`Stream`) não estão disponíveis ao usar o utilitário.

Exemplos de uso do utilitário:

```console
$ echo "2**3" | njs -q
8

$ njs

>> globalThis
global {
 njs: njs {
  version: '0.3.9'
 },
 global: [Circular],
 process: process {
  argv: [
   '/usr/bin/njs'
  ],
...
```

<a id="preloaded-objects"></a>

## Objetos Pré-carregados

Para cada requisição recebida, o módulo cria uma máquina virtual separada. Isso
fornece muitos benefícios, como consumo de memória previsível e
isolamento de requisições. No entanto, como todas as requisições são isoladas, se um manipulador
de requisição precisa acessar quaisquer dados, ele deve lê-los
por conta própria. Isso é ineficiente, especialmente quando o volume de dados é grande.

Para resolver este problema, foi introduzido um mecanismo para objetos compartilhados pré-carregados.
Tais objetos são criados como imutáveis e não possuem cadeias de protótipos: seus valores
não podem ser alterados, propriedades não podem ser adicionadas ou removidas.

Aqui estão alguns exemplos de trabalho com objetos pré-carregados em njs:

- Acessando propriedades por nome:
  ```javascript
  preloaded_object.prop_name
  preloaded_object[prop_name]
  ```
- Enumerando propriedades:
  ```javascript
  for (i in preloaded_object_name) {
        // ...
  }
  ```
- Aplicando métodos integrados não modificadores usando `call()`:
  ```javascript
  Array.prototype.filter.call(preloaded_object_name, ...)
  ```

<a id="api-reference"></a>

## Referência da API

Para uma referência completa de todos os objetos, métodos e propriedades njs, consulte:

- [Referência da API NJS](https://pt.angie.software//angie/docs/configuration/njs-reference.md#njs-reference)

<a id="additional-information-20"></a>

## Informações Adicionais

- Site oficial: [https://nginx.org/en/docs/njs/](https://nginx.org/en/docs/njs/)
- Exemplos de uso: [https://github.com/nginx/njs-examples/](https://github.com/nginx/njs-examples/)