plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Move man pages into a proper man directory

Browse source
This commit is contained in:
Jordan Bancino 2022-09-30 19:11:44 -04:00
parent cfcef45c00
commit 2d6b80a26e
12 changed files with 1231 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
TODO.txt
View file

@ -75,7 +75,6 @@ Phase 4:
[ ] Create an OpenBSD package and get it submitted to ports
[ ] Add relayd examples to contrib/
[ ] Create a command line tool to manage Telodendria
[ ] Configuration file generation
[ ] User management
[ ] Room management
[ ] Migrate from Synapse or Dendrite, whichever is more mainstream by the time we get here
@ -100,7 +99,24 @@ Documentation
[x] Convert documentation to man pages
[x] Clean up dark mode in man page CSS (links)
[x] Synopsis table should not be styled
[ ] Internal API docs
[x] Make available on MANPATH in tools/env.sh
[~] Internal API docs
[x] Array
[x] Base64
[ ] CanonicalJson
[ ] Config
[ ] Constants
[ ] HashMap
[ ] Http
[ ] HttpServer
[ ] Json
[ ] Log
[ ] Matrix
[ ] NonPosix
[ ] Queue
[ ] Routes
[ ] TelodendriaConfig
[ ] Util
[ ] Add onboarding documentation
[ ] Building from source

1
man/.cvsignore Normal file
View file

@ -0,0 +1 @@
mandoc.db

114
man/man3/Array.3 Normal file
View file

@ -0,0 +1,114 @@
.Dd $Mdocdate: September 30 2022 $
.Dt ARRAY 3
.Os Telodendria Project
.Sh NAME
.Nm Array
.Nd A simple dynamic array data structure.
.Sh SYNOPSIS
.In Array.h
.Ft Array *
.Fn ArrayCreate "void"
.Ft void
.Fn ArrayFree "Array *"
.Ft int
.Fn ArrayTrim "Array *"
.Ft size_t
.Fn ArraySize "Array *"
.Ft void *
.Fn ArrayGet "Array *" "size_t"
.Ft int
.Fn ArrayInsert "Array *" "void *" "size_t"
.Ft int
.Fn ArrayAdd "Array *" "void *"
.Ft void *
.Fn ArrayDelete "Array *" "size_t"
.Ft void
.Fn ArraySort "Array *" "int (*) (void *, void *)"
.Sh DESCRIPTION
These functions implement a simple array data structure that
is automatically resized as necessary when new values are added.
This implementation does not actually store the values of the
items in it; it only stores pointers to the data. As such, you will
still have to manually maintain all your data. The advantage of this
is that these functions don't have to copy data, and thus don't care
how big the data is. Furthermore, arbitrary data can be stored in the
array.
.Pp
This array implementation is optimized for storage space and appending.
Deletions are expensive in that all the items of the list above a deletion
are moved down to fill the hole where the deletion occurred. Insertions are
also expensive in that all the elements above the given index must be shifted
up to make room for the new element.
.Pp
Due to these design choices, this array implementation is best suited to
linear writing, and then linear or random reading.
.Pp
These functions operate on an array structure which is opaque to the
caller.
.Pp
.Fn ArrayCreate
and
.Fn ArrayFree
allocate and deallocate an array, respectively.
Note that
.Fn ArrayFree
does not free any of the values stored in the array; it is the caller's
job to manage the memory for each item. Typically, the caller would
iterate over all the items in the array and free them before freeing
the array.
.Fn ArrayTrim
reduces the amount of unused memory by calling
.Xr realloc 3
on the internal structure to perfectly fit the elements in the array. It
is intended to be used by functions that return relatively read-only arrays
that will be long-lived.
.Pp
.Fn ArrayInsert
and
.Fn ArrayDelete
are the main functions used to modify the array.
.Fn ArrayAdd
is a convenience method that simply appends a value to the end of the
array. It uses
.Fn ArrayInsert .
The array can also be sorted by using
.Fn ArraySort ,
which takes a pointer to a function that compares elements. The function
should take two
.Dv void
pointers as parameters, and return an integer. The return value indicates
to the algorithm how the elements relate to each other. A return value of
0 indicates the elements are identical. A return value greater than 0
indicates that the first item is "bigger" than the second item and should
thus appear after it in the array, and a value less than zero indicates
the opposite: the second element should appear after the first in the array.
.Pp
.Fn ArrayGet
is used to get the element at the specified index.
.Sh RETURN VALUES
.Fn ArrayCreate
returns a pointer on the heap to a newly allocated array structure, or
.Dv NULL
if the allocation fails.
.Pp
.Fn ArrayGet
and
.Fn ArrayDelete
return pointers to values that were put into the array, or
.Dv NULL
if the provided array is
.Dv NULL
or the provided index was out of bounds.
.Fn ArrayDelete
returns the element at the specified index after removing it so that
it can be properly handled by the caller.
.Pp
.Fn ArrayTrim ,
.Fn ArrayInsert ,
and
.Fn ArrayAdd
return a boolean value indicating their status. They return a value of zero
on failure, and a non-zero value on success.
.Sh SEE ALSO
.Xr HashMap 3 ,
.Xr Queue 3

