Webtask

Documentation

Sandboxjs

The JavaScript SDK for webtask.io

For customized documentation and ready to run samples, please log in.

About

The Auth0 Sandboxjs is a node.js package that allows you to sandbox your code and run it on the public webtask.io cluster. It supports returning Promises and/or invoking node-style callbacks.

Setup

To install sandboxjs open a terminal and run the following:

$ npm install sandboxjs

To start using sandboxjs you have to get a webtask token using wt-cli . If you already use wt-cli use:

$ wt profile ls
If you don't have a profile already, then you have to install wt-cli and initialize a new profile:
$ npm install -g wt-cli
$ wt init
In order to configure a webtask profile you need to provide an email or phone number. You will receive a verification code there which you will have to input to the terminal.

Now that you have a profile setup, let's work on some simple examples.

Create and run a webtask using sandboxjs

The code snippet below creates a new webtask and runs it using Sandbox. The webtask code is defined as module.exports = function (ctx, cb) { cb(null, "hello world"); } and the Sandbox.fromToken method is used to create a Sandbox instance from your webtask token. The token in this example is retrieved from the environment variable WEBTASK_TOKEN. Once the Sandbox instance (profile) is defined, the instance method run is used. This method is a shortcut to create and run a Webtask from the given options. The method's structure is sandbox.run([codeOrUrl], [options], [cb]), where [codeOrUrl] is the code or the URL for the webtask (in our example the code variable holds the webtask code), [options] is the set of options (for example, secrets) used to create the webtask (omitted in our example), and [cb] is the optional callback function for node-style callbacks. In our example the callback function uses Assert to display:

  • the error if the callback returns one
  • The webtask executed as expected if the status code returned by the webtask is 200
  • The webtask returned the expected string if the webtask returns the expected hello world
You can read more on this method here.
var Assert = require('assert');
var Sandbox = require('sandboxjs');

var code = 'module.exports = function (ctx, cb) { cb(null, "hello world"); }';
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

// This library lets you create a webtask and run it in one step as a shortcut
profile.run(code, function (err, res, body) {
  Assert.ifError(err);
  Assert.equal(res.statusCode, 200, 'The webtask executed as expected');
  Assert.equal(body, 'hello world', 'The webtask returned the expected string');
});

Create a webtask and get the URL

Our second example creates a webtask but instead of running it, returns the URL as output. Making requests to this url will run the specified custom code in a node.js sandbox and will give it access to your secrets in the firstargument of your exported webtask function. In this example we are utilizing the [options] argument and use it to set a secret: auth0: 'rocks'.

var Assert = require('assert');
var Sandbox = require('sandboxjs');

var code = 'module.exports = function (ctx, cb) { cb(null, "hello world"); }';
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

// This library lets you create a webtask and returns the URL:
profile.create(code, { secrets: { auth0: 'rocks' } }, function (err, webtask) {
  Assert.ifError(err);
  console.log(webtask.url);
});

Update the code of an existing webtask

Our third example retrieves an existing named webtask and updates its code. Let's say that you already have a webtask named my-webtask and it prints Hello world. We will update its code to print Hello there instead. The code snippet uses the method sandbox.updateWebtask(options, [cb]) to update the webtask's code. This function can also be used to update a webtask's secrets or other claims. Note that this method should be used with caution as there is the potential for a race condition where another agent updates the webtask between the time that the webtask details and claims are resolved and when the webtask update is issued.

var Sandbox = require('sandboxjs');

var webtaskName = 'my-webtask'; //existing webtask name
var webtaskCode = 'module.exports = function (ctx, cb) { cb(null, "Hello there"); }'; //updated code
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

profile.updateWebtask({
  name: webtaskName,
  code: webtaskCode,
});

List of methods

For a list of supported API methods please refer to our GitHub repository.