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?

Use the following table to determine which standard Node.js modules are included on Edge. In some cases, included modules are only partially supported. These are modules that are built-in to Node.js.

Module	Status	Notes
assert	Supported
buffer	Supported
child_process	Restricted	An exception will be thrown if an attempt is made to spawn a sub-process. However, "fork" is supported for spawning sub-scripts.
cluster	Disabled	The method cluster.isMaster always returns true, and other methods are not implemented. One copy of each Node.js script is deployed to each Edge message processor.
crypto	Supported
dns	Supported
domain	Supported
dgram	Restricted	Node.js applications in the Apigee environment will not be able to access services on the Internet via UDP due to our network architecture.
events	Supported
fs	Restricted	Filesystem access is restricted to the directory where the script was launched: the /resources/node directory. Node.js scripts may 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.
http	Supported	The virtual host and path for incoming requests is specified in the API Proxy, not by the HTTP module. See "Understanding support for the http and https modules" for more information.
https	Supported	Creating an "https" server behaves identically to an "http" server. See "Understanding support for the http and https modules" for more information.
module	Supported
net	Restricted	Attempts to listen for incoming TCP connections will generate an exception.
path	Supported
module	Supported
process	Partial support	Functionality to manipulate user ID, group membership, and working directory is not supported.
punycode	Supported
querystring	Supported
readline	Disabled	There is no standard input for scripts running on Apigee Edge.
repl	Disabled	There is no standard input for scripts running on Apigee Edge.
module	Included
STDIO	Supported	Standard output and error are routed to a log file within the Apigee Edge infrastructure. You can view these logs by clicking the Node.js Logs button in and Apigee Edge management UI for your API proxy. There is no standard input for scripts running on Apigee Edge. However, you can pass arguments using the ScriptTarget element of TargetEndpoint. See Advanced ScriptTarget configuration for more information.
stream	Supported
string_decoder	Supported
timers	Included
tls	Supported	Transport Layer Security (TLS) parameters work basically the same way they work in regular Node.js. See Using the TLS (SSL) Node.js module on Apigee Edge for details.
tty	Disabled	There is no standard input for scripts running on Apigee Edge.
url	Supported
util	Supported
vm	Supported
zlib	Supported

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.

Module	Description
apigee-access	Allows Node.js applications running on the Apigee Edge platform a way to access Apigee-specific functionality. You can use this module to: access and modify flow variables, retrieve data from the secure store, and use Edge cache, quota, and OAuth services. See also Using the apigee-access module.
trireme-support	Lets Node.js applications take advantage of features specific to Trireme. Currently there is only one feature supported -- loading Node.js modules built in Java. Note: loadJars is not supported in Edge Cloud.
trireme-xslt	Presents an abstraction of XLST processing. It is specifically designed for the Trireme platform to allow efficient processing of XSLT when Node.js applications are run on Java.
trireme-jdbc	Provides access to JDBC from Node.js. Note: Unsupported in Edge Cloud. For Edge Private Cloud, you can put JDPC JAR files in the class path and use this module.

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>