Telodendria

Telodendria: The terminal branches of an axon.

Telodendria is a Matrix homeserver implementation written from scratch in ANSI C. It is designed to be lightweight and simple, yet functional. Telodendria differentiates itself from other Matrix homeserver implementations because it:

• Is written in C, a stable, low-level programming language with a long history, low build and runtime overhead, and wide compatibility.
• Is written with minimalism as a primary design goal. Whenever possible and practical, no third-party libraries are pulled in to the source code. Everything Telodendria needs is custom written. As a result, Telodendria depends only on a standard C compiler and POSIX C library to be built, both of which are built in to a good Unix-style operating system already, which means you shouldn't have to install anything extra.
• Uses a flat-file directory structure to store data instead of a database. This has a number of advantages:
  • It makes setup and maintenance much easier.
  • It allows Telodendria to run on systems with fewer resources.
  • It provides both runtime and data safety and stability. Since no database is running, there's fewer things that could go wrong because there's a lot less code running on the system.
• Is packaged as a single small, statically-linked and highly-optimized binary that can be run just about anywhere. It is designed to be extremely easy to set up and consume as few resources as possible.
• Is permissively licensed. Telodendria is licensed under a modified MIT license, which imposes few restrictions on what you can do with it.

Telodendria is on Matrix! Check out the official Matrix rooms:

Table of Contents

• Telodendria
  • Table of Contents
  • Download
  • Building The Source
  • Configure Telodendria
  • Project Status
    • Phase 1: Getting Off The Ground
    • Phase 2: Building A Foundation
    • Phase 3: Welcome To Matrix
    • Phase 4: A Real Homeserver
  • Documentation Status
  • Rationale
  • Project Goals
  • Getting Support
  • Contributing
    • Reporting Issues
    • Developing
      • Getting The Code
      • Code Style
      • The Build Script
      • Submitting Patches
  • License
  • Contributors
  • Change Log
  • Resources

Download

Telodendria is distributed as source tarballs, in true Unix fashion. If you want, you can verify the checksum of your download, and check the signature. To check the signature, you'll need signify, and the signify public key: telodendria-signify.pub.

If your operating system has an official package or port of Telodendria, you should prefer to use that instead of manually downloading the source and building it. If your operating system's package or port is too out of date for your tastes, please contact the package's maintainers to notify them, or offer to update the package yourself.

You can check out the change log here.

Building The Source

Telodendria is designed to be light enough that it can be built from source on just about any operating system. It only has the following requirements, all of which should be already available to you on a sufficiently complete operating system:

• A standards-compliant C compiler with a POSIX.1c standard library. Because Telodendria is written in ANSI C and sticks to POSIX.1c features, it should compile on almost any compiler and operating system with minimal effort, but the following compilers and operating systems are known to work:
  • GCC on Linux
  • Clang on OpenBSD, Linux, and WSL
  • Tiny C Compiler (Note: must remove -Wl,-static -Wl,-gc-sections from LDFLAGS) on OpenBSD.
  Other compilers should work as well, but you may have to play with the flags.
• POSIX base utilities, including find, stat, env, and compliant sh-like shell.

If everything went well, that will produce build/telodendria, which you can then place wherever you want, and run as a system daemon. See the contrib folder for configuration examples.

If you're going to be doing more than just building the code, see The Build Script for full documentation on what the td script can do.

Configure Telodendria

Once you get Telodendria built, you will have to write a configuration file for it. The configuration file is a simple OpenBSD-style configuration file, which should be called telodendria.conf.

Project Status

Telodendria is a very ambitious project. There's a lot that needs to happen yet before it is usable. At the moment, there's nothing that even remotely ressembles a Matrix homeserver here; I'm still getting off the ground and building a foundation.

But just because there's nothing here yet doesn't mean you should go away! I could always use help, so you are more than welcome to help out if you want things to go quicker. Please see the Contributing section for details on how you can get involved.

Phase 1: Getting Off The Ground

• Name this project
• Set up a CVS repository
• Make CVS repository public
• Write a coding style guide
• Write a build script
• Add a license
• Add support and issue reporting guide
• Add table of contents to this document

Phase 2: Building A Foundation

