mlua-batteries 0.3.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, LLM chat completion, structured async tasks, and SQLite-backed storage — all behind a configurable policy layer that can sandbox untrusted code.

Core modules (json, env, path, time, fs, http, hash, llm, string, regex, validate, log, uuid, base64, schema, sandbox) are synchronous (blocking) and require no async runtime. The optional task / sql / kv modules require a tokio current-thread runtime driving a LocalSet (see the Async modules section).

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
string string String utilities beyond Lua's built-ins
regex regex Regex match / replace (regex crate)
validate validate Lightweight value validation helpers
log log Bridge to the host's log facade
uuid uuid UUID v4 / v7 generation
base64 base64 Base64 encode / decode
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
schema schema JSON Schema validation (schema-bridge)
sandbox sandbox Capability-based filesystem sandbox (cap-std)
task task Structured async tasks with cooperative cancellation (requires tokio)
sql sql SQLite bridge via rusqlite + spawn_blocking
kv kv SQLite-backed key-value store (namespace-scoped)

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

Quick start

[dependencies]
mlua-batteries = "0.3"

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.3", 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.

Async modules

task, sql, and kv are async-first and require a tokio current-thread runtime driving a LocalSet. They are not part of the default feature set — opt in explicitly.

[dependencies]
mlua-batteries = { version = "0.3", features = ["task", "sql", "kv"] }
tokio = { version = "1", features = ["rt", "macros"] }
  • task provides structured concurrency primitives (spawn, scope, with_timeout, sleep, checkpoint) with cooperative, level-triggered cancellation. with_timeout applies a 3-stage graceful-abort pattern (deadline → drain under grace_ms → hard-abort).
  • sql is a SQLite bridge over rusqlite + spawn_blocking. The host owns the rusqlite::Connection and InterruptHandle; cancel integrates with the enclosing scope via sqlite3_interrupt.
  • kv is a namespace-scoped key-value store backed by a SQLite table on a host-supplied connection. Durability and atomicity come from SQLite's WAL journal.

See the module-level rustdoc on src/task/mod.rs, src/sql.rs, and src/kv.rs for the full API and wiring contract.

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.