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 or run 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

Link to this type

elixir_eval_fun()

View Source
elixir_eval_fun() :: (lua_state(), [any()] -> lua_result())
Link to this type

elixir_play_fun()

View Source
elixir_play_fun() :: (lua_state(), [any()] -> lua_state())
Link to this type

elixir_run_fun()

View Source
elixir_run_fun() :: (lua_state(), [any()] -> {lua_result(), lua_state()})
Link to this type

lua_chunk()

View Source
lua_chunk() :: {:lua_func, any(), any(), any(), any(), any()}
Link to this type

lua_path()

View Source
lua_path() :: String.t() | [String.t()]
Link to this type

lua_result()

View Source
lua_result() :: number() | String.t() | [tuple()]
Link to this type

lua_state()

View Source
lua_state() ::
  {:luerl, any(), any(), any(), any(), any(), any(), any(), any(),
   any(), any(), any(), any(), any(), any()}

Link to this section Functions

Link to this function

chunk(state, code)

View Source
chunk(lua_state(), lua_code()) :: {:ok, lua_chunk()} | {:error, any()}

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.

Link to this function

eval(state, code, max_reductions \\ 0)

View Source
eval(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.

Link to this function

eval!(state, code, max_reductions \\ 0)

View Source

Same as eval/3, but will return the raw result or raise a RuntimeError.

Link to this function

eval_file(state, file_path, max_reductions \\ 0)

View Source
eval_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.

Link to this function

eval_file!(state, file_path, max_reductions \\ 0)

View Source
eval_file!(lua_state(), String.t(), pos_integer()) :: lua_result()

Same as eval_file/3, but will return the raw result or raise a RuntimeError.

Link to this function

eval_function!(state, path, args \\ [], max_reductions \\ 0)

View Source

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.

Link to this function

play(state, code, max_reductions \\ 0)

View Source

Runs a Lua string or chunk against a Lua state and returns a new Lua state in an ok-error tuple.

Link to this function

play!(state, code, max_reductions \\ 0)

View Source

Same as play/3, but will return the raw result or raise a RuntimeError.

Link to this function

play_file!(state, file_path, max_reductions \\ 0)

View Source

Runs a Lua file in the context of a Lua state and returns a new Lua state.

Link to this function

play_function!(state, path, args \\ [], max_reductions \\ 0)

View Source

Runs a Lua function defined in the given Lua state and returns a new Lua state.

Link to this function

run(state, code, max_reductions \\ 0)

View Source
run(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.

Link to this function

run!(state, code, max_reductions \\ 0)

View Source

Same as run/3, but will return the raw {result, state} or raise a RuntimeError.

Link to this function

run_function!(state, path, args \\ [], max_reductions \\ 0)

View Source

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"].

Link to this function

set!(state, path, value, force \\ false)

View Source

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.

Link to this function

set_elixir_to_eval!(state, name, fun)

View Source
set_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.

Link to this function

set_elixir_to_play!(state, path, fun)

View Source
set_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.

Link to this function

set_elixir_to_run!(state, name, fun)

View Source
set_elixir_to_run!(lua_state(), lua_path(), elixir_run_fun()) :: lua_state()