Noções básicas sobre o suporte do Edge para módulos Node.js

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Qual versão do Node.js é compatível com o Apigee Edge?

No momento, o Edge oferece suporte ao Node.js 0.10.32.

Quais módulos Node.js padrão são compatíveis com o Edge?

Use a tabela a seguir para determinar quais módulos Node.js padrão estão incluídos no Edge. Em alguns casos, os módulos incluídos têm suporte apenas parcial. São módulos integrados ao Node.js.

Módulo Status Observações
assert Compatível
buffer Compatível
child_process Restrito Uma exceção será gerada se for feita uma tentativa de gerar um subprocesso. No entanto, "fork" é compatível com a geração de subscripts.
cluster Desativado O método cluster.isMaster sempre retorna "true", e outros métodos não são implementados. Uma cópia de cada script Node.js é implantada em cada processador de mensagens do Edge.
crypto Compatível
dns Compatível
domain Compatível
dgram Restrito Os aplicativos Node.js no ambiente da Apigee não poderão acessar serviços na Internet por UDP, devido à nossa arquitetura de rede.
events Compatível
fs Restrito O acesso ao sistema de arquivos é restrito ao diretório em que o script foi iniciado: o diretório /resources/node. Os scripts Node.js podem ler e gravar arquivos nesse diretório, por exemplo, como uma área de rascunho temporária, mas não há garantias de quanto tempo os arquivos vão persistir.
http Compatível O host virtual e o caminho para as solicitações recebidas são especificados no proxy da API, não pelo módulo HTTP. Consulte "Noções básicas sobre o suporte aos módulos http e https" para mais informações.
https Compatível Criar um servidor "https" se comporta de maneira idêntica a um servidor "http". Consulte "Noções básicas sobre o suporte aos módulos http e https" para mais informações.
module Compatível
net Restrito As tentativas de detectar conexões TCP de entrada gerarão uma exceção.
path Compatível
module Compatível
process Suporte parcial As funcionalidades para manipular o ID do usuário, a associação ao grupo e o diretório de trabalho não são compatíveis.
punycode Compatível
querystring Compatível
readline Desativado Não há entrada padrão para scripts em execução no Apigee Edge.
repl Desativado Não há entrada padrão para scripts em execução no Apigee Edge.
module Incluído
STDIO Compatível

A saída e o erro padrão são encaminhados para um arquivo de registros na infraestrutura do Apigee Edge. Para visualizar esses registros, clique no botão Registros do Node.js na interface de gerenciamento do Apigee Edge para o proxy de API.

Não há entrada padrão para scripts em execução no Apigee Edge. No entanto, você pode transmitir argumentos usando o elemento ScriptTarget de TargetEndpoint. Consulte Configuração avançada do ScriptTarget para mais informações.

stream Compatível
string_decoder Compatível
timers Incluído
tls Compatível Os parâmetros do Transport Layer Security (TLS) funcionam basicamente da mesma forma que no Node.js normal. Para mais detalhes, consulte Como usar o módulo TLS (SSL) Node.js no Apigee Edge.
tty Desativado Não há entrada padrão para scripts em execução no Apigee Edge.
url Compatível
util Compatível
vm Compatível
zlib Compatível

Outros módulos com suporte

Nesta seção, listamos outros módulos que não são compatíveis com o Node.js padrão, mas têm o Trireme e o Trireme em execução na Apigee Edge. O Trireme é o contêiner Node.js de código aberto executado na Apigee Edge. Ele foi projetado para executar scripts Node.js em uma máquina virtual Java (JVM). Todos esses módulos estão disponíveis no NPM.

Módulo Descrição
apigee-access Permite que aplicativos Node.js em execução na plataforma Apigee Edge acessem funcionalidades específicas da Apigee. É possível usar este módulo para acessar e modificar variáveis de fluxo, recuperar dados do armazenamento seguro e usar o cache do Edge, a cota e os serviços do OAuth. Consulte também Como usar o módulo apigee-access.
trireme-support (em inglês) Permite que os aplicativos Node.js aproveitem os recursos específicos do Trireme. Atualmente, há apenas um recurso compatível: o carregamento de módulos Node.js criados em Java. Observação: loadJars não é compatível com o Edge Cloud.
trireme-xslt (em inglês) Apresenta uma abstração do processamento XLST. Ele foi projetado especificamente para a plataforma Trireme de permitir o processamento eficiente de DEX quando os aplicativos Node.js são executados em Java.
trireme-jdbc Dá acesso ao JDBC no Node.js. Observação: não compatível com o Edge Cloud. Para a nuvem privada de borda, coloque os arquivos JAR JDPC no caminho da classe e use esse módulo.

