Moonbridge Network Server for Lua Applications

Moonbridge is a stand-alone TCP/IP (and HTTP) network server for applications that are written in the Lua programming language. For every connect, a cloned Lua machine is used to handle the request. Pre-forking is configurable in which case libraries may be loaded and initialized before forking. While waiting for a request, each cloned Lua machine can already perform preparatory work (e.g. opening database connections in advance) to avoid unnecessary delays. It is either possible to reuse the cloned Lua machines or to terminate their processes and always use freshly cloned Lua machines for every request.


  • Multiple sources for request handler invocation
    • Listening on TCP/IP sockets (IPv4 and IPv6)
    • Listening on local sockets (Unix Domain Sockets)
    • Integrated interval timer for regularly executing background tasks
  • Memory limiter
    • Terminates processes that exceed their memory limit
  • Time limiter
    • Terminates processes that exceed a certain execution time (or where a call exceeds a certain execution time)
    • Resettable timeout (watchdog functionality)
  • Pre-forking
    • Configurable fork rates and fork counts
    • Preparatory work possible before and after forking
    • Forked processes may be discarded or reused
  • Asynchronous I/O module (since v1.0.0)
    • Non-blocking communication with client and/or other peers
    • Automatic yielding (for coroutine-based programming)
  • HTTP/1.1 module
    • Parsing of cookies, GET and POST params, and other request header fields
    • Support for persistent and non-persistent connections (including chunked content-transfer-encoding)
    • Handling of multipart/form-data request bodies (i.e. HTML file upload)
    • Optional streaming of whole request body or selected POST fields
    • Possibility to send a response before the request body is received (automatic fallback if client would block) (since v1.0.0)
  • Lightweight architecture
    • Less than 64kB of gzip-compressed source code (including example application)
    • Small memory footprint
    • No unnecessary dependencies (except libbsd on GNU systems)
  • Good performance
    • Fast implementation in C (except HTTP module)


  • Lua version 5.2 or 5.3
  • libbsd (only needed for platforms other than BSD)


Moonbridge is easy to use. Check the Hello World example for a quick introduction, or the API reference.




  • 2015-07-12: Version 1.0.1
    • Fixed bug in write buffer, which caused data to be lost when I/O is blocked
    • Fixed bug in error handler regarding broken client connection
    • Fixed trivial bug in example application (missing comma)
  • 2015-06-23: Version 1.0.0
    • Added capabilities for asynchronous I/O
    • Reimplementation of HTTP module
      • Fixes bug which caused crash on lowercase HTTP header fields
      • Proper treatment of cases where a response is sent before the request body was received
  • 2015-03-24: Version 0.4.0
    • Bugfix in global timeout(...) function
    • Timeout support in HTTP module
    • Proper reporting of I/O and protocol errors
      • Methods of socket return nil as first and an error message as second return value in case of an I/O error; socket:close() and socket:cancel() return true on success
      • Writing data to a disconnected client does not cause a SIGPIPE process termination anymore
      • I/O and protocol errors in HTTP module will set request.faulty to true, which disallows further operations
      • HTTP module tries to send an error response to the client in case of unexpected EOF or other protocol errors (also fixes bug regarding error responses)
    • Do not use SHUT_RD shutdown on sockets due to different behavior on different operating systems and problems with Linux
    • Support pairs(...) on get_params, get_params_list, post_params, and post_params_list attributes of request object of HTTP module
    • New method request:close_after_finish() to announce closing of connection after response
    • request:send_header(...) method of request object of HTTP module does not discard duplicate "Connection: close" headers anymore (it is recommended to use request:close_after_finish() instead)
    • Added the global _MOONBRIDGE_VERSION Lua constant
    • Perform a full garbage-collection cycle after initialization of Lua machine (forked processes will consume less memory at startup)
    • Default fork rate increased to 4 spawned processes per second
  • 2015-02-17: Version 0.3.0
    • Removed (broken) method request:send_text_status_response()
      (applications are now requested to implement their own error response function, if needed)
    • Bugfix: Avoid error condition after sending a "Connection: close" header
  • 2015-01-31: Version 0.2.1
    • Fixed bug that caused error when finishing requests with certain status codes (that do not have a request body)
  • 2015-01-30: Version 0.2
    • Changes in API
      • request.path does no longer contain a leading slash
      • request.query contains a leading question mark
      • request.url has been removed and may be reconstructed using ("/" .. request.path .. request.query)
      • New helper method request:send_text_status_response(...) to simplify generating (plain text) HTTP error responses where desired
    • Renamed "http" module to "moonbridge_http"
    • Allow passing command line arguments to a moonbridge application
    • Lua 5.3 compatibility
    • Added MOONBR_LUA_PATH and MOONBR_LUA_CPATH compile-time options to allow appending a path to LUA_PATH or LUA_CPATH respectively at run-time
    • Fixes and code cleanup in example_application.lua file
      • Corrected bad mistake in comment on prepare function: it is executed AFTER forking!
      • Removed memory limit to avoid unexpected results when modifying the example application
    • Better conformance to RFC 7230
      • Accept absolute URLs as target (forward compatibility to future HTTP versions)
      • Strict requirement of "Host" header
    • Addressed compiler warnings
      • Use memcpy() instead of dereferencing type-punned pointers to avoid breaking strict-aliasing rules
      • Modified Makefile to suppress unused-result compiler warnings
      • Include bsd/stdio.h on Linux systems to avoid compiler warning on implicitly declared fpurge() function
    • Extended Makefile to contain default settings for Debian and Ubuntu Linux to allow easier compilation on those systems
  • 2015-01-04: Version 0.1
    • Initial release