forked from Telodendria/Telodendria
Compare commits
No commits in common. "5ad199353b909800a245eb61bbbfd88bad7f59f6" and "d9217946f38ee5f23a3e5b33b558789eff94fa74" have entirely different histories.
5ad199353b
...
d9217946f3
14 changed files with 815 additions and 741 deletions
137
README.md
137
README.md
|
|
@ -1,136 +1,7 @@
|
|||
<p align="center"><img src="https://telodendria.io/assets/Telodendria-500x500.png"></p>
|
||||
<h1 align="center">Telodendria</h1>
|
||||
# [Telodendria](https://telodendria.io)
|
||||
|
||||
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.
|
||||
**Telodendria** is an open source Matrix homeserver implementation written from scratch in ANSI C and designed to be lightweight and simple, yet functional.
|
||||
|
||||
> **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—and should—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 →](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.
|
||||
**Important:** This project is not developed on GitHub or CVS anymore, but instead on a dedicated [Gitea forge](https://git.telodendria.io/Telodendria/telodendria).
|
||||
|
||||
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.
|
||||
|
|
|
|||
64
README.txt
Normal file
64
README.txt
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
.= -=-
|
||||
:.:+ .=:.
|
||||
.=+-==. :.
|
||||
.+- =.
|
||||
.+ :+.
|
||||
==. -+:
|
||||
=++==--:: =+.
|
||||
.:::--=+=: :+=
|
||||
:==. -=:
|
||||
===----=-. ... :+.
|
||||
:==+=======: .-+-::-+-=+=
|
||||
.==*%#======= :+- ..
|
||||
.:--=-===+=========-. :+:
|
||||
.=++=::..:============-+=-=-
|
||||
:+=: :=+-: .-=========-. .
|
||||
=+++: .:=+-: .:--. .--:==:
|
||||
::---:.. :=+: ==
|
||||
++. .+-
|
||||
=+ .+- ...:
|
||||
+- -+-:-+=::+:
|
||||
:=-....:-=: .--: =-
|
||||
-++=:.:::..
|
||||
|
||||
=======================================================
|
||||
|_ _|__| | ___ __| | ___ _ __ __| |_ __(_) __ _
|
||||
| |/ _ \ |/ _ \ / _` |/ _ \ '_ \ / _` | '__| |/ _` |
|
||||
| | __/ | (_) | (_| | __/ | | | (_| | | | | (_| |
|
||||
|_|\___|_|\___/ \__,_|\___|_| |_|\__,_|_| |_|\__,_|
|
||||
=======================================================
|
||||
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
|
||||
|
||||
|
|
@ -1,245 +0,0 @@
|
|||
# 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.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!
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
# 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.
|
||||
|
||||
## 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.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)
|
||||
|
||||
|
|
@ -1,94 +0,0 @@
|
|||
## 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.
|
||||
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
# 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.
|
||||
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# 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
|
||||
|
||||
**TODO:** Update this section before #19 is closed.
|
||||
|
|
@ -1,60 +0,0 @@
|
|||
# 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.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.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.
|
||||
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
# 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.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.
|
||||
119
man/man7/porting.7
Normal file
119
man/man7/porting.7
Normal file
|
|
@ -0,0 +1,119 @@
|
|||
.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
|
||||
480
man/man7/telodendria-changelog.7
Normal file
480
man/man7/telodendria-changelog.7
Normal file
|
|
@ -0,0 +1,480 @@
|
|||
.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!
|
||||
75
man/man7/telodendria-setup.7
Normal file
75
man/man7/telodendria-setup.7
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
.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
|
||||
73
man/man8/telodendria.8
Normal file
73
man/man8/telodendria.8
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
.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
|
||||
Loading…
Reference in a new issue