• Implement an array
• Implement a logging facility
• Implement argument parsing (-c file -Vh)
• Implement a hash map
• Combine library code files
• Implement configuration file parsing using the hash map
• Base64 encoding/decoding with padded/unpadded support
• Write a release script
• UTF-8 encoder
• Implement a JSON library using the hash map and array
  • Basic encoding from HashMap/Array/strings, etc.
  • Basic decoding to HashMap/Array/strings, etc.
  • Proper string encoding
  • Proper string decoding
  • Canonical JSON
    • Keys are sorted lexicographically
    • Floats are not allowed (ignore any float values)
    • Encode as UTF-8 instead of using \u escapes
    • Decode encoded strings to UTF-8
• Write a function that gets the current Unix timestamp in milliseconds.
• Figure out how to wWrite unit tests for array/hashmap/etc
• Parse the Telodendria config file
• Add license/documentation comments to all source files
• Implement a simple HTTP server
• Design the server architecture
  • Route requests
  • Handle requests
  • Data abstraction layer
  • Error generation

Phase 3: Welcome To Matrix

• Implement the Client-Server API
• Implement the Server-Server API
• Implement the other Matrix APIs

Phase 4: A Real Homeserver

• Create an OpenBSD package and get it submitted to ports
• Create a command line tool to manage Telodendria
  • Configuration file generation
  • User management
  • Room management
• Migrate from Synapse. I run a Synapse homeserver right now, so somehow I have to get all my data into the Telodendria format.

Documentation Status

This documentation needs just a little work. Here's the things on my list for that:

• Update Rationale section
• Update Project description (no longer a CGI binary)
• Update project code requirements (ANSI C, POSIX.1c)
• Clean up dark mode colors (tables, background, code snippets)
• Add logo (possibly center title?)
• Update Code Style to not include indent or line rules, but to use indent(1) instead.
• Fix typo "Subitting Patches" in Table of Contents
• Make a note in Getting The Code that the password for the anoncvs account is just anoncvs.
• Add Contributors list
• Add list of make.sh recipes, and what they do
• Lighthouse Score
  • Image elements do not have explicit width and height
  • Background and foreground colors do not have a sufficient contrast ratio. (msg-error div)
  • Lists do not contain only li elements.
• Add other message divs for notes and warnings.

Rationale

I want a lightweight Matrix homeserver designed specifically for OpenBSD and other Unix-like operating systems. I want a homeserver that can be developed in vi(1) and compiled with the built-in C compiler. I want it to function entirely on a base OS install without having to install any extra packages whatsoever. I've found that as far as these priorities are concerned, the existing homeserver implementations fall tremendously short. This project aims to point out that existing homeserver implementations are way over-engineered and written in such a way that many programs and libraries have to be pulled in to use them.

I also want to learn how Matrix works, and I want to understand the code I'm running on my server, which is why I'm writing every component from scratch, even the HTTP server.

Telodendria doesn't use a database like all the other homeservers. Instead, it operates more like email: it uses a flat-file data structure similar to Maildir to store data. The advantage of this is that it saves server maintainers from also having to maintain a database. It greatly simplifies the process of getting a Matrix homeserver up and running, and it makes it highly portable. It also is extremely easy to back up and restore with base tools; just tar(1) up the directory, and you're good to go.

Telodendria is developed and tested on OpenBSD, but you'll find that it should just run on any POSIX operating system without modification.

Project Goals

The goals of this project are generally divided into user goals, and developer goals, depending on who they impact the most. This isn't an exhaustive list, but it is a list of things that I want to prioritize, because other server implementations lack them.

The user goals are as follows:

• To be a production-ready Matrix server capable of handling a lot of users. Telodendria should have good performance in many diverse environments. It should scale up well for large instances, and yet also be able to scale down to a peer-to-peer device.
• To be easier to configure than any of the other Matrix homeserver implementations. The configuration file should be flexible, well-documented, and easy to understand and modify. An intuitive command-line tool for administrative tasks should also be available.

The developer goals are as follows:

• To have as few external build and run dependencies as possible. It should be possible to compile Telodendria on any POSIX operating system right out of the box, and have it be totally statically linked, ready to run under a chroot(8). You'll even notice that the documentation is written in HTML directly, not Markdown, to remove the dependency on a Markdown parser and renderer.
• To have a simple yet elegant workflow, and not depend on any large or complex development tools, such as code forges. The entire development workflow should be able to be successfully and efficiently completed on a base OpenBSD install. Of course you don't have to use OpenBSD for development by any means, but the point is, the workflow should not require a lot of tools.
• To be written in clean, elegant, and well-documented code. The goal is to build a Matrix homeserver from the ground up, not just because I don't like the way existing homeservers are implemented, but also so I can learn how Matrix really works, and maybe even teach others along the way.

