<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="author" content="Jordan Bancino"> <meta name="description" content="Telodendria, a Matrix homeserver written in ANSI C."> <meta property="og:title" content="Telodendria | A Matrix Homeserver written in ANSI C."> <meta property="og:type" content="website"> <meta property="og:url" content="https://telodendria.io"> <meta property="og:description" content="Telodendria, a Matrix homeserver written in ANSI C."> <link rel="stylesheet" href="style.css"> <link rel="icon" href="assets/Telodendria-196x196.png"> <title>Telodendria | A Matrix Homeserver written in ANSI C.</title> </head> <body> <img id="logo" src="assets/Telodendria-500x500.png" alt="Telodendria Logo" /> <h1 id="telodendria">Telodendria</h1> <p> <b>Telodendria:</b> The terminal branches of an axon. </p> <div class="msg-error"> <b><i>Note:</i></b> <b>Telodendria</b> is under <i>heavy</i> development. Please see the <a href="#project-status">Project Status</a>. </div> <p> <b>Telodendria</b> is a Matrix homeserver implementation written from scratch in ANSI C. It is designed to be lightweight and simple, yet functional. <b>Telodendria</b> differentiates itself from other Matrix homeserver implementations because it: <ul> <li> Is written in C, a stable, low-level programming language with a long history, low build and runtime overhead, and wide compatibility. </li> <li> 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 <b>Telodendria</b> needs is custom written. As a result, <b>Telodendria</b> 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. </li> <li> Uses a flat-file directory structure to store data instead of a database. This has a number of advantages: <ul> <li>It makes setup and maintenance much easier.</li> <li> It allows <b>Telodendria</b> to run on systems with fewer resources. </li> </ul> </li> <li> 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. </li> <li> Is permissively licensed. <b>Telodendria</b> is licensed under a modified MIT license, which imposes few restrictions on what you can do with it. </li> </ul> <p> <b>Telodendria</b> is on Matrix! Check out the official Matrix rooms: </p> <table> <tr> <th>Room</th> <th>Description</th> </tr> <tr> <td> <code>#telodendria-releases:bancino.net</code> </td> <td> Get notified of new releases. </td> </tr> <tr> <td> <code>#telodendria-general:bancino.net</code> </td> <td> General discussion and support for <b>Telodendria</b>. </td> </tr> <tr> <td> <code>#telodendria-issues:bancino.net</code> </td> <td> Report issues with <b>Telodendria</b>. </td> </tr> <tr> <td> <code>#telodendria-patches:bancino.net</code> </td> <td> Submit code patches to the <b>Telodendria</b> project. </td> </tr> </table> <h2 id="download">Download</h2> <p> <b>Telodendria</b> 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 <code>signify</code>, and the signify public key: <a href="/telodendria-signify.pub"> telodendria-signify.pub</a>. </p> <p> If your operating system has an official package or port of <b>Telodendria</b>, 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. </p> <table> <tr> <th>Version</th> <th>Download</th> <th>Checksum</th> <th>Signature</th> </tr> <!-- <tr> <td>v0.0.0</td> <td> <a href="/pub/v0.0.0/Telodendria-v0.0.0.tar.gz"> Telodendria-v0.0.0.tar.gz </a> </td> <td> <a href="/pub/v0.0.0/Telodendria-v0.0.0.tar.gz.sha256"> SHA256 </a> </td> <td> <a href="/pub/v0.0.0/Telodendria-v0.0.0.tar.gz.sig"> Signify </a> </td> </tr> --> <tr> <td colspan="4" style="text-align: center;"> No downloads here yet. See the <a href="#project-status">Project Status</a> for more information. </td> </tr> </table> <p> You can check out the change log <a href="#change-log">here</a>. </p> <h2 id="documentation">Documentation</h2> <p> <b>Telodendria</b>'s documentation is distributed with the source code as <code>man</code> pages, which contain all of the information on what <b>Telodendria</b> is, what its goals are, how to build the source, configure it, as well as contribute to the project. The <code>man</code> pages are also available online for convenience: </p> <ul> <li><a href="telodendria.7.html">telodendria(7)</a> - Introduction</li> <li><a href="telodendria.8.html">telodendria(8)</a> - Command line</li> <li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li> <li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li> </ul> <h2 id="project-status">Project Status</h2> <p> <b>Telodendria</b> 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. </p> <p> 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 <a href="#contributing">Contributing</a> section for details on how you can get involved. </p> <p> The <b>Telodendria</b> roadmap is organized into phases, with each phase representing a new milestone in the project's lifetime. </p> <h3 id="phase-1">Phase 1: Getting Off The Ground</h3> <p> A new open-source project needs a few basic things before development can begin. This phase covers the pre-development stage of <b>Telodendria</b>. </p> <ul> <li><s>Name this project</s></li> <li><s>Set up a CVS repository</s></li> <li><s>Make CVS repository public</s></li> <li><s>Write a coding style guide</s></li> <li><s>Write a build script</s></li> <li><s>Add a license</s></li> <li><s>Add support and issue reporting guide</s></li> <li><s>Add table of contents to this document</s></li> </ul> <h3 id="phase-2">Phase 2: Building A Foundation</h3> <p> Matrix homeservers require a few prerequisites. In this phase, we build up all the tools required to properly implement a Matrix homeserver. This includes basic data structures, exchange format parsers, and more. We also build up a command line application, multi-threaded HTTP server, and architect a flat-file database framework. </p> </p> <ul> <li><s>Implement an array</s></li> <li><s>Implement a logging facility</s></li> <li><s>Implement argument parsing (<code>-c file -Vh</code>)</s></li> <li><s>Implement a hash map</s></li> <li><s>Combine library code files</s></li> <li><s>Implement configuration file parsing using the hash map</s></li> <li><s>Base64 encoding/decoding with padded/unpadded support</s></li> <li><s>Write a release script</s></li> <li><s>UTF-8 encoder</s></li> <li> <s>Implement a JSON library using the hash map and array</s> <ul> <li><s>Basic encoding from HashMap/Array/strings, etc.</s></li> <li><s>Basic decoding to HashMap/Array/strings, etc.</s></li> <li><s>Proper string encoding</s></li> <li><s>Proper string decoding</s></li> <li> <s><q>Canonical JSON</q></s> <ul> <li><s>Keys are sorted lexicographically</s></li> <li><s>Floats are not allowed (ignore any float values)</s></li> <li><s>Encode as UTF-8 instead of using <code>\u</code> escapes</s></li> <li><s>Decode encoded strings to UTF-8</s></li> </ul> </li> </ul> </li> <li><s>Write a function that gets the current Unix timestamp in milliseconds.</s></code> <li><s>Figure out how to w</s>Write unit tests for array/hashmap/etc</li> <li><s>Parse the <b>Telodendria</b> config file</s></li> <li>Add <s>license/</s>documentation comments to all source files</li> <li><s>Implement a simple HTTP server</s> <ul> <li>Implement param parser</li> <li><s>URL encoder/decoder</s></li> </ul> </li> <li> Design the server architecture <ul> <li>Route requests</li> <li><s>Handle requests</s></li> <li>Data abstraction layer</li> <li><s>Error generation</s></li> </ul> </li> </ul> <h3 id="phase-3">Phase 3: Welcome To Matrix</h3> <p> When the foundations are laid, we can start implementing a real Matrix homeserver. This phase tracks our current progress in implementing the Matrix specification. </p> <ul> <li> Client-Server API <ul> <li><s>Error responses</s></li> <li><code>/_matrix/client/versions</code></li> <li><s>CORS Headers</s></li> <li>Well-known URIs</li> <li>Client Authentication</li> <li>Capabilities negotiation</li> </ul> </li> <li> Server-Server API </li> <li> Application Service API </li> <li> Identity Service API </li> <li> Push Gateway API </li> <li> Room Versions </li> </ul> <h3 id="phase-4">Phase 4: A Real Homeserver</h3> <p> The Matrix specification is only a part of what it takes to be a production-ready Matrix homeserver. While the spec details how clients and homeservers interact with each other, we still need a way to administer our homeserver. This phase tracks our progress on getting <b>Telodendria</b> packaged, as well as writing some useful administrative tools. Only when these things are completed can we call <b>Telodendria</b> "production-ready." </p> <ul> <li> Create an OpenBSD package and get it submitted to ports </li> <li> Create a command line tool to manage Telodendria <ul> <li>Configuration file generation</li> <li>User management</li> <li>Room management</li> </ul> </li> <li> Migrate from Synapse. I run a Synapse homeserver right now, so somehow I have to get all my data into the Telodendria format. </li> </ul> <h2 id="documentation-status">Documentation Status</h2> <p> This documentation needs just a little work. Here's the things on my list for that: </p> <ul> <li><s>Update Rationale section</s></li> <li><s>Update Project description (no longer a CGI binary)</s></li> <li><s>Update project code requirements (ANSI C, POSIX.1c)</s></li> <li><s>Clean up dark mode colors (tables, background, code snippets)</s></li> <li><s>Add logo (possibly center title?)</s></li> <li><s>Update Code Style to not include indent or line rules, but to use <code>indent(1)</code> instead.</s></li> <li><s>Fix typo "Subitting Patches" in Table of Contents</s></li> <li><s>Make a note in Getting The Code that the password for the <code>anoncvs</code> account is just <code>anoncvs</code>.</s></li> <li><s>Add Contributors list</s></li> <li><s>Add list of <code>make.sh</code> recipes, and what they do</s></li> <li>Improve Google Lighthouse score <ul> <li>Image elements do not have explicit width and height</li> <li>Background and foreground colors do not have a sufficient contrast ratio. (<code>msg-error</code> div)</li> <li><s>Lists do not contain only <code>li</code> elements.</s></li> </ul> </li> <li>Add other message <code>div</code>s for notes and warnings.</li> </ul> <h2 id="getting-support">Getting Support</h2> <p> <b>Telodendria</b> 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 <b>Telodendria</b> up and running, you're more than welcome to reach out for support. Just join the <code>#telodendria-general:bancino.net</code> Matrix channel. Before you do though, make sure you're running the latest version of <b>Telodendria</b> and you've thoroughly read through all the relevant documentation. </p> <h2 id="contributing">Contributing</h2> <p> <b>Telodendria</b> 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. </p> <h3 id="reporting-issues">Reporting Issues</h3> <p> If—after you've reached out to <code>#telodendria-general:bancino.net</code>—it has been determined that there is a problem with <b>Telodendria</b>, it should be reported to <code>#telodendria-issues:bancino.net</code>. There it can be discussed further. The issues room serves as the official issue tracker of <b>Telodendria</b>; although severe issues may be copied into a <code>TODO</code> file in the CVS repository just so they don't get lost. </p> <h3 id="developing">Developing</h3> <p> The primary language used to write <b>Telodendria</b> code is ANSI C. Other languages you'll find in the <b>Telodendria</b> 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. </p> <h4 id="getting-the-code">Getting The Code</h4> <p> If you'd like to hack on <b>Telodendria</b>, you'll need the following tools in addition to the tools required to <a href="#building-the-source">build the source</a>: </p> <ul> <li><code>cvs</code> for checking out and updating a local copy of the source code.</li> <li><code>indent</code> for formatting your code before generating patches</li> <li><code>patch</code> for applying patches to your local copy of the source code.</li> </ul> <p> Note that all of these tools are built into OpenBSD. While you of course don't have to use OpenBSD to develop <b>Telodendria</b>, it may make the process a little easier. In fact, these tools were chosen precisely <i>because</i> they were built into OpenBSD, the operating system I use. </p> <p> 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. </p> <div class="code"> $ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria $ cd Telodendria </div> <p> If you already checkout out the code previously, make sure you update your local copy before you start developing: </p> <div class="code"> $ cvs -q update -dP </div> <p> You should now have the latest <b>Telodendria</b> source code. Follow the <a href="#code-style">Code Style</a> as you make your changes. If the <code>cvs</code> command fails with a <code>Connection refused</code> error message, then try setting the <code>CVS_RSH</code> environment variable to <code>ssh</code>, like this: </p> <div class="code"> $ export CVS_RSH=ssh </div> <p> Then run the checkout again. Some versions of CVS don't use SSH to checkout by default, so if yours doesn't, you might want to put that line in your <code>.bashrc</code> or other shell init script. </p> <h4 id="code-style">Code Style</h4> <p> 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. </p> <ul> <li> All function, enumeration, structure, and header names are <code>CamelCase</code>. This is preferred to <code>snake_case</code> because it is more compact. </li> <li> All variable names are <code>lowerCamelCase</code>. This is preferred to <code>snake_case</code> because it is more compact. </li> <li> <code>enum</code>s and <code>struct</code>s are always <code>typedef</code>-ed to their same name. The <code>typedef</code> occurs in the public API header, and the actual declaration occurs in the implementation file. </li> <li> A feature of the code base lives in a single <code>.c</code> file that has a matching header file. The header file should only export public symbols, everything else in the <code>.c</code> file should be <code>static</code>. </li> <li> 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. </li> </ul> <p> As far as actually formatting the code goes, such as where to put brackets and whether you use tabs or spaces, use <code>indent(1)</code> to take care of all of that. The root of the repository has a <code>.indent.pro</code> file that should automatically be loaded by <code>indent(1)</code> to set the correct rules. If you don't have access to a working <code>indent(1)</code>, just indicate in your patch that I should run <code>indent(1)</code> on the code after applying it. I'll likely run my <code>indent(1)</code> on the code anyway though, just to make sure the spacing is consistent, if nothing else. </p> <h4 id="submitting-patches">Submitting Patches</h4> <p> <b>Telodendria</b> aims at remaining as minimal as possible. This doesn't just mean minimal code, it also means a minimal development process, which is why <b>Telodendria</b> 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. </p> <p> 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 <a href="#the-build-script">The Build Script</a>, just run the <code>patch</code> recipe: </p> <div class="code"> $ td patch </div> <p> 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 <code>PATCHSET</code>, like this: </p> <div class="code"> # Only write a patch for README.txt and the files in site/ $ PATCHSET="README.txt site/" td patch </div> <p> As you'll notice, the top of the patch file should have some email-style headers that look like this: </p> <div class="code"> From: Jordan Bancino <@jordan:bancino.net> Date: Fri Jul 29 03:21:21 PM EDT 2022 Subject: Document Patch Procedure </div> <p> As much information as possible should be filled out for you, such as the date. An attempt to fill out the <code>From</code> header was also made, but the information there can be made more accurate by setting <code>MXID</code> to your Matrix ID, and <code>DISPLAY_NAME</code> to your real name in your environment, or the <code>.env</code> file. The <code>Subject</code> should very briefly describe what the patch is about. </p> <p> You'll also notice these lines: </p> <div class="code"> [ ] I have read the Telodendria Project developer certificiate of origin, and certify that I have permission to submit this patch under the conditions specified in it. </div> <p> This is a checkbox that tells me whether or not you actually have the rights to submit your patch, and that once you submit the patch, your code is bound by the Telodendria license. The full text of the developer certificate of origin is as follows: </p> <ol> <li>The contribution was created in whole or in part by me, and I have the right to submit it under the open source license of the Telodendria project; or</li> <li>The contribution is based upon a previous work that, to the best of my knowledge, is covered under an appropriate open-source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the Telodendria project license; or</li> <li>The contribution was provided directly to me by some other person who certified (1), (2), or (3), and I have not modified it.</li> <li>I understand and agree that this project and the contribution are public and that a record of the contribution—including all personal information I submit with it—is maintained indefinitely and may be redistributed consistent with this project or the open-source licenses involved.</li> </ol> <p> After the headers, but before the checkbox, write a more thorough description of the patch and why it was created. Then, send the resulting patch file to <code>#telodendria-patches:bancino.net</code>, so it can be discussed and reviewed by the community. </p> <p> 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 <a href="/patches">public patch directory</a>, 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. </p> <p> The public patch directory works as follows: when you send your patch to the Matrix room, it is downloaded by the <b>Telodendria</b> Bot and placed in the <code>ingress/</code> directory, named as the message ID. Then, it is assigned a <b>Telodendria</b> patch ID and copied to the <code>p/</code> directory as just <code>${id}.patch</code>. This is a permanent link that will always reference your patch. Then, your patch is symlinked to the <code>queue/</code> 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 <code>accepted/</code> 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 <code>rejected/</code> directory. Regardless of the state of your patch, it will always remain permalinked in the <code>p/</code> directory, and when it is accepted or rejected, <b>Telodendria</b> Bot will send a message. </p> <p> 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. </p> <h2 id="resources">Resources</h2> <ul> <li><a target="_blank" href="/pub">Old <b>Telodendria</b> Versions</a></li> <li><a target="_blank" href="/spec.matrix.org">Matrix Spec Mirror</a> (<a href="/matrix-spec-v1.3.tar.gz">Download matrix-spec-v1.3.tar.gz</a>) </li> <li><a target="_blank" href="/patches">Public Patch Directory</a></li> </ul> <hr> © 2022 Jordan Bancino <@jordan:bancino.net> </body> </html>