luart

README

English | 한국어

go-lua-perf (luart)

luart runs Lua scripts in Go with high performance and concurrency safety — a per-key:version bytecode cache, per-script VM pooling, and a self-managing dynamic registry — on top of lua-pure, a pure-Go PUC-Lua 5.4 engine.

• Module github.com/htcom-code/go-lua-perf · Go 1.25+ · lua-pure v0.1.2 (Lua 5.4) · v0.0.1
• The core library depends only on lua-pure (the config loader's YAML dependency is isolated in luartconfig).

Features

• Bytecode cache — compile once per key:version. A script is parsed and compiled only on its first run; every later run is a 0-alloc cache hit, independent of source size.
• Concurrency-safe VM pooling. Each script gets its own pool of Lua States, never shared across goroutines, so thousands of concurrent Run calls reuse warm VMs.
• Self-managing registry — lazy load, TTL & memory-budget eviction, hot reload. Scripts load on demand, idle States are reclaimed (TTL + LRU under a memory cap), the cap applies backpressure, and a notification hot-reloads with no restart.
• Pluggable SourceLoader + metrics/logging/tracing. Fetch scripts from any backend (file, DB, in-memory, caching, routing); opt into Metrics, Logger, and a per-stage TraceHook at zero cost when unset.
• Sandboxed Lua 5.4 with exec-time & instruction limits. A safe default library set (customizable via Config.Libs), plus ExecTimeout (wall-clock) and MaxInstructions (opcode) caps for untrusted scripts.

Installation

go get github.com/htcom-code/go-lua-perf

The library lives at the module root; the package name is luart, so import it with an alias:

import luart "github.com/htcom-code/go-lua-perf"

Public module — go get works directly via the module proxy. The API is 0.x and may change between minor versions.

Quick Start

import (
	"context"
	"fmt"

	lua "github.com/htcom-code/lua-pure/lua"
	luart "github.com/htcom-code/go-lua-perf"
)

loader := luart.NewMapLoader() // a SourceLoader (where your cache/DB plugs in)
src := `function greet(name) return "hello, " .. name end`
loader.Set("greeter", src, luart.HashVersion(src), "1.0.0")

rt := luart.New(loader, luart.Config{MaxStates: 4})
defer rt.Close()

out, _ := rt.Run(context.Background(), "greeter", "greet", lua.LString("luart"))
fmt.Println(out[0].String()) // hello, luart

[!IMPORTANT] SourceLoader is the interface you implement — write it to fetch sources from your external cache/DB/service: Load(key string) (src, version, displayVersion string, err error)

NewMapLoader (and Set / Loads) is a test/demo-only in-memory implementation, not suitable for production (it keeps every source resident forever). Only the content-hash helper HashVersion(src string) string is meant for use beyond demos.

Full guide + File/DB/Memory/hybrid examples: docs/SourceLoader.md.

Usage

The runtime is a small surface: construct with New, execute with Run / RunValues / RunWith, reload with Notify, and stop with Close / Shutdown. You implement SourceLoader to fetch scripts from your own cache/DB/service.

• Run — fastest path; read the returned values synchronously.
• RunValues — deep-copies results to Go values, safe to keep after the call.
• RunWith — consume results inside a handler while the State is still owned.

Runnable, test-covered examples — one folder per feature (hot reload, TTL, memory budget, exec timeout, graceful shutdown, config loading, metrics, logging, tracing, sandbox, custom libs, custom loaders) — live in examples/:

go run ./examples/basics

Full API reference: pkg.go.dev (or make doc).

Configuration

Set luart.Config in code, or load the numeric/duration fields from JSON/YAML/env via the luartconfig subpackage. Key knobs:

Concern	Fields
Concurrency cap	MaxStates, or MemoryBudgetBytes (derives the cap)
Idle reclaim	IdleTTL, JanitorInterval
Runaway guards	ExecTimeout (wall-clock), MaxInstructions (opcodes)
Sandbox / libraries	Libs, ExtraLibs, IsolateGlobals
Observability	Metrics, Logger, Trace

• Field reference & loading (JSON/YAML/env, precedence): docs/config.md
• Choosing values by workload: docs/tuning.md
• Implementing a SourceLoader: docs/SourceLoader.md

Performance

• VM pool reuse ≈ 870× faster than building a fresh State per call (~258 ns vs ~225 µs), and a compile-cache hit is 0-alloc.
• Cache-hit execution is effectively size-independent (~550 ns): the one-time compile is paid once per key:version and amortized across every run.
• Compile cost stays within ~1–2× time / ~2× memory of PUC-Lua's C compiler (lua-pure ports it in pure Go).

Full methodology and per-benchmark tables: docs/BENCHMARKS.md. Reproduce on your machine with make bench and go run ./performance.

Documentation

• API reference — pkg.go.dev (make doc / make doc-web locally)
• Guides — config · tuning · SourceLoader · benchmarks
• Changelog — CHANGELOG.md

Status & Roadmap

luart is at v0.0.1 (0.x) — usable, with an API that may still change between minor versions. See ROADMAP.md for direction and non-goals.

Contributing

Contributions welcome — see CONTRIBUTING.md for the build/test discipline (make all gate, per-file tests, benchmark guardrails) and the architecture map. Bug reports / feature requests use the issue templates; Lua language issues belong to the lua-pure engine.

Security

luart can run untrusted Lua at scale, but the host owns the sandboxing and resource-limit policy. See SECURITY.md for the threat model and how to report a vulnerability privately.

License

MIT © 2026 htjulia

Documentation

Overview

Package luart is a reusable, thread-safe runtime for executing many Lua scripts (lua-pure) from many goroutines. It lazily loads script sources from an external SourceLoader, compiles once per key:version, pools preloaded LStates per script, evicts idle pools, caps total VMs by a memory budget, and hot-reloads on external notification (drop-and-reload).

Observability (Metrics, Logger), config loading (subpackage luartconfig: JSON/YAML/env), graceful shutdown (Shutdown), and developer profiling (TraceHook) are all opt-in and add no required dependency beyond lua-pure.

Since: 2026-06-07

Index

• Variables
• func HashVersion(src string) string
• type Change
• type CompileCache
  • func NewCompileCache() *CompileCache
  • func (c *CompileCache) CompileCount() int64
  • func (c *CompileCache) GetOrCompile(cacheKey, name, src string) (*lua.Proto, error)
• type Config
  • func (c Config) Validate() error
• type Logger
  • func NewSlogLogger(l *slog.Logger) Logger
• type MapLoader
  • func NewMapLoader() *MapLoader
  • func (l *MapLoader) Load(key string) (string, string, string, error)
  • func (l *MapLoader) Loads() int64
  • func (l *MapLoader) Set(key, src, version, displayVersion string)
• type Metrics
• type PoolStat
• type Runtime
  • func New(loader SourceLoader, cfg Config) *Runtime
  • func (m *Runtime) Close()
  • func (m *Runtime) CompileCount() int64
  • func (m *Runtime) Notify(key, version, displayVersion string)
  • func (m *Runtime) NotifyChanges(changes []Change)
  • func (m *Runtime) PoolStats() []PoolStat
  • func (m *Runtime) Run(ctx context.Context, key, entryFn string, args ...lua.Value) ([]lua.Value, error)
  • func (m *Runtime) RunValues(ctx context.Context, key, entryFn string, args ...lua.Value) ([]any, error)
  • func (m *Runtime) RunWith(ctx context.Context, key, entryFn string, ...) error
  • func (m *Runtime) Shutdown(ctx context.Context) error
  • func (m *Runtime) Stats() Stats
• type SourceLoader
• type Stats
• type TraceHook

Examples

• Runtime
• Runtime (Notify)

Variables

var ErrClosed = errors.New("luart: runtime closed")

ErrClosed is returned when a closed Runtime is used.

var ErrInstructionLimit = errors.New("luart: instruction limit exceeded")

ErrInstructionLimit is returned by Run when a script exceeds Config.MaxInstructions (a runaway pure-Lua CPU cap, orthogonal to ExecTimeout). Use errors.Is(err, ErrInstructionLimit) to detect it.

Functions

func HashVersion

func HashVersion(src string) string

HashVersion returns the content hash (sha256 hex) of src — the recommended engine-facing version (any content change yields a different version). The external system usually provides it; this helper is for tests, demos, and self-verification. Since: 2026-06-07

Types

type Change

type Change struct {
	Key            string
	Version        string // engine version (content hash)
	DisplayVersion string // human label (optional)
}

Change is one external change notification.

type CompileCache

type CompileCache struct {
	// contains filtered or unexported fields
}

CompileCache compiles sources into immutable *lua.Proto and caches them permanently.

func NewCompileCache

func NewCompileCache() *CompileCache

NewCompileCache returns an empty cache.

func (*CompileCache) CompileCount

func (c *CompileCache) CompileCount() int64

CompileCount returns the number of actual compiles (distinct key:version).

func (*CompileCache) GetOrCompile

func (c *CompileCache) GetOrCompile(cacheKey, name, src string) (*lua.Proto, error)

GetOrCompile returns the compile result for cacheKey (the same key compiles exactly once; different keys compile in parallel). cacheKey is normally of the form "scriptKey:version".

type Config

type Config struct {
	// MaxStates, if > 0, is the global cap. If 0, it is derived from
	// MemoryBudgetBytes divided by the measured per-state heap cost.
	MaxStates         int
	MemoryBudgetBytes uint64

	IdleTTL         time.Duration // pools idle longer than this are evicted whole
	JanitorInterval time.Duration // janitor sweep period

	// ExecTimeout, if > 0, is a per-execution hard cap: each Run binds the
	// running LState to a context with this deadline so a runaway (e.g. infinite
	// loop) script is aborted. 0 disables it (no per-opcode context check, zero
	// overhead). A cancelable ctx passed to Run is honored regardless. See Run.
	// Since: 2026-06-07
	ExecTimeout time.Duration

	// MaxInstructions, if > 0, caps how many Lua bytecode instructions a single Run
	// may execute before it is aborted with ErrInstructionLimit. It is the runaway
	// pure-Lua CPU guard and is orthogonal to ExecTimeout: ExecTimeout is a
	// wall-clock budget (covers blocking I/O in callbacks via the ctx passed to
	// Run / L.Context()), while MaxInstructions bounds only opcode count — so a
	// blocking but cooperative callback is not charged against it. It is enforced
	// only at the engine's finalizer-poll gate, so the effective cap is rounded up
	// to that granularity. Reset per Run (no carry-over across pooled reuse). 0
	// disables it (zero overhead). Pure-Lua only — a blocking Go callback cannot be
	// preempted by it (use ExecTimeout + a cancelable ctx for that).
	// Since: 2026-06-28
	MaxInstructions uint64

	Libs []func(*lua.LState) // libraries to open on pooled States (defaults to defaultLibs)

	// ExtraLibs are opened on each pooled State after Libs, so you can add custom
	// libraries — register Go functions or module tables, or L.Preload lazy
	// (require) modules — without restating the default set. Leaving Libs at its
	// default and setting ExtraLibs is the safe "keep the sandbox, add mine" path.
	// Each entry runs once per pooled State (in newState), on the goroutine that
	// owns the State, so any shared Go state a lib closes over must be
	// goroutine-safe. Opened after Libs — hence after defaultLibs'
	// stripUnsafeLoaders — so re-adding load/loadfile/dofile here un-sandboxes the
	// State. With IsolateGlobals, globals a lib defines are read-visible to each
	// call via the shared-library fallback (a mutable shared table a lib exposes
	// can be mutated in place across calls, so prefer immutable/functional libs).
	// Since: 2026-07-05
	ExtraLibs []func(*lua.LState)

	// IsolateGlobals, when true, runs each call under a fresh per-call _ENV (Lua
	// 5.4 environment sandbox) so global writes do not leak across Runs that reuse
	// the same pooled State. Without it, the same pooled State carries a script's
	// globals (e.g. `counter = counter + 1`) into the next caller, making results
	// depend on which idle State is picked. Reads fall back to the shared
	// libraries. The trade-off is a chunk re-run per call (cost proportional to the
	// script's top-level definitions), so it is off by default (globals persist on
	// the pooled State — the fastest path). Requires the base library (setmetatable)
	// in Libs. See Run.
	// Since: 2026-06-28
	IsolateGlobals bool

	// ConvertValue, when set, lets RunValues materialize non-data return values
	// (function/userdata/thread) into Go values; it runs while the State still owns
	// the value. If nil, RunValues returns an error for such values (the safe
	// default — it never hands back a value tied to a reused State). Data values
	// (nil/bool/number/string/table) are converted without it.
	// Since: 2026-06-28
	ConvertValue func(L *lua.LState, lv lua.Value) (any, error)

	Metrics Metrics // monitoring sink (defaults to a no-op)
	Logger  Logger  // structured logger (defaults to a no-op)

	// Trace, if set, receives per-stage request timing for developer profiling.
	// Leaving it nil has zero overhead (no timing is taken). See TraceHook.
	Trace TraceHook
}

Config tunes Runtime behavior.

func (Config) Validate

func (c Config) Validate() error

Validate checks the numeric/duration fields of a Config. It is used by the config loaders (luartconfig) and is safe to call directly. Libs, Metrics, and Logger are code-injected and not validated here. Since: 2026-06-07

type Logger

type Logger interface {
	Info(msg string, keyvals ...any)
	Error(msg string, keyvals ...any)
}

Logger receives structured log events as a message plus key/value pairs (slog-style). The zero-overhead default is noopLogger. Since: 2026-06-07

func NewSlogLogger

func NewSlogLogger(l *slog.Logger) Logger

NewSlogLogger adapts a *slog.Logger to the Logger interface. Pass it via Config.Logger to route luart events into slog. Since: 2026-06-07

type MapLoader

type MapLoader struct {
	// contains filtered or unexported fields
}

MapLoader is an in-memory SourceLoader for tests and demos. Set simulates an external change.

func NewMapLoader

func NewMapLoader() *MapLoader

NewMapLoader returns an empty in-memory loader.

func (*MapLoader) Load

func (l *MapLoader) Load(key string) (string, string, string, error)

Load returns the (source, version, displayVersion) for key, or an error if the key is unknown.

func (*MapLoader) Loads

func (l *MapLoader) Loads() int64

Loads returns the number of Load calls so far.

func (*MapLoader) Set

func (l *MapLoader) Set(key, src, version, displayVersion string)

Set registers or updates a script. Calling it with a changed version (hash) simulates an external change. displayVersion is the human label (may be empty — callers fall back).

type Metrics

type Metrics interface {
	OnCompile(key string) // a source was loaded and compiled (new pool created)
	OnBuild(key string)   // a new LState was built (pool miss)
	OnReuse(key string)   // an idle LState was reused (pool hit)
	OnEvict(key string)   // an idle LState was LRU-evicted at the cap
	OnDrop(key string)    // a pool was dropped by a change notification
}

Metrics receives lifecycle events for monitoring. Implementations must be safe for concurrent use. The zero-overhead default is noopMetrics, so wiring a sink is opt-in and adds no required dependency.

The events map naturally to counters; combine them with Runtime.PoolStats and Runtime.Stats (gauges) for a full picture. Since: 2026-06-07

type PoolStat

type PoolStat struct {
	Key            string
	DisplayVersion string // human label
	VersionShort   string // first 8 chars of the engine version (hash)
	Idle           int
	CheckedOut     int
}

PoolStat is a per-pool snapshot for monitoring (displayVersion identifies which version is running).

type Runtime

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime lazily loads, executes, and reclaims many scripts concurrently and safely. Hot reload is a single model: external notification (Notify) driven drop-and-reload.

Example

ExampleRuntime shows the basic public API: load a script from a SourceLoader, run it from the pooled runtime, and clean up.

package main

import (
	"context"
	"fmt"

	lua "github.com/htcom-code/lua-pure/lua"

	luart "github.com/htcom-code/go-lua-perf"
)

func main() {
	loader := luart.NewMapLoader()
	src := `function greet(name) return "hello, " .. name end`
	loader.Set("greeter", src, luart.HashVersion(src), "1.0.0")

	rt := luart.New(loader, luart.Config{MaxStates: 4})
	defer rt.Close()

	out, err := rt.Run(context.Background(), "greeter", "greet", lua.MkString("luart"))
	if err != nil {
		panic(err)
	}
	fmt.Println(out[0].Str())
}

Output:
hello, luart

Example (Notify)

ExampleRuntime_notify shows notification-driven hot reload: after the source changes, Notify drops the pool and the next Run uses the new version.

package main

import (
	"context"
	"fmt"

	luart "github.com/htcom-code/go-lua-perf"
)

func main() {
	loader := luart.NewMapLoader()
	v1 := `function f() return "v1" end`
	loader.Set("s", v1, luart.HashVersion(v1), "1.0.0")

	rt := luart.New(loader, luart.Config{MaxStates: 4})
	defer rt.Close()
	ctx := context.Background()

	out, _ := rt.Run(ctx, "s", "f")
	fmt.Println(out[0].Str())

	v2 := `function f() return "v2" end`
	loader.Set("s", v2, luart.HashVersion(v2), "2.0.0")
	rt.Notify("s", luart.HashVersion(v2), "2.0.0")

	out, _ = rt.Run(ctx, "s", "f")
	fmt.Println(out[0].Str())
}

Output:
v1
v2

func New

func New(loader SourceLoader, cfg Config) *Runtime

New creates a Runtime and starts its janitor. When MaxStates is unset it is derived from the memory budget.

func (*Runtime) Close

func (m *Runtime) Close()

Close stops the janitor and closes all idle States immediately. It does not wait for in-use States — those close when released. Idempotent. For a graceful drain, use Shutdown.

func (*Runtime) CompileCount

func (m *Runtime) CompileCount() int64

CompileCount returns the number of distinct key:version compiled so far (observability).

func (*Runtime) Notify

func (m *Runtime) Notify(key, version, displayVersion string)

Notify applies one external change notification. If the key's pool exists and the version differs, that pool is dropped (reloaded on next use); if only the displayVersion differs, just the label is refreshed (no cold start). If the pool is absent (unused script) it is a no-op. In-flight States keep running on the old version after a drop and are discarded on release.

func (*Runtime) NotifyChanges

func (m *Runtime) NotifyChanges(changes []Change)

NotifyChanges applies several change notifications at once.

func (*Runtime) PoolStats

func (m *Runtime) PoolStats() []PoolStat

PoolStats returns a human-facing snapshot of the live pools (for monitoring — which key runs which displayVersion). Dropped pools are removed from the map and therefore not included.

func (*Runtime) Run

func (m *Runtime) Run(ctx context.Context, key, entryFn string, args ...lua.Value) ([]lua.Value, error)

Run executes the key script's entryFn with args (lazily loading, compiling, and creating the pool if needed) and returns its results.

The returned []lua.Value is only safe to use synchronously, before the next pool operation. Scalars and strings are by-value and always safe, but reference types (table/function/userdata) belong to a pooled State that another goroutine may reuse the instant Run returns — reading or calling them afterwards is a data race. Extract what you need immediately, or prefer the safe paths: RunValues (deep-copies results to Go values) or RunWith (borrows results within the State's ownership window). This raw form stays the fastest path for primitive returns (e.g. a JSON string).

func (*Runtime) RunValues

func (m *Runtime) RunValues(ctx context.Context, key, entryFn string, args ...lua.Value) ([]any, error)

RunValues executes the key script's entryFn and deep-copies its results into Go values, so the caller never holds a value tied to a pooled State (the safe, convenient counterpart to Run). It runs the copy inside RunWith, while the State still owns the values.

Conversion: nil→nil, boolean→bool, integer→int64, float→float64, string→string, table→[]any for a clean 1..n sequence or map[any]any otherwise (recursive; map keys must be scalar/string). function/userdata/thread are delegated to Config.ConvertValue, or return an error when it is unset (so a State-bound value is never handed back).

func (*Runtime) RunWith

func (m *Runtime) RunWith(ctx context.Context, key, entryFn string,
	handle func(L *lua.LState, rets []lua.Value) error, args ...lua.Value) error

RunWith executes the key script's entryFn with args and invokes handle with the running State and the call's results while the State is still owned by this call (before it returns to the pool). Inside handle any return type is safe to read — table/function/userdata included — and returned functions may be called on L.

Do not let L or rets escape handle: once handle returns, the State may be reused by another goroutine, so anything still pointing into it races. Move out whatever you need inside handle (copy values, call returned functions). handle's error is returned as-is; handle is not called if the script itself errors.

func (*Runtime) Shutdown

func (m *Runtime) Shutdown(ctx context.Context) error

Shutdown is a graceful Close: it stops the janitor, closes idle States, then waits for in-flight States to be released (each closes on release) until none remain or ctx is done. Returns ctx.Err() on timeout (any still-in-flight States close on their eventual release, so there is no leak). Idempotent and safe to call alongside Close. Mirrors net/http.Server's Close/Shutdown split. Since: 2026-06-07

func (*Runtime) Stats

func (m *Runtime) Stats() Stats

Stats returns the current global snapshot.

type SourceLoader

type SourceLoader interface {
	Load(key string) (src, version, displayVersion string, err error)
}

SourceLoader abstracts where script sources come from (an external cache or service backed by a DB, etc.). version is the engine-facing change key (a content hash is recommended) — it must change whenever the source changes. displayVersion is a human-facing label (e.g. "1.0.0"); when empty, callers fall back to the hash prefix.

type Stats

type Stats struct {
	Pools      int
	LiveStates int
	MaxStates  int
}

Stats is a global observability snapshot.

type TraceHook

type TraceHook func(stage, key string, dur time.Duration)

TraceHook receives per-request, per-stage timing for developer profiling. It is distinct from Metrics (which is for production aggregation): TraceHook is a request-level profiler for development. Stages are "load" (external fetch), "compile", "acquire" (idle reuse / wait / LRU, includes build if one happened), "build" (NewState + preload), "execute" (the call), and "release".

It is invoked only when Config.Trace is non-nil, so leaving it unset has zero overhead (no time.Now calls). The hook must be safe for concurrent use. Since: 2026-06-07