README
¶
English | 한국어
Examples
Small, self-contained programs that use the luart library as a consumer would —
one folder per public feature. Each is runnable and test-covered.
These differ from
cmd/, which are low-level "how it works under the hood" demos (bytecode caching, pooling techniques) that mostly re-implement mechanics inline.examples/is "how you use the library";cmd/is "how the library works".
Run any example:
go run ./examples/basics
Each folder also has a main_test.go, so go test ./examples/... (and make all) covers them.
Suggested reading order
Start with basics, then pick by the feature you need.
| Example | Demonstrates | Key API |
|---|---|---|
| basics | Load a script, run a function with args, read the result | New, Run, NewMapLoader/Set, HashVersion |
| hot-reload | Drop-and-reload on an external change (no restart) | Notify / NotifyChanges |
| ttl-eviction | Janitor reclaims idle pools after IdleTTL |
Config.IdleTTL, JanitorInterval, Stats |
| memory-budget | Cap live VMs by a memory budget (derived MaxStates + LRU) |
Config.MemoryBudgetBytes |
| exec-timeout | Abort a runaway script via hard cap or caller deadline | Config.ExecTimeout, Run(ctx, …) |
| graceful-shutdown | Drain in-flight calls; ErrClosed afterward |
Shutdown(ctx) vs Close() |
| config-loading | Build Config from JSON/YAML/env with precedence |
luartconfig.ResolveJSONString / FromEnv / Load |
| metrics | Count lifecycle events (compile/build/reuse/…) | Config.Metrics |
| logging | Route events into log/slog |
Config.Logger, NewSlogLogger |
| trace-profiling | Per-stage request timing for profiling | Config.Trace (TraceHook) |
| observability | Read-only introspection for dashboards | Stats, PoolStats, CompileCount |
| sandbox-libs | Control which Lua stdlib a script can reach | Config.Libs |
| custom-libs | Add a user-authored library (Go funcs + module table) on top of the sandbox | Config.ExtraLibs |
| custom-loaders | Implement SourceLoader for File/DB/Memory + caching & routing backends |
SourceLoader, HashVersion (guide) |
See the root README for the full public-API overview and the tuning guide for choosing config values by workload.
Directories
¶
| Path | Synopsis |
|---|---|
|
Example basics is the smallest end-to-end use of the luart library: register a script with a SourceLoader, create a Runtime, and Run a Lua function with an argument, reading back its return value.
|
Example basics is the smallest end-to-end use of the luart library: register a script with a SourceLoader, create a Runtime, and Run a Lua function with an argument, reading back its return value. |
|
Example config-loading shows building a luart.Config from external sources via the luartconfig subpackage: a base JSON string overlaid by environment variables, using the precedence resolver (env > base > defaults).
|
Example config-loading shows building a luart.Config from external sources via the luartconfig subpackage: a base JSON string overlaid by environment variables, using the precedence resolver (env > base > defaults). |
|
Example custom-libs adds a user-authored library to pooled States via Config.ExtraLibs — without restating the sandbox defaults.
|
Example custom-libs adds a user-authored library to pooled States via Config.ExtraLibs — without restating the sandbox defaults. |
|
Example custom-loaders shows how to implement the luart.SourceLoader interface for real backends — a file tree, a database, an in-memory store — plus two hybrid patterns (a caching wrapper and a prefix router).
|
Example custom-loaders shows how to implement the luart.SourceLoader interface for real backends — a file tree, a database, an in-memory store — plus two hybrid patterns (a caching wrapper and a prefix router). |
|
Example exec-timeout shows two ways a runaway script is stopped: a server-side hard cap via Config.ExecTimeout, and a caller deadline via the context passed to Run.
|
Example exec-timeout shows two ways a runaway script is stopped: a server-side hard cap via Config.ExecTimeout, and a caller deadline via the context passed to Run. |
|
Example graceful-shutdown shows the Close vs Shutdown split (mirroring net/http.Server): Close stops immediately, Shutdown drains in-flight calls first (up to the ctx deadline).
|
Example graceful-shutdown shows the Close vs Shutdown split (mirroring net/http.Server): Close stops immediately, Shutdown drains in-flight calls first (up to the ctx deadline). |
|
Example hot-reload shows notification-driven drop-and-reload: when a script's source changes, Notify drops that script's pool so the next Run picks up the new version — with no Runtime restart.
|
Example hot-reload shows notification-driven drop-and-reload: when a script's source changes, Notify drops that script's pool so the next Run picks up the new version — with no Runtime restart. |
|
Example logging shows routing luart's structured events into log/slog via Config.Logger + NewSlogLogger.
|
Example logging shows routing luart's structured events into log/slog via Config.Logger + NewSlogLogger. |
|
Example memory-budget shows capping total live VMs by a memory budget instead of a fixed count: with Config.MaxStates unset, the Runtime derives MaxStates from MemoryBudgetBytes ÷ measured per-state cost, then enforces it with LRU eviction + back-pressure under load.
|
Example memory-budget shows capping total live VMs by a memory budget instead of a fixed count: with Config.MaxStates unset, the Runtime derives MaxStates from MemoryBudgetBytes ÷ measured per-state cost, then enforces it with LRU eviction + back-pressure under load. |
|
Example metrics shows wiring a Config.Metrics sink: the Runtime calls OnCompile/OnBuild/OnReuse/OnEvict/OnDrop at lifecycle points.
|
Example metrics shows wiring a Config.Metrics sink: the Runtime calls OnCompile/OnBuild/OnReuse/OnEvict/OnDrop at lifecycle points. |
|
Example observability shows the read-only introspection API: Stats (global gauges), PoolStats (per-script snapshot incl.
|
Example observability shows the read-only introspection API: Stats (global gauges), PoolStats (per-script snapshot incl. |
|
Example sandbox-libs shows controlling which Lua standard libraries a script can reach via Config.Libs.
|
Example sandbox-libs shows controlling which Lua standard libraries a script can reach via Config.Libs. |
|
Example trace-profiling shows Config.Trace: a TraceHook receives per-request, per-stage timings (load, compile, acquire, build, execute, release).
|
Example trace-profiling shows Config.Trace: a TraceHook receives per-request, per-stage timings (load, compile, acquire, build, execute, release). |
|
Example ttl-eviction shows the background janitor reclaiming idle script pools: a pool unused for longer than Config.IdleTTL is evicted whole (its pooled States closed), freeing memory automatically.
|
Example ttl-eviction shows the background janitor reclaiming idle script pools: a pool unused for longer than Config.IdleTTL is evicted whole (its pooled States closed), freeing memory automatically. |
Click to show internal directories.
Click to hide internal directories.