Javascript Sandbox¶
The Javascript sandbox worker runs Javascript code in a Node.js instance. The provided Javascript code is run inside a thin wrapper which handles sending and receiving sandbox commands.
People writing Javascript code for the sandbox are strongly encouraged to use vumi-jssandbox-toolkit which provides a rich set of features for interacting with the sandbox resources.
Configuration options¶
- class vxsandbox.worker.JsSandboxConfig(config_data, static=False)[source]¶
JavaScript sandbox configuration.
Configuration options:
Parameters: - amqp_prefetch_count (int) – The number of messages fetched concurrently from each AMQP queue by each worker instance.
- transport_name (str) – The name this application instance will use to create its queues.
- send_to (dict) – ‘send_to’ configuration dict.
- sandbox (dict) – Dictionary of resources to provide to the sandbox. Keys are the names of resources (as seen inside the sandbox). Values are dictionaries which must contain a cls key that gives the full name of the class that provides the resource. Other keys are additional configuration for that resource.
- executable (str) – Full path to the executable to run in the sandbox.
- args (list) – List of arguments to pass to the executable (not including the path of the executable itself).
- path (str) – Current working directory to run the executable in.
- env (dict) – Custom environment variables for the sandboxed process.
- timeout (int) – Length of time the subprocess is given to process a message.
- recv_limit (int) – Maximum number of bytes that will be read from a sandboxed process’ stdout and stderr combined.
- rlimits (dict) – Dictionary of resource limits to be applied to sandboxed processes. Defaults are fairly restricted. Keys maybe names or values of the RLIMIT constants in Python resource module. Values should be appropriate integers.
- sandbox_id (str) – This is set based on individual messages.
- javascript (str) – JavaScript code to run.
- app_context (str) – Custom context to execute JS with.
- logging_resource (str) – Name of the logging resource to use to report errors detected in sandboxed code (e.g. lines written to stderr, unexpected process termination). Set to null to disable and report these directly using Twisted logging instead.
Worker class¶
- class vxsandbox.worker.JsSandbox(options, config=None)[source]¶
Configuration options:
As for Sandbox except:
- executable defaults to searching for a node.js binary.
- args defaults to the JS sandbox script in the vumi.application module.
- An instance of JsSandboxResource is added to the sandbox resources under the name js if no js resource exists.
- An instance of LoggingResource is added to the sandbox resources under the name log if no log resource exists.
- logging_resource is set to log if it is not set.
- An extra ‘javascript’ parameter specifies the javascript to execute.
- An extra optional ‘app_context’ parameter specifying a custom context for the ‘javascript’ application to execute with.
Example ‘javascript’ that logs information via the sandbox API (provided as ‘this’ to ‘on_inbound_message’) and checks that logging was successful:
api.on_inbound_message = function(command) { this.log_info("From command: inbound-message", function (reply) { this.log_info("Log successful: " + reply.success); this.done(); }); }Example ‘app_context’ that makes the Node.js ‘path’ module available under the name ‘path’ in the context that the sandboxed javascript executes in:
{path: require('path')}
- CONFIG_CLASS¶
alias of JsSandboxConfig
Javascript sandbox resources¶
This special resource provides a means of sending the Javascript code to be executed into the Node.js process. It is automatically included by the Javascript sandbox worker.