Getting Support

Telodendria is designed to be fairly straightforward, but that doesn't mean there won't be hiccups along the way. If you are struggling to get Telodendria up and running, you're more than welcome to reach out for support. Just join the #telodendria-general:bancino.net Matrix channel. Before you do though, make sure you're running the latest version of Telodendria and you've thoroughly read through all the relevant documentation.

Contributing

Telodendria is an open source project. As such, it welcomes contributions. There are many ways you can contribute, and any way you can is greatly appreciated.

Reporting Issues

If—after you've reached out to #telodendria-general:bancino.net—it has been determined that there is a problem with Telodendria, it should be reported to #telodendria-issues:bancino.net. There it can be discussed further. The issues room serves as the official issue tracker of Telodendria; although severe issues may be copied into a TODO file in the CVS repository just so they don't get lost.

Developing

The primary language used to write Telodendria code is ANSI C. Yes, that's the original C standard from 1989. The reason this standard is chosen, and the reason that it will not be changed, is because the original C is the most portable. Other languages you'll find in the Telodendria repository are shell scripts and HTML. If you have any experience at all with any of these languages, your contributions are valuable. Please follow the guidelines in this section to ensure the contribution workflow goes as smoothly as possible.

Getting The Code

If you'd like to hack on Telodendria, you'll need the following tools in addition to the tools required to build the source:

• cvs for checking out and updating a local copy of the source code.
• indent for formatting your code before generating patches
• patch for applying patches to your local copy of the source code.

Note that all of these tools are built into OpenBSD. While you of course don't have to use OpenBSD to develop Telodendria, it may make the process a little easier. In fact, these tools were chosen precisely because they were built into OpenBSD, the operating system I use.

You can download an official release tarball if you would really like, but the preferred way is to check out the source code from CVS. This makes generating patches a lot easier.

If you already checkout out the code previously, make sure you update your local copy before you start developing:

You should now have the latest Telodendria source code. Follow the Code Style as you make your changes.

Code Style

In general, these are the conventions used by the code base. This guide may be slightly outdated or subject to change, however. The source code itself is the absolute source of truth, so as long as you make your code look like the code surrounding it, you should be fine.

• All function, enumeration, structure, and header names are CamelCase. This is preferred to snake_case because it is more compact.
• All variable names are lowerCamelCase. This is preferred to snake_case because it is more compact.
• enums and structs are always typedef-ed to their same name. The typedef occurs in the public API header, and the actual declaration occurs in the implementation file.
• A feature of the code base lives in a single .c file that has a matching header file. The header file should only export public symbols, everything else in the .c file should be static.
• Anywhere curly braces are optional, there must still be curly braces. This makes it easy to add on to the code later, and just makes things less ambiguous.

As far as actually formatting the code goes, such as where to put brackets and whether you use tabs or spaces, use indent(1) to take care of all of that. The root of the repository has a .indent.pro file that should automatically be loaded by indent(1) to set the correct rules. If you don't have access to a working indent(1), just indicate in your patch that I should run indent(1) on the code after applying it. I'll likely run my indent(1) on the code anyway though, just to make sure the spacing is consistent, if nothing else.

The Build Script

Telodendria uses a custom build script called td, for Telodendria developer. The td script is not only a build script, however. It does all kinds of cool things like format the source code, and generate patch files. td is the only supported way to develop Telodendria.

I opted to write a custom build script instead of just using make, because I felt that there is really no way to make a truly portable Makefile that could do everything I need. I was doing a lot of research on the differences between the GNU and BSD versions of make, and I felt it just wasn't worth it when I could write a small POSIX script that would run on both GNU systems and BSD systems without a fuss. I also wanted a way to automate more than just building code. I wanted a system versatile enough that I could define arbitrary recipes to do whatever I want. I didn't want to be limited by the Makefile syntax.

The td script is fairly intuitive. It operates somewhat like make, in that it has recipes that you specify on the command line. To start using it, just run the following command in your Telodendria directory:

