From c0ecff11cbcf9d73c457516a85bc336e24b9156b Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 30 Sep 2022 19:14:19 -0400 Subject: [PATCH] Remove old docs --- docs/Array.3 | 114 ------------------ docs/Base64.3 | 81 ------------- docs/contributing.7 | 252 ---------------------------------------- docs/td.8 | 238 ------------------------------------- docs/telodendria.7 | 241 -------------------------------------- docs/telodendria.8 | 57 --------- docs/telodendria.conf.5 | 190 ------------------------------ 7 files changed, 1173 deletions(-) delete mode 100644 docs/Array.3 delete mode 100644 docs/Base64.3 delete mode 100644 docs/contributing.7 delete mode 100644 docs/td.8 delete mode 100644 docs/telodendria.7 delete mode 100644 docs/telodendria.8 delete mode 100644 docs/telodendria.conf.5 diff --git a/docs/Array.3 b/docs/Array.3 deleted file mode 100644 index c9262ce..0000000 --- a/docs/Array.3 +++ /dev/null @@ -1,114 +0,0 @@ -.Dd $Mdocdate: September 27 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 diff --git a/docs/Base64.3 b/docs/Base64.3 deleted file mode 100644 index 986bd45..0000000 --- a/docs/Base64.3 +++ /dev/null @@ -1,81 +0,0 @@ -.Dd $Mdocdate: September 27 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. diff --git a/docs/contributing.7 b/docs/contributing.7 deleted file mode 100644 index 1291214..0000000 --- a/docs/contributing.7 +++ /dev/null @@ -1,252 +0,0 @@ -.Dd $Mdocdate: September 23 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. diff --git a/docs/td.8 b/docs/td.8 deleted file mode 100644 index 9cef1d9..0000000 --- a/docs/td.8 +++ /dev/null @@ -1,238 +0,0 @@ -.Dd $Mdocdate: September 23 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 diff --git a/docs/telodendria.7 b/docs/telodendria.7 deleted file mode 100644 index 066af37..0000000 --- a/docs/telodendria.7 +++ /dev/null @@ -1,241 +0,0 @@ -.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. -.sp -.Sy Note: -.Nm -is under -.Sy heavy -development. Please see -.Sx PROJECT STATUS . -.sp -.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 -.sp -.Nm -is on Matrix! Check out the official Matrix rooms: -.sp -.TS -box tab(;); -l l. -#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 -.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. -.sp -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. -.sp -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. -.sp -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 -.sp -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. -.sp -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 -.sp -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. diff --git a/docs/telodendria.8 b/docs/telodendria.8 deleted file mode 100644 index 52cf2ab..0000000 --- a/docs/telodendria.8 +++ /dev/null @@ -1,57 +0,0 @@ -.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 diff --git a/docs/telodendria.conf.5 b/docs/telodendria.conf.5 deleted file mode 100644 index 2bce499..0000000 --- a/docs/telodendria.conf.5 +++ /dev/null @@ -1,190 +0,0 @@ -.Dd $Mdocdate: September 29 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