81
man/man3/Base64.3 Normal file
View file

@ -0,0 +1,81 @@
.Dd $Mdocdate: September 30 2022 $
.Dt BASE64 3
.Os Telodendria Project
.Sh NAME
.Nm Base64
.Nd A simple base64 encoder/decoder with "unpadded base64" support.
.Sh SYNOPSIS
.In Base64.h
.Ft size_t
.Fn Base64EncodedSize "size_t"
.Ft size_t
.Fn Base64DecodedSize "const char *" "size_t"
.Ft char *
.Fn Base64Encode "const char *" "size_t"
.Ft char *
.Fn Base64Decode "const char *" "size_t"
.Ft void
.Fn Base64Unpad "char *" "size_t"
.Ft int
.Fn Base64Pad "char **" "size_t"
.Sh DESCRIPTION
This is an efficient yet simple base64 encoding and decoding
library that supports regular base64, as well as the Matrix
specification's extension to base64, called "unpadded base64."
.Nm provides the ability to convert between the two, instead of
just implementing "unpadded base64."
.Pp
.Fn Base64EncodedSize
and
.Fn Base64DecodedSize
compute the amount of characters needed to store an encoded or
decoded message, respectively. Both functions take the size of
the message being encoded or decoded, but
.Fn Base64DecodedSize
also takes a pointer to an encoded string, because a few bytes of
the string need to be read in order to compute the size.
.Pp
.Fn Base64Encode
and
.Fn Base64Decode
do the actual work of encoding and decoding base64 data. They both
take a string and its length.
.Pp
.Fn Base64Unpad
and
.Fn Base64Pad
are used to implement Matrix unpadded base64.
.Fn Base64Unpad
takes a valid base64 string and strips off the trailing equal signs,
as per the specification.
.Fn Base64Pad
does the opposite; it takes an unpadded base64 input string, and pads
it with equal signs as necessary, so that it can be properly decoded
with
.Fn Base64Decode
if necessary. However, the Matrix specification envisons unpadded base64
as opaque; that is, once it's encoded, it never needs to be decoded.
In practice, a homeserver might need to decode an unpadded base64 string.
.Sh RETURN VALUES
.Fn Base64EncodedSize
and
.Fn Base64DecodedSize
simply return unsigned integers representing a number of bytes generated
from a simple computation.
.Pp
.Fn Base64Encode
and
.Fn Base64Decode
return pointers to new strings, allocated on the heap, or
.Dv NULL
if a heap allocation fails. These pointers must be
.Xr free 3 -ed
at some point when they are no longer needed.
.Pp
.Fn Base64Unpad
modifies the passed string in-place. It thus has no return value, because
it cannot fail. If the passed pointer is invalid, the behavior is undefined.
.Fn Base64Pad
returns a boolean value indicating whether the pad operation was successful.
In practice, this function will only fail if a bigger string is necessary, but
could not be automatically allocated on the heap.