Note: You will have to run the above command every time you start a new terminal session, as nothing is persisted to your system. I believe in non-invasive, fully self-contained tooling, so it is up to you to hook the Telodendria tools into your environment if you want them to persist.

If you're going to be submitting patches, you should also configure a .env file in the project directory root, which td will include automatically for you. For the best experience, you'll want at least these values:

If you don't provide these values, td will deduce them from your environment. It uses your system username and hostname to create the MXID, and reads the password database to get your configured display name. It also uses vi as the default editor, which may not be suitable for all developers.

You can invoke td recipes with the following syntax:

Multiple recipes can be invoked in a single run of td. At the moment, recipes are run unconditionally; that is, even if parts of a recipe fail, all following recipes still run.

Here is a complete list of recipes currently supported by td, and a description of what they do. Some recipes can alter their behavior based on certain environment variables. Those variables are also documented here.

• build: Build the source code, and generate the build/telodendria binary. This is the default recipe; that is, it runs if no recipes are given as arguments to td. The build recipe is incremental; it only rebuilds sources that have been modified since the last build, which makes builds faster. This recipe makes use of many environment variables:
  • CFLAGS: Compiler flags to generate object files.
  • LDFLAGS: Compiler flags to link the output binary
  • CC: The compiler to use.
  • PROG: The name of the output binary
  • DEFINES: Global preprocessor definitions
  • INCLUDES: Header directories to make available
  TELODENDRIA_VERSION also makes its way into the output binary, but it is primarily used for generating releases.
• clean: Remove the build/ directory, which effectively cleans the source tree. Note that build does not place anything outside of build/, so this is functionally equivalent to running rm -r build.
• format: Make sure the source code copyright headers are up to date, and format the source code using the system's indent(1) command. This should be run before generating patch files, to ensure that the code follows the project conventions. Note that the provided .indent.pro assumes an OpenBSD indent, which may cause the GNU implementation to choke.
• test: Run all of the unit tests, and report the results. It is highly recommended to ensure that the tests all pass before submitting a patch, because patches that break the tests are likely to be rejected.
• site: Deploy the Telodendria website by copying the required files to a web root. The web root is defined by the TELODENDRIA_PUB environment variable. This is mainly used to deploy the official website, but it can be used to set up a local development site if absolutely neccessary.
• release: Generate a release tarball, checksum and sign it, and push it into the web root. The web root is defined by the TELODENDRIA_PUB environment variable. You may also have to set CVSROOT to the official CVS repository of Telodendria. If you want to create a release tarball for an older version, set TELODENDRIA_VERSION. If you want to generate a release tarball for the latest code, set CVS_TAG to HEAD. If you want to sign the generated tarball, set TELODENDRIA_SIGNIFY_SECRET to a signify private key file. This is mainly used to deploy releases to the official website, but it can be used to independently mirror Telodendria releases from the official CVS repository.
• patch: Generate a formatted patch file. The Telodendria project isn't super picky about how patches look as long as they apply cleanly, but this recipe generates patches in the format we like them. It makes them easy to read. This recipe will use the EDITOR variable to open your formatted patch in your preferred editor. If no EDITOR is specified, then vi is used. For more details on how this recipe works, read Submitting Patches. This recipe also makes use of PATCHSET, MXID, and DISPLAY_NAME.
• diff: Generate a temporary preview patch that is opened in the default pager. This recipe uses the PAGER variable to preview patches. If no PAGER is set, then less -F is used as the default. This can be used for quickly previewing patches. Setting PATCHSET allows you to only preview certain changes; see Submitting Patches for more information on how PATCHSET works.

Any environment variables noted above that td recipes use can be specified in a .env file in the root of the Telodendria directory. This saves you from constantly having to set the environment variables in your shell, as well as from having to pollute your user environment with Telodendria variables. td will automatically include the .env file on every run.

Submitting Patches

Telodendria aims at remaining as minimal as possible. This doesn't just mean minimal code, it also means a minimal development process, which is why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead, the contribution workflow operates on submitting patch files to a public Matrix room, sort of like the OpenBSD project operates on patch files sent to a public mailing list.

