Class: Request | nginstack

new Request()

Classe utilizada para acessar as informações contidas em uma requisição HTTP.

Esta classe é criada automaticamente pelo sistema quando um ambiente JavaScript está atendendo uma requisição HTTP. Neste caso, é criada a variável global request. Sessões que não tem relação com um atendimento HTTP, como ambientes do Scheduler, não possuem esta variável global.

Classe também publicada por meio da variável global Request.

Members

acceptLanguage :string

Cabeçalho HTTP que indica as línguas desejadas pelo requisitante.

Type:

string

body :module:@nginstack/engine/lib/http/RequestBody~RequestBody

Corpo da requisição.

Type:

module:@nginstack/engine/lib/http/RequestBody~RequestBody

clientAddress :string

Endereço IP do computador do cliente final da requisição, normalmente o navegador do usuário.

Quando a requisição passa por proxies ou balanceadores de carga, o endereço é obtido dos cabeçalhos "X-Forwarded-For" ou "Forwarded" informados por eles. Caso os dois sejam informados, prevalece o "X-Forwarded-For". Esses cabeçalhos somente são confiáveis quando enviados por um proxy registrado no cadastro "Administração do sistema > Servidores > Proxies confiáveis", o que é indicado pela propriedade clientAddressVerified. Sem cabeçalhos de encaminhamento, é igual a remoteAddress.

Type:

string

See:

Example

// Requisição com "X-Forwarded-For: 203.0.113.5" enviada por um proxy confiável
request.clientAddress; // => '203.0.113.5'
request.clientAddressVerified; // => true

clientAddressVerified :boolean

Indica se o endereço do cliente, obtido pela propriedade clientAddress, é confiável.

É falso quando o endereço foi informado pelos cabeçalhos de encaminhamento e não pode ser verificado: quando eles foram enviados por um computador que não está registrado no cadastro de proxies confiáveis, quando o endereço antecede um elemento da cadeia sem endereço válido, como "unknown", ou quando os cabeçalhos "X-Forwarded-For" e "Forwarded" indicam clientes diferentes. Nesses casos, o endereço pode ter sido forjado pelo próprio cliente e não deve ser utilizado em validações de segurança.

Type:

boolean

See:

#clientAddress

content :string

Conteúdo enviado pelo cliente no corpo da requisição.

Importante: essa propriedade aloca o corpo da requisição em memória e não deve ser utilizada em requisições de tamanho elevado. Tentar ler o corpo de uma requisição com mais de 20MB irá gerar um erro. Utilize o método #read para tratar requisições maiores.

Type:

string

See:

contentLength :number

Tamanho em bytes do conteúdo contido no corpo da requisição informado pelo cliente por meio do cabeçalho content-length.

O valor desta propriedade poderá ser diferente do tamanho de #content no caso de conteúdos textuais codificados em UTF-8. O Engine converterá automaticamente esses conteúdos para ISO-8859-1, o que poderá provocar uma redução do tamanho do conteúdo disponibilizado pela propriedade #content. Nesses casos, o método #read pode ser utilizado para ter acesso ao conteúdo original enviado pelo cliente.

Type:

number

See:

contentType :string

Tipo de mídia do conteúdo enviado pelo cliente.

Ver http://www.iana.org/assignments/media-types/media-types.xhtml para mais detalhes.

Type:

string

See:

cookieCount :number

Quantidade de cookies enviados na requisição.

Type:

number

forwardedFor :string

Endereços da cadeia de encaminhamento da requisição, separados por vírgula, do cliente final ao último proxy, conforme informados pelos cabeçalhos "X-Forwarded-For" ou "Forwarded". Caso os dois sejam informados, prevalece o "X-Forwarded-For". Os endereços são normalizados: as portas e os colchetes dos endereços IPv6 são removidos. Os identificadores ofuscados ou "unknown" do cabeçalho "Forwarded" são mantidos como informados, e um elemento sem o parâmetro "for" é representado por "unknown". É vazio quando a requisição não informa esses cabeçalhos.

O endereço do computador que realizou a requisição, normalmente o último proxy, não faz parte da cadeia e é obtido pela propriedade remoteAddress. Somente os endereços acrescentados por proxies confiáveis são garantidos. Os demais podem ter sido forjados pelo cliente. Para obter o endereço do cliente final, utilize a propriedade clientAddress e verifique se ele é confiável pela propriedade clientAddressVerified.

Type:

string

See:

Example

// Requisição com "Forwarded: for=203.0.113.5;proto=https, for=\"[2001:db8::1]:4711\""
request.forwardedFor; // => '203.0.113.5, 2001:db8::1'

