Object SandBox

Security sandbox object, used to manage an independent operating space

All code runs in its own sandbox, the global require will call the current sandbox to load the module, and the sandbox will be passed to the loaded sandbox through require. The following example creates a sandbox, restricts access to only the assert module in the global base module, and adds two custom modules, a and b:

1
2
3
4
5
6
7
8
var vm = require('vm');
var sbox = new vm.SandBox({
    a: 100,
    b: 200,
    assert: require('assert')
});

var mod_in_sbox = sbox.require('./path/to/mod');

Inheritance

Constructor

SandBox

Construct a new security sandbox object and initialize the basic module

1
new SandBox(Object mods);

Call parameters:

• mods : Object, specify the module object dictionary to be added

Construct a new security sandbox object and initialize the basic module

1
2
new SandBox(Object mods,
    Function require);

Call parameters:

• mods : Object, specify the module object dictionary to be added
• require : Function, custom require function, when the module does not exist, call the custom function first, and then load from the file without returning

Construct a new independent Global security sandbox object and initialize the basic module

1
2
new SandBox(Object mods,
    Object global);

Call parameters:

• mods : Object, specify the module object dictionary to be added
• global : Object, specify the initialized Global property

Construct a new independent Global security sandbox object and initialize the basic module

1
2
3
new SandBox(Object mods,
    Function require,
    Object global);

Call parameters:

• mods : Object, specify the module object dictionary to be added
• require : Function, custom require function, when the module does not exist, call the custom function first, and then load from the file without returning
• global : Object, specify the initialized Global property

Member attributes

global

Object, query the global object of the sandbox

1
readonly Object SandBox.global;

modules

Object, query the dictionary object of all existing modules in the sandbox

1
readonly Object SandBox.modules;

Member function

add

Add a basic module to the sandbox

1
2
SandBox.add(String id,
    Value mod);

Call parameters:

• id : String, specify the name of the module to be added, this path has nothing to do with the currently running script, it must be an absolute path or module name
• mod : Value, specify the module object to be added

Add a set of basic modules to the sandbox

1
SandBox.add(Object mods);

Call parameters:

• mods : Object, specify the module object dictionary to be added, the added javascript module will generate a copy to avoid interference between sandbox modification objects

addScript

Add a script module to the sandbox

1
2
Value SandBox.addScript(String srcname,
    Buffer script);

Call parameters:

• srcname : String, specify the name of the script to be added, srcname must include the extension, such as json or js, jsc
• script : Buffer , specify the binary code to be added

Return result:

• Value , returns the loaded module object

remove

Delete the specified basic module from the sandbox

1
SandBox.remove(String id);

Call parameters:

• id : String, specify the name of the module to be deleted, this path has nothing to do with the currently running script, it must be an absolute path or module name

has

Check whether the basic module exists from the sandbox

1
Boolean SandBox.has(String id);

Call parameters:

• id : String, specify the name of the module to be detected, this path has nothing to do with the currently running script, it must be an absolute path or module name

Return result:

• Boolean , does it exist

clone

Copy the current sandbox, the new sandbox contains the modules of the current sandbox, with the same name and require function

1
SandBox SandBox.clone();

Return result:

• SandBox , the new sandbox copied

freeze

Freeze the current sandbox, the frozen sandbox, the changes made to global will be ignored

1
SandBox.freeze();

refresh

Reload the module in the sandbox. This operation will only reinitialize the module, reset the variables in the module, and not update the module code

1
SandBox.refresh();

run

Run a script

1
2
SandBox.run(String fname,
    Array argv = []);

Call parameters:

• fname : String, specify the path of the script to be run, this path has nothing to do with the currently running script, it must be an absolute path
• argv : Array, specify the parameter to be run, this parameter can be obtained using argv in the script

resolve

Query a module and return the full file name of the module

1
2
String SandBox.resolve(String id,
    String base);

Call parameters:

• id : String, specify the name of the module to be loaded
• base : String, specify the search path

Return result:

• String , returns the full file name of the loaded module

require

Load a module and return the module object

1
2
Value SandBox.require(String id,
    String base);

Call parameters:

• id : String, specify the name of the module to be loaded
• base : String, specify the search path

Return result:

• Value , returns the loaded module object

setModuleCompiler

Add compiler to the specified extname, extname cannot be a system built-in extension (including ('.js','. json ','.jsc','.wasm')), the compiler needs to return a valid javascript script.

1
2
SandBox.setModuleCompiler(String extname,
    Function compiler);

Call parameters:

• extname : String, the specified extname must start with a'.' and is a non-system built-in extension
• compiler : Function, compile callback function, all files with extname will only require once. The format of the callback function is compiler(buf, requireInfo) , buf is the read file Buffer , and the requireInfo structure is {filename: string} .

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var vm = require('vm');
var sbox = new vm.SandBox({});

// 编译 typescript 脚本为 js 并加载
sbox.setModuleCompiler('.ts', tsCompiler);
var mod_ts = sbox.require('./a.ts');

// 编译 coffee 脚本为 js 并加载
sbox.setModuleCompiler('.coffee', cafeCompiler);
var mod_coffee = sbox.require('./a.coffee');

// 编译 jsx 脚本为 js 并加载
sbox.setModuleCompiler('.jsx', reactCompiler);
var mod_react = sbox.require('./a.jsx');

// 编译 yml 脚本为自定义的内容(如 API 集合) 并加载
sbox.setModuleCompiler('.yml', yaml2Rest)
sbox.setModuleCompiler('.yaml', yaml2Rest)

// 编译 markdown 为自定义的内容(如 html 字符串或 XmlDocument 对象) 并加载
sbox.setModuleCompiler('.md', mdCompiler)
sbox.setModuleCompiler('.markdown', mdCompiler)

toString

Returns the string representation of the object, generally returns "[Native Object]", the object can be re-implemented according to its own characteristics

1
String SandBox.toString();

Return result:

• String , returns the string representation of the object

toJSON

Returns the JSON format representation of the object, generally returns a collection of readable attributes defined by the object

1
Value SandBox.toJSON(String key = "");

Call parameters:

• key : String, unused

Return result:

• Value , returns a value containing JSON serializable