sandbox v0.2.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
play
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 should all take two arguments: a Lua state and a list of Lua arguments. They
should return a value corresponding to the
eval
,play
orrun
responses.
Link to this section Summary
Functions
Create a compiled chunk of Lua code that can be transferred between Lua states, returned in an ok-error tuple.
Same as chunk/2
, but will return the raw result or raise a RuntimeError
.
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 only the result. The state itself is not modified.
Lua functions in the Lua state can be referenced by their lua_path
, being a string or list such as math.floor
or ["math", "floor"]
.
Gets a value from a Lua state.
Creates a Lua state with sandbox features.
Runs a Lua string or chunk against a Lua state and returns a new Lua state in an ok-error tuple.
Same as play/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.
Runs a Lua string or chunk against the given Lua state and returns the result and the new Lua state in an ok-error tuple.
Same as run/3
, but will return the raw {result, state}
or raise a RuntimeError
.
Runs a function defined in the the Lua state and returns the result and the new Lua state as {result, state}
.
Lua functions in the Lua state can be referenced by their lua_path
, a string or list such as math.floor
or ["math", "floor"]
.
Sets a value in a Lua state and returns the modified state. If force
is set to true, new tables will be created
automatically if they missing from the given lua_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.
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.
Link to this section Types
elixir_eval_fun()
View Sourceelixir_eval_fun() :: (lua_state(), [any()] -> lua_result())
elixir_run_fun()
View Sourceelixir_run_fun() :: (lua_state(), [any()] -> {lua_result(), lua_state()})
Link to this section Functions
Create a compiled chunk of Lua code that can be transferred between Lua states, returned in an ok-error tuple.
Same as chunk/2
, but will return the raw result or raise a RuntimeError
.
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 only the result. The state itself is not modified.
Lua functions in the Lua state can be referenced by their lua_path
, being a string or list such as math.floor
or ["math", "floor"]
.
Gets a value from a Lua state.
Creates a Lua state with sandbox features.
Runs a Lua string or chunk against a Lua state and returns a new Lua state in an ok-error tuple.
Same as play/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.
run(state, code, max_reductions \\ 0)
View Sourcerun(lua_state(), lua_code(), pos_integer()) :: {:ok, lua_state() | {lua_result(), lua_state()}} | {:error, any()}
Runs a Lua string or chunk against the given Lua state and returns the result and the new Lua state in an ok-error tuple.
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
.
Runs a function defined in the the Lua state and returns the result and the new Lua state as {result, state}
.
Lua functions in the Lua state can be referenced by their lua_path
, a string or list such as math.floor
or ["math", "floor"]
.
Sets a value in a Lua state and returns the modified state. If force
is set to true, new tables will be created
automatically if they missing from the given lua_path
.
set_elixir_to_eval!(state, name, fun)
View Sourceset_elixir_to_eval!(lua_state(), lua_path(), elixir_eval_fun()) :: lua_state()
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.
set_elixir_to_play!(state, path, fun)
View Sourceset_elixir_to_play!(lua_state(), lua_path(), elixir_play_fun()) :: lua_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.
set_elixir_to_run!(state, name, fun)
View Sourceset_elixir_to_run!(lua_state(), lua_path(), elixir_run_fun()) :: lua_state()