Telodendria

Telodendria: The terminal branches of an axon.

Note: Telodendria is under heavy development. Please see the Project Status.

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:

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

Room Description
#telodendria-releases:bancino.net Get notified of new releases.
#telodendria-general:bancino.net General discussion and support for Telodendria.
#telodendria-issues:bancino.net Report issues with Telodendria.
#telodendria-patches:bancino.net Submit code patches to the Telodendria project.

Table of Contents

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.

Version Download Checksum Signature
No downloads here yet. See the Project Status for more information.

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:

$ ./make.sh

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.

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

Phase 2: Building A Foundation

Phase 3: Welcome To Matrix

Phase 4: A Real Homeserver

Documentation Status

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

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 is written entirely in portable ANSI C. It depends on no third-party C libraries other than the standard POSIX C library. The only thing you need to run it is a reverse proxy with HTTPS support, such as relayd(8), and a directory that data can be written to. Everything Telodendria needs to run itself is compiled into a single static binary, and the source code can be built anywhere, right out of the box. This makes it suitable for running in a chroot(8) environment.

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:

The developer goals are as follows:

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:

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.

$ export CVSROOT=anoncvs@bancino.net:/cvs $ cvs checkout Telodendria $ cd Telodendria

The password for the anoncvs account is simply anoncvs.

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.

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.

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, just run cvs diff:

$ cvs diff -uNp > your-changes.patch

At this point, it would be a good idea to open up your patch file in your preferred editor and look it over to make sure everything looks good. While you have the file open, you should also add some email-style headers to the top of your patch file, for quick identification:

From: Jordan Bancino <@jordan:bancino.net> Subject: Document Patch Procedure Date: 2022-07-27

Obviously, set the actual values to your own information. From should be your name and Matrix ID, and Date should be in the format %Y-%m-%d. 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: as soon as your patch is recieved, it will be downloaded and placed in the queue/ directory. Then, if your patch is accepted, it will be moved to the accepted/ directory and then committed to the official CVS repository. If you patch is rejected for some reason, it will be moved to the rejected/ directory. Regardless of the state of your patch, it will always be permalinked in the p/ directory.

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 and documentation 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:

Contributors

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

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


© 2022 Jordan Bancino <@jordan:bancino.net>