WardrikLua.Sandbox (wardrik_lua v0.1.0-rc.1)

Copy Markdown

Runs Lua code under limits, with no access to the node.

Built on lua, a Lua 5.3 VM written in Elixir.

WardrikLua.Sandbox.run("return ('%d apples'):format(3)", WardrikLua.Sandbox.Limits.new())
#=> {:ok, "3 apples"}

Errors are returned as a sentence, since a model reads them.

Globals

string, table, math, utf8 and the safe parts of os are available. io, file, os.execute, os.exit, os.getenv, package, require, load, dofile, print and debug raise when called.

Return values

  • No value returns nil, one value returns itself, several return a list.
  • A table returns a map, or a list when its keys are exactly 1..n.
  • Map keys become strings. Keys that collide after conversion are an error.
  • Functions, cyclic tables and strings that aren't valid UTF-8 are an error.

Limits

WardrikLua.Sandbox.Runner enforces the deadline and memory budget. The VM enforces the step budget and call depth itself. See WardrikLua.Sandbox.Limits.

Summary

Types

result()

The value the code returned, or why it failed.

Functions

check(code)

Returns :ok if code can be run, without running it.

evaluate(code, limits)

Evaluates code in the calling process and returns its value.

run(code, limits)

Checks code with check/1, then evaluates it in a task of its own under limits.

Types

result()

@type result() :: {:ok, term()} | {:error, String.t()}

The value the code returned, or why it failed.

Functions

check(code)

@spec check(term()) :: :ok | {:error, String.t()}

Returns :ok if code can be run, without running it.

Returns an error if code isn't a string or is longer than 64 KB.

evaluate(code, limits)

@spec evaluate(String.t(), WardrikLua.Sandbox.Limits.t()) :: result()

Evaluates code in the calling process and returns its value.

Enforces only the limits the VM checks. Use run/2 for the deadline and memory budget.

run(code, limits)

@spec run(String.t(), WardrikLua.Sandbox.Limits.t()) :: result()

Checks code with check/1, then evaluates it in a task of its own under limits.