在 njs 中使用 Node.js 模块

开发人员通常希望使用第三方代码，这些代码通常以某种库的形式提供。在 JavaScript 世界中，模块的概念相对较新，因此直到最近才有了标准。许多平台（浏览器）仍然不支持模块，这使得代码重用变得更加困难。本文介绍了如何在 njs 中重用 Node.js 代码。

本文中的示例使用了在 njs 0.3.8 版本中出现的功能

将第三方代码添加到 njs 时可能会出现一些问题

相互引用及其依赖的多个文件
平台特定的 API
现代标准语言结构

好消息是，这类问题对于 njs 来说并不是新的或特有的。JavaScript 开发人员在尝试支持具有非常不同属性的多个不同平台时，每天都会面临这些问题。有一些工具旨在解决上述问题。

相互引用及其依赖的多个文件
这可以通过将所有相互依赖的代码合并到单个文件中来解决。诸如 browserify 或 webpack 之类的工具可以接受整个项目并生成一个包含您的代码和所有依赖项的单个文件。
平台特定的 API
您可以使用多个以平台无关方式实现此类 API 的库（但这会牺牲性能）。特定功能也可以使用 polyfill 方法实现。
现代标准语言结构
此类代码可以进行转译（transpile）：这意味着执行一系列转换，根据旧标准重写较新的语言特性。例如，可以使用 babel 项目来实现此目的。

在本指南中，我们将使用两个相对较大的 npm 托管库

protobufjs — 用于创建和解析由 gRPC 协议使用的 protobuf 消息的库
dns-packet — 用于处理 DNS 协议包的库

环境

本文档主要采用通用方法，并避免提供有关 Node.js 和 JavaScript 的特定最佳实践建议。在按照本文建议的步骤操作之前，请务必查阅相应软件包的手册。

首先（假设已安装 Node.js 并可运行），让我们创建一个空项目并安装一些依赖项；以下命令假定我们在工作目录中

$ mkdir my_project && cd my_project
$ npx license choose_your_license_here > LICENSE
$ npx gitignore node

$ cat > package.json <<EOF
{
  "name":        "foobar",
  "version":     "0.0.1",
  "description": "",
  "main":        "index.js",
  "keywords":    [],
  "author":      "somename <some.email@example.com> (https://example.com)",
  "license":     "some_license_here",
  "private":     true,
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}
EOF
$ npm init -y
$ npm install browserify

Protobufjs

该库提供了用于解析 .proto 接口定义的文件解析器以及用于消息解析和生成的代码生成器。

在此示例中，我们将使用来自 gRPC 示例的 helloworld.proto 文件。我们的目标是创建两个消息：HelloRequest 和 HelloResponse。我们将使用 protobufjs 的静态（static）模式，而不是动态生成类，因为出于安全考虑，njs 不支持动态添加新函数。

接下来，安装该库，并从协议定义中生成实现消息编组（marshalling）的 JavaScript 代码

$ npm install protobufjs
$ npx pbjs -t static-module helloworld.proto > static.js

因此，static.js 文件成为我们的新依赖项，存储了实现消息处理所需的所有代码。set_buffer() 函数包含了使用该库创建一个包含序列化 HelloRequest 消息的缓冲区（buffer）的代码。该代码位于 code.js 文件中

var pb = require('./static.js');

// Example usage of protobuf library: prepare a buffer to send
function set_buffer(pb)
{
    // set fields of gRPC payload
    var payload = { name: "TestString" };

    // create an object
    var message = pb.helloworld.HelloRequest.create(payload);

    // serialize object to buffer
    var buffer = pb.helloworld.HelloRequest.encode(message).finish();

    var n = buffer.length;

    var frame = new Uint8Array(5 + buffer.length);

    frame[0] = 0;                        // 'compressed' flag
    frame[1] = (n & 0xFF000000) >>> 24;  // length: uint32 in network byte order
    frame[2] = (n & 0x00FF0000) >>> 16;
    frame[3] = (n & 0x0000FF00) >>>  8;
    frame[4] = (n & 0x000000FF) >>>  0;

    frame.set(buffer, 5);

    return frame;
}

var frame = set_buffer(pb);

为了确保其正常工作，我们使用 node 执行代码

$ node ./code.js
Uint8Array [
    0,   0,   0,   0,  12, 10,
   10,  84, 101, 115, 116, 83,
  116, 114, 105, 110, 103
]

您可以看到，这得到了一个正确编码的 gRPC 帧。现在让我们用 njs 运行它

$ njs ./code.js
Thrown:
Error: Cannot find module "./static.js"
    at require (native)
    at main (native)

模块不受支持，因此我们收到了一个异常。为了解决这个问题，让我们使用 browserify 或其他类似工具。

尝试处理我们现有的 code.js 文件将产生一堆旨在在浏览器中运行的 JS 代码，即加载后立即运行。这不是我们实际想要的。相反，我们希望有一个可以从 nginx 配置中引用的导出函数。这需要一些包装代码。

在本指南中，为简单起见，所有示例都使用 njs cli。在实际应用中，您将使用 nginx njs 模块来运行代码。

load.js 文件包含库加载代码，该代码将其句柄存储在全局命名空间中

global.hello = require('./static.js');

此代码将被合并内容替换。我们的代码将使用“global.hello”句柄来访问库。

接下来，我们使用 browserify 处理它，将所有依赖项打包到单个文件中

$ npx browserify load.js -o bundle.js -d

结果是一个包含所有依赖项的巨大文件

(function(){function......
...
...
},{"protobufjs/minimal":9}]},{},[1])
//# sourceMappingURL..............

要获得最终的“njs_bundle.js”文件，我们将“bundle.js”与以下代码连接起来

