JS#

O módulo é usado para implementar manipuladores em njs — um subconjunto da linguagem JavaScript.

Em nossos repositórios, o módulo é construído dinamicamente e está disponível como um pacote separado chamado angie-module-njs ou angie-pro-module-njs.

Nota

Uma versão leve do pacote, chamada ...-njs-light, também está disponível; no entanto, ela não pode ser usada junto com a versão regular.

Exemplo de Configuração#

http {
    js_import http.js;

    js_set $foo     http.foo;
    js_set $summary http.summary;
    js_set $hash    http.hash;

    resolver 10.0.0.1;

    server {
        listen 8000;

        location / {
            add_header X-Foo $foo;
            js_content http.baz;
        }

        location = /summary {
            return 200 $summary;
        }

        location = /hello {
            js_content http.hello;
        }

        location = /fetch {
            js_content                   http.fetch;
            js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
        }

        location = /crypto {
            add_header Hash $hash;
            return     200;
        }
    }
}

O arquivo http.js:

function foo(r) {
    r.log("hello from foo() handler");
    return "foo";
}

function summary(r) {
    var a, s, h;

    s = "JS summary\n\n";

    s += "Method: " + r.method + "\n";
    s += "HTTP version: " + r.httpVersion + "\n";
    s += "Host: " + r.headersIn.host + "\n";
    s += "Remote Address: " + r.remoteAddress + "\n";
    s += "URI: " + r.uri + "\n";

    s += "Headers:\n";
    for (h in r.headersIn) {
        s += "  header '" + h + "' is '" + r.headersIn[h] + "'\n";
    }

    s += "Args:\n";
    for (a in r.args) {
        s += "  arg '" + a + "' is '" + r.args[a] + "'\n";
    }

    return s;
}

function baz(r) {
    r.status = 200;
    r.headersOut.foo = 1234;
    r.headersOut['Content-Type'] = "text/plain; charset=utf-8";
    r.headersOut['Content-Length'] = 15;
    r.sendHeader();
    r.send("nginx");
    r.send("java");
    r.send("script");

    r.finish();
}

function hello(r) {
    r.return(200, "Hello world!");
}

async function fetch(r) {
    let results = await Promise.all([ngx.fetch('https://example.com/'),
                                     ngx.fetch('https://example.org/')]);

    r.return(200, JSON.stringify(results, undefined, 4));
}

async function hash(r) {
    let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host);
    r.setReturnValue(Buffer.from(hash).toString('hex'));
}

export default {foo, summary, baz, hello, fetch, hash};

Diretivas#

js_body_filter#

Sintaxe

js_body_filter function | module.function [buffer_type=string | buffer];

Padrão

—

Contexto

location, if in location, limit_except

Define uma função njs como filtro do corpo da resposta. A função de filtro é chamada para cada bloco de dados do corpo da resposta com os seguintes argumentos:

r

o objeto requisição HTTP

data

o bloco de dados recebido, pode ser uma string ou Buffer dependendo do valor buffer_type, por padrão é uma string.

flags

um objeto com as seguintes propriedades: - last — um valor booleano, true se data é o último buffer

A função de filtro pode passar sua própria versão modificada do bloco de dados de entrada para o próximo filtro de corpo chamando r.sendBuffer(). Por exemplo, para transformar todas as letras minúsculas no corpo da resposta:

function filter(r, data, flags) {
    r.sendBuffer(data.toLowerCase(), flags);
}

Para parar a filtragem (os blocos de dados seguintes serão passados para o cliente sem chamar js_body_filter), r.done() pode ser usado.

Se a função de filtro alterar o comprimento do corpo da resposta, então é necessário limpar o cabeçalho de resposta Content-Length (se houver) em js_header_filter para forçar a codificação de transferência em blocos.

Nota

Como o manipulador js_body_filter retorna seu resultado imediatamente, ele suporta apenas operações síncronas. Assim, operações assíncronas como r.subrequest() ou setTimeout() não são suportadas.

js_content#

Sintaxe

js_content function | module.function;

Padrão

—

Contexto

location, if in location, limit_except

Define uma função njs como manipulador de conteúdo de localização. Funções de módulo podem ser referenciadas.

js_context_reuse#

Sintaxe

js_context_reuse number;

Padrão

js_context_reuse 128;

Contexto

http, server, location

Define o número máximo de contextos JS a serem reutilizados para o mecanismo QuickJS. Cada contexto é usado para uma única requisição. O contexto finalizado é colocado em um pool de contextos reutilizáveis. Se o pool estiver cheio, o contexto é destruído.

js_engine#

Sintaxe

js_engine njs | qjs;

Padrão

js_engine njs;

Contexto

http, server, location

Define o mecanismo JavaScript a ser usado para scripts njs. O parâmetro njs define o mecanismo njs, também usado por padrão. O parâmetro qjs define o mecanismo QuickJS.

js_fetch_buffer_size#

Sintaxe

js_fetch_buffer_size size;

Padrão

