Class: Route

@nginstack/engine/lib/router/Route~ Route

new Route(opt_routeSet)

Representação de uma rota na API de roteamento HTTP do Engine. Uma rota associa um caminho ao método de um controlador que será responsável por processar a requisição.

Parameters:
Name Type Argument Description
opt_routeSet module:@nginstack/engine/lib/router/RouteSet~RouteSet <nullable>

Conjunto de rotas onde esta rota foi declarada, caso tenha sido declarada em um. O conjunto de rotas é utilizado para herdar propriedades que não tenham sido explicitamente configuradas na rota.
See:

Extends

Members

action :string

Indica qual método do controlador deve ser executada e com quais parâmetros ele deve ser chamado. Os parâmetros solicitados serão extraídos do #path definido na rota. Para isso, deve ser utilizada a sintaxe ':NAME' para indicar quais partes de path devem ser interpretadas como parâmetros a serem passados para o controlador.

Caso o controlador necessite dados da requisição que não estejam apenas no path, ele poderá utilizar o parâmetro request, que será atribuído com uma instância de Request com todos os dados da requisição.

Type:
  • string
Inherited From:
Example
// Exemplo de uma definição literal em um arquivo de rotas:
{method: 'POST', path: '/api/operacoes/requisicao/:id/movdepos', action: 'criar(request, id)'}

allowedOrigins :Array.<string>

Determina quais domínios podem acessar esta rota. Por padrão, qualquer domínio poderá acessar. Esta propriedade é validada apenas por clientes HTTP que respeitam o protocolo CORS. Mais detalhes em https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS.

Type:
  • Array.<string>
Inherited From:
Default Value:
  • ['*']

controller :string|number

Chave ou caminho do módulo que define o construtor do controlador que executará a ação indicada na rota. Caminhos na UFS devem ter o prefixo 'ufs:' e os da VFS o 'vfs:'. O arquivo indicado deve ter a estrutura de um módulo CommonJS. O construtor do controlador deve ser retornado por meio da propriedade module.exports.

Type:
  • string| number
Inherited From:

debug :boolean

Indica que o Engine deve adicionar no log do sistema informações de depuração sobre a execução do rota, como o trace das requisições e respostas geradas.

Type:
  • boolean
Inherited From:

method :module:@nginstack/engine/lib/http/Method~Method|Array.<module:@nginstack/engine/lib/http/Method~Method>

Indica qual método da requisição HTTP esta rota trata. Poderá ser: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE' e 'OPTIONS'.

Type:
Inherited From:

order :number

Ordem de pesquisa desta rota na busca de rotas realizada pelo roteador HTTP.

Valores menores serão avaliados primeiro e o roteador interrompe a busca ao encontrar uma rota que satisfaça um caminho de uma requisição, portanto uma rota de menor ordem se sobrepõem a uma rota de maior ordem para o mesmo caminho.

Caso esta definição faça parte de um conjunto de rotas (RouteSet), a ordem será utilizada para determinar a ordem de pesquisa em relação às demais rotas definidas em routes. Por padrão, a ordem será definida automaticamente com base na posição do array routes.

Type:
  • number
Inherited From:

parameterNames :Array.<string>

Array com os nomes dos parâmetros extraídos de #path.

Type:
  • Array.<string>

path :string

Caminho que será associado a ação indicada nesta rota. Dentro do caminho podem ser indicadas partes que devem ser interpretados como parâmetros a serem passados para a ação do controlador. Para isso, deverá ser utilizada as seguintes sintaxes:

  • :param_name: Extrai o parâmetro até localizar o próximo separador '/' dentro de path. Exemplo: a rota com path /api/classes/:id/def interceptará uma requisição para "/api/classes/123456/def" e irá extrair o parâmetro id com o valor '123456'. Todos os parâmetros extraídos por essa sintaxe são do tipo string.
  • :param_name<type>: extrai o parâmetro de forma similar a sintaxe anterior, mas o converte para o tipo informado. Se o tipo não puder ser convertido, será retornado um erro. Atualmente são suportados apenas os tipos number, date, string e boolean. Datas deverão ser informadas no formato ISO 8601 e booleanos aceitarão true e 1 como verdadeiro e false e 0 como falso.
  • *param_name: extrai o restante de path e armazena o valor extraído em param_name. O nome do parâmetro pode ser suprimido, informando apenas *, quando deseja-se criar uma rota para o caminho informado e todos os subcaminhos dele. Exemplo: a rota com path '/api/files/*path' interceptará uma requisição para /api/files/parent/file.js e irá extrair o parâmetro path com o valor parent/file.js.
