[FIX] Fix schemas being in branch

Still as WIP as the original however!

.gitea/issue_template/bug_report.yaml

@@ -0,0 +1,49 @@
+name: Bug Report
+about: File a bug report regarding Telodendria, its website, or its documentation.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        You are submitting a bug report. Please be sure to fill out the
+        title with a brief description of the bug.
+  - type: dropdown
+    attributes:
+      label: Type
+      description: Select the type of issue.
+      options:
+        - Memory Leak
+        - Crash
+        - Unexpected Error Message
+        - Documentation
+        - Website
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        Please give a thorough and detailed description of the bug you
+        are reporting. Provide all the information you have, and do
+        some investigating to ensure you are providing a legitimate
+        issue report that is well thought out. **Include details on
+        how to reproduce the issue, or explicitly state that you were
+        unable to reproduce it.**
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Log Output
+      description: |
+        Please copy and paste the relevant sections of the log output,
+        or the entire log if it is not unreasonably large. The logs
+        will be automatically formatted, no code block is necessary.
+      render: shell
+    validations:
+      required: true
+  - type: markdown
+    attributes:
+      value: |
+        Please attach any additional files that may aid in our
+        investigation of this issue, including screenshots, debugging
+        session stack traces and dumps, etc.

.gitea/issue_template/config.yaml

@@ -0,0 +1,7 @@
+blank_issues_enabled: false
+contact_links:
+  - name: General Matrix Room
+    url: "https://matrix.to/#/#telodendria-general:bancino.net"
+    about: |
+      General discussion on Telodendria happens in this Matrix room. You
+      may get quicker feedback from there.

.gitea/issue_template/feature_request.yaml

@@ -0,0 +1,18 @@
+name: Feature Request
+about: Request a new feature or enhancement be added to Telodendria.
+title: "[Feature] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        You are submitting a feature request. Please be sure to fill
+        out the title with a brief description of the feature you are
+        requesting.
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        Please give a thorough and detailed description of the feature
+        you are requesting.
+    validations:
+      required: true

.gitea/pull_request_template.md

@@ -0,0 +1,25 @@
+
+---
+
+Please review the developer certificate of origin:
+
+1. The contribution was created in whole or in part by me, and I have
+the right to submit it under the open source licenses of the
+Telodendria project; or
+1. 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
+1. The contribution was provided directly to me by some other person
+who certified (1), (2), or (3), and I have not modified it.
+1. I understand and agree that this project and the contribution are
+made 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.
+
+- [ ] I have read the Telodendria Project development certificate of
+origin, and I certify that I have permission to submit this patch
+under the conditions specified in it.
+

.gitignore

@@ -4,9 +4,11 @@ data
 *.patch
 *.log
 vgcore.*
+*.core
 Cytoplasm/build
 Cytoplasm/out
 Cytoplasm/*-leaked.txt
 contrib/.vagrant
 src/Schema
 src/include/Schema
+man/mandoc.db

Cytoplasm/src/HttpRouter.c

@@ -196,7 +196,7 @@ HttpRouterRoute(HttpRouter * router, char *path, void *args, void **ret)
     char *pathPart;
     char *tmp;
     HttpRouteFunc *exec = NULL;
-    Array *matches;
+    Array *matches = NULL;
     size_t i;
     int retval;
 
@@ -254,14 +254,18 @@ HttpRouterRoute(HttpRouter * router, char *path, void *args, void **ret)
             {
                 /* pmatch[0] is the whole string, not the first
                  * subexpression */
+                char * substr;
+                regmatch_t cpmatch;
                 for (i = 1; i < REG_MAX_SUB; i++)
                 {
+                    cpmatch = pmatch[i];
+                    substr = StrSubstr(pathPart, cpmatch.rm_so, cpmatch.rm_eo);
                     if (pmatch[i].rm_so == -1)
                     {
                         break;
                     }
 
-                    ArrayAdd(matches, StrSubstr(pathPart, pmatch[i].rm_so, pmatch[i].rm_eo));
+                    ArrayAdd(matches, substr);
                 }
             }
         }

Cytoplasm/src/Str.c

@@ -147,7 +147,6 @@ StrSubstr(const char *inStr, size_t start, size_t end)
     }
 
     len = end - start;