forwardedHost :string

Host solicitado pelo cliente ao primeiro proxy da requisição, conforme informado pelos cabeçalhos "X-Forwarded-Host" ou "Forwarded". É vazio quando a requisição não passou por um proxy que informe o host.

O valor é apenas informativo, pois esses cabeçalhos podem ter sido forjados pelo cliente.

Type:

string

forwardedProto :string

Protocolo utilizado pelo cliente para acessar o primeiro proxy da requisição, como "https", conforme informado pelos cabeçalhos "X-Forwarded-Proto" ou "Forwarded". É vazio quando a requisição não passou por um proxy que informe o protocolo.

O valor é apenas informativo, pois esses cabeçalhos podem ter sido forjados pelo cliente.

Type:

string

See:

#isHttps

headers :Record.<string, string>

Cabeçalhos informados na requisição HTTP representados por um objeto cujos nomes de propriedades são os nomes dos campos de cabeçalho, normalizados em caixa baixa, e os valores das propriedades são os valores dos campos de cabeçalho.

Type:

Record.<string, string>

Example

// Script que exibe todos os cabeçalhos enviados pelo navegador
const headers = request.headers;
for (const name in headers){
   response.write(name + ": " + headers[name] + "<br>");
}

host :string

Nome do servidor solicitado pelo usuário. Caso a URL informada seja "www.company.com/index.htm", o host será "www.company.com".

Type:

string

httpMessage :string

Mensagem HTTP completa.

Type:

string

localAddress :string

Endereço IP da interface de rede que atendeu a requisição HTTP.

Type:

string

See:

localHost :string

Nome associado ao endereço IP da interface de rede que atendeu a requisição HTTP.

Type:

string

See:

localPort :number

Porta TCP que atendeu a requisição HTTP.

Type:

number

See:

method :string

Indica o método HTTP que será sendo invocado. Poderá ser: GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.

Type:

string

methodType :string

Indica o método HTTP que será sendo invocado. Poderá ser: GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.

Type:

string

Deprecated:

Utilize #method.

parameterCount :number

Quantidade de parâmetros enviados na requisição. Parâmetros podem ser enviados no corpo da requisição ou na query string da URL.

Type:

number

params :Object.<string>

Retorna um objeto com todos os parâmetros informados na "query string" da URL da requisição. Para possibilitar a pesquisa, os nomes dos parâmetros serão em minúsculo no objeto retornado. Caso haja um parâmetro definido mais de uma vez, será considerado o último valor informado na URL. Mais detalhes em http://en.wikipedia.org/wiki/Query_string.

Type:

Object.<string>

path :string

Arquivo requisitado. Caso a URL informada seja "www.company.com.br/index.htm", o path será "/index.htm".

Type:

string

readTimeout :number

Tempo máximo de espera em milissegundos para a leitura do conteúdo. O timeout de leitura será empregado no método #read quando for solicitada uma quantidade de dados superior ao que já foi recebido do cliente.

Type:

number

referer :string

Arquivo que originou a requisição. Exemplo: se o cliente abrir a página /index.htm e nesta for requisitado um segundo documento, o referer deste último será /index.htm.

Type:

string

remoteAddress :string

Endereço IP do computador que realizou a requisição HTTP.

Quando a requisição passa por proxies ou balanceadores de carga, este é o endereço do último deles. Utilize a propriedade clientAddress para obter o endereço do cliente final.

Type:

string

See:

remoteHost :string

Nome do computador que realizou a requisição HTTP.

Type:

string

See:

remotePort :number

Porta TCP utilizada pelo computador remoto para realizar a requisição HTTP.

Type:

number

See:

userAgent :string

Identificação do aplicativo cliente que fez a requisição HTTP.

Type:

string

xml :string

Representação DOM dos dados enviados pelo browser para o servidor. Esta propriedade somente estará preenchida quando o tipo dos dados enviados for "text/xml". Para outros tipos, será null.

Type:

string

See:

Methods

getCookie(indexOrName)

Obtém o valor do cookie informado.

Parameters:

Name	Type	Description
`indexOrName`	number\| string	Índice ou nome do cookie. O índice é um valor dentro da faixa de 0 a #cookieCount - 1.

See:

#cookieCount

getCookieName(index)

Obtém o nome do cookie na posição informada.

Parameters:

Name	Type	Description
`index`		Índice ou nome do cookie. O índice é um valor dentro da faixa de 0 a #cookieCount - 1.

See:

#cookieCount

getHeader()

