Public Software Group e. V.

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.

Features

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)

Dependencies

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

Documentation

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

Download

Repository

mercurial repository

Changes

2021-04-28: Version 1.1.3
- Improved makefile for portability and fixed linker error on certain platforms
- Allow listening for IPv6 and IPv4 connections on the same socket (if requested)
2020-12-20: Version 1.1.2
- Improvements to Makefile
- Bugfixes
  - Fixed error handling for blocking I/O when connecting to local sockets
  - Fixed wrong call of freeaddrinfo() C function when getaddrinfo() returned an error
2018-12-22: Version 1.1.1
- Support for Raspbian in Makefile
- Added methods to allow manipulation of buffer sizes of operating system
2018-07-26: Version 1.1.0
- Better support for coroutines (API changed to pass certain parameters to wait-function or calling coroutine)
- Bugfixes
  - Linux compatibility when using sockets on file system
  - Bugfixes regarding asynchronous I/O
  - Do not call getpeername() when opening TCP connections in non-blocking mode
- Renamed HTTP header_size_limit and body_size_limit options to request_header_size_limit and request_body_size_limit (to match documentation in example code)
2017-11-19: Version 1.0.2
- Bugfixes
  - Corrected socket:read_call(...) and socket:read_yield(...) to properly concatenate buffered data (could cause data corruption)
  - Fixed behavior of socket:close() regarding TCP FIN and TCP RST packets
- Support for main function(s) in listen… (in addition to port/socket listeners and interval handlers)
- New function moonbridge_io.catch_sigterm() to allow process termination of asynchronous I/O applications through SIGTERM
- Changed default of :kill() to SIGKILL instead of SIGTERM
- Support for child termination and SIGTERM handling in moonbridge_io.poll(...)
- Experimental support for TLS through libtls (optional during compilation)
- Fixed documentation of socket.drain_call() (callback does not receive arguments)
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