Skip to content

allegory-software/allegory-sdk

Repository files navigation

🍬 The Allegory SDK

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.

Who is this for?

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.

Status

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.

Where it's used

Compatibility

  • 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

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

Building

See our Building Guide which also teaches how to create build scripts for new libraries without using a build system.

Server Runtime

  • LuaJIT - Custom build of LuaJIT

Server Modules

  • 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
    • fs - Files, directories, symlinks, pipes, memory mapping
    • proc - Async process execution with I/O redirection
    • path - Path manipulation
    • unixperms - Unix permissons string parser
    • time - Wall clock, monotonic clock, sleep
  • Multi-threading
    • os_thread - High-level threads API based on pthread and luastate
    • luastate - Create Lua interpreters to use with OS threads
    • pthread - Low-level threads
  • 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
    • base64 - Base64 encoding & decoding
    • json - Fast JSON encoding & decoding
    • msgpack - MessagePack encoding & decoding
    • xml_parse - XML SAX parsing
    • xml - XML formatting
    • csv - CSV parsing
    • xlsxwriter - Excel 2007+ XLSX file generation
    • multipart - Multipart MIME encoding
  • Hashing
  • Compression
  • Databases
    • sqlpp - SQL preprocessor
    • mysql - MySQL async driver
    • tarantool - Tarantool async driver
    • schema - Database schema diff'ing and migrations
    • query - SQL queries with preprocessor on a connection pool
  • Raster Images
  • Templating
  • Data Structures
  • Math
    • ldecnumber - Fixed-precision decimal numbers math
    • rect - 2D rectangle math
  • Support Libs
  • Dev Tools

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.

Web Framework

UI Widgets

Widgets are provided by canvas-ui.

Working on the SDK

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.

License

The Allegory SDK is MIT Licensed. 3rd-party libraries have various non-viral free licenses.

Questions you might have

Why Lua (for web apps)?

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.

Why not OpenResty?

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.

Why not 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

About

🍬 Self-contained cross-platform programming environment for developing web-based database-driven business apps in LuaJIT and JavaScript

Resources

License

Stars

Watchers

Forks