Lê o conteúdo do cabeçalho informado da requisição HTTP. Retorna vazio, caso o cabeçalho não tenha sido preenchido pelo cliente.

Returns:

Type: string

Example

// Verifica se o navegador aceita a compressão da resposta utilizando o
// algoritmo Gzip
var encodings = request.getHeader("Accept-Encoding")
encodings = encodings.toLowerCase().split(",")
var useGzip = encodings.indexOf("gzip") >= 0

getParameter(indexOrName)

Obtém o valor do parâmetro informado.

Parameters:

Name	Type	Description
`indexOrName`	number\| string	Índice ou nome do parâmetro. O índice é um valor dentro da faixa de 0 a #parameterCount - 1.

Deprecated:

See:

#parameterCount

Returns:

Valor do parâmetro.

Type: string

getParameterName(index)

Obtém o nome do parâmetro informado.

Parameters:

Name	Type	Description
`index`	number\| string	Índice do parâmetro. O índice é um valor dentro da faixa de 0 a #parameterCount - 1.

See:

#parameterCount

isHttps( [trustProxy])

Avalia se a requisição foi estabelecida utilizando o protocolo HTTPS.

A conexão HTTPS pode ter sido estabelecida diretamente até o Engine ou indiretamente via um proxy reverso configurado com o certificado digital. Neste último caso, o tráfego entre o proxy reverso e o Engine pode ter sido estabelecido via HTTP.

Por padrão, o cabeçalho "x-forwarded-proto" é aceito de qualquer origem, sem depender do cadastro de proxies confiáveis, para que ambientes atrás de balanceadores de carga funcionem sem configuração adicional. Um cliente que forje esse cabeçalho altera apenas a resposta da sua própria requisição. Informe false em trustProxy quando o resultado for utilizado em uma decisão de segurança que não possa depender de um valor informado pelo cliente.

Parameters:

Name	Type	Argument	Default	Description
`trustProxy`	boolean	<optional>	`true`	Indica se o cabeçalho "x-forwarded-proto" recebido deve ser considerado como confiável para avaliar se o protocolo utilizado foi o HTTPS.

Returns:

True se a conexão for HTTPS.

Type: boolean

param(name, opt_default)

Obtém um parâmetro informado na "query string" da URL da requisição. Mais detalhes do formato em http://en.wikipedia.org/wiki/Query_string.

Parameters:

Name	Type	Description
`name`	string	Nome do parâmetro.
`opt_default`	*	Valor padrão a ser utilizado caso o parâmetro não tenha sido informado na URL. Caso não seja informado, será considerado null.

Returns:

Valor do parâmetro informado ou "opt_default" caso não haja o parâmetro informado na "query string" da URL.

Type: string

read(size)

Lê os dados contidos no corpo da requisição.

O uso deste método é recomendado para requisições de tamanho elevado, como upload de arquivos, pois ele permite que o conteúdo seja lido parcialmente, sem que seja necessário alocar o conteúdo inteiro da requisição em memória.

Importante: ao utilizar este método para ler o corpo da requisição, nenhum tratamento automático de codificação de UTF-8 para ISO-8859-1 será realizado, nem poderão ser utilizadas outras propriedades ou métodos de acesso ao corpo da requisição, como #content. A propriedade #httpMessage não exibirá o conteúdo da requisição e #params não irá considerar os parâmetros informados no corpo da requisição, mesmo que o tipo do conteúdo seja application/x-www-form-urlencoded.

Parameters:

Name	Type	Description
`size`	number	Quantidade de dados a serem lidos. O método bloqueará até que a quantidade de dados solicitada esteja disponível ou irá gerar um erro caso o tempo limite #readTimeout seja atingido. No máximo poderá ser solicitado 1 MB de dados a cada leitura, será lançada uma exceção caso seja solicitado um valor superior a esse.

See:

#content

Returns:

Dados lidos do corpo da requisição.

Type: string

Example

var timeout = 60000;
var outFile = new File(File.getTempFileName());
var remain = request.contentLength;
while (remain > 0 && Date.now() < timeout) {
  var buffer = request.read(Math.min(1024, remain));
  remain -= buffer.length;
  outFile.write(buffer);
}

saveToStream(stream)

Grava o corpo da requisição no arquivo ou stream informado.

Parameters:

Name	Type	Description
`stream`	module:@nginstack/engine/lib/io/File~File\| module:@nginstack/engine/lib/io/MemoryStream~MemoryStream	Objeto stream onde o corpo da requisição será gravado.

Example

const file = new File(path);
try {
  request.saveToStream(file);
} finally {
  file.close();
}