diff --git a/DOCS.md b/DOCS.md index 45205c0..1d714c8 100644 --- a/DOCS.md +++ b/DOCS.md @@ -361,118 +361,6 @@ Compiles and immediately executes Lua code. err := L.CompileAndRun("answer = 42", "test") ``` -## Sandbox Operations - -### NewSandbox() *Sandbox -Creates a new sandbox with standard libraries loaded. -```go -sandbox := luajit.NewSandbox() -defer sandbox.Close() -``` - -### Close() -Releases all resources used by the sandbox. -```go -sandbox.Close() -``` - -### Initialize() error -Sets up the environment system for the sandbox. -```go -err := sandbox.Initialize() -``` - -### RegisterFunction(name string, fn GoFunction) error -Registers a Go function in the sandbox. -```go -adder := func(s *luajit.State) int { - sum := s.ToNumber(1) + s.ToNumber(2) - s.PushNumber(sum) - return 1 -} -err := sandbox.RegisterFunction("add", adder) -``` - -### SetGlobal(name string, value any) error -Sets a global variable in the sandbox base environment. -```go -err := sandbox.SetGlobal("answer", 42) -``` - -### GetGlobal(name string) (any, error) -Retrieves a global variable from the sandbox base environment. -```go -value, err := sandbox.GetGlobal("answer") -``` - -### Run(code string) (any, error) -Executes Lua code in the sandbox and returns the result. -```go -result, err := sandbox.Run("return 40 + 2") -``` - -### RunFile(filename string) error -Executes a Lua file in the sandbox. -```go -err := sandbox.RunFile("script.lua") -``` - -### Compile(code string) ([]byte, error) -Compiles Lua code to bytecode. -```go -bytecode, err := sandbox.Compile("return 42") -``` - -### RunBytecode(bytecode []byte) (any, error) -Executes precompiled Lua bytecode in the sandbox. -```go -result, err := sandbox.RunBytecode(bytecode) -``` - -### LoadModule(name string) error -Loads a Lua module in the sandbox. -```go -err := sandbox.LoadModule("mymodule") -``` - -### SetPackagePath(path string) error -Sets the sandbox package.path. -```go -err := sandbox.SetPackagePath("./?.lua;/usr/local/share/lua/5.1/?.lua") -``` - -### AddPackagePath(path string) error -Adds a path to the sandbox package.path. -```go -err := sandbox.AddPackagePath("./modules/?.lua") -``` - -### AddModule(name string, module any) error -Adds a module to the sandbox environment. -```go -module := map[string]any{ - "version": "1.0", - "name": "mymodule", -} -err := sandbox.AddModule("mymod", module) -``` - -### AddPermanentLua(code string) error -Adds Lua code to the environment permanently. -```go -err := sandbox.AddPermanentLua(` - function hello(name) - return "Hello, " .. name .. "!" - end -`) -``` - -### ResetEnvironment() error -Resets the sandbox to its initial state. -```go -err := sandbox.ResetEnvironment() -``` - ## Package Path Operations ### SetPackagePath(path string) error @@ -519,7 +407,6 @@ err := s.safeCall(func() C.int { - Individual Lua states are not thread-safe - Create separate states for concurrent operations - Use the function registry to share functions between states -- Sandboxes are not thread-safe but provide mutex locking for their operations ## Memory Management @@ -541,17 +428,4 @@ Sandbox management: ```go sandbox := luajit.NewSandbox() defer sandbox.Close() -``` - -## Sandbox Best Practices - -- **Initialization**: Always call `Initialize()` before first use -- **Memory Management**: Use defer to ensure proper cleanup with `Close()` -- **Isolation**: Use separate sandboxes for unrelated script executions -- **Performance**: For frequently used code, compile to bytecode first -- **Error Handling**: Check error returns from all sandbox operations -- **Environment Management**: Reset the environment if state becomes corrupted -- **Library Control**: Use `AddModule()` to restrict available functionality -- **Resource Sharing**: Register functions with `RegisterFunction()` for better performance -- **Persistence**: Use `SetGlobal()` to maintain state between executions -- **Safety**: Use sandboxes for untrusted or user-provided code \ No newline at end of file +``` \ No newline at end of file diff --git a/README.md b/README.md index 3ffbf5d..b51e094 100644 --- a/README.md +++ b/README.md @@ -76,54 +76,6 @@ Use bytecode when you: - Want to precompile your Lua code - Are distributing Lua code to many instances -## Sandboxed Execution - -For more controlled execution, the sandbox provides isolation and environment management: - -```go -// Create a sandbox -sandbox := luajit.NewSandbox() -defer sandbox.Close() - -// Initialize the environment -err := sandbox.Initialize() - -// Register a function -adder := func(s *luajit.State) int { - sum := s.ToNumber(1) + s.ToNumber(2) - s.PushNumber(sum) - return 1 -} -sandbox.RegisterFunction("add", adder) - -// Run code in the sandbox -result, err := sandbox.Run(` - local result = add(40, 2) - return "The answer is: " .. result -`) -fmt.Println(result) // "The answer is: 42" - -// Add permanent functions to the environment -sandbox.AddPermanentLua(` - function square(x) - return x * x - end -`) - -// Run bytecode for better performance -bytecode, _ := sandbox.Compile(`return square(10)`) -result, _ = sandbox.RunBytecode(bytecode) -``` - -### When to Use the Sandbox - -Use the sandbox when you need: -- Isolated execution environments -- Persistent state between executions -- Control over available libraries and functions -- Enhanced security for untrusted code -- Better resource management for long-running applications - ## Registering Go Functions Want to call Go code from Lua? It's straightforward: @@ -210,15 +162,6 @@ for i := 0; i < 1000; i++ { - Consider compiling critical Lua code to bytecode at startup - For small scripts (< 1024 bytes), direct execution might be faster -### Sandbox Usage -- Call `Initialize()` before first use of a sandbox -- Use `defer sandbox.Close()` to ensure proper cleanup -- For persistent objects, add them with `SetGlobal()` -- Control available libraries with `AddModule()` -- For frequently used functions, use `RegisterFunction()` -- Reset the environment with `ResetEnvironment()` if state gets corrupted -- For maximum performance, compile scripts to bytecode first, then run with `RunBytecode()` - ## Advanced Features ### Bytecode Serialization @@ -263,45 +206,6 @@ L.GetGlobal("increment") L.Call(0, 1) // Returns 2 ``` -### Sandbox Environment Customization - -You can tailor the sandbox environment for specific needs: - -```go -// Add a custom module -myModule := map[string]any{ - "version": "1.0", - "config": map[string]any{ - "debug": true, - "maxItems": 100, - }, -} -sandbox.AddModule("myapp", myModule) - -// Add permanent Lua code -sandbox.AddPermanentLua(` - -- Utility functions available to all scripts - function myapp.formatItem(item) - return string.format("%s: %d", item.name, item.value) - end -`) - -// Use in script -result, _ := sandbox.Run(` - local item = {name="test", value=42} - return myapp.formatItem(item) -`) -``` - -## Performance Considerations - -- The sandbox adds a small overhead to execution but provides better isolation -- For maximum performance with the sandbox, use bytecode compilation -- The wrapper optimizes for common operations with specialized C helpers -- For small scripts (<1KB), direct execution with `DoString` is fastest -- For larger scripts or repeated execution, bytecode provides better performance -- Table operations are optimized for both array-like and map-like tables - ## Need Help? Check out the tests in the repository - they're full of examples. If you're stuck, open an issue! We're here to help.