Suporte para módulos Node.js mais usados

Restrições em scripts Node.js

No entanto, o Edge impõe algumas restrições aos scripts Node.js, como estas:

  • Os aplicativos Node.js no ambiente do Apigee Edge não podem acessar serviços na Internet por UDP devido à arquitetura de rede de borda.
  • O acesso ao sistema de arquivos é restrito ao diretório em que o script Node.js foi iniciado: o diretório /resources/node. Os scripts Node.js podem ler e gravar arquivos nesse diretório, por exemplo, como uma área de rascunho temporária, mas não há garantias de quanto tempo os arquivos vão persistir.
  • As tentativas de detectar conexões TCP de entrada geram uma exceção.
  • As funcionalidades para manipular o ID do usuário, a associação ao grupo e o diretório de trabalho não são compatíveis.
  • Na entrada padrão, só é possível transmitir argumentos usando o elemento ScriptTarget de TargetEndpoint. Consulte Configuração avançada do ScriptTarget para mais informações.
  • Na saída padrão, você só pode usar o botão "Registros" do Node.js na IU de gerenciamento de borda do proxy. Também é possível usar o comando "apigeetool getlogs". Para mais informações, consulte Como implantar um app Node.js autônomo.
  • Módulos que dependem de código nativo não são compatíveis.
  • Módulos que dependem de recursos do EcmaScript 6, como promessas e geradores, não são compatíveis.
  • As sinalizações do ambiente de execução do Node.js, como "harmony-proxies", não são compatíveis.

Como configurar restrições de conexão de IP no Edge para nuvem privada

O Edge para nuvem privada pode restringir o acesso do código Node.js a endereços IP que começam com "10.", "192.168" e localhost. Se você tentar acessar esses endereços IP, verá um erro no formato:

{ [Error: connect EINVAL] message: 'connect EINVAL', code: 'EINVAL', errno: 'EINVAL', syscall: 'connect' }

Você pode modificar essas restrições configurando a propriedade conf_nodejs_connect.ranges.denied no arquivo message-processors.properties para cada processador de mensagens. Por padrão, essa propriedade tem o valor:

  • Edge 4.17.05 e anteriores: conf_nodejs_connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32
  • Edge 4.17.09 e mais recentes: conf_nodejs_connect.ranges.denied= (ou seja, sem restrições)

Para definir essa propriedade:

  1. Abra o arquivo message-processor.properties em um editor. Se o arquivo não existir, crie-o:
    > vi /<inst_root>/apigee/customer/application/message-processor.properties
  2. Defina a propriedade como quiser. Por exemplo, para negar o acesso apenas ao localhost:
    conf_nodejs_connect.ranges.denied=127.0.0.1/32
  3. Salve as mudanças.
  4. Verifique se o arquivo de propriedades pertence ao usuário "apigee":
    > chown apigee:apigee /<inst_root>/apigee/customer/application/message-processor.properties
  5. Reinicie o processador de mensagens:
    > /<inst_root>/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Noções básicas sobre o suporte aos módulos http e https

Todos os aplicativos Node.js em execução no Apigee Edge precisam usar o módulo http ou https para detectar as solicitações recebidas. Se você implanta um script que não detecta solicitações recebidas, ele simplesmente é executado e sai.

O método listen dos módulos http e https no Node.js usa um número de porta como parâmetro. Exemplo:

svr.listen(process.env.PORT || 9000, function() {
   console.log('The server is running.');
});

Esse argumento "porta" é obrigatório no Node.js, mas o Apigee Edge ignora esse parâmetro. Em vez disso, o proxy de API em que o script Node.js é executado especifica o "host virtual" que detecta, e o aplicativo Node.js usa esses mesmos hosts virtuais, assim como qualquer outro proxy do Apigee Edge.

