Turbo: an event-driven network framework for LuaJIT

A network framework for a specific runtime

Turbo is described as a framework built for LuaJIT 2 to simplify the task of building fast and scalable network applications, using an event-driven, non-blocking, no thread design to deliver performance and a minimal footprint for high-load applications while also providing support for embedded uses.

The runtime constraint is stated without hedging. LuaJIT 2 is REQUIRED, and PUC-RIO Lua is unsupported. That single line rules out a lot of deployments, because LuaJIT is a separate interpreter with its own FFI, and a project on stock Lua cannot just add this dependency.

The payoff for accepting it is stated just as plainly. Running this with LuaJIT provides you with roughly the speed of compiled C code with only a fraction of the development time, and the README suggests it as suitable for small devices running cheap CPUs on battery power as well as for a pay per use cluster.

The toolkit is aimed at the HTTP(S) protocol first, which makes web developers and HTTP API developers the first class citizens, and it also contains generic pieces such as an I/O loop, IO Stream classes and customizable TCP server classes with SSL. It speaks directly to existing C libraries and will happily create native C structs, which is the FFI doing the work that a C extension would otherwise do.

The primary language is Lua, the licence is Apache-2.0, and the homepage is turbo.readthedocs.io. The recent releases are v2.1.5 and v2.1.4, both on 2026-08-16, and v2.1.3 from 2019-09-05, and the last push to the repository was on 2026-10-03.

Why the API looks like Tornado

The design principles are listed in the README and they read like a summary of the framework's lineage.

The first is a simple and intuitive API, much like Tornado. The last is good documentation, with the API docs published at turbo.readthedocs.io or buildable from source with make html from the doc directory in the tree.

The lineage is more than a resemblance. Many of the modules in the software package are derivatives of the Tornado web server, which the README states directly and notes is also licensed under Apache 2.0. The copyright line reads 2011 to 2016 John Abrahamsen, and the licence is the Apache License, Version 2.0 with the standard disclaimer.

Two external pieces are named as dependencies. All of the modules are made with the class implementation that Middleclass provides, from the kikito project, which is the object system Tornado itself was built on. And the HTTP parser by Ryan Dahl is used for HTTP parsing, which is the C library that later became Node's HTTP parser, and here it is built and installed as part of the package.

So the design is a Lua translation of a Python web framework, which is a useful thing to know when you are reading the code, because the concepts will be familiar and the naming will not always be. The remaining principles are that low-level operations are possible if the user wishes, that the implementation is in straight Lua and LuaJIT FFI on Linux so the user can study and modify the inner workings without too much effort, that the design is event driven, asynchronous and threadless, that the footprint is small, and that SSL support requires OpenSSL or the LuaSec module on Windows. The Windows implementation uses some Lua modules to make compatibility possible.

Installing on Linux, Windows and by hand

On Linux the supported route is LuaRocks, and the command is short:

``luarocks install turbo``

If that fails, the README names the required packages:

``apt-get install luajit luarocks git build-essential libssl-dev``

For Windows there is an install.bat file that installs everything: Visual Studio, git, mingw, gnuwin and openssl using Chocolatey, then installs LuaJIT, the LuaRocks package manager and Turbo itself at C:\turbo.lua, along with LuaSocket and LuaFileSystem via LuaRocks. The environment is ready to use on success, and the README gives a first command to try, running the helloworld example under luajit from the installed tree.

If a .dll or .so ends up somewhere other than the default location, environment variables point at the right one, with TURBO_LIBTFFI for the FFI wrapper and TURBO_LIBSSL for the OpenSSL library as the two examples given.

For Linux and macOS there is also the included Makefile. You download the tree and run make install, which requires root, and it installs into the default Lua 5.1 and LuaJIT 2.0 module directory. You can specify your own prefix with make install PREFIX=<prefix>, and you can specify the LuaJIT version with a LUAJIT_VERSION=2.0.0 style parameter.

The build has switches for the TLS backend as well. To compile without support for OpenSSL, and therefore without SSL connections, you use the make option SSL=none. To compile with axTLS support instead of OpenSSL, you use SSL=axTLS. And if you want the framework installed in bytecode form, make bcodeinstall.

One operational note is worth keeping: the toolkit can run from anywhere, but it must be able to load the libtffi_wrap.so at run time. To verify an installation, the README suggests running the applications in the examples folder.

Packaging for devices with limited storage

The Packaging section describes a target that is not about developer convenience. The included Makefile supports packaging the current tree as a versioned tar.gz file, which includes only the necessary bits and pieces for Turbo to run. The files are built as bytecode, with luajit -b -g, with debug info.

The stated effect is that this reduces size drastically, and that it also reduces startup time, which makes it suitable for embedded devices with limited storage. The command is make package, and the result is a turbo.x.x.x.tar.gz file together with a package directory.

For a project whose stated audience includes small devices running cheap CPUs on battery power, this is the feature that makes the framework usable at all in that setting. A Lua source tree is a lot of files to ship and a lot of parsing to do at boot, and turning the whole thing into bytecode with a single make target removes both costs. It is also a sign of how the project is used, since the packaging target is not something a general web framework would bother with.

The rest of the tree supports the same audience. The supported architectures are x86, x64, ARM, PPC and MIPSEL, and the supported operating systems are Linux distributions on x86 and x64, macOS on Intel, and Windows x64, with the note that other platforms may work using LuaSocket but are not tested or supported.