190
man/man5/telodendria.conf.5 Normal file
View file

@ -0,0 +1,190 @@
.Dd $Mdocdate: September 30 2022 $
.Dt TELODENDRIA.CONF 5
.Os Telodendria Project
.Sh NAME
.Nm telodendria.conf
.Nd Configuration file for Telodendria
.Sh DESCRIPTION
.Nm
is the configuration file for the Telodendria homeserver,
.Xr telodendria 8 .
Telodendria is designed to be extremely configurable. As such,
it has a fairly extensive configuration file. The configuration
file can be passed to the Telodendria binary with the
.Sy -f
option, and is typically located at
.Pa /etc/telodendria.conf
.sp
.Nm
uses OpenBSD-style syntax, though it is a little more rigid in its
parser. All values must be surrounded by quotes, and each directive
must be ended with a semicolon.
.Sh MACROS
Macros can be defined that will later be expanded in context.
Macro names must start with a letter, digit, or underscore, and may
contain only those characters. Macros are not expanded inside quotes.
.sp
For example:
.Bd -literal -offset indent
macro1 = "value1";
directive $macro1;
.Ed
.Sh GLOBAL OPTIONS
Here are the settings that can be set globally:
.Bl -tag -width Ds
.It Ic listen Ar port
The port to listen on. Telodendria will bind to all interfaces, but it
is recommended to configure your firewall so that it only listens on
localhost, and then configure a reverse proxy such as
.Xr relayd 8
in front of it, because Telodendria does not implement TLS. Note that
Telodendria doesn't provide multiple ports for the various services it
offers. ALl APIs are made available over the same port, so care should
be taken in
.Xr relayd.conf 5
to ensure that only the public Matrix API paths are made available over
the internet.
.Ar port
should be a decimal port number. This directive is entirely optional. If
it is omitted, then Telodendria will listen on port 8008 by default.
.It Ic server-name 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 base-url 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 identity-server Ar url
The identity server that clients should use to perform identity lookups.
.Pp
.Ar url
follows the same rules as
.Ic base-url .
.Pp
This directive is optional. If it is not specified, it is automatically
set to be the same as the base URL.
.It Ic chroot Ar directory
Change the root directory to the specified directory as soon as possible.
Note that all other paths and files specified in
.Nm
must be accessible relative from this directory. This directive only
takes effect if Telodendria is running as root. If it isn't, then a
warning is printed to the log, and no
.Xr chroot 2
call is made. In that case, Telodendria will still change into the
specified directory, so that the other paths referenced can be made
relative to this one. This directive is required. It is expected that
the homeserver data and logs will be stored in a subdirectory of this one.
.It Ic id Ar uid Ar gid
The effective UNIX user and group to drop to after binding to the socket
and changing the filesystem root. This only works if Telodendria is
running as the root user, and is used as a security mechanism. If 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
required, even if Telodendria is unable to switch to the given user and
group. It should be used as a sanity check to make sure the permissions are
working properly.
.It Ic data-dir Ar directory
The data directory into which Telodendria will write all user and event
information. Telodendria doesn't use a database like other Matrix homeserver
implementations; it uses a flat-file directory structure, similar to how an
SMTP server uses Maildirs to deliver email. This directive is required.
.Ar directory
should be a path relative to the
.Ic chroot
directory. Don't depend on the
.Ic chroot
option working, because there may be legitimate cases when Telodendria will
not be started as root, thus causing the chroot to fail.
.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 aset 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 file|stdout
The log configuration. Telodendria uses its own logging facility, which can output to
either standard output or a file. A number of child directives can be added to this
directive to customize the log output:
.Bl -tag -width Ds
.It Ic level Ar error|warning|task|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 task
shows tasks, 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 .
.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.
.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.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/telodendria.conf
The default
.Xr telodendria 8
configuration file.
.It Pa /var/telodendria
The recommended chroot directory.
.El
.Sh EXAMPLES
Please consult the default
.Nm
that ships with Telodendria for a complete example. If you installed Telodendria
as a package, then the example should be located at the default location. If you
are building from source, you can find the default config in the
.Pa contrib/
directory.
.Sh SEE ALSO
.Xr telodendria 8