Type:
  • string
Inherited From:

realm :string|number

Indica o nome ou a chave da configuração do Realm HTTP que deve ser utilizado no atendimento desta rota. As configurações dos realms estão disponíveis em /Configuração/Realms.

Um Realm HTTP define um isolamento dos ambientes JavaScript e sessões de usuário. Um controlador em um determinado realm não compartilhará o ambiente JavaScript de um outro controlador definido em outro realm.

Defina um realm diferente do padrão quando observar que os recursos e scripts utilizados por um controlador serão muito diferentes do padrão de uso dos demais controladores ou quando for necessário um controle diferenciado do tempo de vida do ambiente JavaScript ou do tipo de ambiente (stateful ou stateless).

Type:
  • string| number
Inherited From:

requiresAuth :boolean

Determina se esta rota exige que o requisitante informe um usuário do sistema no cabeçalho Authorization, podendo ser informado um bearer token (OAuth2) ou o usuário e senha seguindo o formato de autorização básica do HTTP.
Caso a autenticação seja solicitada, o objeto session estará autenticado com o usuário indicado no token durante a execução do método do controlador.

Type:
  • boolean
Inherited From:
See:
  • RouteSetDef#requiresAuth

scope :string|Array.<string>

Lista separada por espaço dos escopos de autorização necessários para utilizar esta rota. Opcionalmente pode ser informado um array com os escopos, o qual será convertido em uma lista.

Via de regra, o acesso a esta rota será permitido se os escopos autorizados pelas credenciais utilizadas na autenticação da sessão contiverem ao menos um dos escopos informados nesta propriedade. Essa regra padrão pode ser alterada adicionando os prefixos '+' e '!' aos escopos informados.

O prefixo '+' tornará o escopo obrigatório e ele sempre deverá estar relacionado nos escopos associados às credenciais. Já o prefixo '!' indica que a rota não será autorizada se o escopo for encontrado. Por exemplo, o escopo 'api.read api.readWrite +api.admin !api.readOnly' requer que os escopos autorizados pelas credenciais do usuário tenham o escopo ´api.admin´, não tenham o 'api.readOnly' e inclua ao menos um dos escopos 'api.read' ou 'api.readWrite'.

Type:
  • string| Array.<string>
Inherited From:
See:

<static> resolveGlobalParameter

Função que será chamada por esta classe para resolver parâmetros esperados por uma ação que não foram parametrizados no path. Será gerado um erro ao tentar definir uma ação que espere um parâmetro que não esteja definido em path e que não seja resolvido por esta função.

Methods

assign(def)

Atribui a esta instância os valores de uma definição de rota.

Parameters:
Name Type Description
def module:@nginstack/engine/lib/router/RouteDef~RouteDef| Record.<*, *>

Definição que terá as propriedades copiadas.

testScope(scope)

Verifica se o escopo informado satisfaz o escopo requerido pela rota.

Parameters:
Name Type Description
scope string

Escopo a ser verificado.
Returns:

True se o escopo satisfizer a configuração desta rota.

Type
boolean

<static> parseAction(action)

Interpreta a expressão da ação definida na rota e retorna o nome do método a ser executado no controlador e os parâmetros que devem ser informados.

Parameters:
Name Type Description
action string

Ação definida na rota.
Returns:
Type
Object

<static> testScope(scope, requiredScope)

Verifica se scope satisfaz o escopo requerido por requiredScope.

Parameters:
Name Type Description
scope string| Array.<string>

Escopos de autorização atribuídos a um usuário e que serão testados. Poderá ser informada uma lista de escopos separados por espaço ou um array de identificadores.
requiredScope string| Array.<string>

Escopo que deve ser satisfeito.
Returns:

True se scope satisfizer requiredScope.

Type
boolean