// Example usage of protobuf library: prepare a buffer to send
function set_buffer(pb)
{
    // set fields of gRPC payload
    var payload = { name: "TestString" };

    // create an object
    var message = pb.helloworld.HelloRequest.create(payload);

    // serialize object to buffer
    var buffer = pb.helloworld.HelloRequest.encode(message).finish();

    var n = buffer.length;

    var frame = new Uint8Array(5 + buffer.length);

    frame[0] = 0;                        // 'compressed' flag
    frame[1] = (n & 0xFF000000) >>> 24;  // length: uint32 in network byte order
    frame[2] = (n & 0x00FF0000) >>> 16;
    frame[3] = (n & 0x0000FF00) >>>  8;
    frame[4] = (n & 0x000000FF) >>>  0;

    frame.set(buffer, 5);

    return frame;
}

// functions to be called from outside
function setbuf()
{
    return set_buffer(global.hello);
}

// call the code
var frame = setbuf();
console.log(frame);

让我们使用 node 运行该文件，确保一切正常

$ node ./njs_bundle.js
Uint8Array [
    0,   0,   0,   0,  12, 10,
   10,  84, 101, 115, 116, 83,
  116, 114, 105, 110, 103
]

现在让我们继续使用 njs

$ njs ./njs_bundle.js
Uint8Array [0,0,0,0,12,10,10,84,101,115,116,83,116,114,105,110,103]

最后一件事是使用 njs 特定的 API 将数组转换为字节字符串，以便 nginx 模块可以使用它。我们可以在代码行 return frame; } 之前添加以下代码片段

if (global.njs) {
    return String.bytesFrom(frame)
}

最后，我们成功运行了它

$ njs ./njs_bundle.js |hexdump -C
00000000  00 00 00 00 0c 0a 0a 54  65 73 74 53 74 72 69 6e  |.......TestStrin|
00000010  67 0a                                             |g.|
00000012

这是预期的结果。响应解析也可以类似地实现

function parse_msg(pb, msg)
{
    // convert byte string into integer array
    var bytes = msg.split('').map(v=>v.charCodeAt(0));

    if (bytes.length < 5) {
        throw 'message too short';
    }

    // first 5 bytes is gRPC frame (compression + length)
    var head = bytes.splice(0, 5);

    // ensure we have proper message length
    var len = (head[1] << 24)
              + (head[2] << 16)
              + (head[3] << 8)
              + head[4];

    if (len != bytes.length) {
        throw 'header length mismatch';
    }

    // invoke protobufjs to decode message
    var response = pb.helloworld.HelloReply.decode(bytes);

    console.log('Reply is:' + response.message);
}

DNS-packet

此示例使用一个用于生成和解析 DNS 数据包的库。这是一个值得考虑的案例，因为该库及其依赖项使用了 njs 尚不支持的现代语言结构。反过来，这要求我们额外执行一个步骤：转译（transpile）源代码。

需要额外的 node 包

$ npm install @babel/core @babel/cli @babel/preset-env babel-loader
$ npm install webpack webpack-cli
$ npm install buffer
$ npm install dns-packet

配置文件：webpack.config.js

const path = require('path');

module.exports = {
    entry: './load.js',
    mode: 'production',
    output: {
        filename: 'wp_out.js',
        path: path.resolve(__dirname, 'dist'),
    },
    optimization: {
        minimize: false
    },
    node: {
        global: true,
    },
    module : {
        rules: [{
            test: /\.m?js$$/,
            exclude: /(bower_components)/,
            use: {
                loader: 'babel-loader',
                options: {
                    presets: ['@babel/preset-env']
                }
            }
        }]
    }
};

请注意，我们使用的是“production”模式。在此模式下，webpack 不使用 njs 不支持的“eval”结构。引用的 load.js 文件是我们的入口点

global.dns = require('dns-packet')
global.Buffer = require('buffer/').Buffer

我们以同样的方式开始，为库生成一个单独的文件

$ npx browserify load.js -o bundle.js -d

接下来，我们使用 webpack 处理该文件，webpack 会调用 babel

$ npx webpack --config webpack.config.js

此命令生成 dist/wp_out.js 文件，它是 bundle.js 的转译版本。我们需要将其与存储我们代码的 code.js 连接起来

function set_buffer(dnsPacket)
{
    // create DNS packet bytes
    var buf = dnsPacket.encode({
        type: 'query',
        id: 1,
        flags: dnsPacket.RECURSION_DESIRED,
        questions: [{
            type: 'A',
            name: 'google.com'
        }]
    })

    return buf;
}

请注意，在此示例中，生成的代码未封装在函数中，我们无需显式调用它。结果位于“dist”目录中

$ cat dist/wp_out.js code.js > njs_dns_bundle.js

让我们在文件末尾调用我们的代码

var b = set_buffer(global.dns);
console.log(b);

并使用 node 执行它

$ node ./njs_dns_bundle_final.js
Buffer [Uint8Array] [
    0,   1,   1, 0,  0,   1,   0,   0,
    0,   0,   0, 0,  6, 103, 111, 111,
  103, 108, 101, 3, 99, 111, 109,   0,
    0,   1,   0, 1
]

确保其按预期工作，然后使用 njs 运行它

$ njs ./njs_dns_bundle_final.js
Uint8Array [0,1,1,0,0,1,0,0,0,0,0,0,6,103,111,111,103,108,101,3,99,111,109,0,0,1,0,1]

响应可以按如下方式解析

function parse_response(buf)
{
    var bytes = buf.split('').map(v=>v.charCodeAt(0));

    var b = global.Buffer.from(bytes);

    var packet = dnsPacket.decode(b);

    var resolved_name = packet.answers[0].name;

    // expected name is 'google.com', according to our request above
}