Milua

Lua micro framework for web development

Milua is inspired by frameworks like Flask or Express, so it just aims to be quick to install and simple to use, enough to prototype any idea you have in mind without needing to worry too much about third-party software.

• Preview
• Features
• Installation
  • Troubleshooting
• Contributors
• Alternatives
• License

Preview

Here's a minimal example of how to use Milua:

local app = require("milua")

app.get(
    "/",
    function()
        return "<h1>Welcome to the <i>handsome</i> server!</h1>", {
            ["Content-Type"] = "text/html"
        }
    end
)

-- Example capturing a path variable
app.get(
    "/user/{username}/tell",
    function(path_params, query)
        local times = query.times or 1
        return "The user " .. path_params.username .. " is" .. (" very"):rep(times) .. " handsome\n"
    end
)

app.start()

You can run an extended version of this example directly:

lua doc/examples/handsome_server.lua

And test it with curl:

$ curl localhost:8800/
<h1>Welcome to the handsome server!</h1> 

$ curl localhost:8800/user/foo
The user foo is very handsome

$ curl localhost:8800/user/foo?times=3
The user foo is very very very handsome

Features

Right now the milua module only offers:

• get(path, callback). Associates a path to a callback when called with the HTTP verb GET.

  • The callback function must accept the following arguments:
    • captures: A table with the path parameters, that appear appear brackets in the path: {param}.
    • query: A table with the key-value pairs of the query in the URL.
    • headers: The headers of the HTTP request.
    • body: The body of the HTTP request.
  • and must return the following values:
    • The body of the repsonse.
    • (Optional) A table with the headers of the response.

• Equivalent functions for all other HTTP verbs: post, put, patch, delete, etc.

• shutdown_hook(func) where func is a function which will be called before closing the server.

• start(config) where config contains the host and the port to run the application.

• logger table with support for INFO, DEBUG, and ERROR logging levels

  • usage:
    • logger:INFO("this is an info message")
    • logger:ERROR("this is an error message")
    • logger:DEBUG("this is a debug message")
  • How to custom logger levels:
    • logger:add_logger("INFO", function(...) print("THIS A TEMPLATE", logger.format(...)) end)

• config table with support for getting configuration values from environment variables as well as .env files

  • This also lets you extend the config table with a new table where if you define an empty value for a key it will try to get it from a .env file or the os environment
  • example:

    local config = require("milua_config")
    
    config:extend({
        DB_NAME="name",
        DB_PASS="pass",
        DB_HOST="host",
        HOST="localhost",
        STDOUT="localhost",
        MY_SECRET_KEY=""
    })
    
    config.add_config("NEW_KEY", "NEW_VALUE")
    
    app.start(config)

Installation

You can install it directly from luarocks:

luarocks install milua

Alternatively, install it from the root of the directory of the repository.

git clone https://github.com/MiguelMJ/Milua
cd Milua
sudo luarocks make

Troubleshooting

You may want to install Milua as with the --local flag via Luarocks. In that case you will need to install luaossl as a local dependency too. In Debian (derived) system this is solved easily with the installation of libssl-dev. But, on Arch (derived) systems, the installation of OpenSSL variants/versions (which include headers files) will not solve the installation problem. Because luaossl is a prerequisite for Milua, Arch base systems will not finish successfully the installation of Milua complaining about not being able to compile a ssl.o file. And most of the documentation online will suggest to provide manually the OPENSSL_INCDIR path pointing to the include/ssl.h file, which will not fix the issue.

The solution is to install previously the luaossl library with a proper flag, like this:

CFLAGS="-Wno-error=incompatible-pointer-types" luarocks install --local luaossl

After that you can install Milua with the --local flag as usual.

Contributors

MiguelMJ ☕

wmb1207 💻 📖

rdleal 💻 📖

Danilo Hoffmann 💻 💡

Offray Vladimir Luna Cárdenas 📖

Alternatives

There are great frameworks and libraries also written in Lua. I personally find that none satisfies at the same time the requirements I had when creating Milua, but maybe you'll find one better suited for your needs.

• Lapis
• Pegasus.lua

License

Milua is licensed under the MIT license, a copy of which you can find in the repository.