Module supple.host

Running the host-side of sandboxed code

When running code in Supple sandboxes, the starting point is this module.

The host application should require supple and then begin from here…

local supple = require 'supple'
print(supple.host.run("return ...", "example code", "arg1", "arg2"))
-- Expect: 'arg1    arg2' as output

Functions

run (codestr, codename[, ...]) Run some code in a Supple sandbox

Call this routine to run some code in a Supple sandbox.

loadstring (codestr, codename) Load a string into the sandbox and return it as a wrappered function.
set_name (newname) Set the name by which the host refers to itself in traces.
set_limits (newlimits) Set a new limits table for use in a new sandbox instance.
set_globals (newglobals) Set a new globals table to be used by new sandbox runs.


Functions

run (codestr, codename[, ...])
Run some code in a Supple sandbox

Call this routine to run some code in a Supple sandbox. The code is compiled and run entirely within the sandbox process. Any kind of value can be passed to the code as an argument. Intrinsics are transferred immediately (numbers, booleans, nils, strings) but complex values (tables, userdata, and functions) are sent over as a proxy and actions on those values are proxied back to the host to be run. Users of Supple should be aware that those routines are therefore not sandboxed.

Parameters:

  • codestr string The code to run in the sandbox, as a string.
  • codename string The name to give to the code running in the sandbox.
  • ... Arguments to pass to the code running in the sandbox. (optional)

Returns:

  1. boolean A value which has ‘truth’
  2. … The results returned from running the code in the sandbox.

Or

  1. boolean A value which has ‘falsehood’
  2. string The basic Lua error message associated with the failure
  3. string The Supple traceback (very large, not useful for users)
loadstring (codestr, codename)
Load a string into the sandbox and return it as a wrappered function.

This loads the given string (with given name) into the sandbox interpreter and then wrappers the function and returns it to the caller. This can then be used to call code inside the sandbox. This is the entry point to load further code into the sandbox and should only be called during running sandboxed code (i.e. supple.host.run is running)

Parameters:

  • codestr string The code to be loaded in the sandboxed interpreter
  • codename string The name to be given to the code when it is loaded

Returns:

  1. function The wrappered function which can then be called or handed back to the sandbox as needed.
  2. table The function environment for the loaded sandboxed code.
set_name (newname)
Set the name by which the host refers to itself in traces.

Calling this resets the host sandbox counter and sets the name of the host to the given new name. This mostly has an effect on object names and trace data which typically only appear if the user of Supple chooses to trace the activity of the sandbox, or if an error occurs.

Parameters:

  • newname string The new host name to set
set_limits (newlimits)
Set a new limits table for use in a new sandbox instance.

When a sandbox is run (from supple.host.run) it has a number of soft limits sent to it to be honoured during the runtime of the sandbox. Normally the sandbox limits itself only by hard limits, but this call allows tighter soft limits to be set if so-desired.

The table provided takes the form:

 { [count = maxopcodestorun], [memory = maxbytestouse] }

If you call this function then at least one, but optionally both of the count and memory table entries need to be present.

Parameters:

  • newlimits table The new soft-limits for any new sandboxes
set_globals (newglobals)
Set a new globals table to be used by new sandbox runs.

When a sandboxed function is run, it is run within a given globals table. The globals in question are provided by calling this function. Remember that the table will be passed shallowly and new globals created by the sandboxed code will not be copied back to the host.

Parameters:

  • newglobals table The set of globals to be passed to the sandbox
generated by LDoc 1.4.6 Last updated 2022-04-25 14:03:04