mlua-batteries 0.2.0

Batteries-included standard library modules for mlua
Documentation

mlua-batteries

Batteries-included standard library modules for mlua.

Lua 5.4 scripts gain access to JSON, environment variables, filesystem, HTTP, hashing, and LLM chat completion — all behind a configurable policy layer that can sandbox untrusted code.

All APIs are synchronous (blocking). No async runtime required.

Modules

Module Feature flag Description
json json JSON encode / decode (serde_json)
env env Environment variable access (overlay-safe set)
path path Path manipulation (pure computation + absolute)
time time Timestamps, sleep, measure
fs fs File I/O, walk, glob (walkdir + globset)
http http HTTP client (ureq)
hash hash SHA-256 hashing (sha2)
llm llm Chat completion — OpenAI, Anthropic, Ollama

Default features: json, env, path, time. Enable everything: full.

Quick start

[dependencies]
mlua-batteries = "0.1"

use mlua::prelude::*;

let lua = Lua::new();
mlua_batteries::register_all(&lua, "std").unwrap();

lua.load(r#"
    local data = std.json.decode('{"name":"Lua"}')
    print(data.name)                     -- Lua
    print(std.env.get("HOME"))           -- /Users/...
    print(std.path.join("/tmp", "a.txt"))-- /tmp/a.txt
    print(std.time.now())                -- 1740000000.123
"#).exec().unwrap();

Per-module registration

For integration with mlua-pkg or custom loaders:

for (name, factory) in mlua_batteries::module_entries() {
    // name: "json", "env", ...
    // factory: fn(&Lua) -> LuaResult<LuaTable>
    let table = factory(&lua).unwrap();
}

Sandboxing

The default configuration uses Unrestricted policies — Lua scripts can access any file, URL, and env var. For untrusted scripts, use Sandboxed (requires the sandbox feature):

[dependencies]
mlua-batteries = { version = "0.1", features = ["full"] }

use mlua::prelude::*;
use mlua_batteries::config::Config;
use mlua_batteries::policy::Sandboxed;

let lua = Lua::new();
let config = Config::builder()
    .path_policy(Sandboxed::new(["/app/data"]).unwrap().read_only())
    .max_walk_depth(50)
    .build()
    .expect("invalid config");

mlua_batteries::register_all_with(&lua, "std", config).unwrap();

Policy layers

Policy Controls Built-in options
PathPolicy Filesystem access Unrestricted, Sandboxed (cap-std)
HttpPolicy Outbound URLs Unrestricted
EnvPolicy Env var read/write Unrestricted
LlmPolicy LLM provider/model access Unrestricted

All policies are trait objects — implement the trait to create custom policies.

LLM module

Built-in providers: OpenAI, Anthropic, Ollama. API keys are read from environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY).

local resp = std.llm.chat({
    provider = "openai",
    model    = "gpt-4o",
    prompt   = "Hello!",
    system   = "You are helpful.",
    max_tokens  = 1024,
    temperature = 0.7,
})
print(resp.content)

-- Batch parallel requests
local results = std.llm.batch({
    { provider = "ollama",  model = "llama3.2", prompt = "Q1" },
    { provider = "openai",  model = "gpt-4o",   prompt = "Q2" },
})

Custom providers can be registered via mlua_batteries::llm::register_provider.

Configuration

Config::builder() exposes all tunable limits:

Setting Default Description
max_walk_depth 256 Max directory depth for fs.walk
max_walk_entries 10,000 Max entries from fs.walk / fs.glob
max_json_depth 128 Max nesting depth for JSON
http_timeout 30s Default HTTP request timeout
max_response_bytes 10 MiB Max HTTP response body size
max_sleep_secs 86,400 Max time.sleep duration
llm_default_timeout_secs 120 Default LLM request timeout
llm_max_response_bytes 10 MiB Max LLM response body size
llm_max_batch_concurrency 8 Max threads for llm.batch

Platform support

Unix only (Linux, macOS). Windows is not a supported target.

All path arguments are UTF-8. Non-UTF-8 Lua strings are rejected at the FromLua boundary.

MSRV

Rust 1.77 or later.

Contributing

Bug reports and feature requests are welcome — please open an issue. Pull requests are also appreciated.

License

Licensed under either of

at your option.