Understanding Edge support for Node.js modules

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

What version of Node.js is supported on Apigee Edge?

Edge currently supports Node.js 0.10.32.

Which standard Node.js modules are supported on Edge?

Additional supported modules

This section lists additional modules that are not supported in standard Node.js, but are supported by Trireme and Trireme running on Apigee Edge. Trireme is the open-source Node.js container that runs on Apigee Edge. It is designed to run Node.js scripts inside a Java Virtual Machine (JVM). All of these modules are available on NPM.

Support for commonly used Node.js modules

Restrictions on Node.js scripts

Note, however, that Edge imposes certain restrictions on Node.js scripts, such as the following:

• Node.js applications in the Apigee Edge environment cannot access services on the Internet via UDP because of the Edge network architecture.

• Filesystem access is restricted to the directory where the Node.js script was launched: the /resources/node directory. Node.js scripts can read and write files within this directory, for instance as a temporary scratch area, but there are no guarantees as to how long the files will persist.

• Attempts to listen for incoming TCP connections generate an exception.

• Functionality to manipulate user ID, group membership, and working directory is not supported.

• For standard input, you are limited to passing arguments using the ScriptTarget element of TargetEndpoint. See Advanced ScriptTarget configuration for more information.
  
• For standard output, you are limited to using the Node.js Logs button in the Edge management UI for your proxy. You can also use the "apigeetool getlogs" command. For more information, see Deploying a standalone Node.js app.
  
• Modules that depend on native code are not supported.
  
• Modules that depend on EcmaScript 6 features, such as Promises and Generators, are not supported.
  
• The Node.js runtime flags such as "harmony-proxies" are not supported.

Setting IP connection restrictions on Edge for Private Cloud

Edge for Private Cloud can restrict Node.js code from accessing IP addresses starting with “10.", "192.168", and localhost. If you attempt to access these IP addresses, you will see an error in the form:

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

You can modify these restrictions by setting the conf_nodejs_connect.ranges.denied property in the message-processors.properties file for each Message Processor. By default, this property has the value:

• Edge 4.17.05 and earlier: conf_nodejs_connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32
• Edge 4.17.09 and later: conf_nodejs_connect.ranges.denied= (meaning no restrictions)

To set this property:

1. Open the message-processor.properties file in an editor. If the file does not exist, create it:
   > vi /<inst_root>/apigee/customer/application/message-processor.properties
2. Set the property as desired. For example, to deny access to only localhost:
   conf_nodejs_connect.ranges.denied=127.0.0.1/32
3. Save your changes.
4. Make sure the properties file is owned by the 'apigee' user:
   > chown apigee:apigee /<inst_root>/apigee/customer/application/message-processor.properties
5. Restart the Message Processor:
   > /<inst_root>/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Understanding support for the http and https modules

All Node.js applications running in Apigee Edge must use the http or https module to listen for incoming requests. If you were to deploy a script that doesn't listen for incoming requests, it would simply execute and exit.

The listen method of the http and https modules in Node.js takes a port number as a parameter. For example:

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

This "port" argument is required in Node.js, but Apigee Edge ignores this parameter. Instead, the API proxy in which the Node.js script runs specifies the "virtual host" that it listens on, and the Node.js application uses those same virtual hosts, just like any other Apigee Edge proxy.

Every environment in Apigee has at least one virtual host. The virtual host defines the HTTP settings for connection with the Apigee organization. All API proxies in an environment share the same virtual hosts. By default, two virtual hosts are available for each environment: default and secure. For more information, see Get Virtual Host and API development lifecycle.

The apigeetool deploynodeapp command generates an Apigee Edge proxy wrapper around the Node.js application. When deployed, the Node.js application listens on the default virtual host defined for the environment. The URL for a Node.js application will always be http://{org_name}-{env_name}.apigee.net.

Handling incoming requests

Like other Apigee Edge applications, if the proxy application is set up to listen on the secure virtual host, then it will accept incoming requests using HTTPS.

Handling outgoing requests

In addition to receiving incoming traffic, Node.js applications inside Apigee Edge may use the http and https modules to make outbound requests like any other Node.js application. These modules work just as they always do inside Node.js.

Understanding support for the tls module

Apigee Edge supports the Node.js tls module. This module uses OpenSSL to provide Transport Layer Security (TLS) and/or Secure Socket Layer (SSL) encrypted stream communication. You can use the tls module to create secure connections to backend services from Node.js applications running on Edge.

To understand how the tls module works on Apigee Edge, it's important to understand how virtual hosts are used on Apigee Edge. Every environment in Apigee has at least one virtual host. The virtual host defines the HTTP settings for connection with the Apigee organization. All API proxies in an environment share the same virtual hosts. By default, two virtual hosts are available for each environment: default and secure. For more information on virtual hosts, see Get Virtual Host and API development lifecycle.

Now, let's look at how Apigee Edge handles TLS (SSL) communication for incoming and outgoing requests on Node.js applications:

Handling incoming requests

Depending on how virtual hosts are configured for your organization, Edge provides these options:

• If the API proxy is configured to listen on the default virtual host, then it accepts requests over HTTP.
• If the API proxy is configured to listen on the secure virtual host, then it accepts requests over HTTPS. The URL will be under the apigee.net domain, and a wildcard SSL certificate for *.apigee.net will be used. As long as apps make requests to the apigee.net domain, then the SSL certificate will validate normally.

Handling outgoing requests

You can make outgoing requests with the tls module the same way you would normally in Node.js. Basically, you need to add client-side keys and certificates (.pem files) to the resources/node directory and load them inside your script. For information on using the tls module and its methods, see the Node.js tls module documentation.

Advanced ScriptTarget Configuration

<TargetEndpoint name="default">
  <ScriptTarget>
     <ResourceURL>node://hello.js</ResourceURL>
     <EnvironmentVariables>
         <EnvironmentVariable name="NAME">VALUE</EnvironmentVariable> 
     </EnvironmentVariables>
     <Arguments>
         <Argument>ARG</Argument>
     </Arguments>
  </ScriptTarget>
</TargetEndpoint>