Sandbox¶

Runs custom application logic in a sandbox.

Sandbox application workers¶

Sandbox¶

class vumi.application.sandbox.SandboxConfig(config_data, static=False)¶

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.
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.
sandbox_id (str) – This is set based on individual messages.

class vumi.application.sandbox.Sandbox(options, config=None)¶: Sandbox application worker.

Javascript Sandbox¶

class vumi.application.sandbox.JsSandboxConfig(config_data, static=False)¶

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.

class vumi.application.sandbox.JsSandbox(options, config=None)¶

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')}

Javascript File Sandbox¶

class vumi.application.sandbox.JsFileSandbox(options, config=None)¶

class CONFIG_CLASS(config_data, static=False)¶

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.
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.
sandbox_id (str) – This is set based on individual messages.
javascript_file (str) – The file containting the Javascript to run
app_context (str) – Custom context to execute JS with.

Sandbox resources¶

RedisResource¶

class vumi.application.sandbox.RedisResource(name, app_worker, config)¶

Resource that provides access to a simple key-value store.

Configuration options:

Parameters:

redis_manager (dict) – Redis manager configuration options.
keys_per_user_soft (int) – Maximum number of keys each user may make use of in redis before usage warnings are logged. (default: 80% of hard limit).
keys_per_user_hard (int) – Maximum number of keys each user may make use of in redis (default: 100). Falls back to keys_per_user.
keys_per_user (int) – Synonym for keys_per_user_hard. Deprecated.

handle_delete(*args, **kwargs)¶

Delete a key.

Command fields:

key: The key to delete.

Reply fields:

success: true if the operation was successful, otherwise false.

Example:

api.request(
    'kv.delete',
    {key: 'foo'},
    function(reply) {
        api.log_info('Value deleted: ' +
                     reply.success);
    }
);

handle_get(*args, **kwargs)¶

Retrieve the value of a key.

Command fields:

key: The key whose value should be retrieved.

Reply fields:

success: true if the operation was successful, otherwise false.
value: The value retrieved.

Example:

api.request(
    'kv.get',
    {key: 'foo'},
    function(reply) {
        api.log_info(
            'Value retrieved: ' +
            JSON.stringify(reply.value));
    }
);

handle_incr(*args, **kwargs)¶

Atomically increment the value of an integer key.

The current value of the key must be an integer. If the key does not exist, it is set to zero.

Command fields:

key: The key to delete.
amount: The integer amount to increment the key by. Defaults to 1.

Reply fields:

success: true if the operation was successful, otherwise false.
value: The new value of the key.

Example:

api.request(
    'kv.incr',
    {key: 'foo',
     amount: 3},
    function(reply) {
        api.log_info('New value: ' +
                     reply.value);
    }
);

handle_set(*args, **kwargs)¶

Set the value of a key.

Command fields:

key: The key whose value should be set.
value: The value to store. May be any JSON serializable object.
seconds: Lifetime of the key in seconds. The default null indicates that the key should not expire.

Reply fields:

success: true if the operation was successful, otherwise false.

Example:

api.request(
    'kv.set',
    {key: 'foo',
     value: {x: '42'}},
    function(reply) { api.log_info('Value store: ' +
                                   reply.success); });

OutboundResource¶

class vumi.application.sandbox.OutboundResource(name, app_worker, config)¶

Resource that provides the ability to send outbound messages.

Includes support for replying to the sender of the current message, replying to the group the current message was from and sending messages that aren’t replies.

JsSandboxResource¶

class vumi.application.sandbox.JsSandboxResource(name, app_worker, config)¶

Resource that initializes a Javascript sandbox.

Typically used alongside vumi/applicaiton/sandboxer.js which is a simple node.js based Javascript sandbox.

Requires the worker to have a javascript_for_api method.

LoggingResource¶

class vumi.application.sandbox.LoggingResource(name, app_worker, config)¶

Resource that allows a sandbox to log messages via Twisted’s logging framework.

handle_critical(api, command)¶

Logs a message at the CRITICAL log level.

See handle_log() for details.

handle_debug(api, command)¶

Logs a message at the DEBUG log level.

See handle_log() for details.

handle_error(api, command)¶

Logs a message at the ERROR log level.

See handle_log() for details.

handle_info(api, command)¶

Logs a message at the INFO log level.

See handle_log() for details.

handle_log(*args, **kwargs)¶

Log a message at the specified severity level.

The other log commands are identical except that level need not be specified. Using the log-level specific commands is preferred.

Command fields:

level: The severity level to log at. Must be an integer log level. Default severity is the INFO log level.
msg: The message to log.

Reply fields:

success: true if the operation was successful, otherwise false.

Example:

api.request(
    'log.log',
    {level: 20,
     msg: 'Abandon ship!'},
    function(reply) {
        api.log_info('New value: ' +
                     reply.value);
    }
);

handle_warning(api, command)¶

Logs a message at the WARNING log level.

See handle_log() for details.

log(api, msg, level)¶

Logs a message via vumi.log (i.e. Twisted logging).

Sub-class should override this if they wish to log messages elsewhere. The api parameter is provided for use by such sub-classes.

The log method should always return a deferred.

HttpClientResource¶

class vumi.application.sandbox.HttpClientResource(name, app_worker, config)¶

Resource that allows making HTTP calls to outside services.

All command on this resource share a common set of command and response fields:

Command fields:

url: The URL to request
verify_options: A list of options to verify when doing

an HTTPS request. Possible string values are VERIFY_NONE, VERIFY_PEER, VERIFY_CLIENT_ONCE and VERIFY_FAIL_IF_NO_PEER_CERT. Specifying multiple values results in passing along a reduced OR value (e.g. VERIFY_PEER | VERIFY_FAIL_IF_NO_PEER_CERT)
headers: A dictionary of keys for the header name and a list

of values to provide as header values.
data: The payload to submit as part of the request.

files: A dictionary, submitted as multipart/form-data

in the request:

[{
    "field name": {
        "file_name": "the file name",
        "content_type": "content-type",
        "data": "data to submit, encoded as base64",
    }
}, ...]

The data field in the dictionary will be base64 decoded before the HTTP request is made.

Success reply fields:

success: Set to true
body: The response body
code: The HTTP response code

Failure reply fields:

success: set to false
reason: Reason for the failure

Example:

api.request(
    'http.get',
    {url: 'http://foo/'},
    function(reply) { api.log_info(reply.body); });

agent_class¶: alias of Agent

handle_delete(api, command)¶

Make an HTTP DELETE request.