Todo ambiente na Apigee tem pelo menos um host virtual. O host virtual define as configurações de HTTP para conexão com a organização da Apigee. Todos os proxies de API em um ambiente compartilham os mesmos hosts virtuais. Por padrão, dois hosts virtuais estão disponíveis para cada ambiente: default e secure. Para mais informações, consulte Acessar host virtual e Ciclo de vida de desenvolvimento da API.

O comando apigeetool deploynodeapp gera um wrapper de proxy do Apigee Edge em torno do aplicativo Node.js. Quando implantado, o aplicativo Node.js detecta o host virtual padrão definido para o ambiente. O URL de um aplicativo Node.js sempre será http://{org_name}-{env_name}.apigee.net.

Processar solicitações recebidas

Como outros aplicativos da Apigee Edge, se o aplicativo de proxy estiver configurado para detectar no host virtual secure, ele vai aceitar solicitações recebidas usando HTTPS.

Processar solicitações de saída

Além de receber o tráfego de entrada, os aplicativos Node.js na Apigee Edge podem usar os módulos http e https para fazer solicitações de saída como qualquer outro aplicativo Node.js. Esses módulos funcionam como sempre no Node.js.

Noções básicas sobre o suporte ao módulo tls

O Apigee Edge oferece suporte ao módulo tls do Node.js. Este módulo usa o OpenSSL para fornecer comunicação de stream criptografada por Transport Layer Security (TLS) e/ou Secure Socket Layer (SSL). Use o módulo tls para criar conexões seguras para serviços de back-end de aplicativos Node.js em execução no Edge.

Para entender como o módulo tls funciona no Apigee Edge, é importante entender como virtual hosts são usados no Apigee Edge. Todo ambiente na Apigee tem pelo menos um host virtual. O host virtual define as configurações de HTTP para conexão com a organização da Apigee. Todos os proxies de API em um ambiente compartilham os mesmos hosts virtuais. Por padrão, dois hosts virtuais estão disponíveis para cada ambiente: default e secure. Para mais informações sobre hosts virtuais, consulte Acessar host virtual e Ciclo de vida de desenvolvimento da API.

Agora vamos conferir como o Apigee Edge lida com a comunicação por TLS (SSL) para solicitações recebidas e enviadas em aplicativos Node.js:

Processar solicitações recebidas

Dependendo de como os hosts virtuais estão configurados para sua organização, o Edge oferece estas opções:

  • Se o proxy de API estiver configurado para detectar no host virtual default, ele vai aceitar solicitações por HTTP.
  • Se o proxy de API estiver configurado para detectar no host virtual secure, ele vai aceitar solicitações por HTTPS. O URL estará no domínio apigee.net, e um certificado SSL com caractere curinga para *.apigee.net será usado. Se os apps fizerem solicitações ao domínio apigee.net, o certificado SSL será validado normalmente.

Processar solicitações de saída

É possível fazer solicitações de saída com o módulo tls da mesma maneira que faria normalmente no Node.js. Basicamente, você precisa adicionar chaves e certificados do lado do cliente (arquivos .pem) ao diretório resources/node e carregá-los dentro do script. Para ver informações sobre como usar o módulo tls e os métodos dele, consulte a documentação do módulo tls do Node.js.

Configuração avançada do ScriptTarget

Na definição de <TargetEndpoint>, o elemento <ScriptTarget> aceita outros parâmetros opcionais além de <ResourceURL>. Também é possível transmitir argumentos de linha de comando e variáveis de ambiente para um script Node.js usando os parâmetros <EnvironmentVariables> e <Arguments>:
<TargetEndpoint name="default">
  <ScriptTarget>
     <ResourceURL>node://hello.js</ResourceURL>
     <EnvironmentVariables>
         <EnvironmentVariable name="NAME">VALUE</EnvironmentVariable> 
     </EnvironmentVariables>
     <Arguments>
         <Argument>ARG</Argument>
     </Arguments>
  </ScriptTarget>
</TargetEndpoint>