Luna Framework Documentation

Complete guide for using the Luna server library and Lunac client library for creating network applications in Lua (5.1/LuaJIT).

Warning: Client Disconnect Timeout

Clients will automatically disconnect if no requests are sent within the specified disconnect_time (default: 10 seconds). To prevent disconnection, implement a ping mechanism as shown below:

local default_router = app:new_router({
    prefix = "default",
})
default_router:new({
    prefix = "ping",
    fun = function(args, client) end,
})

local t = 0
function love.update(dt)
    t = t + dt
    if t > 2 then
        client:noawait_fetch("default/ping", function(data, err)end, {})
        t = 0
    end
end

Luna - Server Side

Core methods for working with the Luna server.

luna.update(dt)

Updates server state. Should be called in the main application loop.

function love.update(dt)
    luna.update(dt)
end
luna.new_app(config)
app_data

Creates a new server application.

Configuration Parameters:

Parameter Type Required Description
name string Yes Application name (for debugging)
max_ip_connected number No Maximum connections from a single IP
error_handler function No Function for error handling
no_errors boolean No If false, errors will stop the server. If true, errors will be passed to error_handler
debug boolean No When debug = false is set - disables application debugging, default is true
host string Yes Host to run server on (e.g. "127.0.0.1")
port number Yes Port to run server on (e.g. 8080)
new_client function No Callback when new client connects: function(client)
close_client function No Callback when client disconnects: function(client)
request_listener function No Callback when new request: function(message, client)
timeout_client function No Callback when client timeout is about to expire: function(client, inactive_time, disconnect_time)
disconnect_time number No Time in seconds after which the client will disconnect if no requests are sent (default: 10)
encryption boolean No Enables or disables message encryption (default: true)

Example:

local app = luna.new_app({
    name = "My Server",
    max_ip_connected = 20,
    error_handler = function(err)
        print("Server error:", err)
    end,
    no_errors = true,
    host = "127.0.0.1",
    port = 8080,
    encryption = false, -- Disable encryption for better performance
    new_client = function(client)
        print("New client connected")
    end,
    close_client = function(client)
        print("Client disconnected")
    end,
    timeout_client = function(client, inactive_time, disconnect_time)
        print("Client inactive for " .. inactive_time .. " seconds")
        -- Return true or nil to disconnect the client
        -- Return false to keep the client connected and reset the timer
        return true -- Disconnect the client
    end,
    disconnect_time = 10
})
luna.remove_app(app)

Removes a server application. Accepts either the app_data object returned by new_app, or the application name.

luna.remove_app("My Server")
-- or
luna.remove_app(app)
luna.close()

Closes all server applications and cleans up resources.

luna.close()
print("All server applications closed")

Client Methods

Methods and properties available on the client object, accessible in callbacks such as new_client, close_client, request_listener, and router handler functions.

client.ip
string

Returns the IP address of the connected client.

local client_ip = client.ip
print("Client IP:", client_ip) -- e.g., "127.0.0.1"
client.port
number

Returns the port number of the connected client.

local client_port = client.port
print("Client Port:", client_port) -- e.g., 54321
client:getpeername()
string, number

Returns the IP address and port number of the connected client.

local ip, port = client:getpeername()
print("Client:", ip, port) -- e.g., "127.0.0.1", 54321
client:close()

Closes the connection to the client.

client:close()
print("Client connection closed")
client:send(message)

Sends a private message to the client. The message will be received by the app.listener on the client.

Parameters:

message string Yes The message to send to the client

Example:

client:send("Welcome to the server!")
print("Message sent to client")

Application (App)

Methods for working with server applications.

app:get_clients()
table

Returns a table of all connected clients.

local clients = app:get_clients()
app:new_router(config)
router_data

Creates a new router for request handling.

Configuration Parameters:

prefix string No Prefix for all routes in this router
no_errors boolean No Overrides global no_errors setting for this router
error_handler function No Error handling function for this router

Example:

local api_router = app:new_router({
    prefix = "api",
    no_errors = true
})
app:remove_router(router)

Removes a router. Accepts either the router_data object or the router prefix.

app:remove_router("api")
-- or
app:remove_router(api_router)
app:set_max_message_size(new_max_message_size)

Sets the maximum size of received messages. Default is unlimited.

Parameters:

new_max_message_size number Yes Maximum size of received messages in bytes

Example:

app:set_max_message_size(1024) -- Sets max message size to 1KB
app:set_max_retries(new_max_retries)

Sets the maximum number of message sending retries. Default is 10.

Parameters:

new_max_retries number Yes Maximum number of retry attempts for sending messages

Example:

app:set_max_retries(5) -- Sets max retries to 5
app:set_message_timeout(new_message_timeout)

Sets the timeout duration for sending messages. Default is 2 seconds.

Parameters:

