Lua Scripting API

The Lua scripting API provides a way to execute Lua scripts within the application. It allows developers to write custom logic and interact with the application's data and functionality.

As well as a normal Lua 5.3 environment, the API provides access to the application's core functionality through a set of predefined functions and modules.

Security and Actor Model

All API modules operate within an actor-based security model. The executing script must have an associated actor (typically a user) with appropriate permissions to access resources. Each module function validates permissions before executing operations.

Modules

Core Modules

• cache: Distributed caching with TTL support and prefix isolation
• database: Execute SQL queries against configured databases
• graphql: Execute GraphQL queries against the application's schema
• notifiers: Send notifications to individual recipients or groups
• http: Make HTTP requests with security restrictions
• templates: Render Liquid templates with optional function preprocessing
• encoding: Encode data into JSON and XML formats
• print: Enhanced print functionality with output capture
• time: Time-related functions for date and time manipulation

Error Handling

All modules follow consistent error handling patterns:

• Boolean Returns: Functions return false or nil on failure
• Tuple Returns: Database and GraphQL modules return [success, result] tuples
• Object Returns: HTTP module returns objects with success boolean field
• Logging: Errors are logged to the application's logger system

Best Practices

1. Always check return values before using results
2. Use parameter bindings for SQL queries to prevent injection
3. Handle HTTP errors gracefully and respect rate limits
4. Cache expensive operations when possible
5. Use appropriate data structures for template contexts
6. Follow the principle of least privilege for actor permissions

Example: Complete Workflow

-- Fetch user data via GraphQL
local success, user_data = graphql.query([[
    query($userId: ID!) {
        getUser(id: $userId) {
            name
            email
            preferences
        }
    }
]], { userId = current_user_id })

if not success then
    print("Failed to fetch user data")
    return false
end

-- Make external API call
local api_response = http.request({
    method = "post",
    url = "https://external-api.example.com/process",
    headers = {
        ["Content-Type"] = "application/json"
    },
    body = '{"user_id": "' .. current_user_id .. '"}',
    format = "json"
})

if not api_response.success then
    print("External API call failed: " .. api_response.error)
    return false
end

-- Process and store results
local db_success, db_result = database.query(
    "analytics-db",
    "INSERT INTO user_events (user_id, event_type, data) VALUES (?, ?, ?)",
    {current_user_id, "api_processed", api_response.data.body}
)

if not db_success then
    print("Database insert failed: " .. db_result)
    return false
end

-- Send notification
local template_output = template.render("process-complete", {
    user_name = user_data.data.getUser.name,
    result_count = #api_response.data.body.results
})

if template_output then
    notifiers.recipient(
        current_user_id,
        "Processing Complete",
        template_output
    )
end

print("Workflow completed successfully")
return true