Web Applications with Luna Framework

Build powerful web servers and WebSocket applications with Luna Framework. Full-featured WebSocket server implementation for Lua with SSL support and asynchronous request processing.

Important Note

Web applications are not available in the Python version of Luna Framework. If you're using Luna with Python, please use standard WebSocket libraries for Python instead of the new_web_app and remove_web_app methods.

Luna Web Applications Features

Luna Framework provides a complete WebSocket server implementation for Lua with SSL support, asynchronous request processing, and a simple API for creating web applications of any complexity.

Advantages

Full WebSocket Servers

Complete WebSocket protocol implementation for creating real web applications in Lua.

Coroutine-based Server

Asynchronous request processing using coroutines for maximum performance.

Built-in SSL Support

Secure connections with SSL/TLS support for data protection. Requires installed ssl, if not available, regular ws will be available.

Multiple Protocol Support

Flexible protocol system for handling different connection and data types.

Broadcast Messages

Ability to send messages to all connected clients simultaneously.

High Performance

Optimized code for handling hundreds of simultaneous connections.

Usage Example

Simple example of a WebSocket server that initializes a timer for each client and sends updates to clients.

-- Initializing Luna for web applications
_G.love = love
local luna
local inc_clients = {}

function love.load()
    luna = require("luna.init")

    local app
    app = luna.new_web_app({
        name = "web socket test",
        host = "*",
        port = 12345,

        debug = true,
        no_errors = true,

        protocols = {
            default = function(ws)
                local ip, port = ws:getpeername()
                print("New client ip: "..ip .. " port: "..port)
                
                -- Access to raw socket (useful for advanced operations)
                local raw_socket = ws.raw_socket
                print("Raw socket type: " .. type(raw_socket))
                
                ws.on_close = function ()
                    print("ws "..tostring(ws) .. " on_close.")
                end
                inc_clients[ws] = 0
                while true do
                    local message, opcode = ws:receive()
                    if not message then
                        ws:close()
                        inc_clients[ws] = nil
                        return
                    end
                    if opcode == app.opcodes.TEXT then
                        if message:match('reset') then
                            inc_clients[ws] = 0
                        end
                        ws:send(tostring(inc_clients[ws]))
                    end
                end
            end,
        }
    })
end

local last_werserv_update = 0
function love.update(dt)
    last_werserv_update = last_werserv_update + dt
    if last_werserv_update >= 0.1 then
        last_werserv_update = 0
        for ws, number in pairs(inc_clients) do
            ws:send(tostring(number))
            inc_clients[ws] = number + 1
        end
    end

    luna.update(dt)
end

API Reference

Complete documentation of methods and properties for working with web applications in Luna Framework.

luna.new_web_app(config)

Creates a new web application with WebSocket support.

luna.new_web_app(config)

app_data

Creates and starts a new web application with the specified configuration.

Configuration Parameters:

Parameter	Type	Required	Description
name	string	Yes	Application name (for debugging)
host	string	Yes	Host to run the server on (e.g., "*" or "127.0.0.1")
port	number	Yes	Port to run the server on (e.g., 8080)
debug	boolean	No	Enable debug mode
error_handler	function	No	Function for error handling
no_errors	boolean	No	If true, errors don't stop the server
ssl	table	No	SSL configuration for secure connections
protocols	table	Yes	Table of protocols for connection handling

SSL Configuration:

