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

Default features: json, env, path, time, string, validate, sqlite-bundled (inert unless sql is enabled). 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

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.4", 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-isle. The host owns the AsyncIsle (and the AsyncIsleDriver that shuts its thread down) and passes a clone of the handle; statements run on the isle's connection thread, and cancel integrates with the enclosing scope by dropping the job, which the isle turns into sqlite3_interrupt.
• kv is a namespace-scoped key-value store backed by a SQLite table on a host-supplied isle. Writes run under BEGIN IMMEDIATE; durability and atomicity come from SQLite's WAL journal. Registration is async because the __kv table is created through the isle.

use mlua_batteries::sqlite_backend::rusqlite_isle::AsyncIsle;

let (isle, _driver) = AsyncIsle::open_in_memory(|_conn| Ok(())).await?;
mlua_batteries::sql::register(&lua, isle.clone())?;
mlua_batteries::kv::register(&lua, isle).await?;

SQLite version track

libsqlite3-sys declares links = "sqlite3", so a build graph can hold exactly one of its major versions — and cargo enforces that when it resolves dependencies, so no crate can offer several clusters behind mutually exclusive features. Each release line of this crate therefore tracks one cluster, the same way rusqlite-isle does:

Pick the line whose cluster your other rusqlite-dependent crates already sit on. The bridges name the stack only through mlua_batteries::sqlite_backend, which re-exports the active rusqlite and rusqlite_isle — hosts can wire everything through that re-export instead of declaring a second, separately-versioned dependency.

sqlite-bundled (on by default) forwards to rusqlite/bundled; use default-features = false to link the system SQLite instead.

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:

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

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.