new_message_timeout number Yes Timeout duration for sending messages in seconds

Example:

app:set_message_timeout(3) -- Sets message timeout to 3 seconds
app:set_disconnect_time(new_time)

Sets the time after which a client will disconnect if no requests are sent. Default is 10 seconds.

Parameters:

new_time number Yes Time in seconds after which the client will disconnect if no requests are sent

Example:

app:set_disconnect_time(15) -- Sets disconnect time to 15 seconds

Router

Methods for working with routers and request handling.

router:new(config)
req_data

Creates a new request handler.

Configuration Parameters:

prefix string No Request prefix (added to router prefix)
fun function Yes Handler function: fun(args, client)
no_errors boolean No Overrides no_errors settings for this request
async boolean No Creating an asynchronous function
error_handler function No Error handling function for this request
validate table No Parameter validation: {["param"] = {"type1", "type2"}}
response_validate table No Response validation: {"type1", "type2"}
max_message_size number No Maximum size of the request message in bytes
message_penalty string No Penalty for exceeding max_message_size ("timeout" or "closed", default: "timeout")
timeout_duration number No Duration of timeout penalty in seconds (used when message_penalty is "timeout")
middlewares table No List of middleware functions to process requests and responses middleware(context, is_pre)

Example:

api_router:new({
    prefix = "echo",
    validate = {text = {"string", "nil"}},
    response_validate = {"string"},
    fun = function(args, client)
        return args.text or "no text provided"
    end
})
router:remove(req)

Removes a request handler. Accepts either the req_data object or the request prefix.

api_router:remove("echo")
-- or
api_router:remove(echo_handler)

Lunac - Client Side

Core methods for working with the Lunac client.

lunac.update(dt)

Updates client state. Should be called in the main application loop.

function love.update(dt)
    lunac.update(dt)
end
lunac.close()

Closes all client applications and cleans up resources.

lunac.close()
print("All client applications closed")
lunac.disconnect_to_app(app_data or "app_name")

Disconnects from a server application. Accepts either the app_data object or the application name.

lunac.disconnect_to_app("My Client")
-- or
lunac.disconnect_to_app(client)
lunac.connect_to_app(config)
app_data

Connects to a server application.

Configuration Parameters:

name string No Application name (for debugging)
host string Yes Server host (e.g. "127.0.0.1")
port number Yes Server port (e.g. 8080)
no_errors boolean No If true, errors won't stop the client
error_handler function No Function for error handling
listener function No Function to handle messages from client:send
server table No Luna object (if client and server are in the same app)
reconnect_time number No Reconnection time in seconds (if connection is lost)
connect_server function No Callback when successfully connected to server
disconnect_server function No Callback when disconnected from server: function(error_message)
encryption boolean No Enables or disables message encryption (default: true)

Example:

local client = lunac.connect_to_app({
    name = "My Client",
    host = "127.0.0.1",
    port = 8080,
    no_errors = true,
    encryption = false, -- Disable encryption for better performance
    reconnect_time = 5, -- will attempt to reconnect every 5 seconds if disconnected
    listener = function(message)
        print("Received message:", message)
    end,
    server = luna -- only if server is in the same application,
    connect_server = function()
        print("Successfully connected to server!")
    end,
    disconnect_server = function(err)
        print("Disconnected from server:", err)
    end
})
client:set_max_message_size(new_max_message_size)

Sets the maximum size of received messages. Default is unlimited.

Parameters:

new_max_message_size number Yes Maximum size of received messages in bytes

Example:

client:set_max_message_size(1024) -- Sets max message size to 1KB
client:set_max_retries(new_max_retries)

Sets the maximum number of message sending retries. Default is 10.

Parameters:

new_max_retries number Yes Maximum number of retry attempts for sending messages

Example:

client:set_max_retries(5) -- Sets max retries to 5
client:set_message_timeout(new_message_timeout)

Sets the timeout duration for sending messages. Default is 2 seconds.

Parameters:

new_message_timeout number Yes Timeout duration for sending messages in seconds

Example:

client:set_message_timeout(3) -- Sets message timeout to 3 seconds

Request Methods

Methods for interacting with the server.

app:fetch(path, args, timeout)
response

Sends a request to the server and waits for response.

Parameters:

path string Yes Request path (router_prefix/request_prefix)
args table No Request parameters
timeout number No Response timeout (default 5 seconds)

Example:

local response = client:fetch("api/echo", {text = "Hello"}, 3)
print(response) -- "Hello"
app:noawait_fetch(path, args)

Asynchronously sends a request.

Parameters:

path string Yes Request path (router_prefix/request_prefix)
callback function Yes Called when the request has returned a response. callback(data, err)
args table No Request parameters

Example:

client:noawait_fetch("api/log", {message = "Debug info"})
Install Luna Framework