When SSL is configured, the server will use secure WebSocket connections (wss://). The SSL configuration table should include:

key - Path to the private key file
cert - Path to the certificate file
Other SSL options as needed

Example:

local app = luna.new_web_app({
    name = "My Web App",
    host = "*",
    port = 8080,
    debug = true,
    no_errors = true,
    error_handler = function(err)
        print("Web app error:", err)
    end,
    -- SSL configuration (optional)
    ssl = {
        key = "path/to/private.key",
        cert = "path/to/certificate.crt",
        -- other SSL options
    },
    protocols = {
        default = function(ws)
            -- Handler for default protocol
        end,
        chat = function(ws)
            -- Handler for chat protocol
        end
    }
})

luna.remove_web_app(app_data_or_name)

Removes a web application and releases resources.

luna.remove_web_app(app_data_or_name)

Stops and removes a web application. Accepts either the app_data object returned by new_web_app, or the application name.

Example:

luna.remove_web_app("My Web App")
-- or
luna.remove_web_app(app)

WebSocket Client Methods

Methods available for the WebSocket client object in protocol handlers.

ws:getpeername()

string, number

Returns the IP address and port of the connected client.

local ip, port = ws:getpeername()
print("Client connected from:", ip, port)

ws:receive()

string, number

Receives a message from the client. Returns the message and operation code. If no message is received, the client has likely closed the connection.

while true do
    local message, opcode = ws:receive()
    if not message then
        -- Client disconnected
        break
    end
    -- Process message
end

ws:send(data, opcode)

Sends a message to the client.

Parameters:

data	string	Yes	Data to send
opcode	number	No	Operation code (e.g., app.opcodes.TEXT or app.opcodes.BINARY)

Example:

ws:send("Hello, client!", app.opcodes.TEXT)

ws:close(code, reason)

Closes the connection with the client.

Parameters:

code	number	No	Close code
reason	string	No	Close reason

Example:

ws:close(1000, "Normal closure")

ws:broadcast(data, opcode)

Sends a message to all connected clients.

Parameters:

data	string	Yes	Data to send
opcode	number	No	Operation code

Example:

ws:broadcast("Server announcement!", app.opcodes.TEXT)

WebSocket Client Properties

Properties and callbacks available for the WebSocket client object.

ws.raw_socket

Provides access to the raw underlying socket. This can be useful for advanced operations that require direct socket access, especially when SSL is enabled and the socket is wrapped.

local raw_socket = ws.raw_socket
print("Raw socket type:", type(raw_socket))
-- Use raw_socket for advanced operations

ws.on_close

Callback function that is called when the client closes. Can be set to perform cleanup or logging.

ws.on_close = function()
    print("Client disconnected:", ws:getpeername())
    -- Perform cleanup
end

Lunac WebSocket Client

Connect to WebSocket servers using Lunac client library.

lunac.connect_to_web_app(config)

app_data

Creates a connection to a WebSocket server.

Configuration Parameters:

Parameter	Type	Required	Description
name	string	No	Application name (for debugging)
url	string	Yes	WebSocket server URL (e.g., "ws://localhost:8080" or "wss://secure-server.com")
debug	boolean	No	Enable debug mode
error_handler	function	No	Function for error handling: function(error_message)
no_errors	boolean	No	If true, errors don't stop the client
protocol	string	No	WebSocket subprotocol
ssl	table	No	SSL configuration for secure connections
on_connect	function	No	Callback when successfully connected: function(self)
on_message	function	No	Callback when message received: function(self, message, opcode)
on_close	function	No	Callback when connection closed: function(self, code, reason)

Example:

local web_client = lunac.connect_to_web_app({
    name = "My WebSocket Client",
    url = "ws://localhost:8080",
    debug = true,
    no_errors = true,
    protocol = "chat",
    error_handler = function(err)
        print("WebSocket error:", err)
    end,
    on_connect = function(self)
        print("Connected to WebSocket server!")
        -- Send initial message
        self:send("Hello Server!")
    end,
    on_message = function(self, message, opcode)
        print("Received message:", message, "opcode:", opcode)
    end,
    on_close = function(self, code, reason)
        print("Connection closed. Code:", code, "Reason:", reason)
    end
})

lunac.disconnect_to_web_app(app_data_or_name)

Disconnects from a WebSocket server.

lunac.disconnect_to_web_app(app_data_or_name)

Closes the connection to a WebSocket server. Accepts either the app_data object returned by connect_to_web_app, or the application name.

Example:

lunac.disconnect_to_web_app("My WebSocket Client")
-- or
lunac.disconnect_to_web_app(web_client)

WebSocket Client Methods

Methods available for WebSocket client applications.

app:send(data, opcode)

Sends a message to the WebSocket server.

Parameters:

data	string	Yes	Data to send
opcode	number	No	Operation code (default: app.opcodes.TEXT)

Example:

web_client:send("Hello from client!", web_client.opcodes.TEXT)
web_client:send("binary data", web_client.opcodes.BINARY)

app.opcodes

table

Table containing WebSocket operation codes.

Available opcodes:

CLOSE = 8 - Close connection
TEXT = 1 - Text data
BINARY = 2 - Binary data
PING = 9 - Ping frame
PONG = 10 - Pong frame
CONTINUATION = 0 - Continuation frame

Example:

local opcodes = web_client.opcodes
print("Text opcode:", opcodes.TEXT) -- 1
print("Binary opcode:", opcodes.BINARY) -- 2

Install Luna Framework