Node.js runtime

Currently, Function Compute supports Node.js 6.10 with runtime version 6 and Node.js 8.9.0 with runtime version 8. This topic describes the following features of the Node.js runtime environments:

• Use the logging module
• Use built-in modules
• Use custom modules
• Run external commands
• Understand callback
• Handle exceptions

Use the logging module

You can specify a Logstore when you create a service. The Logstore collects the data that the function outputs to print by using the console.log file. For more information about function logs, see Logs.

exports.handler = function (event, context, callback) {
    console.info(null, 'hello world');
    callback(null, 'hello world');
};

The preceding code outputs the following log content:

message:2017-07-05T05:13:35.920Z a72df088-f738-cee3-e0fe-323ad89118e5 [INFO] hello world

You can run the console.warn and console.error commands to package WARN and ERROR logs, respectively.

You can change log levels by using the setLogLevel handler. The following log levels are listed in descending order in terms of priority:

• error: indicates that the corresponding handler is console.error.
• warn: indicates that the corresponding handler is console.warn.
• info: indicates that the corresponding handler is console.info.
• verbose: indicates that the corresponding handler is console.log.
• debug: indicates that the corresponding handler is console.debug.

'use strict';
exports.handler = function(evt, ctx, cb) {
    console.setLogLevel("error");
    console.error("console error 1");
    console.info("console info 1");
    console.warn("console warn 1");
    console.log("console log 1");
    console.setLogLevel("warn");
    console.error("console error 2");
    console.info("console info 2");
    console.warn("console warn 2");
    console.log("console log 2");
    console.setLogLevel("info");
    cb(null, evt);
};

The preceding code outputs the following log content:

message:2017-07-05T05:13:35.920Z a72df088-f738-cee3-e0fe-323ad89118e5 [ERROR] console error 1
message:2017-07-05T05:13:35.920Z a72df088-f738-cee3-e0fe-323ad89118e5 [ERROR] console error 2
message:2017-07-05T05:13:35.920Z a72df088-f738-cee3-e0fe-323ad89118e5 [WARN] console warn 2

Use built-in modules

In addition to the standard Node.js modules, the Node.js runtime environments for Function Compute provide the following common modules.

For example, the function that uses GraphicsMagick to flip an image is as follows:

var gm = require('gm').subClass({ imageMagick: true });
exports.handler = function (event, context, callback) {
    gm(event)
        .flip()
        .toBuffer('PNG', function (err, buffer) {
            if (err) return callback(err);
            callback(null, buffer);
        });
};

Note: The preceding function directly uses event as the binary data of the image, and directly returns the generated image as the binary data.

Use custom modules

If you need to use a custom module, package the module and the code together. The following steps describe how to use Fun to add a mysql module to access MySQL. For the installation guide of Fun, see here.

1. Create a folder to store code and dependent modules:

   mkdir /tmp/code

2. Create a new code file, such as /tmp/code/index.js, and use the mysql module in the code:

   var mysql = require('mysql');
   var connection;
   // exports.initializer: initializer function
   exports.initializer = function (context, callback) {
      connection = mysql.createConnection({
        host: 'localhost',
        user: 'me',
        password: 'secret',
        database: 'my_db'
      });
      connection.connect();
   }
   exports.handler = function (event, context, callback) {
      connection.query('SELECT 1 + 1 AS solution', function (error, results, fields) {
        if (error) return callback(error);
        console.log('The solution is: ', results[0].solution);
        callback(null, results[0].solution);
      });
      connection.end();
   };

   • Why is the operation of database connection in initializer?

     The initializer runs only once within the lifecycle of a Function Compute instance. Establishing a database connection belongs to a cold start overhead at the application layer. To optimize the function performance and avoid establishing the database connection repeatedly due to multiple subsequent requests, we put this operation under the initializer to maintain the database connection during the lifecycle of a Function Compute instance.

   • Why is using initializer better than using a global variable for the initialization?

     Within the lifecycle of a Function Compute instance, the initializer runs only once before the request to call the function. However, using the global variable affects the performance during the cold start on some occasions, such as calling a new Function Compute instance, upgrading code, periodic recycling for Function Compute, or updating containers.

3. Install dependencies in the /tmp/code folder.

   cd /tmp/code
   npm install mysql

