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 and restricts access to the global basic moduleassert Module, and add 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 sandbox global Object

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 the interference of 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, Return 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

Detect the existence of the basic module 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, Copied new sandbox

---

freeze

Freeze the current sandbox, the sandbox after freezing, right global Modifications made 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 script path 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, Return 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, Return the loaded module object

---

setModuleCompiler

Add compiler to the specified extname, extname cannot be the 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'.', and is a non-system built-in extension
• compiler: Function, compile the callback function, all files with extname will only require once. The format of the callback function is compiler(buf, requireInfo), buf is the read fileBuffer, 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