252
man/man7/contributing.7 Normal file
View file

@ -0,0 +1,252 @@
.Dd $Mdocdate: September 30 2022 $
.Dt CONTRIBUTING 7
.Os Telodendria Project
.Sh NAME
.Nm contributing
.Nd Guide to contributing to Telodendria
.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 8 ,
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 8 ,
but the information there can be modifed as necessary. Consult the manual
for
.Xr td 8
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, as noted in
.Xr telodendria 7 ,
so it can be discussed and reviewed by the community.
.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.

248
man/man7/telodendria.7 Normal file
View file

@ -0,0 +1,248 @@
.Dd $Mdocdate: September 30 2022 $
.Dt TELODENDRIA 7
.Os Telodendria Project
.Sh NAME
.Nm Telodendria
.Nd The terminal branches of an axon.
.Sh DESCRIPTION
.Nm
is an open source Matrix homeserver written entirely from scratch in ANSI C.
It is designed to be lightweight and simple, yet functional.
.Pp
.Sy Note:
.Nm
is under
.Sy heavy
development. Please see
.Sx PROJECT STATUS .
.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(;);
l l.
#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-issues:bancino.net;Report bugs and issues.
#telodendria-patches:bancino.net;Submit code patches to the project.
.TE
.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 PROJECT STATUS
Telodendria is a very ambitious project. There's a lot that needs to happen yet
before it is usable. At the moment, there's nothing here that even remotely resembles
a Matrix homeserver. I'm still getting off the ground and building a foundation.
.Pp
But just because there's nothing here yet doesn't mean you should go away! I could
always use help, so you are more than welcome to help out if you want things to go
quicker. Please see the
.Xr contributing 7
page for details on how you can get involved. The CVS repository has a file called
.Pa TODO.txt ,
which contains a checklist of what has been done so far, and what's on the radar
to be done. You can take a look at it once you've checked out the source code.
If you'd like to help out, feel free to grab an item on the list that's not done
yet and start getting patches written. When you're done, enjoy the satisfaction
of crossing the item off the list yourself.
.Sh SEE ALSO
.Xr telodendria 8 ,
.Xr telodendria.conf 5 ,
.Xr td 8
.Sh STANDARDS
The installed version of
.Nm
conforms to the latest Matrix specification available at the time
of its release.
.Sh HISTORY
At this time,
.Nm
does not have any tagged releases because it is not yet functional
as a Matrix homeserver. Please checkout out
.Sx PROJECT STATUS
to see where things are currently at. When
.Nm
is mature enough to have a change log, it will go in this section.
.Sh AUTHORS
.Nm
was started by Jordan Bancino <@jordan:bancino.net>.
Contributions to the code, website, documentation, or other
components of
.Nm
were made by the following people:
.Bl -bullet
.It
Jonah Evans <@jonah:bancino.net>
.El
.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, however, 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.

238
man/man8/td.8 Normal file
View file