4. Create a template.yml file, such as /tmp/code/template.yml, and enter the content as follows:

    ROSTemplateFormatVersion: '2015-09-01'
    Transform: 'Aliyun::Serverless-2018-04-03'
    Resources:
      FunDemo: 
        Type: 'Aliyun::Serverless::Service'
        nodejsdemo: 
          Type: 'Aliyun::Serverless::Function'
          Properties:
            Handler: index.handler
            Runtime: nodejs8
            Initializer: index.initializer
            CodeUri: '. /'

   The description of the template.yml file is as follows: Declare a FunDemo service and a nodejsdemo function for the FunDemo service. Then, specify the function runtime environment as nodejs8, and configure the function handler as index.handler and the initializer as index.initializer. In addition, specify the CodeUri property as the current folder. Fun packages and uploads the folder or files that the CodeUri property specifies during the deployment. For more configuration rules, see here.

   After the installation, the content of the /tmp/code folder is as follows:

    ls -l /tmp/code
    -rw-r--r--   1 tan  wheel   522B Jun 18 14:50 index.js
    drwxr-xr-x  13 tan  wheel   416B Jun 18 14:49 node_modules
    -rw-r--r--   1 tan  wheel   297B Jun 18 14:58 template.yml

5. Use Fun to deploy:

    fun deploy

   Related logs appear as follows when you successfully run the fun deploy command:

    using region: cn-hangzhou
    using accountId: ***********3557
    using accessKeyId: ***********r3Ra
    using timeout: 300
    Waiting for service FunDemo to be deployed...
          Waiting for function nodejsdemo to be deployed...
              Waiting for packaging function nodejs code...
              package function nodejs code done
          function nodejsdemo deploy success
    service FunDemo deploy success

   Log on to the console. You can see the related services and functions that are successfully created. The execution of functions can be triggered to return correct results.

   Here is a brief description about what the fun deploy command does: When you use the fun deploy command, it creates a FunDemo service according to the configuration of the template.yml file. In addition, it creates a nodejsdemo function with a runtime environment nodejs8. Then, the nodejsdemo function packages and uploads the current folder that the CodeUri property specifies to Function Compute as the function code. The packaged code contains the node_modules folder that includes all the installed packages, so Function Compute can directly use these packages.

Run external commands

The functions may use some tools that are not written in Node.js, such as shell scripts or executable files that are compiled in C++ or Go. You can still package these tools and the function code together and use them by running external commands in the functions. The following example demonstrates how to run a shell script:

var exec = require('child_process');
exports.handler = function(event, context, callback) {
  var scriptPath = process.env['FC_FUNC_CODE_PATH'] + '/script.sh';
  exec.exec('bash '+scriptPath, {}, function(err, stdout, stderr) {
    if (err) return callback(err);
    console.log(stdout, stderr);
    callback(null, stdout);
  });
};

Executable files that are compiled in C, C++, or Go must be compatible with the runtime environment of Function Compute. The Node.js runtime environment of Function Compute is:

• • Linux kernel version: Linux 4.4.24-2.al7.x86_64
• • Docker base image: Docker Pull Node:6.10

Understand callback

Node.js uses an asynchronous programming model. Therefore, the function must call callback to respond. If no callback is used in the function, the system prompts that the function execution has timed out.

1. Make sure that callback is called

If a function does not call callback, the system assumes that the function is still in process, then waits for the result of the function until the operation times out. For example, when the following function is called, a time-out error is returned:

exports.handler = function(event, context, callback) {
  console.log('hello world');
};

Result of the call:

{"errorMessage":"Function timed out after 3 seconds"}

2. The function execution ends after callback is called

The function execution ends after callback is called. If callback is called multiple times, only the result of the first callback takes effect. Make sure that all tasks are completed before calling callback. Otherwise, the remaining tasks will not run. For example, the following function returns “hello world” but does not output “message”:

exports.handler = function(event, context, callback) {
  callback(null, 'hello world');
  callback(null, 'done');
  setTimeout(function() {
    console.log('message');
  }, 1000);
};

Handle exceptions

After you run a function in the Node.js runtime environment, you may receive the following types of errors of which the error types are in the returned HTTP header field X-Fc-Error-Type:

1. HandledInvocationError: indicates the error returned by the first callback parameter.
2. UnhandledInvocationError: indicates other errors, such as an uncaptured exception, a timeout error, or an out-of-memory (OOM) error.

Example 1: Return HandledInvocationError

exports.handler = function(event, context, callback) {
  callback(new Error('oops'));
};

When callback is called, the following response is returned:

{
  "errorMessage": "oops",
  "errorType": "Error",
  "stackTrace": [
    "at exports.handler (/code/index.js:2:12)"
  ]
}

Example 2: Return UnhandledInvocationError

exports.handler = function(event, context, callback) {
  throw new Error('oops');
};

When callback is called, the following response is returned:

{"errorMessage":"Process exited unexpectedly before completing request"}

For more information about errors in Function Compute, see Error types.