js_fetch_buffer_size 16k;

Contexto

http, server, location

Define o tamanho do buffer usado para leitura e escrita com Fetch API.

js_fetch_ciphers#

Sintaxe

js_fetch_ciphers ciphers;

Padrão

js_fetch_ciphers HIGH:!aNULL:!MD5;

Contexto

http, server, location

Especifica as cifras habilitadas para conexões HTTPS com Fetch API. As cifras são especificadas no formato compreendido pela biblioteca OpenSSL.

A lista de cifras depende da versão do OpenSSL instalada. A lista completa pode ser visualizada usando o comando openssl ciphers.

js_fetch_max_response_buffer_size#

Sintaxe

js_fetch_max_response_buffer_size size;

Padrão

js_fetch_max_response_buffer_size 1m;

Contexto

http, server, location

Define o tamanho máximo da resposta recebida com Fetch API.

js_fetch_protocols#

Sintaxe

js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

Padrão

js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;

Contexto

http, server, location

Habilita os protocolos especificados para conexões HTTPS com Fetch API.

js_fetch_timeout#

Sintaxe

js_fetch_timeout time;

Padrão

js_fetch_timeout 60s;

Contexto

http, server, location

Define um timeout para leitura e escrita para Fetch API. O timeout é definido apenas entre duas operações sucessivas de leitura/escrita, não para toda a resposta. Se nenhum dado for transmitido dentro deste tempo, a conexão é fechada.

js_fetch_trusted_certificate#

Sintaxe

js_fetch_trusted_certificate file;

Padrão

—

Contexto

http, server, location

Especifica um arquivo com certificados CA confiáveis no formato PEM usado para verificar o certificado HTTPS com Fetch API.

js_fetch_verify#

Sintaxe

js_fetch_verify on | off;

Padrão

js_fetch_verify on;

Contexto

http, server, location

Habilita ou desabilita a verificação do certificado do servidor HTTPS com Fetch API.

js_fetch_verify_depth#

Sintaxe

js_fetch_verify_depth number;

Padrão

js_fetch_verify_depth 100;

Contexto

http, server, location

Define a profundidade de verificação na cadeia de certificados HTTPS com Fetch API.

js_fetch_keepalive#

Sintaxe

js_fetch_keepalive connections;

Padrão

js_fetch_keepalive 0;

Contexto

http, server, location

Ativa o cache para conexões com servidores de destino. Quando o valor é maior que 0, habilita conexões keepalive para Fetch API.

O parâmetro connections define o número máximo de conexões keepalive ociosas para servidores de destino que são preservadas no cache de cada processo worker. Quando esse número é excedido, as conexões usadas menos recentemente são fechadas.

Exemplo:

location /fetch {
    js_fetch_keepalive 32;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
    js_content main.fetch_handler;
}

js_fetch_keepalive_requests#

Sintaxe

js_fetch_keepalive_requests number;

Padrão

js_fetch_keepalive_requests 1000;

Contexto

http, server, location

Define o número máximo de requisições que podem ser atendidas através de uma conexão keepalive com Fetch API. Após o número máximo de requisições ser feito, a conexão é fechada.

Fechar conexões periodicamente é necessário para liberar alocações de memória por conexão. Portanto, usar um número máximo de requisições muito alto pode resultar em uso excessivo de memória e não é recomendado.

js_fetch_keepalive_time#

Sintaxe

js_fetch_keepalive_time time;

Padrão

js_fetch_keepalive_time 1h;

Contexto

http, server, location

Limita o tempo máximo durante o qual as requisições podem ser processadas através de uma conexão keepalive com Fetch API. Após esse tempo ser atingido, a conexão é fechada após o processamento da requisição subsequente.

js_fetch_keepalive_timeout#

Sintaxe

js_fetch_keepalive_timeout time;

Padrão

js_fetch_keepalive_timeout 60s;

Contexto

http, server, location

Define um timeout durante o qual uma conexão keepalive ociosa para um servidor de destino permanecerá aberta com Fetch API.

js_header_filter#

Sintaxe

js_header_filter function | module.function;

Padrão

—

Contexto

location, if in location, limit_except

Define uma função njs como filtro de cabeçalho de resposta. A diretiva permite alterar campos de cabeçalho arbitrários de um cabeçalho de resposta.

Nota

Como o manipulador js_header_filter retorna seu resultado imediatamente, ele suporta apenas operações síncronas. Assim, operações assíncronas como r.subrequest() ou setTimeout() não são suportadas.

js_import#

Sintaxe

js_import módulo.js | nome_exportação from módulo.js;

Padrão

—

Contexto

http, server, location

Importa um módulo que implementa manipuladores de location e variável em njs. O nome_exportação é usado como namespace para acessar funções do módulo. Se o nome_exportação não for especificado, o nome do módulo será usado como namespace.

js_import http.js;

Aqui, o nome do módulo http é usado como namespace ao acessar exportações. Se o módulo importado exporta foo(), http.foo é usado para se referir a ele.

Várias diretivas js_import podem ser especificadas.

js_path#

Sintaxe

js_path caminho;

Padrão

—

Contexto

http, server, location

Define um caminho adicional para módulos njs.

js_periodic#

Sintaxe

js_periodic module.function [interval=\ time] [jitter=\ number] [worker_affinity=\ mask];

Padrão

—

Contexto

location

Especifica um manipulador de conteúdo a ser executado em intervalos regulares. O manipulador recebe um objeto de sessão como seu primeiro argumento, e também tem acesso a objetos globais como ngx.

O parâmetro opcional interval define o intervalo entre duas execuções consecutivas, por padrão, 5 segundos.

O parâmetro opcional jitter define o tempo dentro do qual o manipulador de conteúdo da localização será atrasado aleatoriamente, por padrão, não há atraso.

Por padrão, o js_handler é executado no processo worker 0. O parâmetro opcional worker_affinity permite especificar processos worker particulares onde o manipulador de conteúdo da localização deve ser executado. Cada conjunto de processos worker é representado por uma máscara de bits de processos worker permitidos. A máscara all permite que o manipulador seja executado em todos os processos worker.

Exemplo:

example.conf:

location @periodics {
    # para ser executado em intervalos de 1 minuto no processo worker 0
    js_periodic main.handler interval=60s;

    # para ser executado em intervalos de 1 minuto em todos os processos worker
    js_periodic main.handler interval=60s worker_affinity=all;

    # para ser executado em intervalos de 1 minuto nos processos worker 1 e 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}

example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://example.com/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}

js_preload_object#

Sintaxe

js_preload_object nome.json | nome from arquivo.json;

Padrão

—

Contexto

http, server, location

Pré-carrega um objeto imutável no momento da configuração. O nome é usado como nome da variável global através da qual o objeto está disponível no código njs. Se o nome não for especificado, o nome do arquivo será usado em seu lugar.

js_preload_object map.json;

Aqui, o map é usado como nome ao acessar o objeto pré-carregado.

Várias diretivas js_preload_object podem ser especificadas.

js_set#

Sintaxe

js_set $variable function | module.function [nocache];

Padrão

—

Contexto

http, server, location

Define uma função njs para a variável especificada. Funções de módulo podem ser referenciadas.

A função é chamada quando a variável é referenciada pela primeira vez para uma determinada requisição. O momento exato depende de uma fase na qual a variável é referenciada. Isso pode ser usado para executar alguma lógica não relacionada à avaliação de variável. Por exemplo, se a variável é referenciada apenas na diretiva log_format, seu manipulador não será executado até a fase de log. Este manipulador pode ser usado para fazer alguma limpeza logo antes da requisição ser liberada.

Desde o njs 0.8.6, se um argumento opcional nocache for especificado, o manipulador é chamado toda vez que é referenciado. Devido às limitações atuais do módulo rewrite, quando uma variável nocache é referenciada pela diretiva set, seu manipulador deve sempre retornar um valor de comprimento fixo.

Nota

Como o manipulador js_set retorna seu resultado imediatamente, ele suporta apenas operações síncronas. Assim, operações assíncronas como r.subrequest() ou setTimeout() não são suportadas.

js_shared_dict_zone#

Sintaxe

js_shared_dict_zone zone=name:size [timeout=time] [type=string | number] [evict] [state=file];

Padrão

—

Contexto

http

Define o name e size da zona de memória compartilhada que mantém o dicionário chave-valor compartilhado entre processos worker.

type

parâmetro opcional, permite redefinir o tipo de valor para number; por padrão, o dicionário compartilhado usa string para chaves e valores

timeout

parâmetro opcional, define o tempo após o qual todas as entradas do dicionário compartilhado são removidas da zona

evict

parâmetro opcional, remove o par chave-valor mais antigo quando o armazenamento da zona está esgotado

state

parâmetro opcional, especifica um arquivo que mantém o estado do dicionário compartilhado em formato JSON e o torna persistente entre reinicializações do nginx

Exemplos:

example.conf:
    # Cria um dicionário de 1MB com valores string,
    # pares chave-valor são removidos após 60 segundos de inatividade:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Cria um dicionário de 512KB com valores string,
    # par chave-valor mais antigo é removido quando a zona transborda:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Cria um dicionário persistente de 32KB com valores numéricos:
    js_shared_dict_zone zone=num:32k type=number;

    # Cria um dicionário de 1MB com valores string e estado persistente:
    js_shared_dict_zone zone=persistent:1M state=/tmp/dict.json;

example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function delete(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }

js_var#

Sintaxe

js_var $variável [valor];

Padrão

—

Contexto

http, server, location

Declara uma variável gravável. O valor pode conter texto, variáveis e sua combinação. A variável não é sobrescrita após um redirecionamento, diferentemente de variáveis criadas com a diretiva set.

Argumento de Requisição#

Cada manipulador HTTP njs recebe um argumento, um objeto request.