@ -0,0 +1,238 @@
.Dd $Mdocdate: September 30 2022 $
.Dt TD 8
.Os Telodendria Project
.Sh NAME
.Nm td
.Nd Telodendria build script
.Sh SYNOPSIS
.Nm
.Op recipe
.Sh DESCRIPTION
Telodendria uses a custom build script called
.Nm .
The
.Nm
script is not only a build script, however. It does all kinds of
cool things like format the source code, and generate patch files.
.Nm
is the only supported way to develop Telodendria.
.sp
I opted to write a custom build script instead of just writing a
.Pa Makefile
because I felt that there is really no way to make a truly portable
.Pa Makefile
that could do everything I wanted, with the flexibility I wanted. I
was doing a lot of research on the differences between the GNU and BSD
versions, and I felt it just wasn't worth trying to reconsile the two
when I could write a small and relatively robust POSIX shell script that
would run on both GNU and BSD systems without any problems. I also
think that shell scripts are a lot easier to read than complex
.Pa Makefiles.
They're easier to follow because they're not so cryptic.
.sp
The
.Nm
script is fairly intuitive. It operates somewhat like
.Xr make 1
in that it has recipes that you specify on the command line. To start
using it, just run the following command in the Telodendria source
directory:
.Bd -literal -offset indent
$ . tools/env.sh
.Ed
.sp
.Sy Note:
You will have to run the above command every time you start a new
terminal session, as nothing is persisted to your system. I believe in
non-invasive, fully self-contained tooling, so it is up to you to hook the
Telodendria tools into your environment as you see fit if you want them to
persist.
.sp
If you're going to be submitting patches, you should also configure a
.Pa .env
file in the project directory root, which
.Nm
will include automatically for you. See
.Em FILES
and
.Em ENVIRONMENT .
.sp
Telodendria is designed to be light enough that it can be built from source
on just about any operating system. It only requires an ANSI C compiler and a
standard POSIX environment. To build the Telodendria binary, run
.Nm
with no arguments, or with the
.Pa build
recipe. This will produce
.Pa build/telodendria ,
which you can then install to your system and run as a daemon.
.sp
A complete list of recipes is below. Note that you can run multiple recipes
with a single invocation of
.Nm ,
but recipes are run unconditionally; that is, even if a recipe fails, all the
following recipes are still executed.
.Bl -tag
.It build
Build the source code and generate the output binary. This is the default recipe,
which means it runs if no other recipes are specified. This recipe is incremental;
it only rebuilds sources that have been modifed since the last build, making
subsequent builds faster.
.It run
Run the build binary with the development configuration in the
.Pa contrib/
directory. This recipe is used for quick testing during development. It is
.Sy not
the recommended way to run Telodendria in a production environment; it should only
be used for development.
.It clean
Remove the
.Pa build/
directory and any ephemeral files in the source tree, such as
.Pa .orig
files. The build recipe does not place anything outside of
.Pa build/ ,
so you can usually just delete that directory and get the same effect.
.It format
Make sure the source code copyright headers are up to date, and format the code
using the system's
.Xr indent 1 .
This should be run before generating patch files, to ensure that the code follows
the project conventions. Note that the provided
.Pa .indent.pro
assumes an OpenBSD indent, which may cause the GNU implementation to choke. In
that case, don't send patch files with totally different formatting; just submit
the patch as-is and they will get formatted before committing.
.It test
Run all of the unit tests and report the results. It is highly recommended to
ensure that all the tests pass before submitting a patch, because patches that
break the tests are likely to be rejected.
.It site
Deploy the Telodendria website by generating HTML files for the documentation,
and copying them along with the front page to the specified web root. This is
used to deploy the official website, but it could be used to deploy a local
development site as necessary. See
.Em ENVIRONMENT .
.It release
Generate a release tarball, checksum and sign it, and push it to the web root.
See the relevant environment variables below.
.It patch
Generate a formatted patch file. The Telodendria project isn't super picky about
how patches look as long as they apply cleanly, but this recipe generates patches
in the format we like them, and is therefore recommended. It makes patches easy
to read. This recipe will use your configured editor to open your formatted patch
so you can review and edit it as necessary before sending it off.
.It diff
Generate a temporary preview patch that is opened in the system pager. This can
be used for quickly quickly previewing your changes and the patch file you'll
be creating.
.El
.sp
.Sh ENVIRONMENT
Any of the following environment variables are used in the build recipes.
They can all be specified in your shell when invoking
.Nm ,
or they can be placed in a
.Pa .env
file. For most of these variables, if you would like to append or prepend
to the default values, do so in the
.Pa .env
file, which is sourced after the defaults are set, allowing you to reference
the default values in your new value.
.Bl -tag
.It Ev CC
The C compiler to use. This defaults to
.Pa cc,
which is usually a symlink to your system's preferred compiler. If for some
reason you want to use a diferent compiler, do so with this environment
variable.
.It Ev CFLAGS
The compiler flags used to generate object files.
.Nm
comes with reasonable defaults that shouldn't need to be changed in most
scenarios, but if you do need to change the compiler flags, you can do
so with this environment variable.
.It Ev LDFLAGS
The compiler flags used to link the object files to create an output
binary.
.Nm
comes with reasonable defaults that shouldn't need to be changed in most
scenarios, but if you need to change the linker flags, you do so with this
environment variable.
.It Ev PROG
The name of the output binary. This defaults to
.Pa build/telodendria.
.It Ev DEFINES
Global preprocessor definitions to append to
.Ev CFLAGS.
This is just kept separate to keep things organized.
.It Ev INCLUDES
Header directories to make available. This is appended to
.Ev CFLAGS,
it is just kept separate to keep things organized.
.It Ev DEBUG
If set to "1", append some debug flags to
.Ev CFLAGS
and whipe out any
.Ev LDFLAGS
that awould cause the output binary to be optimized in any way. This also
depends "-debug" to
.Ev PROG .
.It Ev TELODENDRIA_VERSION
This variable does make its way into the output binary, but it is primarily
used for generating and publishing releases. This variable affects the
.Sy release
recipe.
.It Ev TELODENDRIA_PUB
The web root where the Telodendria website lives. This is where the site
is pushed to, and where generated releases go.
.It Ev PATCHSET
This variable restricts the files that
.Nm
operates on when generating patches or diffs. If you only want to generate
a diff or patch for a certain file, directory, or collection of files and
directories, set this variable to those files and directories, separated
by a space. You can mix files and directories as necessary.
.It Ev MXID
Your Matrix ID in standard format. This is used when generating patches,
so that you can be assigned credit for your patches, as well as be contacted
about your patches.
.Nm
will automatically deduce this from your system, but it will most
likely get it wrong. Please make sure you are reachable at this ID.
.It Ev DISPLAY_NAME
The display name you want to appear on your patches. This should probably
match your Matrix display name, although it doesn't necessarily have to.
.Nm
will deduce this from your system, and if you set it up properly, you may
not even have to set this variable. If
.Nm
gets it wrong, this allows you to override your display name.
.It Ev EDITOR
Your preferred editor for writing patch file descriptions. This can be a
GUI or terminal editor. If unset, this defaults to the system's
.Xr vi 1
editor.
.It Ev PAGER
Your preferred pager for previewing patches. If left unset, this defaults
to
.Xr less 1 .
.Sh FILES
.Bl -tag
.It Pa .env
An environment file that contains lines in the form of
.Pa VARIABLE=value
with environment variables to set in the
.Nm
script. See
.Em ENVIRONMENT .
Note that
.Nm
simply sources this file, which means that any shell code in it will be
executed each time
.Nm
is invoked.
.Sh EXIT STATUS
.Sh HISTORY
.Sh CAVEATS
.Sh BUGS

