The Allegory SDK is a self-contained cross-platform programming environment for developing web-based database-driven business apps in LuaJIT and JavaScript.
The server-side stack is written entirely in Lua and contains:
- a coroutine-based scheduler for epoll and IOCP multiplexing.
- a programmable web-server-as-a-library (like golang).
- a fully-featured http client and async DNS resolver.
- OS threads with synchronized queues.
- async process execution with pipes and shared memory.
- the fastest libraries for hashing, encryption, compression, image codecs, image resizing, JSON and XML codecs, CSV parsing and XLS generation.
- async clients for MySQL and Tarantool.
- a powerful SQL preprocessor with macros and conditionals.
- a database schema DSL with automatic schema synchronization.
- ...and more, see full list of modules below.
On the frontend we use canvas-ui, an IMGUI library written in JavaScript with no dependencies, featuring an editable virtual grid, built-in screen sharing, a UI builder, and more. It is included as a git submodule so you can use your own frontend tech instead.
This is for people who could write the whole thing themselves if they wanted to but just don't have the time and could use a head start of about 2-5 years depending on experience. You will have to read the code while you're using it and gradually start to own it so that in time you gain the ability and the freedom to work on it like you wrote it yourself. The code is simplified and organized to facilitate that (there are no dark corners).
This is a very different proposition than the black-box approach of most frameworks that don't encourage looking under the hood. Our approach comes from the observation that in order to keep things simple, you have to solve problems at the right level of abstraction, and you can only do that if you own as much of the stack as you possibly can. We'd own the OS if we could, we'd definitely own the browser. Another way of saying this is that accidental complexity builds up at the boundary between the software that you control and the software that you don't control. When you can't fix a bad or incomplete API that you nevertheless have to build on, all you get is hacks and bugs. As a middleware, the Allegory SDK is in the worst position in that regard, it can never cover everything for everybody, so you'll have to tailor it to suit your needs. Treating it as a black box will only bring you sadness.
We understand that this approach might seem alien to some, that it comes with a learning curve, that it's probably not suited for beginners or people who just want to get something done quickly and move on, but as someone once said: "In the beginning all you want is results. In the end, all you want is control."
So if you think you're too far away from making your own full stack from scratch, server and all, or you prefer the black-box approach, then you will probably not be happy using this. If, on the other hand, you're comfortable reading other people's code, and you're of the mind that procedural > functional > OOP, library > framework, SQL > ORM, JavaScript > TypeScript, relational > nosql, less LOC > more LOC, and you get a rash whenever you hear the words "build system", "package manager", "folder structure", "microservice", "container" or "dependency injection", then you might actually enjoy this.
Follow the releases
to see what's new and the dev branch
to see what's cooking for the next release.
Look at the issues
to see what's missing, broken or wanted.
- Many Machines - the independent man's SAAS provisioning tool (in development)
- Home Designer - a 3D modeller and BIM for residential construction (in development)
- Operating Systems: Debian 10+, Windows 10
- Browsers: Desktop Chrome, Firefox, Edge, Safari 16.3+
- CPUs: x86-64 with SSE 4.2 (AVX2 used if found).
Binaries are included in separate repos for each supported platform and are versioned to follow the main repo.
$ git clone git@github.com:allegory-software/allegory-sdk-bin-debian10 bin/linux
> git clone git@github.com:allegory-software/allegory-sdk-bin-windows bin/windows
See our Building Guide which also teaches how to create build scripts for new libraries without using a build system.
- LuaJIT - Custom build of LuaJIT
- Standard Library
- glue - "Assorted lengths of wire" library
- pp - Pretty printer and serializer
- coro - Symmetric coroutines for cross-yielding
- logging - Logging to files and network
- events - Event system (pub/sub) mixin for any object or class
- lpeglabel - PEG (Parsing Expression Grammars) parser with labels
- daemon - Scaffold/boilerplate for writing server apps
- cmdline - Command-line arg processing
- pbuffer - Dynamic binary buffer for decoding and encoding
- lang - Multi-language, country and currency support
- Platform APIs
- Multi-threading
- Multi-tasking
- tasks - Task system with process hierarchy, output capturing and scheduling
- Networking
- sock - Sockets & async scheduler for sockets & pipes
- sock_libtls - TLS-encrypted async TCP sockets
- connpool - Connection pools
- resolver - Async DNS resolver
- http_client - Async HTTP(s) 1.1 client for high-volume web scraping
- http_server - Async HTTP(s) 1.1 server
- smtp - Async SMTP(s) client
- mess - simple TCP-based protocol for Lua programs
- url - URL parsing and formatting
- ipv6 - IPv6 conversion routines
- Data Exchange
- Hashing
- Compression
- gzip - DEFLATE & GZIP (based on zlib-ng)
- zip - ZIP file reading, creating and updating (based on minizip-ng)
- Databases
- Raster Images
- jpeg - Fast JPEG decoding & encoding (based on libjpeg-turbo)
- png - Fast PNG decoding & encoding (based on libspng)
- bmp - BMP decoding & encoding
- bitmap - Bitmap conversions
- pillow - Fast image resizing (based on Pillow-SIMD)
- resize_image - Image resizing and format conversion
- Templating
- mustache - Logic-less templates rendered on the server
- Data Structures
- heap - Priority Queue
- queue - Ring Buffer
- linkedlist - Linked List
- lrucache - LRU Cache
- Math
- ldecnumber - Fixed-precision decimal numbers math
- rect - 2D rectangle math
- Support Libs
- cpu_supports - check CPU SIMD sets at runtime
- Dev Tools
- debugger - Lua command-line debugger
The runtime and the modules up to here can be used as a base to build any kind of app including desktop apps (just add your favorite UI toolkit). You can also use it as a base for your own web framework, since this part is mostly mechanical and non-opinionated. The opinionated part comes next.
- The Webb Web Framework
- webb - Procedural web framework
- webb_action - Action-based routing with multi-language URL support
- webb_auth - Session-based authentication
- webb_spa - Single-page app scaffolding
- xapp - App server for canvas-ui-based apps
- The Webb Web Framework / Client-side
- webb_spa.js - client-side counterpart of webb_spa.lua
- mustache.js - Logic-less templates rendered on the client
- glue.js - Utilities on the client side (part of canvas-ui).
- Support Libs
- jsmin - JavaScript minification
Widgets are provided by canvas-ui.
If you want to contribute to the SDK, we patched together a Programming Guide to help you understand the code a little better and keep with the style and conventions that we use.
The Allegory SDK is MIT Licensed. 3rd-party libraries have various non-viral free licenses.
Because Lua is like modern JavaScript, except it got there 10 years earlier and it didn't keep the baggage while doing so. That said, we're all engineers here, we don't have language affectations. We're just happy to use a language with stackful coroutines, real closures with full lexical scoping, hash maps, a garbage collector, a better C ffi than we could ever ask for, and an overall non-opinionated design that doesn't pretend to know better than its user.
We actually used OpenResty in the past, nothing wrong with it. It's probably even faster. It definitely has more features. Nginx is however quite large, not nearly as hackable as our pure-Lua server, it wants to control the main loop and manage threads all by itself, and its configuration directives are inescapably byzantine and undebuggable by trying to do declaratively what is sometimes better done procedurally in a web server.
We also don't like inversion-of-control in general. The industry is also waking up to this in recent years by moving from scriptable web servers like apache and nginx to more flexible build-your-own kits like golang or node.
It's the same answer: hackability. Golang and Node have their networking guts written in C while ours is Lua all the way down to OS APIs with a few exceptions (libtls).
Allegory SDK (c) 2020-2024 Allegory Software
