@@ 0,0 1,92 @@
+# baal
+
+Today I will be talking about the _baal_ project, and what it entails.
+
+The _baal_ project can be found _[here](https://git.sr.ht/~skiqqy/baal)_, if you
+would like to contribute, please feel free to drop me an
+[email](mailto:skiqqy@redxen.eu) containing your patch.
+
+Now, you migh be asking yourself: "what exactly is _baal_", allow me to answer
+your question. _baal_ (always written lowercase) was originally meant to be an
+implementation of my good friend [Tristan (deavmi)
+Kildaire](http://deavmi.assigned.network/)'s json based email protocol
+[butterfly](http://deavmi.assigned.network/projects/butterfly/), but then
+slowly morphed into my own take on a json based email protocol, and hence all
+credit for the idea should be directed towards deavmi.
+
+## Basics
+
+Everything in _baal_ is json based, config files, emails, etc. This keeps it
+simple and allows for easily extending config format without breaking anything
+else. i.e we keep backwords compatibility.
+
+Likewise, persistant storage is also done as json files (Although I am tempted
+to use a database, if I do, I will use
+[sqlite3](https://sqlite.org/index.html), as _baal_ is not inteded to have a
+large concurrent user base (max something like 32 users), as it is inteded to
+be used almost on a user by user basis, that is each user hosts thier own
+server.
+
+## baal query
+
+First, everything that happens in _baal_ is in the form of a _baal_ query, for
+example.
+
+* Sending an email
+* Syncing mailboxes
+* Creating mailboxes
+
+A _baal_ query is a json messaged, prefixed with a VLI of 4 bytes, with the
+json being of the form:
+
+```json
+{
+ "query" : "BAAL_QUERY",
+ "data" : <Any json object>
+}
+```
+We have 2 fields to unpack, namely
+* query
+ - What type of query this is, for example: `register`.
+* data
+ - The data needed to fulfill this query, varies from query to query.
+
+## More Queries
+
+Since the documentation for _baal_ is rather lacking, this blog post acts as
+the first offical documentation for baal, in the next post (Which will most
+likely be written tomorrow), I shall explain more of the currently implemented
+queries
+
+## Slightly long, tl;dr on baal
+
+* single binary (for both server and client).
+ - That is, to run a server or client for the _baal_ protocol, you just use a
+ single (more specifically, the __same__) binary.
+ - This is vastly simpler to setting up an email server, and should allow
+ users to easily setup thier own _baal_ mail servers.
+* open protocol (well it still needs to be written).
+* Multi user registration
+* Rich command set
+ - Easily extensible, adding new commands consists of simply creating a
+ starter function, which takes argc and argv (as a usual C prog does), and
+ execs the command.
+* Thread safe
+ - A _baal_ server can handle up to `n` (Decided at compile time) concurrent
+ connections, and all operations within these threads are (as of writing
+ this) thread safe.
+* Server query hooks
+ - The server can easily be extended, as the handling of incoming requests
+ consists of passing the incoming packet to the approriate hook, hence adding
+ new features requires 2 simple changes:
+ - Adding a function which execs the hook
+ - Adding a mapping of the command string in the request json to the
+ hook function
+ - Examples of hooks getting exec'd can be found
+ [here](https://git.sr.ht/~skiqqy/baal/tree/f8995d7d/item/src/baalserver.c#L395).
+
+## Actual tl;dr
+
+_baal_ = json + sockets = email server and or client
+
+~ Skiqqy
@@ 1,4 1,5 @@
# Summary
+[2021/10/27 baal](./20211027-baal.md)
[2021/10/26 Migration](./20211026-Migration.md)
[2021/04/16 Shell Scripting](./20210416-Shell-Scripting.md)
[2021/02/18 ctagd](./20210218-ctagd.md)