sandbox v0.1.0 Sandbox View Source
Sandbox provides restricted, isolated scripting environments for Elixir through the use of embedded Lua.
This project is powered by Robert Virding's amazing Luerl, an Erlang library that lets one execute Lua scripts on the BEAM. Luerl executes Lua code without running a Lua VM as a separate application! Rather, the state of the VM is used as a data structure that can be externally manipulated and processed.
The :luerl_sandbox
module is utilized wherever possible. This limits access to dangerous core libraries.
It also permits Lua scripts to be run with enforced CPU reduction limits. To work with Lua's full library, use
Sandbox.unsafe_init/0
as opposed to Sandbox.init/0
.
Conventions followed in this library:
- Functions beginning with
eval
return a Lua result. - Functions starting with
confer
return a new Lua VM state. - Functions preceded by
run
return a tuple of{result, new_state}
- All functions return ok-error tuples such as
{:ok, result}
or{:error, reason}
unless followed by a bang. - Elixir functions exposed to Lua return a value indicated by the injecting function (e.g.,
set_elixir_to_confer/3
should return a bare Lua VM state).
Link to this section Summary
Functions
Create a compiled chunk of Lua code that can be transferred between Lua states.
Runs a Lua string or chunk against a Lua state and returns a new Lua state in an ok-error tuple.
Same as confer/3
, but will return the raw result or raise a RuntimeError
.
Runs a Lua file in the context of a Lua state and returns a new Lua state.
Runs a Lua function defined in the given Lua state and returns a new Lua state.
Evaluates a Lua string or chunk against the given Lua state and returns the result in an ok-error tuple. The state itself is not modified.
Same as eval/3
, but will return the raw result or raise a RuntimeError
.
Evaluates a Lua file against the given Lua state and returns the result in an ok-error tuple. The state itself is not modified.
Same as eval_file/3
, but will return the raw result or raise a RuntimeError
.
Calls a function defined in the the Lua state and returns the result. The state itself is not modified.
Lua functions can be referenced by a string or list, i.e. math.floor
or ["math", "floor"]
.
Gets a value from a Lua state.
Creates a Lua state with sandbox features.
Same as run/3
, but will return the raw {result, state}
or raise a RuntimeError
.
Sets a value in a Lua state and returns the modified state.
Exposes an Elixir function that can modify the Lua state of the script calling it. This is primarily for letting Lua scripts use something like inheritance, dynamically adding external functionality and settings.
Exposes an Elixir function for use within the Lua state. This function cannot modify the state of the Lua VM; it can only return a value.
Link to this section Types
Link to this section Functions
Create a compiled chunk of Lua code that can be transferred between Lua states.
Runs a Lua string or chunk against a Lua state and returns a new Lua state in an ok-error tuple.
Same as confer/3
, but will return the raw result or raise a RuntimeError
.
Runs a Lua file in the context of a Lua state and returns a new Lua state.
Runs a Lua function defined in the given Lua state and returns a new Lua state.
eval(state, code, max_reductions \\ 0)
View Sourceeval(lua_state(), lua_code(), pos_integer()) :: {:ok, lua_result()} | {:error, any()}
Evaluates a Lua string or chunk against the given Lua state and returns the result in an ok-error tuple. The state itself is not modified.
eval!(state, code, max_reductions \\ 0)
View Sourceeval!(lua_state(), lua_code(), pos_integer()) :: lua_result()
Same as eval/3
, but will return the raw result or raise a RuntimeError
.
eval_file(state, file_path, max_reductions \\ 0)
View Sourceeval_file(lua_state(), String.t(), pos_integer()) :: {:ok, lua_result()} | {:error, any()}
Evaluates a Lua file against the given Lua state and returns the result in an ok-error tuple. The state itself is not modified.
eval_file!(state, file_path, max_reductions \\ 0)
View Sourceeval_file!(lua_state(), String.t(), pos_integer()) :: lua_result()
Same as eval_file/3
, but will return the raw result or raise a RuntimeError
.
Calls a function defined in the the Lua state and returns the result. The state itself is not modified.
Lua functions can be referenced by a string or list, i.e. math.floor
or ["math", "floor"]
.
Gets a value from a Lua state.
Creates a Lua state with sandbox features.
run(state, code, max_reductions \\ 0)
View Sourcerun(lua_state(), lua_code(), pos_integer()) :: {:ok, {lua_result(), lua_state()}} | {:error, any()}
run!(state, code, max_reductions \\ 0)
View Sourcerun!(lua_state(), lua_code(), pos_integer()) :: lua_result()
Same as run/3
, but will return the raw {result, state}
or raise a RuntimeError
.
Sets a value in a Lua state and returns the modified state.
Exposes an Elixir function that can modify the Lua state of the script calling it. This is primarily for letting Lua scripts use something like inheritance, dynamically adding external functionality and settings.
The given Elixir function will receive two arguments, a Lua state and a list containing any arguments from Lua. It should return a new Lua VM state.
This function will return a new Lua state with access to the Elixir function at the given table path.
Exposes an Elixir function for use within the Lua state. This function cannot modify the state of the Lua VM; it can only return a value.