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:

• 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 library to be built, and only a web server with CGI capabilities to run.
• 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.
• Runs as a CGI application. Telodendria is delivered as a single small, highly-optimized binary that can be dropped in a web server's web root to be executed. This allows it to consume very few resources and be very easy to set up.

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

Table of Contents

• Telodendria
  • Table of Contents
  • Getting Started
    • Install Telodendria
      • OpenBSD
      • Building From 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
  • Rationale
  • Project Goals
  • Getting Support
  • Documentation Status
  Contributing
  • Reporting Issues
  • Developing
    • Getting The Code
    • Code Style
    • Subitting Patches
  • License
  • Change Log

Getting Started

Install Telodendria

If your operating system has an official package or port of Telodendria, you should prefer to use that. 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.

If your operating system does not have an official package, see below for instructions on building from source and use them to create one.

OpenBSD

Telodendria is available in the ports tree and as a binary package. You can install it with the following command:

Building From 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 the C standard library. Because Telodendria is written in ANSI C, it should compile on just about any compiler, but the following compilers are known to work:
  • GCC
  • Clang
  • Tiny C Compiler (Note: must edit make.sh and remove -Wl,-static -Wl,-gc-sections from LDFLAGS)
  Other compilers should work as well, but you may have to play with the flags in make.sh.
• POSIX base utilities, including find, stat, env, and compliant sh-like shell.

If everything went well, that will produce telodendria.cgi, which you can then place under your web root and configure your web server to execute. You'll need to make sure /.well-known/matrix and /_matrix and all the paths under them actually execute telodendria.cgi. See the provided OpenBSD httpd.conf for reference. Even if you aren't using OpenBSD's httpd(8), you should find its configuration syntax simple enough to adequately demonstrate the proper configuration.

Configure Telodendria

Once you get Telodendria built and hooked into your web server, you will have to write a configuration file for it. The configuration file is just JSON, and it should be called Telodendria.json.

Project Status

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

Just because there's nothing here yet doesn't mean you should go away though! We desparately need 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
• Implement a JSON library using the hash map and array
• Figure out how to write unit tests for array/hashmap/etc
• 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)

Rationale

This section explains

I want a lightweight Matrix homeserver designed for OpenBSD. I want a homeserver that can be developed in vi(1) and compiled with a C compiler. I want it to function entirely on a base OpenBSD install without having to install any extra packages whatsoever. I've found that the 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.

So I wrote Telodendria.

Telodendria is written entirely in portable ANSI C. It depends on no third-party C libraries other than the standard C library. The only thing you need to run it is a web server that supports executing CGI programs, 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.

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 run under any web server that supports CGI. I chose to write Telodendria as a CGI program because anyone running an existing Matrix server is likely running a web server acting as a reverse proxy in front of it anyway, so why not just hook the homeserver directly into the web server? That's one less daemon to run, which means memory and CPU savings. CGI also allows Telodendria to remain single-threaded. Each request that comes in is handled as its own process, and operations are entirely isolated.

Project Goals

The goals of this project 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.
• To have as few external build and run dependencies as possible. It should be possible to compile Telodendria on any operating system out of the box, and have it be totally statically linked, ready to run under a chroot(8)-ed web server. 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 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 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 channel serves as the official issue tracker of Telodendria; although 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

There are multiple ways to get the source code for Telodendria. You can download an official release tarball from here if you would like, but the preferred way is to check out the source code from CVS. This makes generating patches a lot easier. If you do not have CVS, consult your operating system's package repository to install it. CVS was the chosen version control system for this project primarily because it is built into OpenBSD.

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

Code Style

Telodendria's code style is very unique. In general, these are the conventions used by the code base.

• All function, enumeration, structure, and header names are CamelCase. 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 private implementation header.
• Indentation is done with spaces. This ensures that files look the same for everyone. It also makes line wrapping rules much easier because the indentations are the same size. Please configure your editor to make the Tab key insert spaces, and if it does automatic indentation, make sure it indents with spaces. If you cannot configure your editor to insert spaces, then you can try running the code files you were working on through expand. A unit of indentation is 4 spaces.
• Lines should not exceed 72 characters, including indentations. Some developers use vi(1) in an 80x24 terminal to write code.

This guide may be subject to change. The source code is the absolute source of truth, so as long as you make your code look like the code surrounding it, you should be fine.

Submitting Patches

Submitting patches is fairly easy to do if you've got the CVS sources checked out. Once you have made your changes, just run cvs diff:

Then, send the resulting patches to #telodendria-patches:bancino.net, where they will be promptly reviewed by the community.

License

All of the code and documentation for Telodendria is licensed under the following terms and conditions:

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.