Lua SDK

The Connix Lua SDK provides a lightweight, easy-to-use interface for integrating Connix services into your Lua applications.

Requirements

• Lua 5.1, 5.2, 5.3, 5.4, or LuaJIT
• luarocks (recommended for installation)

Installation

Using LuaRocks

luarocks install connix-sdk

Manual Installation

git clone https://github.com/connix/connix-lua.git
cd connix-lua
luarocks make

Download and Include

Download the single-file SDK and include it in your project:

wget https://github.com/connix/connix-lua/releases/latest/download/connix.lua

Quick Start

local connix = require("connix")

-- Initialize the client
local client = connix.new("your-api-key")

-- Make a request
local result, err = client:some_method("parameter")
if err then
    print("Error: " .. err)
else
    print("Result: " .. result.data)
end

Configuration

Configure the SDK with various options:

local connix = require("connix")

-- Using configuration table
local config = {
    timeout = 30,
    max_retries = 3,
    base_url = "https://api.connix.io",
    headers = {
        ["Custom-Header"] = "value"
    }
}

local client = connix.new("your-api-key", config)

-- Or using method chaining
local client = connix.new("your-api-key")
    :timeout(30)
    :max_retries(3)
    :base_url("https://api.connix.io")
    :header("Custom-Header", "value")

Error Handling

The SDK uses Lua’s standard error handling patterns:

local connix = require("connix")

local client = connix.new("your-api-key")

-- Method 1: Check return values
local result, err = client:some_method("parameter")
if err then
    if err.type == "validation" then
        print("Validation error: " .. err.message)
        for _, detail in ipairs(err.details) do
            print("  - " .. detail)
        end
    elseif err.type == "network" then
        print("Network error: " .. err.message)
    else
        print("Connix error: " .. err.message .. " (code: " .. (err.code or "unknown") .. ")")
    end
else
    print("Success: " .. result.data)
end

-- Method 2: Using pcall for exception handling
local success, result = pcall(function()
    return client:some_method_strict("parameter") -- throws on error
end)

if not success then
    print("Error: " .. result)
else
    print("Result: " .. result.data)
end

Async Support (with OpenResty/ngx_lua)

For OpenResty environments, the SDK supports non-blocking operations:

local connix = require("connix")

-- Initialize with async support
local client = connix.new("your-api-key", {async = true})

-- Non-blocking request
local result, err = client:some_method_async("parameter")
if err then
    ngx.log(ngx.ERR, "Error: ", err)
    ngx.exit(500)
end

ngx.say("Result: ", result.data)

API Reference

Client Creation

-- Basic client
local client = connix.new(api_key)

-- Client with configuration
local client = connix.new(api_key, config_table)

-- Client with method chaining
local client = connix.new(api_key)
    :timeout(30)
    :max_retries(3)
    :base_url("https://api.connix.io")

Configuration Options

local config = {
    timeout = 30,           -- Request timeout in seconds
    max_retries = 3,        -- Number of retry attempts
    base_url = "https://api.connix.io",
    headers = {},           -- Additional headers
    async = false,          -- Enable async mode (OpenResty only)
    debug = false           -- Enable debug logging
}

Client Methods

-- Main API methods
result, err = client:some_method(param)
result, err = client:get_data()

-- Configuration methods
client:timeout(seconds)
client:max_retries(count)
client:base_url(url)
client:header(name, value)

-- Utility methods
client:close()              -- Clean up resources
is_open = client:is_open()  -- Check if client is active

Result Structure

local result = {
    id = "result-id",
    data = "result-data",
    timestamp = "2023-01-01T00:00:00Z"
}

Error Structure

local err = {
    type = "validation",    -- "validation", "network", "connix", "unknown"
    message = "Error message",
    code = 400,            -- HTTP status code (if applicable)
    details = {}           -- Additional error details (for validation errors)
}

Framework Integration

OpenResty/Kong Plugin

local connix = require("connix")

local ConnixPlugin = {
    VERSION = "1.0.0",
    PRIORITY = 1000,
}

function ConnixPlugin:access(conf)
    local client = connix.new(conf.api_key, {async = true})

    local result, err = client:validate_request(ngx.var.request_uri)
    if err then
        ngx.log(ngx.ERR, "Validation failed: ", err.message)
        ngx.exit(403)
    end

    ngx.ctx.connix_result = result
end

return ConnixPlugin

Love2D Game Integration

local connix = require("connix")

local GameStats = {}

function GameStats:init()
    self.client = connix.new("your-api-key")
end

function GameStats:submit_score(player_name, score)
    local result, err = self.client:submit_score({
        player = player_name,
        score = score,
        timestamp = os.time()
    })

    if err then
        print("Failed to submit score: " .. err.message)
    else
        print("Score submitted successfully!")
    end
end

function GameStats:get_leaderboard()
    local result, err = self.client:get_leaderboard()
    if err then
        return nil, err
    end
    return result.players
end

return GameStats

Examples

Basic Usage

local connix = require("connix")

local function main()
    local client = connix.new("your-api-key")

    local response, err = client:get_data()
    if err then
        print("Error: " .. err.message)
        return
    end

    for _, item in ipairs(response.items) do
        print("Item: " .. item.name)
    end

    client:close()
end

main()

With Custom Configuration

local connix = require("connix")

local function main()
    local client = connix.new("your-api-key")
        :timeout(60)
        :max_retries(5)
        :header("User-Agent", "MyLuaApp/1.0")

    local result, err = client:process_large_data("large-dataset")
    if err then
        print("Error: " .. err.message)
    else
        print("Processing complete: " .. result.status)
    end

    client:close()
end

main()

Batch Processing

local connix = require("connix")

local function process_batch(items)
    local client = connix.new("your-api-key")
    local results = {}
    local errors = {}

    for i, item in ipairs(items) do
        local result, err = client:process_item(item)
        if err then
            errors[i] = err
            print("Item " .. i .. " failed: " .. err.message)
        else
            results[i] = result
            print("Item " .. i .. " processed: " .. result.status)
        end
    end

    client:close()
    return results, errors
end

-- Usage
local items = {"item1", "item2", "item3"}
local results, errors = process_batch(items)

Environment-based Configuration

local connix = require("connix")

local function create_client()
    local api_key = os.getenv("CONNIX_API_KEY")
    if not api_key then
        error("CONNIX_API_KEY environment variable not set")
    end

    local config = {
        timeout = tonumber(os.getenv("CONNIX_TIMEOUT")) or 30,
        max_retries = tonumber(os.getenv("CONNIX_MAX_RETRIES")) or 3,
        base_url = os.getenv("CONNIX_BASE_URL") or "https://api.connix.io"
    }

    if os.getenv("CONNIX_DEBUG") then
        config.debug = true
    end

    return connix.new(api_key, config)
end

local client = create_client()

Logging and Debug

Enable debug logging to troubleshoot issues:

local connix = require("connix")

-- Enable debug mode
local client = connix.new("your-api-key", {debug = true})

-- Or enable for existing client
client:debug(true)

-- Make requests (will log detailed information)
local result, err = client:some_method("parameter")

Support

For support and questions, visit our GitHub repository or contact support.