If you're not used to manually creating and submitting patches instead of opening a "pull request," you should be pleased to hear that submitting patches is fairly easy to do if you've got the CVS sources checked out. In fact, I find it easier than having to make a GitHub account, forking a project repository, and then making a pull request for it. Once you have made your changes in your local copy of the code, and you've configured your environment using the instructions in The Build Script, just run the patch recipe:

This will automatically generate a patch file for all your changes, and then open it in your preferred editor. You can also generate a patch for only certain files and directories. To do that, set PATCHSET, like this:

As you'll notice, the top of the patch file should have some email-style headers that look like this:

As much information as possible should be filled out for you, such as the date. An attempt to fill out the From header was also made, but the information there can be made more accurate by setting MXID to your Matrix ID, and DISPLAY_NAME to your real name in your environment, or the .env file. The Subject should very briefly describe what the patch is about. Below these headers, write a more in-depth description of the patch.

Then, send the resulting patch file to #telodendria-patches:bancino.net, so it can be discussed and reviewed by the community. If you don't have a Matrix account, and you really don't want to create one—ignoring how odd it is that you are trying to contribute to a Matrix homeserver project—you can email your patches to jordan@bancino.net. However, the preferred way of submitting patches is to the official Matrix room, so I will upload your patch there along with your email address. If you are going to send patches via email, they must be plain text emails, and the patch must be in the main body of the email. No MIME, base64, or printed-quotable garbage. I will silently reject emails that are not purely plain text. I should be able to write a raw copy of your message to an mbox file, and then apply it onto my code right from there, with no further processing. If you're going to be a regular contributor, it would just be easier to create a Matrix account. It doesn't have to be on my public homeserver, but it certainly can be. Note that the discussion and ultimately the decision on what to do with your patch will all happen in the Matrix room, so if you submit patches using email, you'll miss out on any feedback.

Try to keep your patches on topic—make one patch file per feature or bug fix being implemented. It is okay if your patches depend on previous patches, just indicate that in the patch. Note that it may take a while for patches to be committed, and some patches may not be committed at all. In either case, all sent patches are queued from the Matrix room into the public patch directory, so they can be referenced easier in the future. If you want to reference a submitted patch in a Matrix message or email, it might be a good idea to link to it in the public patch directory.

The public patch directory works as follows: when you send your patch to the Matrix room, it is downloaded by the Telodendria Bot and placed in the ingress/ directory, named as the message ID. Then, it is assigned a Telodendria patch ID and copied to the p/ directory as just ${id}.patch. This is a permanent link that will always reference your patch. Then, your patch is symlinked to the queue/ directory. I have a script that automatically ingresses patches and queues them for me, and I'll use this to review patches. If your patch is accepted, the queue symlink will be moved to the accepted/ directory and the patch is committed to the official CVS repository. If you patch is rejected for some reason, its symlink will be moved to the rejected/ directory. Regardless of the state of your patch, it will always remain permalinked in the p/ directory, and when it is accepted or rejected, Telodendria Bot will send a message.

You're always welcome to inquire about rejected patches, and request they be reviewed again, or you can use them as a starting point for future patches.

License

All of the code for Telodendria is licensed under a modified MIT license. Please consult the src/header.txt file for the actual license text. The Telodendria license text differs from the MIT license in the following ways:

• Where the MIT license states that the copyright notice and permission notice shall be included in all copies or substantial portions of the software, the Telodendria license requires the copyright notice and permission notice be included in all portions—regardless of size—of the software by omitting the word substantial.

The documentation for Telodendria is also licensed under the modified MIT license that lives in src/header.txt. Whether you obtain the documentation by printing, or otherwise downloading this page, or by checking it out from the CVS source, it is licensed the same as the code.

The Telodendria logo, however, belongs solely to the Telodendria project. It must only be used to represent the official Telodendria project, and may only appear in official Telodendria media. If Telodendria is forked, the logo must be removed from the project and optionally replaced by a different one. The logo may not be modified in any way or for any purpose.

Contributors

Telodendria would not be possible without the support of the following people:

• Project Manager: Jordan Bancino <@jordan:bancino.net>
• Logo/site design: Jonah

Change Log

At this time, Telodendria does not have any tagged releases because it is not yet functional as a Matrix homeserver. Please check out the Project Status to see where things are currently at.

Resources

• Old Telodendria Versions
• Matrix Spec Mirror (Download matrix-spec-v1.3.tar.gz)
• Public Patch Directory