HTTP first, with the primitives underneath

The examples directory is the clearest catalogue of what the framework actually does, and the file names give the list away.

There are the server basics, httpserver.lua, helloworld.lua, helloworld6.lua, iosimple.lua and tablehandler.lua. There is the TLS story in sslserver.lua and an sslkeys directory. There is the open connection story in websocket.lua and websocketclient.lua. There is templating in mustache.lua, which is how the framework does traditional dynamic web pages, and JSON handling in json.lua.

Then there are the pieces you only need once you are past the basics: multipart.lua for uploads, cookie.lua and securecookie.lua for sessions, parameters.lua for query strings, chunked.lua for chunked transfer encoding, keepalive.lua for connection reuse, static.lua for serving files, signalfd.lua for Unix signal handling, thread.lua, parrot.lua, githubfeed.lua, curl.lua, and a chatapp directory that looks like a small complete application.

Read as a set, the list tells you what the framework is for. It is a server framework first, with a template engine and a WebSocket implementation, and the low level layer of an I/O loop, IO stream classes and customizable TCP servers with SSL underneath it for people who need to build something the HTTP layer does not cover.

That two-level structure is the reason to look at this project at all if you are not writing an HTTP service. The README's promise is a fast and scalable network application framework with an HTTP bias, and for a TCP or SSL server that is not HTTP, the generic nuts and bolts are the part you would use, with the request handling as a reference implementation of how they fit together.

The Dockerfile is a testing decision, not a packaging one

The Dockerfile at the repository root is a test image, and its comments explain more about how the project is maintained than the README does.

It builds Turbo against LuaJIT on Debian and runs the busted test suite, and the header says it replaces the defunct Travis CI setup with a reproducible Linux environment. The base image is debian:bookworm-slim with luajit, libluajit-5.1-dev, luarocks, build-essential, libssl-dev and git installed, and busted installed with luarocks.

There is a subtlety in how the tests are run. Busted installs into the lua 5.1 rock tree because LuaJIT is 5.1-compatible, and the generated wrapper hardcodes the PUC lua5.1 interpreter, which lacks FFI, so the rock's entry point is invoked under luajit instead, through a copy of the docker/busted-luajit script into /usr/local/bin.

Then the part that matters for anyone evaluating the project. The default command runs only the deterministic, self-contained unit specs. The HTTP, async and iostream specs are intentionally excluded from the default run, because they require real outbound network access, with async_spec fetching google.com with a 60 second wait, and a working loopback HTTP path that does not behave reliably in a headless container, so they hang or time out regardless of code correctness.

That is an honest statement about what the test suite does and does not prove, and it is unusual to see it written down. It also means a green default run tells you the deterministic parts work and nothing about the networked parts.

The image also notes that it runs on whatever architecture the daemon uses, and that on Apple Silicon this is linux/arm64, which exercises the ARM64 syscall code paths.

A Makefile with the platform differences in it

The Makefile is where the portability story is written down, and it is a long one.

The version is assembled from three variables, MAJVER 2, MINVER 1 and MICVER 3, producing 2.1.3, which matches the version in the release list. The compiler is gcc by default and clang on Darwin, and the CFLAGS are -O3 -Wall -g.

The install locations are laid out per runtime, with a Lua module directory at $(PREFIX)/share/lua/5.1, a Lua library directory at $(PREFIX)/lib/lua/5.1, and a separate LuaJIT module directory at $(PREFIX)/share/luajit-$(LUAJIT_VERSION), where LUAJIT_VERSION defaults to 2.0.4. The separate LuaJIT path is the practical consequence of the FFI requirement, since the FFI library is only present in the LuaJIT tree.

The FFI wrapper library is installed under a different name on each platform, as a .so on Linux, a .dylib on Darwin and a .dll for Windows, with a versioned SONAME and a symlinked short name, which is the standard arrangement for a shared library that programs load at runtime.

The HTTP parser is built from the deps directory rather than fetched, with the include path pointed at deps/http-parser, and there is an SSL=axTLS branch that changes what gets linked.

The rest of the top-level tree matches the README's description: turbo.lua as the main module, a turbo directory, turbovisor.lua, bin, deps, doc, docker, examples, rockspecs, spec for the busted specs, install.bat for Windows, and both a Dockerfile and a .travis.yml.

The licence and the upstream notices sit at the bottom of the README, and they are the part to read before you build on this. The Apache 2.0 grant applies to the code, and the Tornado derivation is disclosed with its own Apache 2.0 licence and a link to the project, so the obligations that matter are attribution and the notice file rather than anything restrictive.

Editorial conclusion

Turbo fits a Lua developer who wants an HTTP server or an API endpoint without pulling in a full stack, especially on a small device where footprint matters, since the packaging target compiles the tree to bytecode and cuts both size and startup time. It is the wrong choice if you need a maintained, dependency-light HTTP stack today, because the release history has a six year gap between v2.1.3 in 2019 and v2.1.4 in 2026, and it is the wrong choice if you want to run on PUC Lua rather than LuaJIT, which the project does not support. Verify first that LuaJIT 2 is what you have available, that your platform is one of the listed architectures and operating systems, and that the OpenSSL requirement matches what you intend to ship.

Frequently asked questions

Official sources

1. kernelsauce/turbo on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases