Language
Docs

Documentation

Contributors: Dylan Shade
Last Updated:

Lua Serverless Functions

HyperBEAM's ~lua@5.3a device enables you to run serverless Lua functions with permanent availability, instant execution, and cryptographic verification. Unlike traditional serverless platforms, your functions are deployed permanently to Arweave and executed on the decentralized HyperBEAM network.

How HyperBEAM Lua Works

HyperBEAM executes Lua functions through HTTP requests using a specific URL structure:

https://forward.computer/~lua@5.3a/{function_name}/~json@1.0/serialize?param1=value1&module={ARWEAVE_TX_ID}

URL Components:

  • ~lua@5.3a - The Lua execution device
  • {function_name} - The function to call from your deployed module
  • ~json@1.0/serialize - Output formatting set to JSON
  • Query parameters - Function arguments with optional type casting
  • module - Arweave transaction ID of your deployed Lua code

Function Parameters

HyperBEAM calls your Lua functions with three parameters:

function your_function(base, req, opts)
    -- base: Base object to extend (usually empty table {})
    -- req: Request parameters including query params and HTTP headers
    -- opts: Options and configuration (advanced usage)
    
    return base  -- Must return a table
end

Example Functions

1. Simple Calculator

-- calculator.lua
function add(base, req, opts)
    base = base or {}
    
    local a = tonumber(req.a) or 0
    local b = tonumber(req.b) or 0
    
    base.a = a
    base.b = b
    base.result = a + b
    base.operation = "addition"
    
    return base
end

2. Text Analysis

function analyze_text(base, req, opts)
    base = base or {}
    
    local text = req.text or ""
    if text == "" then
        base.error = "Text parameter required"
        return base
    end
    
    -- Word count
    local word_count = 0
    for word in string.gmatch(text, "%S+") do
        word_count = word_count + 1
    end
    
    -- Character counts
    local char_count = string.len(text)
    local char_count_no_spaces = string.len(string.gsub(text, "%s", ""))
    
    base.text_length = char_count
    base.text_length_no_spaces = char_count_no_spaces
    base.word_count = word_count
    
    return base
end

3. Data Processing

function process_numbers(base, req, opts)
    base = base or {}
    
    local numbers_str = req.numbers or ""
    local numbers = {}
    
    -- Parse comma-separated numbers
    for num_str in string.gmatch(numbers_str, "[^,]+") do
        local num = tonumber(num_str:gsub("^%s*(.-)%s*$", "%1"))
        if num then
            table.insert(numbers, num)
        end
    end
    
    if #numbers == 0 then
        base.error = "No valid numbers found"
        return base
    end
    
    -- Calculate basic statistics
    local sum = 0
    local min_val = numbers[1]
    local max_val = numbers[1]
    
    for i, num in ipairs(numbers) do
        sum = sum + num
        if num < min_val then min_val = num end
        if num > max_val then max_val = num end
    end
    
    base.count = #numbers
    base.sum = sum
    base.average = sum / #numbers
    base.min = min_val
    base.max = max_val
    base.numbers = numbers
    
    return base
end

Deployment

1. Deploy to Arweave

# Using permaweb-deploy (recommended)
DEPLOY_KEY=$(base64 -i wallet.json) npx permaweb-deploy --arns-name my-lua-functions --deploy-file calculator.lua

Propagation Delay

After deployment, it can take up to 20 minutes for your Lua module to fully propagate across the Arweave network. You may not be able to access it via HyperBEAM until propagation is complete.

2. Execute Your Function

# Simple addition
curl 'https://forward.computer/~lua@5.3a/add/~json@1.0/serialize?a+integer=10&b+integer=20&module=YOUR_MODULE_ID'

# Text analysis
curl 'https://forward.computer/~lua@5.3a/analyze_text/~json@1.0/serialize?text=Hello%20world%20example&module=YOUR_MODULE_ID'

# Number processing
curl 'https://forward.computer/~lua@5.3a/process_numbers/~json@1.0/serialize?numbers=1,2,3,4,5&module=YOUR_MODULE_ID'

Type Casting Parameters

Use type casting to convert parameters from strings:

Available Type Casts:

  • +integer - Convert to integer
  • +float - Convert to floating point number
  • +boolean - Convert to boolean
  • +list - Convert comma-separated values to array

Example:

curl 'https://forward.computer/~lua@5.3a/add/~json@1.0/serialize?a+integer=10&b+integer=20&module=YOUR_MODULE_ID'

JavaScript Integration

async function callLuaFunction(moduleId, functionName, params = {}) {
    const queryParams = new URLSearchParams();
    queryParams.append('module', moduleId);
    
    for (const [key, value] of Object.entries(params)) {
        if (typeof value === 'number') {
            queryParams.append(`${key}+${Number.isInteger(value) ? 'integer' : 'float'}`, value.toString());
        } else {
            queryParams.append(key, value.toString());
        }
    }
    
    const url = `https://forward.computer/~lua@5.3a/${functionName}/~json@1.0/serialize?${queryParams}`;
    const response = await fetch(url);
    
    if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    return await response.json();
}

// Usage
const result = await callLuaFunction('YOUR_MODULE_ID', 'add', { a: 10, b: 20 });
console.log(result); // { a: 10, b: 20, result: 30, operation: "addition" }