57
man/man8/telodendria.8 Normal file
View file

@ -0,0 +1,57 @@
.Dd $Mdocdate: September 30 2022 $
.Dt TELODENDRIA 8
.Os Telodendria Project
.Sh NAME
.Nm telodendria
.Nd Matrix homeserver daemon
.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 f Ar file
Specify an alternate configuration file. The default is
.Pa /etc/telodendria.conf .
.It Fl n
Configtest mode. Only check the configuration file for validity.
.It Fl V
Only print the version information header.
.It Fl v
Verbose mode. This overrides the configuration file and sets the
log level to
.Em LOG_DEBUG
.El
.Sh ENVIRONMENT
.Nm
does not read any environment variables. All configuration should
be done via the configuration file.
.Sh FILES
Just the configuration file and the data directory; see
.Xr telodendria.conf 5
for more details.
.El
.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.conf 5

40
site/index.html
View file

@ -16,20 +16,20 @@
<meta property="og:description"
content="Telodendria, a Matrix homeserver written in ANSI C.">
<link rel="stylesheet" href="style.css">
<link rel="stylesheet" href="/style.css">
<link rel="icon" href="assets/Telodendria-196x196.png">
<title>Telodendria | A Matrix Homeserver written in ANSI C.</title>
</head>
<body>
<img id="logo" src="assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
<img id="logo" src="/assets/Telodendria-500x500.png" alt="Telodendria Logo"/>
<h1 id="telodendria">Telodendria</h1>
<p>
<b>Telodendria:</b> The terminal branches of an axon.
</p>
<div class="msg-error">
<b><i>Note:</i></b> <b>Telodendria</b> is under <i>heavy</i> development.
Please see the <a href="telodendria.7.html#PROJECT_STATUS">Project Status</a>.
Please see the <a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a>.
</div>
<p>
<b>Telodendria</b> is an open source Matrix homeserver implementation written from
@ -159,7 +159,7 @@ Signify
<tr>
<td colspan="4" style="text-align: center;">
No downloads here yet. See the
<a href="telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
<a href="/man/man7/telodendria.7.html#PROJECT_STATUS">Project Status</a> for more
information.
</td>
</tr>
@ -175,23 +175,23 @@ on what <b>Telodendria</b> is, what its goals are, how to build the source,
configure it, as well as contribute to the project. The <code>man</code>
pages are also available online for convenience:
</p>
<ul>
<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction and project information, including licensing information</li>
<li><a href="telodendria.8.html">telodendria(8)</a> - Command line usage</li>
<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
<li><a href="contributing.7.html">contributing(7)</a> - Contributing guide</li>
<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
</ul>
<h2>Getting Support</h2>
<b>Telodendria</b> is designed to be fairly straightforward, but that
doesn't mean there won't be hiccups along the way. If you are struggling
to get <b>Telodendria</b> up and running, you're more than welcome to
reach out for support. Just join the
<code>#telodendria-general:bancino.net</code> Matrix channel. Before
you do though, make sure you're running the latest version of
<b>Telodendria</b> and you've thoroughly read through all the
relevant documentation.
<p>
User documentation:
</p>
<ul>
<li><a href="/man/man7/telodendria.7.html">telodendria(7)</a> - Introduction and project information, including project status and licensing information</li>
<li><a href="/man/man8/telodendria.8.html">telodendria(8)</a> - Command line usage</li>
<li><a href="/man/man5/telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
<li><a href="/man/man7/contributing.7.html">contributing(7)</a> - Contributing guide</li>
<li><a href="/man/man8/td.8.html">td(8)</a> - Build script and patch instructions</li>
</ul>
<p>
Developer documentation:
</p>
<ul>
<li><a href="/man/man3/Array.3.html">Array(3)</a> - Dynamic array structure</li>
<li><a href="/man/man3/Base64.3.html">Base64(3)</a> - Base64 encoder/decoder with unpadded support</li>
</ul>
<h2 id="resources">Resources</h2>
<ul>
<li><a target="_blank" href="/pub">Old <b>Telodendria</b> Versions</a></li>

10
tools/bin/td
View file

@ -164,13 +164,15 @@ recipe_site() {
exit 1
fi
# In the future, this might do more.
cp -v site/* "$TELODENDRIA_PUB/"
find docs/ -name '*.[1-9]' | while IFS= read -r man; do
find man/ -name '*.[1-9]' | while IFS= read -r man; do
dir=$(dirname "$man")
html=$(basename "$man")
mandoc -Thtml -O style=style.css "$man" > "$TELODENDRIA_PUB/$html.html"
echo "$man -> $TELODENDRIA_PUB/$html.html"
mkdir -p "$TELODENDRIA_PUB/$dir/"
mandoc -Thtml -O style=/style.css "$man" > "$TELODENDRIA_PUB/$dir/$html.html"
echo "$man -> $TELODENDRIA_PUB/$dir/$html.html"
done
}

7
tools/env.sh
View file

@ -4,4 +4,9 @@ find tools/bin -type f | while IFS= read -r tool; do
chmod +x "$tool"
done
PATH="$(pwd)/tools/bin:$PATH"
makewhatis "$(pwd)/man"
export PATH="$(pwd)/tools/bin:$PATH"
export MANPATH="$(pwd)/man:$MANPATH"
PS1="(td) $PS1"