-
     outStr = Malloc(len + 1);
     if (!outStr)
     {

README.md

@@ -1,7 +1,136 @@
-# [Telodendria](https://telodendria.io)
+<p align="center"><img src="https://telodendria.io/assets/Telodendria-500x500.png"></p>
+<h1 align="center">Telodendria</h1>
 
-**Telodendria** is an open source Matrix homeserver implementation written from scratch in ANSI C and designed to be lightweight and simple, yet functional.
+Telodendria is an extremely powerful, yet lightweight and portable
+chat server designed to be easy to install and configure. Powered by
+the [Matrix](https://matrix.org) protocol, Telodendria empowers
+everyone to run their own chat server on ordinary hardware, including
+old and embedded devices. Whether you want a simple chat server just
+for you and your friends and family, or want to talk to users on other
+Matrix homeservers but don't want to go through all the hastle of
+hosting a complicated, high-maintenance homeserver or joining an
+existing homeserver for privacy or other reasons, then Telodendria
+might be for you.
 
-**Important:** This project is not developed on GitHub or CVS anymore, but instead on a dedicated [Gitea forge](https://git.telodendria.io/Telodendria/telodendria).
+> **Note:** Telodendria still in development. See [Status](#status).
+
+## What is Matrix?
+
+Matrix is an **open standard** for *interoperable*, *decentralized*,
+*secure*, and *real-time* communication over the internet.
+
+Matrix can be thought of as the successor to email, but it works
+very similar to iMessage, Discord, or direct messaging on most
+social media networks. The primary difference between Matrix and these
+other services, however, is that Matrix doesn't depend on one central
+authority, and is designed in such a way to respect your privacy.
+Matrix has proven itself over the last few
+years to be a reliable communication tool, and has only gotten more
+user-friendly over the course of its development. Matrix is capable
+enough that it can&mdash;and should&mdash;totally replace any other
+means of digital communication, and it offers a much higher degree
+of security, simplicity, and functionality.
+
+Strictly speaking, Matrix itself is just the *protocol* by which
+clients and servers communicate. In order to use Matrix, we need
+implementations of both clients and servers. Telodendria is a server
+implementation of the Matrix protocol.
+
+## Why Telodendria?
+
+- **Lightweight:** Written in the C programming language, Telodendria
+is automatically lighter and faster than other self-hosted chat servers.
+It has very few external dependencies and is as self-contained as
+possible.
+- **Fully-Featured:** Most lightweight chat solutions compromise on
+features. Telodendria is built on the fully-featured Matrix protocol,
+which provides a chat experience that most normal users are familiar
+with.
+- **Portable:** You can run Telodendria on just about everything,
+including more traditional options like a personal home server or VPS,
+but also more obscure platforms like Raspberry Pis or retro computers.
+Telodendria can run on a broad number of operating systems, which means
+that no matter which platform and OS you prefer, there is a good chance
+you can add Telodendria without much difficulty. It is also extremely
+easy to migrate a Telodendria instance between platforms; just copy the
+data directory to a new device.
+- **Simple:** Telodendria is designed to be a simple, no-frills
+chat server. It is easy to install, easy to configure, and easy to
+maintain.
+- **Stable:** Other Matrix homeservers develop at the pace of the
+Matrix specification itself, which is to say quite rapidly. Changes are
+always being made, and a version shipped 6 months ago is already
+incredibly outdated. Telodendria, on the other hand, aims to be stable.
+It should *just work* for long periods of time between upgrades, and
+you should never feel like Telodendria is going to change significantly
+between upgrades.
+
+[Read Technical Rationale &rightarrow;](docs/dev/rationale.md)
+
+## Get Started
+
+Check out the [Documentation](docs/README.md) to get started with
+Telodendria.
+
+## Status
+
+Telodendria is in the very early stages of development. As such, it may
+not yet deliver on all of its promises. Currently, Telodendria is not
+ready for end-users yet. While it features very basic user
+authentication, it does not actually work as a chat server yet.
+
+We are hoping to ship Telodendria `v0.4.0` by May of 2024. This
+release should be usable for communication between **local users**
+only. Additional features, including federation with other Matrix
+homeservers will be added in future releases.
+
+You can help speed up development by [sponsoring](#sponsorship)
+Telodendria or [getting involved](docs/CONTRIBUTING.md).
+
+## Sponsorship
+
+Telodendria is maintained by a loosely-knit band of volunteers. The
+project currently has no sponsors and thus no source of income to
+pay for infrastructure costs and developer time. To ensure
+Telodendria's long-term success, please consider sponsoring the
+project.
+
+You can make a recurring donation to Telodendria using
+[LiberaPay](https://bancino.net/Telodendria/donate). You can also make
+one-time donations using
+[Stripe](https://donate.stripe.com/8wM29AfF5bRJc48eUU). If you would
+like to make a recurring donation larger than that allowed by
+LiberaPay, please contact Jordan Bancino over Matrix at
+`@jordan:bancino.net` or email at `jordan@bancino.net`.
+
+### Benefits
+
+While there are no set sponsorship tiers at this time, sponsoring
+Telodendria is a mutually beneficial relationship. Depending on the
+amount you donate, you can get your name, logo, and website links
+on the [Sponsors](docs/SPONSORS.md) page, the project `README`, or the
+main website.
+
+## License
+
+All of the code and documentation for Telodendria is licensed under a
+modified MIT license. The MIT license is an extremely permissive
+license that has very few restrictions. Please consult the
+[`LICENSE.txt`](LICENSE.txt) file for the actual license text. It is
+important to note that the Telodendria license text differs from the
+original 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 requires the copyright notice and
+permission notice be included with *all* portions, regardless of the
+size, by omitting the word *substantial*.
+
+The Telodendria logo in all its forms, including the ASCII
+representation, belongs solely to the Telodendria project. It must be
+used only to represent the official Telodendria project. You are free
+to use the logo in any way as long as it represents or links to the
+official project. If Telodendria is forked, the logo must be removed
+completely from the project, and optionally replaced by a different
+one.
 
-Please see the `README.txt` file for the actual project `README`, which simply details the repository structure a little bit. All of **Telodendria**'s user and developer documentation is available as `man` pages, or online. 

README.txt

@@ -1,64 +0,0 @@
-            .=                       -=-               
-          :.:+                     .=:.                
-         .=+-==.                  :.                   
-           .+-                   =.                    
-           .+                   :+.                    
-            ==.                 -+:                    
-             =++==--::           =+.                   
-               .:::--=+=:        :+=                   
-                       :==.      -=:                   
-                         ===----=-.           ... :+.  
-                       :==+=======:        .-+-::-+-=+=
-                      .==*%#=======       :+-      ..  
-                 .:--=-===+=========-.   :+:           
-              .=++=::..:============-+=-=-             
-:+=:        :=+-:      .-=========-.  .                
- =+++:  .:=+-:      .:--. .--:==:                      
-   ::---:..       :=+:        ==                       
-                  ++.        .+-                       
-                  =+         .+-     ...:              
-                  +-          -+-:-+=::+:              
-        :=-....:-=:            .--:    =-              
-     -++=:.:::..                                       
-
-=======================================================
-|_   _|__| | ___   __| | ___ _ __   __| |_ __(_) __ _ 
-  | |/ _ \ |/ _ \ / _` |/ _ \ '_ \ / _` | '__| |/ _` |
-  | |  __/ | (_) | (_| |  __/ | | | (_| | |  | | (_| |
-  |_|\___|_|\___/ \__,_|\___|_| |_|\__,_|_|  |_|\__,_|
-=======================================================
-Copyright (C) 2023 Jordan Bancino <@jordan:bancino.net>
-
-This is the source code for Telodendria, a Matrix homeserver written
-in C. All of the documentation is available as man pages in the
-man/ directory, or online at https://telodendria.io
-
-If information is missing from the documentation, please feel free
-to reach out to #telodendria-general:bancino.net on Matrix.
-
-This file documents the directory structure of the source code
-repository.
-
-Telodendria/
-	contrib/ - Supplemental files, such as example configs.
-	man/ - The official documentation as man pages.
-    proposals/ - Proposals for new features or fixes, as man pages.
-	site/ - The official website.
-	src/ - The C source code for Telodendria.
-		include/ - Header files for the source code.
-		Routes/ - Where Matrix API endpoints are implemented.
-        Static/ - Endpoints that just generate static HTML pages.
-	tests/ - Unit and integration tests will eventually go here.
-	tools/ - Development environment and tools.
-
-To cut a new release for Telodendria, perform the following
-steps. This is just a reference for me so I don't mess it up.
-
-	- Update tools/bin/td to declare the next version number.
-	- Make sure man/man7/telodendria-changelog.7 is up to date.
-	  with the latest information. (Be sure to set the date
-      correctly)
-	- Commit all changes.
-	- Run the release recipe: td release
-	- Deploy the site: td site
-

docs/CHANGELOG.md

@@ -0,0 +1,245 @@
+# Telodendria Change Log
+
+This document contains the complete change log for every official release of Telodendria.
+It is intended to be updated with every commit that makes a user-facing change worth
+reporting in the change log. As such, it changes frequently between releases. Final
+change log entries are published as [Releases](releases).
+
+## v0.4.0
+
+**Not Released Yet.**
+
+This release brings filters, rooms, and events! The core of the Matrix protocol architecture
+is not in place.
+
+### Matrix Specification
+
+The following endpoints were added:
+
+- **POST** `/_matrix/client/v3/user/{userId}/filter`
+- **GET** `/_matrix/client/v3/user/{userId}/filter/{filterId}`
+
+## v0.3.0
+
+**Saturday, June 10, 2023**
+
+Introducing a new configuration API and Cytoplasm, a general-purpose C library that
+supports source/sink-agnostic I/O, TLS, an HTTP client, and more! The third major
+release of Telodendria packs a lot of architectural improvements on top of supporting
+more of the Matrix specification.
+
+### Matrix Specification
+
+Added support for the following endpoints:
+
+- `/_matrix/client/v3/account/whoami`
+- `/_matrix/client/v3/account/password`
+- `/_matrix/client/v3/account/deactivate`
+- `/_matrix/client/v3/profile/*`
+- `/_matrix/client/v3/capabilities`
+- `/_matrix/client/v3/auth/*/fallback/web`
+
+There is also support for token-based user registration. Note that there is as of
+yet no admin-facing way to create these registration tokens, but the APIs are in
+place.
+
+### New Features
+
+- Added a new `HttpClient` API for making HTTP requests. This will eventually be
+used for federating with other Matrix homeservers.
+- Added support for pretty-printing JSON in `Json`. Telodendria itself does not
+pretty-print JSON, but this is useful for debugging and building useful tools.
+- Added a handful of new development tools built on the Telodendria APIs. New
+tools include `http`, a command line tool for making HTTP requests, similar to
+`curl`, `json`, a command line tool for working with JSON, similar to `jq`, and
+`http-debug-server`, a simple HTTP server that just prints requests out to standard
+output and returns an empty JSON object. `http` and `json` are replacements for
+`curl` and `jq` that build on the `HttpClient` and `Json` APIs. They exist mainly
+to test those APIs, but also to reduce the number of dependencies that Telodendria
+has. `http-debug-server` exists to test the `HttpServer` and `HttpClient` APIs.
+- Replaced all usage of `jq` with the new `json` tool. `jq` is no longer a development
+dependency.
+- Replaced all usage of `curl` with the new `http` tool. `curl` is no longer a
+required development dependency.
+- Added a new `tt` script for easily making Matrix requests against Telodendria
+in development.
+- Added TLS support to both the HTTP client and server. Currently, Telodendria
+supports LibreSSL and OpenSSL, but other TLS libraries should be extremely easy
+to add support for.
+- Added support for spinning up multiple HTTP servers. This is useful for having
+a TLS port and a non-TLS port, for example.
+- Moved all program configuration to the data directory and added an administrator
+API endpoint to manage it. It is now no longer recommended to manually update the
+configuration file. Consult the [Administrator API](user/admin/README.md) documentation
+and the [Configuration](user/config.md) documentation.
+- Added an administrator API endpoint for process control. Telodendria can now be
+restarted or shutdown via API endpoint.
+- Added an administrator API endpoint for getting statistics about the running
+Telodendria process.
+- Added support for user privileges, a way to have fine-grained control over what
+users are allowed to do with the administrator API. Administrator APIs for setting
+and getting privileges is now supported, and registration tokens have privileges
+associated with them so that users created with a token will automatically be given
+the specified privileges.
+
+### Fixes & General Improvements
+
+- Fixed a few warnings that were generated on some obscure compilers.
+- Moved the `main()` function to its own file to make it easier to link other
+programs with the Telodendria APIs.
+- Fixed the development tools environment script. Apparently using a hyphen as a bullet
+point is not very portable, because some shell implementations of `printf` interpret it
+as a flag. Switched to an asterisk.
+- Fixed some intermittent I/O errors that would occur as a result of race conditions in
+`JsonConsomeWhitespace()`. This function, and a few others, expect I/O to be blocking,
+but the `HttpServer` sets up I/O to be non-blocking, leading to occasional failures in
+JSON parsing.
+- Abstracted all I/O into the new `Io` and `Stream` APIs, which provide an input- and
+output- agnostic stream processing interface. This allows for a simple implementation of
+proxies, TLS, and other stream filters without having to change any of the existing
+code.
+- Remove all non-POSIX function calls, including the call to `chroot()` and, on
+OpenBSD, `pledge()` and `unveil()`. This may seem like a downgrade in security, but
+these are platform-specific system calls that should be patched in by package maintainers
+if they are desired. They also caused problems when implementing other features, because
+some library calls need to be able to access files on the filesystem.
+- Fixed the build script to supply `LDFLAGS` after the object files when linking.
+Apparently the order in which libraries are passed matters to some compilers.
+-  Added the response status of a request to the log output. This means that requests are
+logged after they have completed, not before they are started.
+- Memory allocations, reallocations, and frees are no longer loged when the log level
+is set to debug in the configuration file. To enable the logging of memory operations,
+pass the `-v` flag.
+- Implemented a proper HTTP request router with POSIX regular expression support.
+Previously, a series of nested `if`-statements were used to route requests, but this
+approach quickly becamse very messy. While the HTTP request router incurs a small memory
+and runtime speed penalty, the code is now much more maintainable and easier to follow.
+- Fixed some memory bugs in `Db` that were related to caching data. Caching should
+now work as expected.
+- Fixed a major design flaw in `Db` that would cause deadlock when multiple threads
+request access to the same object. Database locking is now in a per-thread basis,
+instead of a per-reference basis.
+- Telodendria now shuts down cleanly in response to `SIGTERM`.
+- Did some general refactoring to make the source code more readable and easier
+to maintain.
+Fixed a number of memory-related issues, including switching out some unsafe
+functions for safer versions, per the recommendations of the OpenBSD linker.
+- Moved all code documentation into the C header files to make it more likely
+that it will get updated. A simple header file parser and documentation generator
+have been added to the code base. See the `hdoc` man pages for documentation.
+- Updated the build script to provide static and shared libraries containing
+the code for Telodendria to make it easier to statically and dynamically link to
+other programs. The idea is that these libraries should be shipped with Telodendria,
+or as a separate package, and can be used to provide a high-level programming
+environment.
+- Updated the `Json` API to calculate the length of a JSON object. This is
+used to set the `Content-Length` header in HTTP requests and reponses.
+- Added some string functions, including `StrEquals()`, which replaced almost all
+uses of `strcmp()`, since `strcmp()` is used almost exclusively for equality
+checking. `StrEquals()` provides a standard way to do so, because previously,
+multiple different conventions could be found throughout the code base (for example:
+`!strcmp(str1, str2)` vs `strcmp(str1, str2) == 0`).
+
+... And many more!
+
+## v0.2.1
+
+**Monday, March 6, 2023**
+
+This is a patch release that fixes a few typos and other minor issues.
+
+## v0.2.0
+
+**Monday, March 6, 2023**
+
+This release is focused on providing a decent amount of the client authentication
+API. You can now create accounts on a Telodendria homeserver, and log in to
+get access tokens.
+
+### New
+
+- Added the basic form of the user registration API. If registration is enabled
+in the configuration file, clients can now register for Matrix accounts.
+- Added the basic form of the user login API. Clients can now log in to
+their accounts and generate access tokens to be used to authenticate requests.
+- Added the basic form of the user interactive authentication API, which can be used
+by endpoints that the spec says requires it. Currently, it only implements the
+dummy and password stages, but more stages, such as the registration token stage,
+will be added in future releases.
+- Added a simple landing page that allows those setting up Telodendria to
+quickly verify that it is accessible where it needs to be.
+- Added the static login page for clients that don't support regular login.
+
+### Changes
+
+- Improved HTTP request logging by removing unnecessary log entries and making
+errors more specific.
+- Leaked memory is now hexdump-ed out to the log if the log level is set to debug.
+This greatly simplifies debugging, because developers can now see exactly what the
+contents of the leaked memory are. Note that in some circumstances, this memory
+may contain sensitive data, such as access tokens, usernames, or passwords. However,
+Telodendria should not be leaking memory at all, so if you encounter any leaks,
+please report them.
+- Refactored a lot of the code and accompanying documentation to be more readable and
+maintainable.
+
+### Bug Fixes
+
+- Fixed a memory leak that would occur when parsing an invalid JSON object.
+- Fixed an edge case where HTTP response headers were being sent before they were
+properly set, causing the server to report a status of 200 even when that wasn't the
+desired status.
+- Fixed a few memory leaks in the HTTP parameter decoder that would occur in some
+edge cases.
+- Fixed an "off-by-one" error in the HTTP server request parser that would prevent
+`GET` parameters from being parsed.
+- Fixed the database file name descriptor to prevent directory traversal attacks
+by replacing special characters with safer ones.
+- Fixed a memory leak that would occur when closing a database that contains
+cached objects.
+- Fixed a memory leak that would occur when deleting database objects.
+- Fixed a few non-fatal memory warnings that would show up as a result of passing a
+constant string into certain functions.
+
+ ### Misc.
+
+ - Fixed a bug in `td` that caused `cvs` to be invoked in the wrong directory when
+ tagging a new release.
+ - Added support for environment variable substitution in all site files. This
+ makes it easier to release Telodendria versions.
+ - Fix whitespace issues in various shell scripts.
+ - Fixed the debug log output so that it only shows the file name, not the
+ entire file path in the repository.
+ - Updated the copyright year in the source code and compiled output.
+ - Switched the `-std=c89` flag to `-ansi`, as `-ansi` might be more supported.
+ - Fixed the `-v` flag. It now sets the log level to debug as soon as possible to
+ allow debugging configuration file parsing if necessary.
+
+ ... And many more bug fixes and feature additions! Too much has changed to make a
+ comprehensive change log. A lot of things have been done under the hood to make
+ Telodendria easier to develop in the future. Please test the current functionality,
+ and report bugs.
+
+The following platforms have been known to compile and run Telodendria:
+
+- OpenBSD
+- Linux (GNU and non-GNU)
+- Windows (via Cygwin)
+- FreeBSD
+- NetBSD
+- DragonFlyBSD
+- Haiku OS
+- Android (via Termux)
+
+Telodendria is about being portable; if you compile it on an obscure operating system,
+do let us know about it!
+
+## v0.1.0
+
+**Tuesday, December 13, 2022**
+
+This is the first public release of Telodendria so there are no changes to report.
+Future releases will have a complete change log entry here.
+
+This is a symbolic release targeted at developers, so there's nothing useful to
+ordinary users yet. Stay tuned for future releases though!

docs/CONTRIBUTING.md

@@ -0,0 +1,163 @@
+# Contributing
+
+Telodendria is a fully open source project. As such, it welcomes
+contributions. There are many ways you can contribute, and any way you
+can is greatly appreciated. This document details the ways you can
+contribute, and how to go about contributing.
+
+## Sponsoring Telodendria
+
+If you would like to sponsor Telodendria, see the
+[Sponsorship](../README.md#sponsorship) section on the main project
+page. Donations of any size are greatly appreciated.
+
+## Reporting Issues
+
+An important way to get involved is to just report issues you find with
+Telodendria during experimentation or normal use. To report an issue,
+go to [Issues](/Telodendria/telodendria/issues) →
+[New Issue](/Telodendria/telodendria/issues/new/choose) and follow the
+instructions.
+
+> **Note:** GitHub issues are not accepted. Issues may only be
+> submitted to the official [Gitea](https://git.telodendria.io)
+> instance.
+
+### Feature Requests
+
+Feature requests are allowed, but note that they are low-priority in
+comparison to existing issues and features. That being said, don't
+hesitate to submit feature requests. Just select the "Feature Request"
+option when submitting an issue.
+
+## Developing
+
+If you want to write code for Telodendria, either to fix an issue or
+add a new feature, you're in the right place. Please follow all the
+guidelines in this document to ensure the contribution workflow goes
+as smoothly as possible.
+
+### Who can develop Telodendria?
+
+Everyone is welcome to contribute code to Telodendria, provided that
+they are willing to license their contributions under the same license
+as the project itself.
+
+The primary language used to write Telodendria code is ANSI C. Other
+languages you'll find in the Telodendria repository include shell
+scripts, `mdoc`, a little bit of HTML and CSS, and `Makefiles`.
+Experience with any of these is preferred, but if you want to use
+Telodendria to learn, that's okay too! Telodendria's code base should
+hopefully be a good learning tool, and if you are serious about
+submitting quality work, we'll guide you through the process and
+offer suggestions.
+
+### What do I need?
+
+You'll need a couple of things to develop Telodendria:
+
+- A Unix-like operating system that provides standard POSIX behavior,
+or the Windows Subsystem for Linux (WSL), Cygwin, or Msys2 if you are
+running Windows.
+- A C compiler capable of compiling ANSI C89 code (pretty much all of
+them do—pick your favorite, and if you find it doesn't work,
+open an issue!).
+- `make` for building the project.
+- `git` for managing your changes.
+
+Optionally, you may also find these tools helpful:
+
+- `indent` for formatting code.
+- `valgrind` for debugging particularly nasty issues.
+
+### Getting The Code
+
+Telodendria is developed using Git. The easiest way to contribute
+changes is to fork the main repository, and then creating a pull
+request to ask us to pull your changes into our repo.
+
+1. If you don't have an account on the
+[Gitea instance](https://git.telodendria.io), create one and sign in.
+1. Fork this repository.
+1. In your development environment, clone your fork:
+   ```shell
+   git clone https://git.telodendria.io/[YOUR_USERNAME]/telodendria.git
+   cd telodendria
+   ```
+
+   Please base your changes on the `master` branch. If you need help
+   getting started with Git, that is beyond the scope of this
+   document, but you can find many good tutorials on the web.
+
+### Building & Running
+
+Telodendria uses the `make` build system.
+
+**TODO:** Update this section before #19 is closed. Provide quick
+make, run, and install directions (maybe just redirect to Porting for
+install directions), then list all the `make` recipes. Shouldn't be
+as many as were in `td`.
+
+### Pull Requests
+
+> **Note:** Telodendria does not accept GitHub pull requests at this
+> time. Please submit your pull requests via Gitea.
+
+Telodendria follows the standard pull request procedures. Once you have
+made your changes, committed them, and pushed to your fork, you should
+be able to open a pull request on the main repository. When you do, you
+will be prompted to write a description. Be sure to include the
+related issue that you are closing in your description.
+
+### Code Style
+
+In general, these are the conventions used by the code base. This
+guide may be slightly outdated or subject to change, but it should be
+a good start. The source code itself is always 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. One exception to this rule is
+if a variable name, such as a member of a struct, directly represents
+a JSON key in an object specified by the Matrix specification, which
+may be in `snake_case`.
+- Enumerations and structures are always `typedef`-ed to their same
+name. The `typedef` should occur in the public API header, and the
+actual declaration should live in the implementation file, unless
+the enumeration or structure is intended to be made fully public.
+- A feature of the code base lives in a single C source file that has a
+matching header. The header file should only export public symbols;
+everything else in the C source should be static.
+- Except where absolutely necessary, global variables are forbidden
+to prevent problems with threads and whatnot. Every variable a
+function needs should be passed to it either through a structure, or
+as a separate argument.
+- Anywhere that C allows curly braces to be optional, there still must
+be curly braces. This makes it easier to read the code by making it
+less ambiguous, and it makes it easier to add on to the code later.
+
+As far as actually formatting the code goes, such as where to put
+brackets, and whether or not to use tabs or spaces, use `indent` to
+take care of that. The repository contains a `.indent.pro` that should
+automatically be loaded by `indent` to set the correct rules. If you
+don't have a working `indent`, then just indicate in your pull
+request that I should run my `indent` on the code.
+
+### Documentation
+
+This project places a strong emphasis on documentation. Well-documented
+code is fundamental to a successful project, so when you are writing
+code, please also make sure that it is documented appropriately.
+
+- If you are adding a header, make sure you add the necessary comments
+detailing the header and the functions in it.
+- If you are adding a function, make sure you add the necessary
+comments to the appropriate header.
+
+If your pull request does not also include proper documentation, it
+will likely be rejected.
+

docs/README.md

@@ -0,0 +1,32 @@
+# Telodendria Documentation
+
+Here you will find all of the documentation for Telodendria. If you
+find that some documentation is missing or incorrect, please open an
+issue, and, even better, a pull request to fix the issue.
+
+You are also welcome to join the
+[`#telodendria-general:bancino.net`](https://matrix.to/#/#telodendria-general:bancino.net)
+matrix room, where you can discuss Telodnedria with others and ask
+questions.
+
+## User Documentation
+
+- [System Requirements](user/requirements.md)
+- [Install](user/install.md)
+- [Usage & Running](user/usage.md)
+- [Initial Set Up](user/setup.md)
+- [Configuration Options](user/config.md)
+- [Administrator API](user/admin/README.md)
+
+## Developer Documentation
+
+- [Repository Structure](dev/repo.md)
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Porting Guidelines](dev/ports.md)
+
+## Miscellaneous
+
+- [Matrix Specification](https://spec.matrix.org) ([Mirror](https://telodendria.io/spec.matrix.org))
+- [Change Log](CHANGELOG.md)
+- [Project Road Map](ROADMAP.md)
+

docs/dev/ports.md

@@ -0,0 +1,94 @@
+## Ports
+
+Telodendria is distributed primarily as source code, and the project
+itself does not offer a convenient install process such as in the form
+of a shell script. This is intentional; the Telodendria project is
+primarily concerned with developing Telodendria itself, not packaging
+it for the hundreds of different operating systems and linux
+distributions that exist. It is my firm belief that distributing an
+open source project is not the job of the open source developer; that
+is the reason software distributions exist: to collect and
+*distribute* software.
+
+It would be impossible to single-handedly package Telodendria for
+every platform, because each platform has very different expectations
+and conventions for software. Even different Linux distributions have
+different conventions for where manual pages, binaries, and
+configuration files go.
+
+That being said, this document aims to assist those who want to
+package Telodendria for their operating system or software
+distribution.
+
+---
+
+Before attempting to package Telodendria, make sure that you can build
+it and that it builds cleanly on your target platform. See
+[Install → From Source](../user/install.md#from-source)
+for general build instructions.
+
+To package Telodendria, you should collect the following files, and
+figure out where they should be installed on your system:
+
+- The `telodendria` server binary itself, located at
+`build/telodendria`.
+- All manual pages in the `man/` directory. These should be prefixed
+with `telodendria-`. You may also wish to ship the `docs/` directory
+so that the user can read the documentation offline, and ensure that
+they are reading the correct documentation for the installed version.
+- An init script. People that wish to install Telodendria on their
+system using your package are going to expect it to be integrated
+enough that Telodendria can easily be started at boot and otherwise
+managed by the system's daemon tools, be it `systemd` or another
+init system. Consult your system's documentation for writing an init
+script. **Note:** Telodendria *does not* fork itself to the background;
+the init script should do that.
+
+You may wish to optionally create a dedicated user under which
+Telodendria should run. Telodendria can be directly started as that
+user, or start as root and be configured to automatically drop to that
+user. Additionally, it might be helpful to provide a default
+configuration, which can be placed in the samples directory on your
+platform, or in a default location that Telodendria will load from.
+A good default directory that you may wish to provide for configuration,
+data, and logs could perhaps be `/var/telodendria` on Unix-like systems.
+
+Once you have collected the necessary files and directories that need
+to be installed, make sure your package performs the following tasks
+on install:
+
+- If necessary and depending on the configuration used, create a new
+system user for the Telodnedria daemon to run as.
+- If conventional for your system, enable the Telodendria init script
+so that Telodendria is started on system boot.
+- Instruct the user to carefully read the [Setup](../user/setup.md)
+(`docs/user/setup.md`) instructions and the
+[Configuration](../user/config.md) (`docs/user/config.md`) instructions
+before starting Telodendria.
+
+The goal of a package should be to get everything as ready-to-run as
+possible. The user should be able to start Telodendria right away and
+begin configuring it.
+
+Remember to publicly document the setup of Telodendria on your platform
+if there are additional steps required that are not mentioned in the
+official Telodendria documentation. This ensures that users can get
+up and running quickly and easily. If you're packaging Telodendria
+for a container system such as Docker, you can omit the things that
+containers typically do not have, such as the init scripts and
+documentation.
+
+Also remember that your port should feel like it belongs on your target
+system. Follow all of your system's conventions when placing files
+on the filesystem, so your users know what to expect. The goal is not
+necessarily to have a unified experience across all operating systems,
+rather, you should cater to the opinions of your operating system.
+Telodendria is architected in such a way that it does not impose the
+developer's opinions of where things should go, and since the
+configuration lives in the database, it is fairly self contained.
+
+If there are any changes necessary to the upstream code or build
+system that would make your job in porting Telodendria easier, do not
+hesitate to get involved by opening an issue and/or submitting a pull
+request.
+

docs/dev/rationale.md

@@ -0,0 +1,50 @@
+# Rationale
+
+This document seeks to answer the question of "why Telodendria?" from
+a technical perspective by comparing it to existing Matrix homservers.
+Telodendria is written entirely from scratch in ANSI C. It is designed
+to be lightweight, simple, and functional. Telodendria differentiates
+itself from other homeserver implementations because it:
+
+- Is written 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 into the code.
+Everything Telodnedria needs is custom written. As a result, Telodendria
+depends only on a standard C compiler and a POSIX C library to be
+built, both of which should come with any good Unix-style operating
+system already, which means you shouldn't have to install anything
+additional to use Telodendria.
+- Uses a flat-file directory structure to store data instead of a
+real database. This has a number of advantages:
+    - It make setup and mainenance much easier.
+    - It allows Telodendria to run on systems with fewer resources.
+- 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 very few restrictions on what you can do
+with it.
+
+## What about [Conduit](https://conduit.rs)?
+
+At this point, you may be wondering why one would prefer Telodendria
+over Conduit, a Matrix homeserver that could also say pretty much
+everything this document has said so far. After all, Conduit is older
+and thus better established, and written in Rust, a Memory Safe™
+programming language.
+
+In this section, we will discuss some additional advantages of
+Telodendria that Conduit lacks.
+
+### Small Dependency Chain
+
+**TODO:** See #30.
+
+### Standardized
+
+**TODO:** See #30.
+
+### Portable
+
+**TODO:** See #30.

docs/dev/repo.md

@@ -0,0 +1,17 @@
+# Repository Structure
+
+This document describes the filesystem layout of the Telodendria source
+code repository.
+
+- `Telodendria/`
+    - `Cytoplasm/`: The source code for Cytoplasm, Telodendria's
+    general-purpose support library that provides core functionality.
+    - `contrib/`: Supplemental files, such as example configurations.
+    - `docs/`: All user and developer documentation as Markdown.
+    - `site/`: The official website source code as HTML.
+    - `src/': The C source code and headers for Telodendria.
+        - `Routes/`: Where the Matrix API endpoints are implemented.
+        - `Static/`: Endpoints that just generate static HTML pages.
+        - `include/`: Header files.
+    - `tools/`: Development environment and tools.
+

docs/user/admin/README.md

@@ -0,0 +1,36 @@
+# Administrator API
+
+Telodendria provides an administrator API as an extension to the
+Matrix specification that allows for administrator control over the
+homeserver. This includes profiling and examining the state of
+running instances, as well as managing users and media.
+
+Like Synapse, Telodendria supports designating specific local users as
+administrators. However, unlike Synapse, Telodendria uses a more
+fine-grained privilege model that allows a server administrator to
+delegate specific administration tasks to other users while not
+compromising and granting them full administrative access to the server.
+
+To authenticate with the administrator API, simply use your login
+access token just like you would authenticate any other Matrix client
+request.
+
+- [Privileges](privileges.md)
+- [Configuration](config.md)
+- [Server Statistics](stats.md)
+- [Process Control](proc.md)
+
+## API Conventions
+
+Unless otherwise indicated, HTTP response codes that are not `200 Ok`
+will be accompanied by a standard Matrix API error. Consult the Matrix
+specification for the format of these errors. The following error
+conditions are assumed to be possible for all API endpoints listed
+in the Administrator API documentation:
+
+| Response Code | Description |
+|---------------|-------------|
+| 400           | The user is not authenticated, did not provide a valid JSON object, or provided a JSON object with invalid or missing parameters.|
+| 403           | The user does not have the privileges necessary to carry out the requested action.|
+| 500           | A fatal server error occurred. Check the logs for more information.|
+

docs/user/admin/config.md

@@ -0,0 +1,42 @@
+# Administrator API: Configuration
+
+As mentioned in [Setup](../setup.md), Telodendria's configuration is
+intended to be managed via the configuration API. Consult the
+[Configuration](../config.md) document for a complete list of supported
+configuration options. This document simply describes the API used to
+update the configuration.
+
+## API Endpoints
+
+### **GET** `/_telodendria/admin/config`
+
+Retrieve the current configuration.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The current configuration was successfully retrieved.|
+
+### **POST** `/_telodendria/admin/config`
+
+Installs a new configuration. This endpoint validates the request body,
+ensuring it is a proper configuration, then it replaces the existing
+configuration with the new one.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The new configuration was successfully installed.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `restart_required` | `Boolean` | Whether or not the process needs to be restarted to finish applying the configuration. If this is `true`, then the restart endpoint should be used at a convenient time to apply the configuration.
+

docs/user/admin/privileges.md

@@ -0,0 +1,141 @@
+# Administrator API: Privileges
+
+This document describes the privilege model and the API endpoints that
+allow administrators to modify privileges for users.
+
+## List Of Privileges
+
+A local user can have any of the following privileges. Unless otherwise
+indicated, these privileges only grant access to certain parts of the
+administrator API; the regular Matrix API is unaffected.
+
+- **DEACTIVATE:** Allows a user to deactivate any other local users.
+- **ISSUE_TOKENS:** Allows a user to create, modify, and delete
+registration tokens.
+- **CONFIG:** Allows a user to modify the Telodendria server daemon's
+configuration.
+- **GRANT_PRIVILEGES:** Allows a user to modify his or her own
+privileges or the privileges of other local users.
+- **ALIAS:** Allows a user to modify room aliases created by other
+users. By default, users can only manage their own room aliases, but
+an administrator may wish to take over an alias or remove an offensive
+alias.
+- **PROC_CONTROL:** Allows a user to get statistics on the running
+process, as well as shutdown and resetart the Telodendria daemon
+itself. Typically this will pair well with **CONFIG**, because there
+are certain configuration options that require the process to be
+restarted to take full effect.
+
+There is also a special "pseudo-privilege":
+
+- **ALL:** Grants a user all of the aforementioned privileges, as well
+as privileges that do not yet exist. That is, if an update to
+Telodendria adds more privileges, users with this privilege will
+automatically gain those new privileges in addition to having all the
+existing privileges. This privilege should only be used with
+fully-trusted users. It is typical for a server administrator to not
+fully trust anyone else, and be the only one that holds an account with
+this privilege level.
+
+## API Endpoints
+
+The following API endpoints are implemented for managing privileges.
+
+### **GET** `/_telodendria/admin/privileges/[localpart]`
+
+Retrieve the permissions for a user. If the localpart is omitted, then
+retrieve the privileges for the user that owns the access token being 
+used. Note that the owner of the access token must have the
+**GRANT_PRIVILEGES** privilege to use this endpoint.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The privileges were successfully retrieved.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+### **POST** `/_telodendria/admin/privileges/[localpart]`
+
+Update the privileges of a local user by replacing the privileges array
+with the one specified in the request. Like the **GET** version of this
+endpoint, the localpart can be omitted to operate on the user that
+owns the access token.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The privileges were successfully replaced.|
+
+#### Request Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+### **PUT** `/_telodendria/admin/privileges/[localpart]`
+
+Update the privileges of a local user by adding the privileges
+specified in the request to the users existing privileges.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The privileges were successfully added.|
+
+#### Request Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+### **DELETE** `/_telodendria/admin/privileges/[localpart]`
+
+Update the privileges of a local user by removing the privileges
+specified in the request from the user's existing privileges.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The privileges were successfully removed.|
+
+#### Request Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
+

docs/user/admin/proc.md

@@ -0,0 +1,49 @@
+# Administrator API: Process Control
+
+This document describes the administrator APIs that allow a server
+administrator to manage the Telodendria process itself.
+
+## API Endpoints
+
+### **POST** `/_telodendria/admin/restart`
+
+Restart the Telodendria daemon cleanly. This endpoint will respond
+immediately after signaling to the daemon that it should be restarted
+as soon as possible. Note that the restart wmay not happen
+instantaneously, as Telodendria will finish processing all current
+requests before restarting. Also note that this is not a true restart;
+the process does not exit and restart, rather, Telodendria simply tears
+down all its state and then jumps back to the beginning of its code and
+starts over.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The restart request was successfully sent.|
+
+On success, this endpoint simply returns an empty JSON object.
+
+### **POST** `/_telodendria/admin/shutdown`
+
+Shut down the Telodendria process cleanly. This endpoint will respond
+immediately after signalling to the daemon that it should be shut
+down as soon as possible. Note that the shutdown may not happen
+instantaneously, as Telodendria will finish processing all current
+requests before shutting down. Also note that once shut down, Telodendria
+may be automatically restarted by the system's service manager.
+Otherwise, it will have to be manually restarted. This is a true
+shutdown; the Telodendria process exits as soon as possible.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The shutdown request was successfully sent.|
+
+On success, this endpoint simply returns an empty JSON object.
+

docs/user/admin/stats.md

@@ -0,0 +1,26 @@
+# Administrator API: Server Statistics
+
+The administrator API allows users with the proper privileges to get
+information about how the server process is performing.
+
+## API Endpoints
+
+### **GET** `/_telodendria/admin/stats`
+
+Retrieve basic statistics about the currently running Telodendria
+process.
+
+| Requires Token | Rate Limited |
+|----------------|--------------|
+| Yes            | Yes          |
+
+| Response Code | Description |
+|---------------|-------------|
+| 200           | The server statistics were successfully retrieved.|
+
+#### 200 Response Format
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.|
+| `version` | `String` | The current version of Telodendria.|

docs/user/config.md

@@ -0,0 +1,246 @@
+# Configuration
+
+Telodendria is designed to be configurable. It is configured using
+JSON, which is intended to be submitted to the [Administrator
+API](admin/README.md). This document details Telodendria's configuration
+JSON format, which is used in both the administrator API and on-disk
+in the database. The configuration file on the disk in the databsae
+is `config.json`, though that file should not be edited by hand.
+Use the API described in
+[Administrator API → Configuration](admin/config.md).
+
+## JSON Format
+
+Telodendria's configuration is just a JSON object in the standard
+key-value form:
+
+```json
+{
+    "serverName": "telodendria.io",
+    "listen": [
+        {
+            "port": 8008,
+            "tls": false
+        }
+    ]
+
+    /* ... */
+}
+```
+
+Some keys, called *directives* in this document, have values that are
+objects themselves.
+
+## Directives
+
+Here are the top-level directives:
+
+- **listen:** `Array`
+  
+  An array of listener description objects. Telodendria supports
+  listening on multiple ports, and each port is configured
+  independently of the others. A listener object looks like this:
+
+  - **port:** `integer`
+
+    The port to listen on. Telodendria will bind to all interfaces,
+    so it is recommended to configure your firewall to only allow
+    access on the desired interfaces. Note that Telodendria offers all
+    APIs over each port, including the administrator APIs; there is no
+    way to control which APIs are made available over which ports. If
+    this is a concern, a reverse-proxy such as `relayd` can be placed
+    in front of Telodendria to block access to undesired APIs.
+
+  - **tls:** `Object|null|false`
+
+    Telodendria can be compiled with TLS support. If it is, then a
+    particular listener can be set to use TLS for connections. If
+    **tls** is not `null` or `false`, then it can be an object with
+    the following directives:
+
+    - **cert:** `String`
+
+      The full path—or path relative to the data
+      directory—of the certificate file to load. The certificate
+      file should be in the format expected by the platform's TLS
+      library.
+
+    - **key:** `String`
+
+      Same as **cert**, but this should be the private key that matches
+      the certificate being used.
+
+  - **threads:** `Integer`
+    
+    How many worker threads to spin up to handle requests for this
+    listener. This should generally be less than the total CPU core
+    count, to prevent overloading the system. The most efficient number
+    of threads ultimately depends on the configuration of the machine
+    running Telodendria, so you may just have to play around with
+    different values here to see which gives the best performance.
+
+    Note that this can be set as low as 0; in that case, the listener
+    will never respond to requests. Each listener needs to have at
+    least one thread to be useful. Also note that Telodendria may spin
+    up additional threads for background work, so the actual total
+    thread count at any given time may exceed the sum of threads
+    specified in the configuration.
+
+    This directive is optional. The default value is `4` in the upstream
+    code, but your software distribution may have patched this to be
+    different.
+
+  - **maxConnections:** `Integer`
+
+    The maximum number of simultanious connections to allow to the
+    daemon. This option prevents the daemon from allocating large
+    amounts of memory in the event that it undergoes a denial of
+    service attack. It is optional, defaults to `32`, and typically
+    does not need to be adjusted.
+
+- **serverName:** `String`
+
+  Configure the domain name of your homeserver. Note that Matrix
+  servers cannot be migrated to other domains, so once this is set,
+  it should never change unless you want unexpected things to happen
+  or you want to start over. **serverName** should be a DNS name that
+  can be publicly resolved. This directive is required.
+
+- **baseUrl:** `String`
+
+  Set the server's base URL. **baseUrl** should be a valid URL,
+  complete with the protocol. It does not need to be the same as the
+  server name; in fact, it is common for a subdomain of the server name
+  to be the base URL for the Matrix homeserver.
+
+  This URL is the URL at which Matrix clients will connect to the
+  server, and is thus served as a part of the `.well-known`
+  manifest.
+
+  This directive is optional. If unspecified, it is automatically
+  deduced from the server name.
+
+- **identityServer:** `String`
+
+  The identity server that clients should use to perform identity
+  lookups. **identityServer** folows the same rules as **baseUrl**.
+  It also is optional, and is set to be the same as the **baseUrl**
+  if left unspecified.
+
+- **runAs:** `Object`
+  
+  The effective Unix user and group to drop to after binding to the
+  socket and completing any setup that may potentially require
+  elevated privileges. This directive only takes effect if
+  Telodendria is started as the root user, and is used as a security
+  mechanism. If this option is set and Telodendria is started as a
+  non-privileged user, then a warning is printed to the log if that
+  user and group do not match what's specified here. This directive
+  is optional, but should be used as a sanity check even if not
+  running as `root`, just to make sure you have your permissions
+  working properly.
+
+  This directive takes an object with the following directives:
+
+  - **uid:** `String`
+
+    The Unix username to switch to. If **runAs** is specified, this
+    directive is required.
+
+  - **gid:** `String`
+
+    The Unix group to switch to. This directive is optional; if left
+    unspecified, then the value of **uid** is copied.
+
+- **federation:** `Boolean`
+
+  Whether or not to enable federation with other Matrix homeservers.
+  Matrix by its very nature is a federated protocol, but if you just
+  want to rn your own internal chat server with no contact with the
+  outside, then you can use this option to disable federation. It is
+  highly recommended to set this to `true`, however, if you wish to
+  be able to communicate with users on other Matrix servers. This
+  directive is required.
+
+- **registration:** `Boolean`
+
+  Whether or not to enable new user registration or not. For security
+  and anti-spam reasons, you can set this to `false`. If you do, you
+  can still allow only certain users to be registered using
+  registration tokens, which can be managed via the administrator API.
+  This directive is required.
+
+  In an ideal world, everyone would run their own Matrix homeserver,
+  so no public registration would ever be required. Unfortunately,
+  not everyone has the means to run their own homeserver, especially
+  because of the fact that IPv4 addresses are becoming increasingly
+  hard to come by. If you would like to provide a service to those
+  that are unable to run their homeserver, then set this to `true`,
+  thereby allowing anyone to create an account.
+
+  Telodendria *should* be capable of handling a large amount of users
+  without difficulty, but it is targetted at smaller deployments.
+
+- **log:** `Object`
+
+  The logging configuration. Telodendria uses its own logging
+  facility, which can output logs to standard output, a file, or the
+  syslog. This directive is required, and it takes an object with the
+  following directives:
+
+  - **output:** `Enum`
+
+    The log output destination. This can either be `stdout`, `file`,
+    or `syslog`. If set to `file`, Telodendria will log to
+    `telodendria.log` inside the data directory.
+
+  - **level:** `Enum`
+
+    The level of messages to log. Each level shows all the levels above
+    it. The levels are as follows:
+
+    - `error`
+    - `warning`
+    - `notice`
+    - `message`
+    - `debug`
+
+    For example, setting the level to `error` will show only errors,
+    while setting the level to `warning` will show both warnings
+    *and* errors. The `debug` level shows all messages.
+
+  - **timestampFormat:** `Enum`
+
+    If you want to customize the timestamp format shown in the log,
+    or disable it altogether, you can do so via this option. Acceptable
+    values are `none`, `default`, or a formatter string as described
+    by your system's `strftime()` documentation. This option only
+    applies if **log** is `stdout` or `file`.
+
+  - **color:** `Boolean`
+
+    Whether or not to enable colored output on TTYs. Note that ANSI
+    color sequences will not be written to a log file, only a real
+    terminal, so this option only applies if the log is being written
+    to a standard output which is connected to a terminal.
+
+- **maxCache:** `Integer`
+
+  The maximum size of the cache. Telodendria relies heavily on caching
+  for performance reasons. The cache grows as data is loaded from the
+  data directory. All cache is stored in memory. This option limits the
+  size of the memory cache. If you have a system with a lot of memory
+  to spare, you'll get better performance if this option is set higher.
+  Otherwise, this value should be lowered on systems that have a
+  minimal amount of memory available.
+
+
+## Examples
+
+A number of example configuration files are shipped with Telodendria's
+source code. They can be found in the `contrib/` directory if you are
+viewing the source code directly. Otherwise, if you installed
+Telodendria from a package, it is possible that the example
+configurations were placed in the default locations for such files on
+your operating system.
+

docs/user/install.md

@@ -0,0 +1,60 @@
+# Installation
+
+There are multiple methods of installing Telodendria. Choose the one
+best suited to your use case.
+
+## Package Manager Or System Ports
+
+This is the recommended way to install Telodendria. If your operating
+system has an official package or port of Telodendria, you should
+prefer to use that instead of the other methods documented here,
+because your operating system or software distribution will have
+already figured out how to best integrate Telodendria with your system.
+
+Consult your operating system or software distribution's system
+manual for instructions on how to install packages. Also consult the
+official repository of your distribution to see if a package is
+available. If a package exists but it is too out of date for your
+tastes, please contact the package's maintainer to notify them, or
+offer to update the package yourself using the
+[porting instructions](../dev/ports.md).
+
+If you are maintaining a port or package for an operating system or
+software distribution, open a pull request to include your
+platform-specific instructions as a subheader of this section.
+Eventually, this section should contain basic instructions for the
+operating systems that have packages or ports.
+See [Ports](../dev/ports.md) for the project's distribution
+philosophy.
+
+## Container
+
+At this time, Telodendria does not have any officially recommended
+procedure for running in a container such as Docker or Vagrant. You
+may find helpful files in the [`contrib/`](../../contrib) directory,
+however.
+
+If you are publishing container images, please open a pull request to
+add your source files to `contrib/`, as well as to add documentation
+under this section explaining how to get set started.
+
+## Release Binary
+
+At this time, Telodendria does not publish any official binaries that
+can be downloaded. The tentative plan is to eventually provide binaries
+with each release for a number of supported platforms. When that
+happens, instructions will be provided here for dealing with the
+binaries.
+
+## From Source
+
+If you would like to build Telodendria from source, you can download
+the latest release code from the
+[Releases](/Telodendria/telodendria/releases) page. After extracting
+the tarball, read
+[Contributing → Developing → Building & Running](../CONTRIBUTING#building-and-running)
+for details on how to build Telodendria.
+
+If all goes well, you will find the server binary in the `build/`
+directory. If an error occured, and you didn't modify the code,
+please open an issue.

docs/user/setup.md

@@ -0,0 +1,60 @@
+# Initial Set Up
+
+While Telodendria strives to be extremely simple to deploy and run,
+in most circumstances a few basic setup steps will be necessary.
+Telodendria does not have a traditional configuration file like most
+daemons. Instead, its configuration lives in its database; as such,
+all configuration happens through the administrator API. This design
+decision makes Telodendria extremely flexible, because it is possible
+to re-configure Telodendria without having to manually edit files on
+the filesystem, thus allowing administrators to secure their server
+better.
+
+Please follow the instructions followed here carefully in the order
+they are presented for the best results.
+
+This document assumes that you have installed Telodendria using any
+of the instructions found in [Install](install.md). After installation,
+follow these steps:
+
+1. Start Telodendria. If you installed it via a package or container,
+consult your operating system or container system's documentation. If
+you are running Telodendria from a release binary or have built it from
+source, execute the binary directly. If needed, consult the
+[Usage](usage.md) page for details on how to run Telodendria.
+1. Assuming that Telodendria started properly, it will spin up and
+initialize its database directly with a simple—and, importantly,
+safe—default configuration, as well as a randomly generated,
+single-use registration token that grants a user all privileges
+documented in the [Administrator API](admin/README.md) documentation.
+Consult the log file for this administrator registration token. By
+default, the log file is located in the data directory, and is named
+`telodendria.log`.
+1. Use the registration token to register for an account on the
+server. This account will be the administrator account. You can do this
+using the client of your choice, or using tools such as `curl` or
+`http`, following the Matrix specification for registering accounts.
+The administrator account behaves just like a normal local account
+that an ordinary user would have registered on the server, except that
+it also has all privileges granted to it, so it can make full use of
+the Administrator API.
+1. Using the access token granted for the administrator account via
+the login process, configure Telodendria as descibed in
+[Configuration](config.md). See the [Administrator API](admin/README.md)
+documentation for the configuration endpoint details.
+
+This is the recommended way to set up Telodendria. However, if you
+wish to bypass the account creation step and want to configure
+Telodendria by directly writing a configuration file instead of using
+the administrator API, you can manually create the configuration file
+in the database before starting Telodendria. Simply create `config.json`
+following the description in [Configuration](config.md), then start
+Telodendria.
+
+While this alternative method may seem simpler and more convenient
+to some administrators, it is only so in the short-term. Note that this
+method is not supported, because it gives no access to the
+administrator API whatsoever, unless you manually modify the database
+further to give a user admin privileges, which is error-prone and
+bypasses some of Telodendria's safety mechanisms.
+

docs/user/usage.md

@@ -0,0 +1,64 @@
+# Usage
+
+This document provides general documentation on how to use the
+`telodendria` server binary, as well as details on how it behaves.
+The details here will be useful for setting up init systems, running
+Telodendria in a container, or manually executing the binary for
+testing or debugging purposes.
+
+## Command Line Options
+
+Typically, Telodendria is controlled via the
+[Administrator API](admin/README.md), but the Telodendria binary does include
+a few command line options, which can be used in init scripts or for
+debugging purposes.
+
+The command line arguments are as follows:
+
+- **`-d <dir>`** Specify the data directory to use. All persistent
+storage that Telodendria requires is saved to and loaded from here.
+- **`-V`** Only print the version information header and then quit
+with a success exit code.
+- **`-v`** Verbose mode. This overrides the configuration and sets the
+log level to `debug`. It also enables additional logging of memory
+operations, which can be useful for debugging.
+
+Before proposing additional command line arguments, consider whether or
+not the functionality requested can be provided via a (potentially new
+and as of yet uncreated) administrator API endpoint.
+
+## Environment
+
+Telodendria does not read any environment variables. All configuration
+should be done via the [Configuration API](config.md).
+
+## Signals
+
+Telodendria recognizes and responds to a number of signals:
+
+- **`PIPE`:** This signal is ignored, because all I/O errors should
+already be handled properly.
+- **`USR1`:** Perform a soft restart by shutting down the HTTP servers
+and resetting the program state. Note that the daemon process does
+not exit.
+- **`TERM`:** Perform a clean shutdown after all existing connections
+are closed.
+- **`INT`:** Same as `TERM`.
+
+Any other signals are not explicitly handled, so they have the
+default behavior as defind by the operating system.
+
+## Exit Status
+
+Telodendria exits with a non-0 exit code if the configuration file is
+invalid, or one or more of required paths or files is inaccessible.
+Telodendria will print an error to the log and then terminate
+abnormally.
+
+Telodendria exits with a code of 0 if the configuration file is valid,
+all paths and files required are accessible, and the HTTP listener
+starts as intended. If Telodendria is sent a signal that it catches
+after it begins servicing requests, it will still exit normally after
+it safely shuts down, because the bootstrap process completed
+successfully, and by all accounts, it ran normally and exitted
+normally.

man/man1/send-patch.1

@@ -1,57 +0,0 @@
-.Dd $Mdocdate: April 29 2023 $
-.Dt SEND-PATCH 1
-.Os Telodendria Project
-.Sh NAME
-.Nm send-patch
-.Nd Submit a patch file to the Telodendria Patches Matrix room
-.Sh SYNOPSIS
-.Nm
-.Op patch
-.Sh DESCRIPTION
-.Nm
-is a simple shell script for submitting patch files to Telodendria's patch
-room for review.
-.Pp
-.Nm
-takes a single argument, a patch file. It also reads a number of environment
-variables, as described in the following section. This script is designed to be
-simple; it only pushes files into a hard-coded Matrix room. Thus, as far as
-Matrix clients go, this one is a rather minimal one, and that is by design.
-.Pp
-This script exists so that users who are working on a machine that doesn't have
-a Matrix client installed can still submit work to the Telodendria project. The
-goal is to make development as accessible as possible.
-.Pp
-This script only supports password login, so if your homeserver does not
-support password login, it will not work.
-.Sh ENVIRONMENT
-.Pp
-.Nm
-utilizes the following environment variables:
-.Bl -tag -width Ds
-.It Ev MXID
-Your Matrix ID in the standard format. This is used to connect to your
-homeserver to send the message.
-.It Ev MXPW
-Your Matrix account's password. If not set, you will be prompted for your
-password by the script, unless
-.Ev ACCESS_TOKEN
-is set.
-.It Ev ACCESS_TOKEN
-If you already have an access token for your account, such as one from an
-existing session, then you can set this environment variable to bypass the
-password authentication flow.
-.El
-.Sh FILES
-.Pp
-.Nm
-does utilize the
-.Pa .env
-file, just like
-.Xr td 1 .
-Consult that page for the specifics of the
-.Pa .env
-file.
-.Sh SEE ALSO
-.Xr td 1
-

man/man1/tp.1

@@ -1,63 +0,0 @@
-.Dd $Mdocdate: April 29 2023 $
-.Dt TP 1
-.Os Telodendria Project
-.Sh NAME
-.Nm tp
-.Nd Manage the official patch queue.
-.Sh SYNOPSIS
-.Np
-.Op action
-.Op patch
-.Sh DESCRIPTION
-.Pp
-This script is probably not going to be very useful for anyone other
-than the official project managers, but for completeness, this page
-documents it.
-.Pp
-.Nm
-is a simple script that is used to manage the patch queue. It offers a
-simple way to fetch patches from the patch Matrix room and queue them
-in a patch directory, which is then updated as patches are handled.
-Contributions to Telodendria are entirely patch-based, so this script
-makes dealing with patch files much more convenient.
-.Pp
-.Nm
-doesn't implement a complex command line interface. It simply takes an
-action as the first argument, and a patch file ID as the second
-argument to some actions. The actions are as follows:
-.Bl -tag -width Ds
-.It ingress
-Download all new patches from the patches room. This action is intended
-to be called periodically from
-.Xr cron 8
-to fetch new patches.
-.It queue
-List all the patches in the queue, printing the first three lines of
-each one so they can be easily identified.
-.It view
-View the specified patch. Note that the specified patch must be in
-the queue. Once it is applied or rejected, this script offers no
-facility for viewing it.
-.It apply
-Apply the specified patch to the current working directory.
-.It reverse
-Reverse the specified patch on the current working directory.
-.It accept|reject
-Accept or reject the specified patch by moving it to the appropriate
-directory. These actions also prompt for a message, into which it is
-expected that an explanation for why the patch was accepted or rejected
-will be placed.
-.El
-.Sh ENVIRONMENT
-.Pp
-The following environment variables are read by the
-.Nm
-script:
-.Bl -tag -width Ds
-.It Ev TELODENDRIA_PUB
-The base directory inside which the patch directory relies.
-.It Ev HOMESERVER
-The Matrix homeserver to contact for receiving patches.
-.It Ev ACCESS_TOKEN
-The access token to use to authenticate with the Matrix homeserver.
-.El

man/man7/porting.7

@@ -1,119 +0,0 @@
-.Dd $Mdocdate: April 24 2023 $
-.Dt PORTING 7
-.Os Telodendria Project
-.Sh NAME
-.Nm porting
-.Nd Some guidelines for packaging Telodendria for your operating system.
-.Sh DESCRIPTION
-.Pp
-Telodendria is distributed at source code, and does not offer a
-convenient install process. This is intentional; the Telodendria
-project is primarily concerned with developing Telodendria itself,
-not packaging it for the hundreds of different operating systems
-and Linux distributions that exist.  It is my firm belief that
-distributing an open source project is not the job of the open
-source developer; that's the reason software distributions exist,
-to collect and distribute software.
-.Pp
-It would be impossible to single-handedly package Telodendria for
-every platform, because each platform has very different expectations
-for software. Even different Linux distributions have different
-conventions for where manual pages, binaries, and configuration
-files go.
-.Pp
-That being said, this page aims to assist those who want to package
-Telodendria for their operating system or software distribution.
-.Pp
-See
-.Xr td 1
-for instructions on how to build Telodendria. Only proceed with
-packaging Telodendria after you have successfully built it on your
-operating system.
-.Pp
-To package Telodendria, you should collect the following files, and
-figure out where they should be installed for your system:
-.Bl -bullet
-.It
-The telodendria server binary itself:
-.Pa build/telodendria
-.It
-All manual pages in the
-.Pa man/
-directory that are prefixed with "telodendria". These are the user
-documentation pages. All pages that do not have the "telodendria"
-prefix are intended only for developers, and so do not need to be
-installed to the system.
-.It
-An init script. People that wish to install Telodendria to their
-system expect it to be integrated enough that Telodendria can be
-easily started at boot, and otherwise managed by the system's daemon
-tools, be it systemd, or another init system. Consult your system's
-documentation for writing an init script. Do note that Telodendria
-does not fork itself to the background; the init script should do
-that. Note that the init script probably requires a few things:
-.Bl -bullet
-.It
-A dedicated system user under which Telodendria should run.
-Telodendria can either be started as that user, or started as
-root and configured to automatically drop to that user.
-.It
-A default data directory, in which all Telodendria data, including
-the configuration and logs, will be stored. A good default on
-Unix-like system is probably
-.Pa /var/telodendria .
-.El
-.El
-.Pp
-Optionally, it may be helpful to provide these as well:
-.Bl -bullet
-.It
-A sample Telodendria configuration. This should be placed in the
-examples directory on your
-system, if such a directory exists. You can use or adapt any of the
-configuration files in
-.Pa contrib/ ,
-or write your own specifically for your package.
-.El
-.Pp
-Once you have collected the files that need to be installed, make
-sure your package performs the following tasks on install:
-.Bl -bullet
-.It
-If necessary, depending on the config used, create a new system
-user for the Telodendria daemon to run as.
-.It
-If conventional for your system, enable the Telodendria init script
-so that Telodendria is started on system boot.
-.It
-Insruct the user to carefully read the
-.Xr telodendria-setup 7 ,
-.Xr telodendria-admin 7 ,
-and
-.Xr telodendria-config 7
-manual pages before starting Telodendria.
-.El
-.Pp
-The goal of a package should be to get everything as ready-to-run
-as possible.  The user should be able to start Telodendria
-right away and begin configuring it.
-.Pp
-Remember to publicly document the setup of Telodendria on your
-platform so that users can easily get things running. If you're
-packaging Telodendria for a containerization system such as Docker,
-you can omit the things that containers typically do not have, such
-as the init script and man pages.
-.Pp
-Also remember that your port should feel like it belongs on your
-target system.  Follow all of your system's conventions when placing
-files on the filesystem, so your users know what to expect. The
-goal is not necessarily to have a unified experience across all
-operating systems, rather, you should cater to the opinions of
-your operating system. Telodendria is architected in such a way
-that it does not impose the developers opinions of where things
-should go, and since the configuration lives in the database,
-it is fairly self-contained.
-.Pp
-.Sh SEE ALSO
-.Xr telodendria-contributing 7 ,
-.Xr td 1 ,
-.Xr telodendria 7

man/man7/telodendria-admin.7

@@ -1,421 +0,0 @@
-.Dd $Mdocdate: August 9 2023 $
-.Dt TELODENDRIA-ADMIN 7
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria-admin
-.Nd Administrator API documention.
-.Sh DESCRIPTION
-.Pp
-Telodendria provides an administrator API that allows for administrator control
-over the homeserver. This includes profiling and examining the state of Telodendria,
-as well as managing users and media.
-.Pp
-Like Synapse, Telodendria supports designating specific users as administrators.
-However, unlike Synapse, it uses a more finely-grained privilege model that allows
-a server administrator to designate specific administration tasks to other users
-while not compromising and granting them full administrative access to the server.
-.Pp
-To authenticate with the administrator API, simply use a regular
-access token.
-.Ss Privileges
-.Pp
-Here are all of the privileges a local user can have. Unless otherwise specified,
-these privileges only grant access to certain parts of the administrator API; the
-regular Matrix API is unaffected.
-.Bl -tag -width -Ds
-.It Dv DEACTIVATE
-Allows a user to deactivate any other local users.
-.It Dv ISSUE_TOKENS
-Allows a user to create, modify, and delete registration tokens.
-.It Dv CONFIG
-Allows a user to modify the Telodendria server daemon's configuration.
-.It Dv GRANT_PRIVILEGES
-Allows a user to modify his or her own privileges or the privileges of other
-local users.
-.It Dv ALIAS
-Allows a user to modify room aliases created by other users. By default, users
-can only manage their own room aliases, but an administrator may wish to take
-over an alias or remove an offensive alias.
-.It Dv PROC_CONTROL
-Allows a user to get statistics on the running process, as well as shutdown and
-restart the Telodendria daemon itself. Typically this will pair well with
-.Dv CONFIG ,
-because there are certain configuration options that require the process to be
-restarted.
-.El
-.Pp
-There is also a special ``pseudo-privilege'':
-.Bl -tag -width Ds
-.It Dv ALL
-Grants a user all of the aforementioned privileges, as well as privileges that
-do not yet exist. That is, if an update to Telodendria adds more privileges,
-users with this privilege will automatically gain those new privileges in
-addition to having all of the existing privileges.
-.Pp
-This privilege should only be used with fully-trusted users. It is typical for
-a server administrator to not fully trust anyone else, and be the only one that
-holds an account with this privilege level.
-.El
-.Sh API ENDPOINTS
-.Pp
-The following API endpoints are implemented for the installed version of
-Telodendria.
-.Pp
-Unless otherwise indicated, HTTP response codes that are not 200 Ok
-will be accompanied by a standard Matrix API error. Consult the Matrix specification
-for the format of these errors. The following error conditions are assumed to be
-possible for all of the endpoints listed here:
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-400;T{
-The user is not authenticated, did not provide a valid JSON object,
-or provided a JSON object with invalid parameters. 
-T}
-403;T{
-The user does not have the privileges necessary to carry out the
-specified action.
-T}
-500;T{
-A fatal server error occured. Check the logs for more information.
-T}
-.TE
-.Ss Sy GET No /_telodendria/admin/privileges/[localpart]
-.Pp
-Retrieve the permissions for a user. If the localpart is
-omitted, then retrieve the privileges for the user that owns
-the access token being used. Note that the owner of the
-access token must have the
-.Dv GRANT_PRIVILEGES
-privilege.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The privileges were successfully retrieved.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by replacing the
-privileges array with the one specified in the request.
-Like the
-.Sy GET
-version of this endpoint, the localpart can be omitted to
-operate on the user that owns the access token.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The privileges were successfully replaced.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy PUT No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by adding the privileges
-specified in the request to the user's existing privileges.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The requested privileges were successfully added.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy DELETE No /_telodendria/admin/privileges/[localpart]
-.Pp
-Update the privileges of a local user by removing the privileges
-specified in the request from the user's existing privileges.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The requested privileges were successfully removed.
-T}
-.TE
-.Pp
-Request Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-privileges;Array;T{
-An array of privileges, as described above. The
-privileges are represented as strings in JSON.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/config
-.Pp
-Installs a new configuration. It validates the request body, ensuring it is a
-proper configuration, then replaces the existing configuration with the new one.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token; Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The new configuration was successfully installed.
-T}
-.TE
-.Pp
-Consult the
-.Xr telodendria-config 7
-manual page for a full description of the configuration object that should
-be submitted. That page lists all the fields, and notes which ones are
-required.
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-restart_required;Boolean;T{
-Whether or not the process needs to be restarted to finish applying the
-configuration. If this is true, the restart endpoint may be used.
-T}
-.TE
-.Ss Sy GET No /_telodendria/admin/config
-.Pp
-Retrieve the current configuration.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The current configuration was successfully retrieved.
-T}
-.TE
-.Pp
-Consult the
-.Xr telodendria-config 7
-manual page for a full description of the configuration object that
-is returned. Note that this is the same object that was submitted
-using the
-.Sy POST
-version of this endpoint, otherwise it is the default configuration.
-.Ss Sy GET No /_telodendria/admin/stats
-.Pp
-Retrieve statistics about the currently running Telodendria process.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The server statistics were successfully retrieved.
-T}
-.TE
-.Pp
-200 Response Format:
-.TS
-tab(;) allbox expand;
-lfB lfB lfB
-l l l.
-Field;Type;Description
-memory_allocated;Integer;T{
-The total amount of memory allocated, measured in bytes.
-T}
-version;String;T{
-The current version of Telodendria.
-T}
-.TE
-.Ss Sy POST No /_telodendria/admin/restart
-.Pp
-Restart the Telodendria daemon cleanly. This endpoint will respond immediately
-after signaling to the daemon that it should be restarted as soon as possible.
-Note that the restart may not happen instantaneously, as Telodendria will finish
-processing all current requests before restarting. Also note that this is not a
-``true'' restart; the process does not exit and restart, rather, Telodendria
-simply tears down its state, and then jumps back to the beginning of its code
-and starts over.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The restart request was successfully sent.
-T}
-.TE
-.Pp
-On success, this endpoint simply returns an empty JSON object.
-.Ss Sy POST No /_telodendria/admin/shutdown
-.Pp
-Shut down the Telodendria process cleanly. This endpoint will respond immediately
-after signaling to the daemon that it should be shut down as soon as possible.
-Note that the shutdown may not happen instantaneously, as Telodnedria will
-finish processing all current requests before shutting down. Also note that once
-shut down, Telodendria may be automatically restarted by the system's service
-manager, otherwise, it will have to be manually restarted. This is a ``true''
-shutdown, the Telodendria process exits as soon as possible.
-.Pp
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Requires Token;Rate Limited
-Yes;Yes
-.TE
-.TS
-tab(;) allbox expand;
-lfB lfB
-l l.
-Response Code;Description
-200;T{
-The shutdown request was successfully sent.
-T}
-.TE
-.Pp
-On success, this endpoint simply returns an empty JSON object.
-.Sh SEE ALSO
-.Xr telodendria-config 7 ,
-.Xr telodendria-setup 7

man/man7/telodendria-changelog.7

@@ -1,480 +0,0 @@
-.Dd $Mdocdate: June 18 2023 $
-.Dt TELODENDRIA-CHANGELOG 7
-.Os Telodendria Project
-.Sh NAME
-.Nm Telodendria
-.Nd The change log for the Telodendria project.
-.Sh PROJECT STATUS
-.Pp
-.Nm
-is a very ambitious project. There's a lot that needs to happen yet
-before it is usable. At the moment,
-.Nm
-is starting to resemble a Matrix homeserver, but you can't really
-call it one yet. The foundation is mostly in place; now there's the
-Matrix specification to implement.
-.Pp
-Just because there's not much here yet doesn't mean you should go
-away! I could always use help, so you are more than welcome to get
-involved in the project if you want to see things move quicker.
-Feel free to donate using the links on the project website, or
-see the
-.Xr contributing 7
-page for details on how to get involved. The CVS repository has
-a file called
-.Pa TODO.txt ,
-which contains a checklist of the items that need to be completed.
-Feel free to grab an item on that list and start writing patches!
-It's a good idea to join the Matrix rooms noted in
-.Xr telodendria 7
-as well, so you can discuss your progress and ask questions.
-.Sh v0.4.0
-.Pp
-Not released yet.
-.Pp
-This release brings Filters, Rooms, and Events! The core of the
-Matrix protocol architecture is now in place.
-.Ss Matrix Specification
-.Pp
-The following new endpoints are now supported:
-.Bl -bullet -offset indent
-.It
-.Sy POST Pa /_matrix/client/v3/user/{userId}/filter
-.It
-.Sy GET Pa /_matrix/client/v3/user/{userId}/filter/{filterId}
-.El
-.Sh v0.3.0
-.Pp
-Saturday, June 10, 2023
-.Pp
-Introducing a new configuration API and Cytoplasm, a general-purpose
-C library that supports source/sink-agnostic I/O, TLS, an HTTP client,
-and more! The third major release of
-.Nm
-packs a lot of architectural improvements on top of supporting more of
-the Matrix specification.
-.Pp
-Matrix Specification:
-.Bl -bullet
-.It
-Added support for the
-.Pa /_matrix/client/v3/account/whoami
-endpoint.
-.It
-Added support for the
-.Pa /_matrix/client/v3/account/password
-endpoint.
-.It
-Added support for the
-.Pa /_matrix/client/v3/profile/*
-endpoints.
-.It
-Added support for the
-.Pa /_matrix/client/v3/capabilities
-endpoint.
-.It
-Added support for token-based user registration. Note that there is
-as of yet no admin-facing way to create these registration tokens,
-but the APIs are in place.
-.It
-Added web fallback pages for the supported user-interactive
-authentication mechanisms at
-.Pa /_matrix/client/v3/auth/*/fallback/web .
-.It
-Added support for the
-.Pa /_matrix/client/v3/account/deactivate
-endpoint.
-.El
-.Pp
-New Features:
-.Bl -bullet
-.It
-Added a new
-.Xr HttpClient 3
-API for making HTTP requests. This will eventually be used for
-federating with other Matrix homeservers.
-.It
-Added support for pretty-printing JSON to
-.Xr Json 3 .
-.Nm
-itself doesn't pretty-print JSON, but this is useful for debugging
-and building useful tools.
-.It
-Added a handful of useful development tools built on the
-.Nm
-APIs. New tools include
-.Xr http 1 ,
-a command line tool for making HTTP requests, similar to
-.Xr curl 1 ,
-.Xr json 1 ,
-a command line tool for working with JSON, similar to
-.Xr jq 1 ,
-and
-.Xr http-debug-server 1 ,
-a simple HTTP server that just prints requests out to standard
-output and returns an empty JSON object. 
-.Nm http
-and
-.Nm json
-are replacements for
-.Xr curl 1
-and
-.Xr jq 1
-that build on the
-.Xr HttpClient 3
-and
-.Xr Json
-APIs. They exist mainly to test those APIs, but also to reduce
-the number of dependencies that
-.Nm
-has.
-.Nm http-debug-server
-exists to test the
-.Xr HttpServer 3
-and
-.Xr HttpClient
-APIs.
-.It
-Replaced all usage of
-.Xr jq 1
-with the new
-.Xr json 1
-tool.
-.Xr jq 1
-is no longer a development dependency.
-.It
-Replaced all usage of
-.Xr curl 1
-with the new
-.Xr http 1
-tool.
-.Xr curl 1
-is no longer a development dependency.
-.It
-Added a new
-.Xr tt 1
-script for easily making Matrix requests against
-.Nm
-in development.
-.It
-Added TLS support to both the HTTP client and server. Currently,
-.Nm
-supports LibreSSL and OpenSSL, but other TLS libraries should be
-extremely easy to add support for.
-.It
-Added support for spinning up multiple HTTP servers. This is useful
-for having a TLS and non-TLS port, for example.
-.It
-Moved all program configuration to the data directory and added an
-administrator API endpoint to manage it. It is now no longer
-recommended to manually update the configuration file. Consult
-.Xr telodendria-admin 7
-and
-.Xr telodendria-config 7 .
-.It
-Added an administrator API endpoint for process control.
-.Nm
-can now be restarted or shut down via API endpoint.
-.It
-Added an administrator API endpoint for getting statistics about
-the running
-.Nm
-process.
-.It
-Added support for user privileges, a way to have fine-grained control
-over what users are allowed to do with the administrator API.
-Administrator APIs for setting and getting privileges is now
-supported, and registration tokens have privileges associated with
-them, so that users created with a token will have the specified
-privileges.
-.El
-.Pp
-Fixes and general improvements:
-.Bl -bullet
-.It
-Fixed a few warnings that were generated on some obscure compilers.
-.It
-Moved the
-.Fn main
-function into its own file to make it easier to link other programs
-with the
-.Nm
-APIs.
-.It
-Fixed the development tools environment setup script. Apparently
-using a hyphen as a bullet point is not very portable, because some
-shell implementations of
-.Xr printf 1
-interpret it as a flag. Switched to an asterisk instead.
-.It
-Fixed some intermittent I/O errors that would occur as a result of 
-race conditions in
-.Fn JsonConsumeWhitespace .
-This function, and a few others, expect I/O to be blocking, but
-the
-.Xr HttpServer 3
-sets up I/O to be non-blocking, leading to occasional failures in
-JSON parsing.
-.It
-Abstracted all I/O into the new
-.Xr Io 3
-and
-.Xr Stream 3
-APIs, which provide an input/output-agnostic stream processing.
-This allows for a simple implementation of proxies, TLS, and
-other stream filters without having to change any of the existing
-code.
-.It
-Removed all non-POSIX function calls, including the call to
-.Fn chroot
-and, on OpenBSD, the calls to
-.Fn pledge
-and
-.Fn unveil .
-This may seem like a downgrade in security, but these are
-platform-specific system calls that should be patched in by
-package maintainers if they are desired. They also caused
-problems when implementing other features, because some library
-calls need to be able to access files on the filesystem.
-.It
-Fixed the build script to supply
-.Ev LDFLAGS
-after the object files when linking. Apparently the order in
-which libraries are passed matters to some compilers.
-.It
-Added the response status of a request to the log output. This means
-that requests are logged after they have completed, not before they
-are started.
-.It
-Memory allocations, reallocations, and frees are no longer logged
-when the log level is set to debug in the configuration file. To
-enable the logging of all memory operations, pass the
-.Ic -v
-flag.
-.It
-Implemented a proper HTTP request router with POSIX regular
-expression support. Previously, a series of nested if-statements
-were used to route requests, but this approach quickly became
-very messy. While the HTTP request router incurs a small memory
-and runtime penalty, the code is now much more maintainable and
-easier to follow.
-.It
-Fixed some memory bugs in
-.Xr Db 3
-that were related to caching data. Caching should now work as
-expected.
-.It
-Fixed a major design flaw in
-.Xr Db 3
-that could cause deadlock when multiple threads request access to
-the same object. Database locking is now on a per-thread basis,
-instead of a per-reference basis.
-.It
-.Nm
-now shuts down cleanly in response to SIGTERM.
-.It
-Did some general refactoring to make the source code more
-readable and easier to maintain.
-.It
-Fixed a number of memory-related issues, including switching out
-some unsafe functions for safer versions, per the recommendations
-of the OpenBSD linker.
-.It
-Moved all code documentation into the C header files to make it
-more likely that it will get updated. A simple header file parser
-and documentation generator have been added to the code base.
-See
-.Xr hdoc 1
-for the utility documentation, and
-.Xr hdoc 5
-for the documentation format.
-.It
-Updated the build script to provide static and shared libraries
-containing the code for
-.Nm
-to make it easier to statically and dynamically link to other programs.
-The idea is that these libraries should be shipped with
-.Nm ,
-or as a separate package, and can be used to provide a high-level
-programming environment.
-.It
-Updated the
-.Xr Json 3
-API to calculate the length of a JSON object. This is used to set the
-Content-Length header in HTTP requests and responses.
-.It
-Added some string functions, including
-.Fn StrEquals ,
-which replaced almost all usages of
-.Fn strcmp ,
-since
-.Fn strcmp
-is used almost exclusively for equality checking.
-.Fn StrEquals
-provides a standard way to do so, because previously, multiple
-different conventions could be found throughout the code base.
-.El
-.Pp
-\&... And many more!
-.Sh v0.2.1
-.Pp
-Monday, March 6, 2023
-.Pp
-This is a patch release that fixes a few typos and other minor
-issues.
-.Sh v0.2.0
-.Pp
-Monday, March 6, 2023
-.Pp
-This release is focused on providing a decent amount of the
-client authentication API. You can now create accounts on a
-Telodendria homeserver, and log in to get access tokens.
-.Pp
-New:
-.Bl -bullet
-.It
-Added the basic form of the user registration API. If
-registration is enabled in the configuration file, clients
-can now register for Matrix accounts.
-.It
-Added the basic form of the user login API. Clients can now
-log in to their accounts and generate access tokens to be
-used to authenticate requests.
-.It
-Added the basic form of the user interactive authentication API,
-which can be used by any endpoints that the spec says require
-it. Currently, it only implements the dummy and password stages,
-but more stages, such as the registration token stage, will be
-added in future releases.
-.It
-Added a simple landing page that allows those setting up
-.Nm
-to quickly verify that it is accessible where it needs to be.
-.It
-Added the static login page for clients that don't support
-regular login.
-.El
-.Pp
-Changes:
-.Bl -bullet
-.It
-Improved HTTP request logging by removing unnecessary
-log entries and making errors more specific.
-.It
-Leaked memory is now hexdump-ed out to the log if the log
-level is set to debug. This greatly simplifies debugging,
-because developers can now easily see exactly what the
-contents of the leaked memory are. Note that in some
-circumstances, this memory may contain sensitive data,
-such as access tokens, usernames, or passwords. However,
-.Nm
-should not be leaking memory at all, so if you encounter
-any leaks, please report them.
-.It
-Refactored a lot of the code and accompanying documentation
-to be more readable and maintainable.
-.El
-.Pp
-Bug fixes:
-.Pp
-.Bl -bullet
-.It
-Fixed a memory leak that would occur when parsing an invalid
-JSON object.
-.It
-Fixed an edge case where HTTP response headers were being
-sent before they were properly set, causing the server to
-report a status of 200 even when that wasn't the desired
-status.
-.It
-Fixed a few memory leaks in the HTTP parameter decoder that
-would occur in some edge cases.
-.It
-Fixed an "off-by-one" error in the HTTP server request
-parser that prevented GET parameters from being parsed.
-.It
-Fixed the database file name generator to prevent directory
-traversal attacks by replacing special characters with
-safer ones.
-.It
-Fixed a memory leak that would occur when closing a
-database that contains cached objects.
-.It
-Fixed a memory leak that would occur when deleting database
-objects.
-.It
-Fixed a few non-fatal memory warnings that would show up
-as a result of passing a constant string into certain functions.
-.El
-.Pp
-Misc:
-.Bl -bullet
-.It
-Fixed a bug in
-.Xr td 1 
-that caused
-.Xr cvs 1
-to be invoked in the wrong directory when tagging a new release.
-.It
-Added support for environment variable substitution in all site
-files. This makes it easier to release
-.Nm
-versions.
-.It
-Fix whitespace issues in various shell scripts.
-.It
-Fixed the debug log output so that it only shows the file name,
-not the entire file path in the repository.
-.It
-Updated the copyright year in the source code and compiled output.
-.It
-Switch the -std=c89 flag to -ansi instead, as -ansi might be more
-supported.
-.It
-Fixed the -v flag. It now sets the log level to debug as soon
-as possible to allowe debugging the configuration file parsing
-if necessary.
-.El
-.Pp
-\&... And many more bug fixes and feature additions! Too much
-has changed to make a comprehensive change log. A lot of things
-have been done under the hood to make
-.Nm
-easier to develop in the future. Please test the current
-functionality, and report bugs to the Matrix rooms.
-.Pp
-The following platforms have been known to compile and run
-.Nm :
-.Bl -bullet
-.It
-OpenBSD
-.It
-Linux (GNU and non-GNU)
-.It
-Windows (via Cygwin)
-.It
-FreeBSD
-.It
-NetBSD
-.It
-DragonFlyBSD
-.It
-Haiku OS
-.It
-Android (via Termux)
-.El
-.Pp
-.Nm
-is about being portable; if you compile it on an obscure
-operating system, do let me know about it!
-.Sh v0.1.0
-.Pp
-Tuesday, December 13, 2022
-.Pp
-This is the first public release of
-.Nm
-so there are no changes to report. Future releases will
-have a complete change log entry here.
-.Pp
-This is a symbolic release targeted at developers, so there's nothing
-useful to ordinary users yet. Stay tuned for future releases though!

man/man7/telodendria-config.7

@@ -1,218 +0,0 @@
-.Dd $Mdocdate: April 20 2023 $
-.Dt TELODENDRIA-CONFIG 7
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria-config
-.Nd Telodendria configuration.
-.Sh DESCRIPTION
-.Pp
-Telodendria is designed to be configurable. It is configured using
-JSON, which is intended to be submitted via the administrator API.
-This page documents Telodendria's configuration JSON format, which
-is used both in the administrator API, and on the disk in the
-database. The configuration file on the disk in the database is
-.Pa config.json ,
-though that file should not be edited directly. Use the API described
-in
-.Xr telodendria-admin 7
-instead.
-.Sh DIRECTIVES
-Here are the top-level directives:
-.Bl -tag -width Ds
-.It Ic listen Ar listenArr
-An array of listener description objects. Telodendria supports
-listening on multiple ports, and each port is configured
-independently of the others. A listener description object looks
-like this:
-.Bl -tag -width Ds
-.It Ic port Ar port
-The port to listen on. Telodendria will bind to all interfaces, so it
-is recommended to configure your firewall so you can control what is
-allowed to access the Telodendria ports. Note that
-Telodendria offers all APIs over each port; there is no way to
-control which APIs are available over which ports, although all
-APIs should be safe against attacks, so this should not be a
-major concern.
-.Pp
-.Ar port
-should be a decimal port number. This directive is required. Common
-port numbers are 8008 for non-TLS, and 8448 for TLS.
-.It Ic tls Ar tlsObj|null|false
-Telodendria can be compiled with TLS support. If it is, then a
-particular listener can be set to use TLS for connections. If
-.Ic tls
-is not
-.Ar null
-or
-.Ar false ,
-then it can be an object with the following directives:
-.Bl -tag -width Ds
-.It Ic cert Ar file
-A certificate file in the format native to the platform's TLS
-library. This can be an absolute path, otherwise it is relative
-to the data directory.
-.It Ic key Ar file
-A key file in the format native to the platform's TLS library.
-It follows the same rules as the certificate file.
-.El
-.El
-.It Ic serverName Ar name
-Configure the domain name of your homeserver. Note that Matrix servers
-cannot be migrated to other domains, so once this is set, it should never
-change unless you want unexpected things to happen, or you want to start
-over.
-.Ar name
-should be a DNS name that can be publically resolved. This directive
-is required.
-.It Ic baseUrl Ar url
-Set the server's base URL.
-.Ar url
-should be a valid URL, complete with the protocol. It does not need to
-be the same as the server name; in fact, it is common for a subdomain of
-the server name to be the base URL for the Matrix homeserver.
-.Pp
-This URL is the URL at which Matrix clients will connect to the server,
-and is thus served as a part of the
-.Pa .well-known
-manifest.
-.Pp
-This directive is optional. If it is not specified, it is automatically
-deduced from the server name.
-.It Ic identityServer Ar url
-The identity server that clients should use to perform identity lookups.
-.Pp
-.Ar url
-follows the same rules as
-.Ic baseUrl .
-.Pp
-This directive is optional. If it is not specified, it is automatically
-set to be the same as the base URL.
-.It Ic runAs Ar uidObj
-The effective UNIX user and group to drop to after binding to the socket
-and changing the filesystem root for the process. This only works if
-Telodendria is running as the root user, and is used as a security mechanism.
-If this option is set and Telodendria is started as a non-priviledged user,
-then a warning is printed to the log if that user does not match what's
-specified here. This directive is optional, but should be used as a sanity
-check, if nothing more, to make sure the permissions are working properly.
-.Pp
-This directive takes an object with the following directives:
-.Bl -tag -width Ds
-.It Ic uid Ar user
-The UNIX username to drop to. If
-.Ic runAs
-is specified, this directive is required.
-.It Ic gid Ar group
-The UNIX group to drop to. This directive is optional; if it is not
-specified, then the value of
-.Ic uid
-is copied.
-.El
-.Ic log
-directive is configured to write to a file, the log file will be written
-in the data directory.
-.Ar directory
-should be an absolute path, under which all Telodendria data will live.
-.It Ic federation Ar true|false
-Whether to enable federation with other Matrix homeservers or not. Matrix is
-by its very nature a federated protocol,  but if you just want to run your
-own internal chat server with no contact with the outside, then you can use
-this option to disable federation. It is highly recommended to set this to
-.Ar true ,
-however, if you wish to be able to communicate with users on other Matrix
-servers. This directive is required.
-.It Ic registration Ar true|false
-Whether or not to enable new user registration or not. For security and anti-spam
-reasons, you can set this to
-.Ar false .
-If you do, you can still add users via the administrator API. In an ideal world,
-everyone would run their own homeserver, so no public registration would ever
-be required. Unfortunately, not everyone has the means to run their own homeserver,
-especially because of the fact that public IPv4 addresses are becoming increasingly
-harder to come by. If you would like to provide a service to those that are unable
-to run their own homeserver, you can set this to
-.Ar true ,
-which will allow anyone to create an account. Telodendria should be capable of handling
-a large amount of users without difficulty or security issues. This directive is
-required.
-.It Ic log Ar logObj
-The log file configuration. Telodendria uses its own logging facility, which can
-output logs to standard output, a file, or the syslog. This directive is required,
-and it takes an object with the following directives:
-.Bl -tag -width Ds
-.It Ic output Ar stdout|file|syslog
-The lot output destination. If set to
-.Ar file ,
-Telodendria will log to
-.Pa telodendria.log
-inside the data directory.
-.It Ic level Ar error|warning|notice|message|debug
-The level of messages to log at. Each level shows all the levels above it. For
-example, setting the level to
-.Ar error
-will show only errors, while setting the level to
-.Ar warning
-will show warnings and errors.
-.Ar notice
-shows notices, warnings, and errors, and so on. The
-.Ar debug
-level shows all messages.
-.It Ic timestampFormat Ar format|none|default
-If you want to customize the timestamp format shown in the log, or disable it
-altogether, you can do so via this option. Acceptable values are
-.Ar none ,
-.Ar default ,
-or a formatter string as described by your system's
-.Xr strftime 3 .
-This option only applies if
-.Ic log
-is "stdout" or "file".
-.It Ic color Ar true|false
-Whether or not to enable colored output on TTYs. Note that ANSI color sequences
-will not be written to a log file, only a real terminal, so this option only
-applies if the log is being written to a standard output which is connected to
-a terminal.
-.Pp
-This option only applies if
-.Ic log
-is "stdout".
-.El
-.It Ic threads Ar count
-How many worker threads to spin up to handle requests. This should generally be
-less than the total CPU core count, to prevent overloading the system. The most
-efficient number of threads ultimately depends on the configuration of the
-machine running Telodendria, so you may just have to play around with different
-values here to see which gives the best performance.
-.It Ic maxConnections Ar count
-The maximum number of simultanious connections to allow to the daemon. This option
-prevents the daemon from allocating large amounts of memory in the event that it
-undergoes a denial of service attack. It typically does not need to be adjusted.
-.It Ic maxCache Ar bytes
-The maximum size of the cache. Telodendria relies heavily on caching to speed
-things up. The cache grows as data is loaded from the data directory. All cache
-is stored in memory. This option limits the size of the memory cache. If you have
-a system that has a lot of memory, you'll get better performance if this option
-is set higher. Otherwise, this value should be lowered on systems that have
-minimal memory available.
-.El
-.Sh FILES
-.Bl -tag -width Ds
-.It Pa config.json
-The configuration file stored on the filesystem in the data
-directory. It is not recommended to edit this directly.
-.It Pa /var/telodendria
-The recommended data directory.
-.El
-.Sh EXAMPLES
-.Pp
-A number of example configuration files are shipped with
-Telodendria's source code. They can be found in the
-.Pa contrib/
-directory if you are viewing the source code directly. Otherwise,
-if you installed Telodendria as a package, it is possible that the
-example configurations were placed in the default locations for
-such files on your operating system.
-.Sh SEE ALSO
-.Xr telodendria-setup 7 ,
-.Xr telodendria-admin 7
-.Xr telodendria 8

man/man7/telodendria-contributing.7

@@ -1,268 +0,0 @@
-.Dd $Mdocdate: March 10 2023 $
-.Dt TELODENDRIA-CONTRIBUTING 7
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria-contributing
-.Nd Guide to contributing to the Telodendria project.
-.Sh DESCRIPTION
-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. This page contains some of
-the ways you can help out.
-.Sh REPORTING ISSUES
-Please reach out to the Matrix rooms mentioned at the top of
-.Xr telodendria 7 .
-All issue tracking takes place in those rooms. Start by reaching
-out to the general room, and if you think there's a legitimate
-problem with Telodendria itself, then stick the issue in the
-issues room, where it can be discussed further. Issues usually
-remain in the Matrix rooms, but severe enough issues may be put
-in a
-.Pa TODO
-file in the
-.Xr cvs 1
-repository so that they don't get lost.
-.Sh DEVELOPING
-The primary language used to write Telodendria code is ANSI C.
-Other languages you'll find in the Telodendria repository include
-shell scripts, 
-.Xr mdoc 7 ,
-and a little bit of HTML and CSS. If you have any experience with
-any of these languages, your contributions are valuable! Please follow
-the guidelines on this page to ensure the contribution workflow goes
-as smoothly as possible.
-.Ss Getting the Code
-If you'd like to hack on Telodendria, you'll need the following tools
-in addition to a C compiler and POSIX shell:
-.Bl -tag
-.It Xr cvs 1
-For checking out and updating your local copy of the source code.
-.It Xr indent 1
-For formatting your code before generating patches.
-.It Xr patch 1
-For applying patches to your local copy of the source code.
-.El
-.sp
-All of these tools are built into OpenBSD. While you don't have to
-use OpenBSD to develop Telodendria, it may make the process a bit
-easier. In fact, these tools where chosen precisely because they
-were built into my operating system of choice.
-.sp
-You can download an official release tarball from the website if
-you would really like, but the preferred way to get the source
-code for development is to check it out from CVS. This makes generating
-patches a lot easier.
-.Bd -literal -offset indent
-$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria
-$ cd Telodendria
-.Ed
-.sp
-If you already checked out the code previously, make sure you update
-your local copy before you start developing:
-.Bd -literal -offset indent
-$ cvs -q update -dP
-.Ed
-.sp
-You should now have the latest source code. Follow the
-.Sx CODE STYLE
-as you make your changes. If the
-.Xr cvs 1
-command fails with a "Connection refused" error message, try setting
-the
-.Ev CVS_RSH
-environment variable to "ssh", like this:
-.Bd -literal -offset indent
-$ export CVS_RSH=ssh
-.Ed
-.sp
-Then run the checkout command again. Some versions of CVS on some
-systems don't use SSH to checkout by default, so if yours doesn't,
-you might want to put the above line into your shell init script.
-.Ss 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.
-.sp
-If you're not used to manually creating and submitting patches instead of
-just 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's 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 properly as noted in the manual for
-.Xr td 1 ,
-just run the patch recipe:
-.Bd -literal -offset indent
-$ td patch
-.Ed
-.sp
-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 file for only
-certain files and directories. To do that, set
-.Ev PATCHSET ,
-like this:
-.Bd -literal -offset indent
-# Only write a patch for README.txt and the files in docs/
-$ PATCHSET="README.txt docs/" td patch
-.Ed
-.sp
-As you'll notice, the top of the patch file should have some email-style
-headers that look like this:
-.Bd -literal -offset indent
-From: Jordan Bancino <@jordan:bancino.net>
-Date: Fri Jul 29 03:21:21 PM EDT 2022
-Subject: Document Patch Procedure
-.Ed
-.sp
-As much information should be filled out for you, such as the date. An
-attempt to fill out the From header was also made by
-.Xr td 1 ,
-but the information there can be modifed as necessary. Consult the manual
-for
-.Xr td 1 
-for more details. The Subject should very briefly describe what the patch
-is about.
-.sp
-You'll also notice these lines in the patch:
-.Bd -literal -offset indent
-[ ] I have read the Telodendria Project development certificate of
-    origin, and certify that I have permission to submit this patch
-    under the conditions specified in it.
-.Ed
-.sp
-This is a checkbox that tells me whether or not you actually have the
-rights to submit your patch, and that once you submit your patch, your
-code is bound by the Telodendria project license, which you can and
-should view in
-.Xr telodendria 7 .
-The full text of the developer certificate of origin is as follows:
-.Bl -enum
-.It
-The contribution was created in whole or in part by me, and I have the right
-to submit it under the open source licenses of the Telodendria project; or
-.It
-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
-.It
-The contribution whas provided directly to me by some other person who certified
-(1), (2), or (3), and I have not modifed it.
-.It
-I understand and agree that this project and the contribution are made public
-and that a record of the contribution\(emincluding all personal information
-I submit with it\(emis maintained indefinitely and may be redistributed
-consistent with this project or the open source licenses involved.
-.El
-.sp
-If you agree to the above, fill in the square brackets with an 'x', and then 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 the public
-Matrix room using
-.Xr send-patch 1 .
-.sp
-Try to keep your patches on topic\(emmake 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 description. Note that it may take a while for
-patches to be committed, and some patches may not be comitted 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, email, or other digital medium,
-it might be a good idea to link to it in the public patch directory.
-.sp
-The public patch directory works as follows: when you send your patch to the
-Matrix room, it is downloaded by Telodendria Bot and placed in the
-.Pa ingress/
-directory, named as the message ID. Then, it is assigned a patch ID and
-copied to the
-.Pa p/
-directory as just "%d.patch", where "%d" is obviously the patch ID. This is
-a permanent link that will always reference your patch. Then, your patch will
-be symlinked into the 
-.Pa queue/
-directory. I have a script that automatically ingresses patches and queues them
-for me, and I use this to review patches. If your patch is accepted, the queue
-symlink will be moved to
-.Pa accepted/
-and the submitted patch will be committed to the official CVS repository.
-If your patch is rejected for some reason, its symlink will be moved to the
-.Pa rejected/
-directory. Regardless of the state of your patch, it will always remain
-permalinked in the
-.Pa p/
-directory, and when it is accepted or rejected, Telodendria Bot will send a
-message to the Matrix room.
-.sp
-You're always welcome to inquire about rejected patches, and request that they
-be reviewed again, or you can use them as a starting point for future patches.
-.sp
-The public patch directory is located at
-.Lk https://telodendria.io/patches/
-.Sh CODE STYLE
-In general, these are the conventions used by the code base. This guide
-may be slightly outdated or subject to change, but it should be a good
-start. The source code itself is always the absolute source of truth, so
-as long as you make your code look like the code surrounding it, you should
-be fine.
-.Bl -bullet
-.It
-All function, enumeration, structure, and header names are CamelCase. This
-is preferred to snake_case because it is more compact.
-.It
-All variable names are lowerCamelCase. This is preferred to snake_case
-because it is more compact.
-.It
-enumerations and structures are always typedef-ed to their same name. The
-typedef should occur in the public API header, and the actual declaration
-should live in the implementation file.
-.It
-A feature of the code base lives in a single C source file that has a
-matching header. The header file should only export public symbols;
-everything else in the C source should be static.
-.It
-Except where absolutely necessary, global variables are forbidden to
-prevent problems with threads and whatnot. Every variable a function
-needs should be passed to it either through a structure, or as a
-separate argument.
-.It
-Anywhere curly braces are optional, there still must be curly braces. This
-makes it easier to add on to the code later, and just makes things a bit
-less ambiguous.
-.El
-.sp
-As far as actually formatting the code goes, such as where to put brackets,
-and whether or not to use tabs or spaces, use
-.Xr indent 1
-to take care of all of that. The root of the CVS repository has a
-.Pa .indent.pro
-that should automatically be loaded by
-.Xr indent 1
-to set the correct rules. If you don't have a working
-.Xr indent 1 ,
-then just indicate in your patch that I should run my
-.Xr indent 1
-on the code after applying it. Although in reality, I'll likely
-run my own
-.Xr indent 1
-on the code anyway, just to make sure the spacing is consistent, if nothing
-else.
-.Pp
-This project places a strong emphasis on documentation. Well-documented
-code is fundamental to a successful project, so when you are writing code,
-please also make sure it is documented appropriately.
-.Bl -bullet
-.It
-If you are adding a header, make sure you add a man page that documents
-all the functions in the header.
-.It
-If you're adding a function, make sure you add documentation for it
-to the appropriate man page for the header that your function resides
-in. Do note that you do not have to document static functions, only
-public API functions.
-.El
-.Pp
-If your patch does not also include proper documentation, it will
-likely be rejected.

man/man7/telodendria-setup.7

@@ -1,75 +0,0 @@
-.Dd $Mdocdate: April 20 2023 $
-.Dt TELODENDRIA-SETUP 7
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria-setup
-.Nd First-time setup instructions for Telodendria.
-.Sh DESCRIPTION
-.Pp
-While Telodendria strives to be extremely simple to deploy, in most
-circumstances a few basic setup steps will be necessary. Telodendria
-does not have a traditional configuration file like most daemons.
-Instead, its configuration lives in its database; as such, all
-configuration happens through the administrator API. This design
-decision makes Telodendria extremely flexible, because it is possible
-to re-configure Telodendria without having to manually edit files
-on the filesystem. It is also why the setup instructions provided
-here are in the order they are. Please follow them carefully for the
-best results.
-.Pp
-This page assumes that you have installed Telodendria in the way
-prescribed by your operating system. Immediately following installation,
-perform these steps, in this order:
-.Bl -enum -width Ds
-.It
-Start Telodendria. Consult your operating system's documentation. If
-you are running Telodendria directly from the source code directory,
-use
-.Xr td 8 .
-.It
-Assuming Telodendria started properly, it will spin up and initialize
-its database directory with a simple\(emand importantly,
-safe\(emdefault configuration, and a randomly-generated, single-use
-registration token that grants a user all privileges documented in
-.Xr telodendria-admin 7.
-Consult the log file for this administrator registration token. The
-log file is located in the data directory, and is named
-.Pa telodendria.log .
-.It
-Use the registration token to register the administrator account. You
-can do this using the client of your choice, or using tools such as
-.Xr curl 1
-or
-.Xr http 1 .
-The administrator account functions just like a normal local account,
-except that it has all privileges granted to it, so it can make full
-use of the administrator API.
-.It 
-Using the access token for the administrator account, authenticate
-with the administrator API and configure Telodendria as described
-in
-.Xr telodendria-config 7.
-See
-.Xr telodendria-admin 7
-for the configuration endpoint details.
-.El
-.Pp
-This is the recommended way to set up Telodendria. However, if you
-wish to bypass the account creation step, and want to configure
-Telodendria by directly writing a configuration file instead of using
-the administrator API, you can manually create the configuration file
-in the database before starting Telodendria. Simply create
-.Pa config.json 
-following the description in
-.Xr telodendria-config 7 ,
-then start Telodnedria.
-.Pp
-While this alternative method may seem simpler and more convenient to
-some administrators, it is only so in the short-term. Note that this
-method is not supported, because it gives no access to the
-administrator API whatsoever, unless you manually modify the database
-to give a user admin privileges, which is error-prone and bypasses
-some of Telodendria's safety mechanisms.
-.Sh SEE ALSO
-.Xr telodendria-admin 7 ,
-.Xr telodendria-config 7

man/man7/telodendria.7

@@ -1,221 +0,0 @@
-.Dd $Mdocdate: March 10 2023 $
-.Dt TELODENDRIA 7
-.Os Telodendria Project
-.Sh NAME
-.Nm Telodendria
-.Nd Start here. This page contains the project introduction, and provides information about it, such as its status, how to contact the developers, and what the source code license is.
-.Sh DESCRIPTION
-.Nm
-is an open source Matrix homeserver written entirely from scratch in ANSI C and
-designed to be lightweight and simple, yet functional.
-.Pp
-.Nm
-differentiates itself from the other Matrix homeserver
-implementations because it:
-.Bl -bullet
-.It
-Is written in C, a stable, low-level programming language with a
-long history, low build and runtime overhead, and wide compatibility.
-.It
-Is written with minimalism as a primary design goal. Whenever possible
-and practical, no third-party libraries are pulled into the source code.
-Everything
-.Nm
-needs is custom written. As a result,
-.Nm
-depends only on a standard C compiler and a POSIX C library to be built,
-both of which should come with any good Unix-style operating system already,
-which means you shouldn't have to install anything extra.
-.It
-Uses a flat-file directory structure to store data instead of a database.
-This has a number of advantages:
-.Bl -bullet
-.It
-It makes setup and maintenance much easier.
-.It
-It allows
-.Nm
-to run on systems with fewer resources.
-.El
-.It
-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.
-.It
-Is permissively licensed.
-.Nm
-is licensed under a modified MIT license, which imposes very few restrictions
-on what you can do with it.
-.El
-.Pp
-.Nm
-is on Matrix! Check out the official Matrix rooms:
-.Pp
-.TS
-box tab(;);
-ll.
-#telodendria:bancino.net;The public "space" room.
-#telodendria-releases:bancino.net;Get notified of new releases.
-#telodendria-general:bancino.net;General discussion and support.
-#telodendria-newsletter:bancino.net;Periodic status updates.
-#telodendria-issues:bancino.net;Report bugs and issues.
-#telodendria-patches:bancino.net;Submit code patches to the project.
-#telodendria-ports:bancino.net;Discussion about porting and packaging.
-.TE
-.Pp
-.Nm
-is designed to be fairly straightforward, but that doesn't mean there
-won't be hiccups along the way. If you're struggling to get
-.Nm
-up and running, you're more than welcome to reach out for support. Just
-hop into the appropriate Matrix rooms and talk to me!
-.Sh 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 and compiled with built-in tools. I want it to function entirely
-on a base OS install without having to install any packages whatsoever. I've
-found that as far as these goals are concerned, the existing homeserver
-implementations fall short. This project aims to prove that Matrix homeservers
-can be lightweight and written in such a way that very few, if any, third-party
-libraries need to be pulled in.
-.Pp
-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 and router.
-.Pp
-The advantage of using a flat-file database instead of a real database is that
-your data remains in a format that is incredibly easy to digest. Backups are
-incredibly easy as well\(emjust
-.Xr tar 1
-up the data directory and you're good to go.
-.Sh 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 exaustive list
-of the project's goals, but it is a list of things that I want to prioritize,
-because other server implementations lack them.
-.Pp
-The user goals are as follows:
-.Bl -bullet
-.It
-To implement the latest Matrix specification as fully and completely as possible.
-All features defined by the specification should eventually be present in
-.Nm .
-.It
-To be as privacy-friendly as possible.
-.Nm
-should not store any information it does not absolutely need to function as a
-Matrix homeserver. While
-.Nm
-strives to be feature-complete, it should not implement anything not explicitly
-defined in the Matrix specification.
-.It
-To be a production-ready Matrix server capable of working in constrained environments,
-such as embedded devices, cheap VPSs, or a peer-to-peer device.
-.Nm
-should also work on traditional setups as well, and be able to handle a decent
-amount of users. It should work well for personal Matrix homeservers that also
-host a few friends and/or family members.
-.It
-To be easier to get up and running, and yet also be more configurable than 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.
-.El
-.Pp
-The developer goals are as follows:
-.Bl -bullet
-.It
-To have as few build and runtime dependencies as possible. It should be possible
-to compile and run
-.Nm
-on any POSIX operating system right out of the box. 
-.Nm
-should be fully statically-linked, so it can run under a
-.Xr chroot 3 .
-Furthermore, it should be possible to read all the documentation offline, and
-without any overly complicated tools. You'll notice that this documentation is
-a collection of
-.Xr man 1
-pages, not HTML or Markdown, to remove the dependency on a browser or Markdown
-parser. Any Unix-like system has a manual page viewer, which makes the
-documentation more accessible, even on remote systems that have no graphical
-interface to read the documentation. This ensures that you can read the
-documentation for the installed version of
-.Nm
-without having to go online.
-.It
-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, but the point is that
-the workflow should require fairly standardized and simple tools.
-.It
-To write clean, elegant, well-tested, 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 because I want to learn how Matrix works,
-make it more accessible, and potentially teach others a little bit along the way.
-.It
-To foster a welcoming community. Many big communities such as Linux and OpenBSD
-have hostile leaders.
-.Nm
-shouldn't have a hostile leader. I want to be as understanding as I can, and talk
-through issues politely and in a civil manner. If I'm failing in this way, don't
-be afraid to call me out!
-.El
-.Sh SEE ALSO
-.Xr telodendria 8 ,
-.Xr telodendria.conf 5 ,
-.Xr td 1
-.Sh STANDARDS
-The installed version of
-.Nm
-conforms to the latest Matrix specification available at the time
-of its release.
-.Sh HISTORY
-.Pp
-.Nm
-was started in early July of 2022. For a change log of this
-project, see
-.Xr telodendria-changelog 7 .
-.Sh AUTHORS
-.Nm
-was started by and is almost exclusively developed by
-Jordan Bancino <@jordan:bancino.net>. Contributions to the code,
-website, documentation, or other components of this project have
-been made by various open source developers.
-.Sh LICENSE
-All of the code and documentation for
-.Nm
-is licensed under a modified MIT license. Please consult the
-.Pa LICENSE.txt
-file for the actual license text. The
-.Nm
-license text differs from the MIT license in the following ways:
-.Bl -bullet
-.It
-Where the MIT license states that the copyright notice and permission
-notice shall be included in all copies or
-.Pa substantial
-portions of the software, the
-.Nm
-license requires the copyright notice and permission notice be included
-with
-.Pa all
-portions, regardless of the size, of the software by omitting the word
-.Pa substantial .
-.El
-.Pp
-The
-.Nm
-logo in all forms, including the ASCII representation, belongs solely
-to the
-.Nm
-project. It must only be used to represent the official
-.Nm
-project, and may only appear in official
-.Nm
-media. If
-.Nm
-is forked, the logo must be removed completely from the project, and
-optionally replaced with a different one. The logo may not be modified
-in any way or for any purpose.

man/man8/telodendria.8

@@ -1,73 +0,0 @@
-.Dd $Mdocdate: April 30 2023 $
-.Dt TELODENDRIA 8
-.Os Telodendria Project
-.Sh NAME
-.Nm telodendria
-.Nd Daemon command line manual for Telodendria administrators.
-.Sh SYNOPSIS
-.Nm
-.Op Fl nVv
-.Op Fl f Ar file
-.Sh DESCRIPTION
-.Nm
-is a Matrix homeserver written entirely from scratch in ANSI C.
-It is designed to be lightweight and simple, yet functional.
-.sp
-The options are as follows:
-.Bl -tag -width Ds
-.It Fl d Ar dir
-Specify the data directory to use. All persistant storage that
-Telodendria requires is saved and loaded here.
-.It Fl V
-Only print the version information header and then quit.
-.It Fl v
-Verbose mode. This overrides the configuration file and sets the
-log level to
-.Em LOG_DEBUG .
-It also enables extra logging of memory operations, which can
-be useful for debugging.
-.El
-.Sh ENVIRONMENT
-.Nm
-does not read any environment variables. All configuration should
-be done via the configuration file.
-.Sh FILES
-Just the data directory. Telodendria does not read any files outside
-of its data directory, with the exception of TLS files if configured.
-.Sh SIGNALS
-Telodendria recognizes a number of signals that it handles:
-.Bl -tag -width Ds
-.It PIPE
-This signal is ignored, because all I/O errors should be handled
-properly.
-.It USR1
-Perform a soft restart by shutting down the HTTP servers and resetting
-all program state. However, the daemon process does not exit.
-.It TERM
-Perform a clean shutdown after all existing connections are closed.
-.It INT
-Perform a clean shutdown after all existing connections are closed.
-.El
-.Pp
-Any other signals are not explicitly handled, so they have the
-default behavior defined by the operating system.
-.Sh EXIT STATUS
-.Nm
-exits with a non-0 exit code if the configuration file is invalid, or
-one or more required paths is inaccessible.
-.Nm
-will print an error to the log and then terminate abnormally.
-.Pp
-.Nm
-exits with a code of 0 if the configuration file is valid, all
-paths and files required are accessible, and the HTTP listener starts
-as intended. If
-.Nm
-is sent a signal that it catches after it begins servicing requests, it
-will still exit with a code of 0 after it safely shuts down, because
-the bootstrap process completed successfully, and by all accounts,
-it ran normally and exitted normally.
-.Sh SEE ALSO
-.Xr telodendria 7 ,
-.Xr telodendria-setup 7 ,
-.Xr telodendria-admin 7

src/Routes/RouteUserProfile.c

@@ -172,7 +172,10 @@ ROUTE_IMPL(RouteUserProfile, path, argp)
     }
 finish:
     ConfigUnlock(config);
-    Free(username);
+
+    /* Username is handled by the router, freeing it *will* cause issues
+     * (see #33). I honestly don't know how it didn't come to bite us sooner. 
+    Free(username); */
     Free(entry);
     UserIdFree(userId);
     UserUnlock(user);

tools/bin/send-patch

@@ -1,167 +0,0 @@
-#!/usr/bin/env sh
-#
-# send-patch: "The Telodendria Patch Sender"
-#
-# This is a simple script for posting patch files to
-# a single room(generally the Telodendria patch room.)
-
-. "$(pwd)/tools/lib/common.sh"
-
-# Path to the patch to send.
-PATCHFILE="$1"
-
-# Tries to decompose the name and the HS from an MXID using
-# sed.
-UR_NAME="$(echo "$MXID" | sed "s/\@\(.*\)\:\(.*\)/\1/")"
-HS_NAME="$(echo "$MXID" | sed "s/\@\(.*\)\:\(.*\)/\2/")"
-
-# Prompts the user for a password, while disabling echo-ing.
-readpwd() {
-    printf "$1"
-    stty -echo -ctlecho
-    read -r "$2"
-    echo
-    stty echo ctlecho
-}
-
-# Makes an HTTP request, setting the RETURN variable for the
-# actual reply from the server and the ERROR_CODE variable
-# for a HTTP error code.
-request() {
-    RETURN=$(http -i "$@" 2>/dev/null)
-    ERROR_CODE=$(echo "$RETURN" | head -n1 | awk '{print $2}')
-    RETURN=$(echo "$RETURN" | sed '1,/^[[:space:]]*$/d')
-}
-
-# Prompts user to login and gives out an access token to use
-# in the ACCESS_TOKEN variable
-matrix_login() {
-    # Check authentication methods
-    echo "Checking authentication methods..."
-    request "$HS_BASE/_matrix/client/v3/login"
-    AUTH_METHODS=$RETURN
-    if [ $ERROR_CODE -ne 200 ]; then
-        echo "Homeserver does not support login."
-        exit 1
-    fi
-    if ! echo "$AUTH_METHODS" | grep "m.login.password" >/dev/null; then
-        echo "Homeserver does not support password authentication."
-        exit 1
-    fi
-    # Homeserver does support password authentication, so request
-    # them one.
-    if [ -z "$MXPW" ]; then
-        readpwd "Enter your Matrix password: " MXPW
-    fi
-    # Tries to login using the "Telodendria Patch Script" device
-    # name
-    JSON=$(
-        printf '{'
-        printf '  "identifier": {'
-        printf '    "type": "m.id.user",'
-        printf '    "user": %s' "$(json -e $UR_NAME)"
-        printf '  },'
-        printf '  "initial_device_display_name": "Telodendria Patch Script",'
-        printf '  "type": "m.login.password",'
-        printf '  "password": %s' "$(json -e "$MXPW")"
-        printf '}'
-    )
-    request -X POST -d "$JSON" $HS_BASE/_matrix/client/v3/login
-    LOGIN="$RETURN"
-    if [ $ERROR_CODE -ne 200 ]; then
-        echo "Login failed."
-        echo "$RETURN"
-        exit 1
-    fi
-    ACCESS_TOKEN=$(echo "$LOGIN" | json -s "access_token->@decode")
-}
-
-# Logs out of Matrix using the ACFESS_TOKEN environment variable
-matrix_logout() {
-    if [ -z "$ACCESS_TOKEN" ]; then
-        echo "No access token"
-        exit 1
-    fi
-    request -X POST -H "Authorization: Bearer $ACCESS_TOKEN" "$HS_BASE/_matrix/client/v3/logout"
-    LOGOUT=$RETURN
-    if [ $ERROR_CODE -ne 200 ]; then
-        echo "Logout failed."
-        echo "$RETURN"
-        exit 1
-    fi
-    echo "Logged out."
-}
-
-send_patch() {
-    if [ -z "$ACCESS_TOKEN" ]; then
-        matrix_login
-        DO_LOGOUT=1
-    fi
-    # We are sucessfully logged in as our user, now let's
-    # try to upload and post our patch
-    echo "$PATCHFILE"
-    request -X POST \
-        -H "Content-Type: text/x-patch" \
-        -H "Authorization: Bearer $ACCESS_TOKEN" \
-        -d "@$PATCHFILE" \
-        "$HS_BASE/_matrix/media/v3/upload"
-    MXCID=$RETURN
-    if [ $ERROR_CODE -ne 200 ]; then
-        echo "Upload failed."
-        echo "$RETURN"
-        matrix_logout
-        exit 1
-    fi
-    MXCID=$(echo "$MXCID" | json -s "content_uri->@decode")
-    echo "MXC ID: $MXCID"
-    JSON=$(
-        base=$(basename "$PATCHFILE")
-        printf '{'
-        printf '  "body": %s,' "$(json -e $base)"
-        printf '  "filename": %s,' "$(json -e $base)"
-        printf '  "info": {'
-        printf '    "mimetype": "text/x-patch",'
-        printf '    "size": %d' $(wc -c "$PATCHFILE" | awk '{print $1}')
-        printf '  },'
-        printf '  "msgtype": "m.file",'
-        printf '  "url": %s' "$(json -e $MXCID)"
-        printf '}'
-    )
-    http -X PUT -d "$JSON" -H "Authorization: Bearer $ACCESS_TOKEN" \
-        "$HS_BASE/_matrix/client/v3/rooms/$PATCHES_ROOM/send/m.room.message/$(date +%s)" \
-        2>/dev/null >/dev/null && echo "Patch sent."
-
-    # Log out if we generated an access token
-    if [ "$DO_LOGOUT" -eq "1" ]; then
-        matrix_logout
-    fi
-}
-
-# Check if the patch file is valid.
-if [ "$(basename "$PATCHFILE" .patch)" = "$PATCHFILE" ] || [ ! -f "$PATCHFILE" ]; then
-    echo "Format: $0 file.patch"
-    exit 1
-fi
-echo "Sending file '$PATCHFILE'"
-echo "Checking homeserver's real address using .well-known..."
-request "https://$HS_NAME/.well-known/matrix/client"
-case "$ERROR_CODE" in
-    "200")
-        WELL_KNOWN=$RETURN
-        if [ -z "$WELL_KNOWN" ]; then
-            echo "well-known test returned 200 but no correct input was given."
-            exit 1
-        fi
-        # well-known entry is correct, we can now store our base endpoint
-        HS_BASE=$(printf "$WELL_KNOWN" | json -s "m.homeserver->base_url->@decode") && send_patch
-        ;;
-    *)
-        echo "$ERROR_CODE"
-
-        echo "well-known test failed."
-        printf "Please enter your homeserver base URL: "
-        read -r HS_BASE
-        echo
-        send_patch
-        ;;
-esac

tools/bin/tp

@@ -1,148 +0,0 @@
-#!/usr/bin/env sh
-#
-# tp: "Telodendria Patch"
-#
-# This script is used to manage the patch queue.
-
-. "$(pwd)/tools/lib/common.sh"
-
-if [ -z "$TELODENDRIA_PUB" ]; then
-    echo "TELODENDRIA_PUB not set."
-    exit 1
-fi
-
-TP_DIR="$TELODENDRIA_PUB/patches"
-
-if [ ! -d "$TP_DIR" ]; then
-    echo "$TP_DIR does not exist."
-    exit 1
-fi
-
-matrix_send() {
-    msg="$1"
-    if [ ! -z "$msg" ]; then
-        (
-            printf '{'
-            printf '"body":'
-            json -e "$msg"
-            printf ',"formatted_body":'
-            json -e "$msg"
-            printf ',"format":"org.matrix.custom.html",'
-            printf '"msgtype":"m.text"'
-            printf '}'
-        ) > /tmp/tp-$$
-        http -X PUT -d @/tmp/tp-$$ "$HOMESERVER/client/v3/rooms/$PATCHES_ROOM/send/m.room.message/$(date +%s)?access_token=$ACCESS_TOKEN"
-        rm /tmp/tp-$$
-    fi
-}
-
-case "$1" in
-    "ingress")
-        timeline="/tmp/timeline.json"
-        http "$HOMESERVER/client/v3/sync?access_token=$ACCESS_TOKEN" |
-            json -s "rooms->join->${PATCHES_ROOM}->timeline" >"$timeline"
-
-        length=$(cat "$timeline" | json -s "events->@length")
-
-        i=0
-        while [ $i -lt $length ]; do
-            content=$(cat "$timeline" | json -s "events[$i]->content->^body->^formatted_body")
-            i=$((i + 1))
-
-            type=$(echo "$content" | json -s "msgtype->@decode")
-            if [ "$type" != "m.file" ]; then
-                continue
-            fi
-
-            size=$(echo "$content" | json -s "info->size")
-            if [ "$size" -gt "$MAX_SIZE" ]; then
-                continue
-            fi
-
-            file=$(echo "$content" | json -s "filename->@decode")
-            ext=$(echo "$file" | rev | cut -d '.' -f 1 | rev)
-            if [ "$ext" != "patch" ]; then
-                continue
-            fi
-
-            url=$(echo "$content" | json -s "url->@decode")
-            id=$(echo "$url" | cut -d '/' -f 4)
-
-            if [ -f "$TP_DIR/ingress/$id.patch" ]; then
-                continue
-            fi
-
-            server=$(echo "$url" | cut -d '/' -f 3)
-
-            if ! http "$HOMESERVER/media/v3/download/$server/$id" > "$TP_DIR/ingress/$id.patch"; then
-                rm "$TP_DIR/ingress/$id.patch"
-                echo "Failed to fetch mxc://$server/$id."
-                echo "Will try again next time."
-                continue
-            fi
-
-            count=$(cat "$TP_DIR/count.txt")
-            count=$((count + 1))
-            cp "$TP_DIR/ingress/$id.patch" "$TP_DIR/p/$count.patch"
-            (
-                cd "$TP_DIR/queued"
-                ln -s "../p/$count.patch" "$count.patch"
-            )
-
-            echo "$count" >"$TP_DIR/count.txt"
-
-            matrix_send "Queued <code>$file</code> as <a href=\"https://telodendria.io/patches/p/$count.patch\">#$count</a>" >/dev/null
-        done
-        ;;
-    "queue")
-        find "$TP_DIR/queued" -name '*.patch' | while IFS= read -r patch; do
-            n=$(basename "$patch" .patch)
-            echo "Patch #$n:"
-            head -n3 "$patch"
-            echo
-        done
-        ;;
-    "view")
-        if [ -f "$TP_DIR/queued/$2.patch" ]; then
-            less "$TP_DIR/queued/$2.patch"
-        else
-            echo "Patch #$2 doesn't exist in the queue."
-            exit 1
-        fi
-        ;;
-    "apply")
-        if [ -f "$TP_DIR/queued/$2.patch" ]; then
-            patch <"$TP_DIR/queued/$2.patch"
-        else
-            echo "Patch #$2 doesn't exist in the queue."
-            exit 1
-        fi
-        ;;
-    "reverse")
-        if [ -f "$TP_DIR/queued/$2.patch" ]; then
-            patch -R <"$TP_DIR/queued/$2.patch"
-        else
-            echo "Patch #$2 doesn't exist in the queue."
-            exit 1
-        fi
-        ;;
-    "accept" | "reject")
-        if [ -f "$TP_DIR/queued/$2.patch" ]; then
-            mv "$TP_DIR/queued/$2.patch" "$TP_DIR/${1}ed/$2.patch"
-            msg="Patch <a href=\"https://telodendria.io/patches/p/$2.patch\">#$2</a> was marked as ${1}ed."
-            msgFile="/tmp/patchmsg-$(date +%s).txt"
-            $EDITOR "$msgFile"
-            if [ -f "$msgFile" ]; then
-                msg="$msg<br><blockquote>$(cat $msgFile)<br>&mdash;$DISPLAY_NAME ($MXID)</blockquote>"
-            fi
-            matrix_send "$msg"
-        else
-            echo "Patch #$2 doesn't exist in the queue."
-            exit 1
-        fi
-        ;;
-    *)
-        echo "No action specified."
-        exit 1
-        ;;
-esac