ObjectSandBox

Isolated sandbox object, used to manage an independent running 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 that restricts access to only global base modules.assertmodule, 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');

It should be noted that SandBox is not an attack-proof security sandbox. SandBox is just an independent running space that can be used to isolate different codes and avoid mutual interference, but it cannot prevent malicious code.

inheritance relationship

Constructor

SandBox

Construct a new isolation sandbox object and initialize the basic module

1
new SandBox(Object mods = {});

Call parameters:

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

---

Construct a new isolation sandbox object and initialize the basic module

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

Call parameters:

• mods: Object, specifies the module object dictionary to be added
• require: Function, a custom require function. When the module does not exist, the custom function is called first, without return, and then loaded from the file.

---

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

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

Call parameters:

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

---

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

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

Call parameters:

• mods: Object, specifies the module object dictionary to be added
• require: Function, a custom require function. When the module does not exist, the custom function is called first, without return, and then loaded from the file.
• global: Object, specifies the initialized Global property

member properties

global

Object, query sandboxglobalobject

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

addBuiltinModules

Add built-in base modules to the sandbox

1
SandBox.addBuiltinModules();

---

add

Add a base module to the sandbox

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

Call parameters:

• id: String, specifies 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, specifies the module object to be added

---

Add a set of base modules to the sandbox

1
SandBox.add(Object mods);

Call parameters:

• mods: Object, specifies the module object dictionary to be added. The added javascript module will generate a copy to avoid mutual 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, specifies the name of the script to be added, srcname must include the extension, such asjsonOr js, jsc
• script:Buffer, specifies the binary code to be added

Return results:

• Value, returns the loaded module object

---

remove

Removes the specified base module from the sandbox

1
SandBox.remove(String id);

Call parameters:

• id: String, specifies 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 whether the basic module exists from the sandbox

1
Boolean SandBox.has(String id);

Call parameters:

• id: String, specifies 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 results:

• 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 results:

• SandBox, copied new sandbox

---

freeze

Freeze the current sandbox and the frozen sandbox.globalChanges made will be ignored

1
SandBox.freeze();

---

run

run a script

1
SandBox.run(String fname);

Call parameters:

• fname: String, specifies the path of the script to be run. This path has nothing to do with the currently running script and must be an absolute path.

---

resolve

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

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

Call parameters:

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

Return results:

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

---

require

Loads a module and returns the module object

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

Call parameters:

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

Return results:

• Value, returns the loaded module object

---

setModuleCompiler

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

// compile ts to js and load
sbox.setModuleCompiler('.ts', tsCompiler);
var mod_ts = sbox.require('./a.ts');

// compile coffee to js and load
sbox.setModuleCompiler('.coffee', cafeCompiler);
var mod_coffee = sbox.require('./a.coffee');

// compile jsx to js and load
sbox.setModuleCompiler('.jsx', reactCompiler);
var mod_react = sbox.require('./a.jsx');

// compile yaml to rest and load
sbox.setModuleCompiler('.yml', yaml2Rest)
sbox.setModuleCompiler('.yaml', yaml2Rest)

// compile markdown to html and load
sbox.setModuleCompiler('.md', mdCompiler)
sbox.setModuleCompiler('.markdown', mdCompiler)

---

toString

Returns the string representation of the object. Generally, "[Native Object]" is returned. The object can be re-implemented according to its own characteristics.

1
String SandBox.toString();

Return results:

• String, returns the string representation of the object

---

toJSON

Returns a JSON format representation of the object, generally returning a collection of readable properties defined by the object.

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

Call parameters:

• key: String, not used

Return results:

• Value, returns a value containing JSON serializable