Prelude
I recently started a new project, for which I wanted to build a REST API. Here are the alternatives I considered and why I rejected them:
- Using a framework I'm more familiar with, in a different language, like Flask for Python. My project already required Lua and used a bunch of different technologies, so I'd prefer to keep it simple and not add a whole new language and framework to the list.
- Using an existing framework in Lua, like Lapis. The problem here was that Lapis relies on third-party software, like Nginx, so the dependencies list would keep growing. This wouldn't be a problem in a more heavy project, but the API I need here is really small, so I would consider overkill anything more than a single technology for it.
Cover image by aloiswohlfahrt from Pixabay
Milua
I felt clearly that what I really wanted was a pure Lua solution. After a bit of research I didn't find any de-facto standard (I might be wrong), but I did find a http library by duarnimator that provided an excellent set of functionalities to launch a simple server in a few lines.
So inspired by the experience of using Flask I made Milua
Installation
I learned how the luarocks, a lua package manager, works and published the first version, so you can install it with it's dependencies only with:
luarocks install milua
Examples
Right after, you can try the example that comes in the repository.
local app = require "milua"
-- Basic example
app.add_handler(
"GET",
"/",
function()
return "<h1>Welcome to the handsome server!</h1>"
end
)
-- Example capturing a path variable
app.add_handler(
"GET",
"/user/...",
function (captures, query, headers)
local username = captures[1]
local times = query.times or 1
return "The user " .. username .. " is" ..
(" very"):rep(times) .. " handsome"
end
)
app.start()
Launching this would just require you to execute the script after installing Milua. Then, you can 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
For now, version 0.1 as I write, the milua module only offers two functions:
-
add_handler(method, pattern, handler)to associate a method and a path to a handler.- The
handlerfunction must accept the following arguments:-
captures: An array with the variables fields of the path, specified with three dots (...) in the pattern string. In fact, this pattern is just a regular Lua pattern with some syntactic sugar, so you can capture anything you like in your path and be as specific as you want:/([0-9]+)would capture a path to a numeric value;/admin_...would capture the destination without the prefixadmin_. -
query: A table with the key-value pairs of the query in the URL (the options that come after the?). -
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.
- The
-
start(config)where config contains thehostand theportto run the application.
Conclusion
There is still room for a couple of modifications that would keep the complexity at the same level, like adding error handlers (to allow a 404.html page, for example) or specifying directories for static files. For example, it has no templating functionalities (maybe in a future), but you can require any of your preference and use it in your app. But for now it servers its purpose and it's compatible with anything you want to throw at it, thanks to its minimal nature.
I'm still learning about Lua and its tools and might write more about this language in the future. What's your experience with Lua? Have you used before for web development? I'll be happy to read any comment you have!
Recommended reading
Top comments (6)
This is Good. But lets just say I wish use some GET and POST APIs behind a webserver -- lighttpd. What needs to be done to modify the code in a way that the scripts can be called as CGI Application/script.
I'm afraid I'm not familiar with lighttpd of CGI. If you really want to elaborate more on the topic, feel free to open an issue and let's discuss it there. Thank you!
Did you also consider using Pegasus? That seems to be getting very close to what you want and runs on windows as well as linux :D
I've been reading the code of Pegasus and I like some of their approaches, but obviously it is a framework for more serious work. And still, I'd like it more if it allowed routing the way Flask does (see second example here). That's one of the features that I find most convenient and that I tried to replicate in Milua with the
add_handlerfunction.Thanks again for your comment <3
I don't know how I didn't come across this while searching... Thank you ;)
lapis seems quite solid and you don't need nginx, just luarock install cqueues and you're all set, I just found that out today myself