From 79ce36c8607095713891106ba58d8a7067297f37 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 19:53:56 -0400 Subject: [PATCH 01/28] Add `CHANGELOG.md` --- docs/CHANGELOG.md | 245 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 docs/CHANGELOG.md diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..151ba19 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,245 @@ +# Telodendria Change Log + +This document contains the complete change log for every official release of Telodendria. +It is intended to be updated with every commit that makes a user-facing change worth +reporting in the change log. As such, it changes frequently between releases. Final +change log entries are published as [Releases](releases). + +## v0.4.0 + +**Not Released Yet.** + +This release brings filters, rooms, and events! The core of the Matrix protocol architecture +is not in place. + +### Matrix Specification + +The following endpoints were added: + +- **POST** `/_matrix/client/v3/user/{userId}/filter` +- **GET** `/_matrix/client/v3/user/{userId}/filter/{filterId}` + +## v0.3.0 + +**Saturday, June 10, 2023** + +Introducing a new configuration API and Cytoplasm, a general-purpose C library that +supports source/sink-agnostic I/O, TLS, an HTTP client, and more! The third major +release of Telodendria packs a lot of architectural improvements on top of supporting +more of the Matrix specification. + +### Matrix Specification + +Added support for the following endpoints: + +- `/_matrix/client/v3/account/whoami` +- `/_matrix/client/v3/account/password` +- `/_matrix/client/v3/account/deactivate` +- `/_matrix/client/v3/profile/*` +- `/_matrix/client/v3/capabilities` +- `/_matrix/client/v3/auth/*/fallback/web` + +There is also support for token-based user registration. Note that there is as of +yet no admin-facing way to create these registration tokens, but the APIs are in +place. + +### New Features + +- Added a new `HttpClient` API for making HTTP requests. This will eventually be +used for federating with other Matrix homeservers. +- Added support for pretty-printing JSON in `Json`. Telodendria itself does not +pretty-print JSON, but this is useful for debugging and building useful tools. +- Added a handful of new development tools built on the Telodendria APIs. New +tools include `http`, a command line tool for making HTTP requests, similar to +`curl`, `json`, a command line tool for working with JSON, similar to `jq`, and +`http-debug-server`, a simple HTTP server that just prints requests out to standard +output and returns an empty JSON object. `http` and `json` are replacements for +`curl` and `jq` that build on the `HttpClient` and `Json` APIs. They exist mainly +to test those APIs, but also to reduce the number of dependencies that Telodendria +has. `http-debug-server` exists to test the `HttpServer` and `HttpClient` APIs. +- Replaced all usage of `jq` with the new `json` tool. `jq` is no longer a development +dependency. +- Replaced all usage of `curl` with the new `http` tool. `curl` is no longer a +required development dependency. +- Added a new `tt` script for easily making Matrix requests against Telodendria +in development. +- Added TLS support to both the HTTP client and server. Currently, Telodendria +supports LibreSSL and OpenSSL, but other TLS libraries should be extremely easy +to add support for. +- Added support for spinning up multiple HTTP servers. This is useful for having +a TLS port and a non-TLS port, for example. +- Moved all program configuration to the data directory and added an administrator +API endpoint to manage it. It is now no longer recommended to manually update the +configuration file. Consult the [Administrator API](user/admin.md) documentation +and the [Configuration](user/config.md) documentation. +- Added an administrator API endpoint for process control. Telodendria can now be +restarted or shutdown via API endpoint. +- Added an administrator API endpoint for getting statistics about the running +Telodendria process. +- Added support for user privileges, a way to have fine-grained control over what +users are allowed to do with the administrator API. Administrator APIs for setting +and getting privileges is now supported, and registration tokens have privileges +associated with them so that users created with a token will automatically be given +the specified privileges. + +### Fixes & General Improvements + +- Fixed a few warnings that were generated on some obscure compilers. +- Moved the `main()` function to its own file to make it easier to link other +programs with the Telodendria APIs. +- Fixed the development tools environment script. Apparently using a hyphen as a bullet +point is not very portable, because some shell implementations of `printf` interpret it +as a flag. Switched to an asterisk. +- Fixed some intermittent I/O errors that would occur as a result of race conditions in +`JsonConsomeWhitespace()`. This function, and a few others, expect I/O to be blocking, +but the `HttpServer` sets up I/O to be non-blocking, leading to occasional failures in +JSON parsing. +- Abstracted all I/O into the new `Io` and `Stream` APIs, which provide an input- and +output- agnostic stream processing interface. This allows for a simple implementation of +proxies, TLS, and other stream filters without having to change any of the existing +code. +- Remove all non-POSIX function calls, including the call to `chroot()` and, on +OpenBSD, `pledge()` and `unveil()`. This may seem like a downgrade in security, but +these are platform-specific system calls that should be patched in by package maintainers +if they are desired. They also caused problems when implementing other features, because +some library calls need to be able to access files on the filesystem. +- Fixed the build script to supply `LDFLAGS` after the object files when linking. +Apparently the order in which libraries are passed matters to some compilers. +- Added the response status of a request to the log output. This means that requests are +logged after they have completed, not before they are started. +- Memory allocations, reallocations, and frees are no longer loged when the log level +is set to debug in the configuration file. To enable the logging of memory operations, +pass the `-v` flag. +- Implemented a proper HTTP request router with POSIX regular expression support. +Previously, a series of nested `if`-statements were used to route requests, but this +approach quickly becamse very messy. While the HTTP request router incurs a small memory +and runtime speed penalty, the code is now much more maintainable and easier to follow. +- Fixed some memory bugs in `Db` that were related to caching data. Caching should +now work as expected. +- Fixed a major design flaw in `Db` that would cause deadlock when multiple threads +request access to the same object. Database locking is now in a per-thread basis, +instead of a per-reference basis. +- Telodendria now shuts down cleanly in response to `SIGTERM`. +- Did some general refactoring to make the source code more readable and easier +to maintain. +Fixed a number of memory-related issues, including switching out some unsafe +functions for safer versions, per the recommendations of the OpenBSD linker. +- Moved all code documentation into the C header files to make it more likely +that it will get updated. A simple header file parser and documentation generator +have been added to the code base. See the `hdoc` man pages for documentation. +- Updated the build script to provide static and shared libraries containing +the code for Telodendria to make it easier to statically and dynamically link to +other programs. The idea is that these libraries should be shipped with Telodendria, +or as a separate package, and can be used to provide a high-level programming +environment. +- Updated the `Json` API to calculate the length of a JSON object. This is +used to set the `Content-Length` header in HTTP requests and reponses. +- Added some string functions, including `StrEquals()`, which replaced almost all +uses of `strcmp()`, since `strcmp()` is used almost exclusively for equality +checking. `StrEquals()` provides a standard way to do so, because previously, +multiple different conventions could be found throughout the code base (for example: +`!strcmp(str1, str2)` vs `strcmp(str1, str2) == 0`). + +... And many more! + +## v0.2.1 + +**Monday, March 6, 2023** + +This is a patch release that fixes a few typos and other minor issues. + +## v0.2.0 + +**Monday, March 6, 2023** + +This release is focused on providing a decent amount of the client authentication +API. You can now create accounts on a Telodendria homeserver, and log in to +get access tokens. + +### New + +- Added the basic form of the user registration API. If registration is enabled +in the configuration file, clients can now register for Matrix accounts. +- Added the basic form of the user login API. Clients can now log in to +their accounts and generate access tokens to be used to authenticate requests. +- Added the basic form of the user interactive authentication API, which can be used +by endpoints that the spec says requires it. Currently, it only implements the +dummy and password stages, but more stages, such as the registration token stage, +will be added in future releases. +- Added a simple landing page that allows those setting up Telodendria to +quickly verify that it is accessible where it needs to be. +- Added the static login page for clients that don't support regular login. + +### Changes + +- Improved HTTP request logging by removing unnecessary log entries and making +errors more specific. +- Leaked memory is now hexdump-ed out to the log if the log level is set to debug. +This greatly simplifies debugging, because developers can now see exactly what the +contents of the leaked memory are. Note that in some circumstances, this memory +may contain sensitive data, such as access tokens, usernames, or passwords. However, +Telodendria should not be leaking memory at all, so if you encounter any leaks, +please report them. +- Refactored a lot of the code and accompanying documentation to be more readable and +maintainable. + +### Bug Fixes + +- Fixed a memory leak that would occur when parsing an invalid JSON object. +- Fixed an edge case where HTTP response headers were being sent before they were +properly set, causing the server to report a status of 200 even when that wasn't the +desired status. +- Fixed a few memory leaks in the HTTP parameter decoder that would occur in some +edge cases. +- Fixed an "off-by-one" error in the HTTP server request parser that would prevent +`GET` parameters from being parsed. +- Fixed the database file name descriptor to prevent directory traversal attacks +by replacing special characters with safer ones. +- Fixed a memory leak that would occur when closing a database that contains +cached objects. +- Fixed a memory leak that would occur when deleting database objects. +- Fixed a few non-fatal memory warnings that would show up as a result of passing a +constant string into certain functions. + + ### Misc. + + - Fixed a bug in `td` that caused `cvs` to be invoked in the wrong directory when + tagging a new release. + - Added support for environment variable substitution in all site files. This + makes it easier to release Telodendria versions. + - Fix whitespace issues in various shell scripts. + - Fixed the debug log output so that it only shows the file name, not the + entire file path in the repository. + - Updated the copyright year in the source code and compiled output. + - Switched the `-std=c89` flag to `-ansi`, as `-ansi` might be more supported. + - Fixed the `-v` flag. It now sets the log level to debug as soon as possible to + allow debugging configuration file parsing if necessary. + + ... And many more bug fixes and feature additions! Too much has changed to make a + comprehensive change log. A lot of things have been done under the hood to make + Telodendria easier to develop in the future. Please test the current functionality, + and report bugs. + +The following platforms have been known to compile and run Telodendria: + +- OpenBSD +- Linux (GNU and non-GNU) +- Windows (via Cygwin) +- FreeBSD +- NetBSD +- DragonFlyBSD +- Haiku OS +- Android (via Termux) + +Telodendria is about being portable; if you compile it on an obscure operating system, +do let us know about it! + +## v0.1.0 + +**Tuesday, December 13, 2022** + +This is the first public release of Telodendria so there are no changes to report. +Future releases will have a complete change log entry here. + +This is a symbolic release targeted at developers, so there's nothing useful to +ordinary users yet. Stay tuned for future releases though! \ No newline at end of file From 4bd527aa9a556231793bf50960bf9c210ce91473 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 20:06:12 -0400 Subject: [PATCH 02/28] Remove old change log. --- .gitignore | 2 + man/man7/telodendria-changelog.7 | 480 ------------------------------- 2 files changed, 2 insertions(+), 480 deletions(-) delete mode 100644 man/man7/telodendria-changelog.7 diff --git a/.gitignore b/.gitignore index 8032c58..7d63ee8 100644 --- a/.gitignore +++ b/.gitignore @@ -4,9 +4,11 @@ data *.patch *.log vgcore.* +*.core Cytoplasm/build Cytoplasm/out Cytoplasm/*-leaked.txt contrib/.vagrant src/Schema src/include/Schema +man/mandoc.db diff --git a/man/man7/telodendria-changelog.7 b/man/man7/telodendria-changelog.7 deleted file mode 100644 index f22a5ae..0000000 --- a/man/man7/telodendria-changelog.7 +++ /dev/null @@ -1,480 +0,0 @@ -.Dd $Mdocdate: June 18 2023 $ -.Dt TELODENDRIA-CHANGELOG 7 -.Os Telodendria Project -.Sh NAME -.Nm Telodendria -.Nd The change log for the Telodendria project. -.Sh PROJECT STATUS -.Pp -.Nm -is a very ambitious project. There's a lot that needs to happen yet -before it is usable. At the moment, -.Nm -is starting to resemble a Matrix homeserver, but you can't really -call it one yet. The foundation is mostly in place; now there's the -Matrix specification to implement. -.Pp -Just because there's not much here yet doesn't mean you should go -away! I could always use help, so you are more than welcome to get -involved in the project if you want to see things move quicker. -Feel free to donate using the links on the project website, or -see the -.Xr contributing 7 -page for details on how to get involved. The CVS repository has -a file called -.Pa TODO.txt , -which contains a checklist of the items that need to be completed. -Feel free to grab an item on that list and start writing patches! -It's a good idea to join the Matrix rooms noted in -.Xr telodendria 7 -as well, so you can discuss your progress and ask questions. -.Sh v0.4.0 -.Pp -Not released yet. -.Pp -This release brings Filters, Rooms, and Events! The core of the -Matrix protocol architecture is now in place. -.Ss Matrix Specification -.Pp -The following new endpoints are now supported: -.Bl -bullet -offset indent -.It -.Sy POST Pa /_matrix/client/v3/user/{userId}/filter -.It -.Sy GET Pa /_matrix/client/v3/user/{userId}/filter/{filterId} -.El -.Sh v0.3.0 -.Pp -Saturday, June 10, 2023 -.Pp -Introducing a new configuration API and Cytoplasm, a general-purpose -C library that supports source/sink-agnostic I/O, TLS, an HTTP client, -and more! The third major release of -.Nm -packs a lot of architectural improvements on top of supporting more of -the Matrix specification. -.Pp -Matrix Specification: -.Bl -bullet -.It -Added support for the -.Pa /_matrix/client/v3/account/whoami -endpoint. -.It -Added support for the -.Pa /_matrix/client/v3/account/password -endpoint. -.It -Added support for the -.Pa /_matrix/client/v3/profile/* -endpoints. -.It -Added support for the -.Pa /_matrix/client/v3/capabilities -endpoint. -.It -Added support for token-based user registration. Note that there is -as of yet no admin-facing way to create these registration tokens, -but the APIs are in place. -.It -Added web fallback pages for the supported user-interactive -authentication mechanisms at -.Pa /_matrix/client/v3/auth/*/fallback/web . -.It -Added support for the -.Pa /_matrix/client/v3/account/deactivate -endpoint. -.El -.Pp -New Features: -.Bl -bullet -.It -Added a new -.Xr HttpClient 3 -API for making HTTP requests. This will eventually be used for -federating with other Matrix homeservers. -.It -Added support for pretty-printing JSON to -.Xr Json 3 . -.Nm -itself doesn't pretty-print JSON, but this is useful for debugging -and building useful tools. -.It -Added a handful of useful development tools built on the -.Nm -APIs. New tools include -.Xr http 1 , -a command line tool for making HTTP requests, similar to -.Xr curl 1 , -.Xr json 1 , -a command line tool for working with JSON, similar to -.Xr jq 1 , -and -.Xr http-debug-server 1 , -a simple HTTP server that just prints requests out to standard -output and returns an empty JSON object. -.Nm http -and -.Nm json -are replacements for -.Xr curl 1 -and -.Xr jq 1 -that build on the -.Xr HttpClient 3 -and -.Xr Json -APIs. They exist mainly to test those APIs, but also to reduce -the number of dependencies that -.Nm -has. -.Nm http-debug-server -exists to test the -.Xr HttpServer 3 -and -.Xr HttpClient -APIs. -.It -Replaced all usage of -.Xr jq 1 -with the new -.Xr json 1 -tool. -.Xr jq 1 -is no longer a development dependency. -.It -Replaced all usage of -.Xr curl 1 -with the new -.Xr http 1 -tool. -.Xr curl 1 -is no longer a development dependency. -.It -Added a new -.Xr tt 1 -script for easily making Matrix requests against -.Nm -in development. -.It -Added TLS support to both the HTTP client and server. Currently, -.Nm -supports LibreSSL and OpenSSL, but other TLS libraries should be -extremely easy to add support for. -.It -Added support for spinning up multiple HTTP servers. This is useful -for having a TLS and non-TLS port, for example. -.It -Moved all program configuration to the data directory and added an -administrator API endpoint to manage it. It is now no longer -recommended to manually update the configuration file. Consult -.Xr telodendria-admin 7 -and -.Xr telodendria-config 7 . -.It -Added an administrator API endpoint for process control. -.Nm -can now be restarted or shut down via API endpoint. -.It -Added an administrator API endpoint for getting statistics about -the running -.Nm -process. -.It -Added support for user privileges, a way to have fine-grained control -over what users are allowed to do with the administrator API. -Administrator APIs for setting and getting privileges is now -supported, and registration tokens have privileges associated with -them, so that users created with a token will have the specified -privileges. -.El -.Pp -Fixes and general improvements: -.Bl -bullet -.It -Fixed a few warnings that were generated on some obscure compilers. -.It -Moved the -.Fn main -function into its own file to make it easier to link other programs -with the -.Nm -APIs. -.It -Fixed the development tools environment setup script. Apparently -using a hyphen as a bullet point is not very portable, because some -shell implementations of -.Xr printf 1 -interpret it as a flag. Switched to an asterisk instead. -.It -Fixed some intermittent I/O errors that would occur as a result of -race conditions in -.Fn JsonConsumeWhitespace . -This function, and a few others, expect I/O to be blocking, but -the -.Xr HttpServer 3 -sets up I/O to be non-blocking, leading to occasional failures in -JSON parsing. -.It -Abstracted all I/O into the new -.Xr Io 3 -and -.Xr Stream 3 -APIs, which provide an input/output-agnostic stream processing. -This allows for a simple implementation of proxies, TLS, and -other stream filters without having to change any of the existing -code. -.It -Removed all non-POSIX function calls, including the call to -.Fn chroot -and, on OpenBSD, the calls to -.Fn pledge -and -.Fn unveil . -This may seem like a downgrade in security, but these are -platform-specific system calls that should be patched in by -package maintainers if they are desired. They also caused -problems when implementing other features, because some library -calls need to be able to access files on the filesystem. -.It -Fixed the build script to supply -.Ev LDFLAGS -after the object files when linking. Apparently the order in -which libraries are passed matters to some compilers. -.It -Added the response status of a request to the log output. This means -that requests are logged after they have completed, not before they -are started. -.It -Memory allocations, reallocations, and frees are no longer logged -when the log level is set to debug in the configuration file. To -enable the logging of all memory operations, pass the -.Ic -v -flag. -.It -Implemented a proper HTTP request router with POSIX regular -expression support. Previously, a series of nested if-statements -were used to route requests, but this approach quickly became -very messy. While the HTTP request router incurs a small memory -and runtime penalty, the code is now much more maintainable and -easier to follow. -.It -Fixed some memory bugs in -.Xr Db 3 -that were related to caching data. Caching should now work as -expected. -.It -Fixed a major design flaw in -.Xr Db 3 -that could cause deadlock when multiple threads request access to -the same object. Database locking is now on a per-thread basis, -instead of a per-reference basis. -.It -.Nm -now shuts down cleanly in response to SIGTERM. -.It -Did some general refactoring to make the source code more -readable and easier to maintain. -.It -Fixed a number of memory-related issues, including switching out -some unsafe functions for safer versions, per the recommendations -of the OpenBSD linker. -.It -Moved all code documentation into the C header files to make it -more likely that it will get updated. A simple header file parser -and documentation generator have been added to the code base. -See -.Xr hdoc 1 -for the utility documentation, and -.Xr hdoc 5 -for the documentation format. -.It -Updated the build script to provide static and shared libraries -containing the code for -.Nm -to make it easier to statically and dynamically link to other programs. -The idea is that these libraries should be shipped with -.Nm , -or as a separate package, and can be used to provide a high-level -programming environment. -.It -Updated the -.Xr Json 3 -API to calculate the length of a JSON object. This is used to set the -Content-Length header in HTTP requests and responses. -.It -Added some string functions, including -.Fn StrEquals , -which replaced almost all usages of -.Fn strcmp , -since -.Fn strcmp -is used almost exclusively for equality checking. -.Fn StrEquals -provides a standard way to do so, because previously, multiple -different conventions could be found throughout the code base. -.El -.Pp -\&... And many more! -.Sh v0.2.1 -.Pp -Monday, March 6, 2023 -.Pp -This is a patch release that fixes a few typos and other minor -issues. -.Sh v0.2.0 -.Pp -Monday, March 6, 2023 -.Pp -This release is focused on providing a decent amount of the -client authentication API. You can now create accounts on a -Telodendria homeserver, and log in to get access tokens. -.Pp -New: -.Bl -bullet -.It -Added the basic form of the user registration API. If -registration is enabled in the configuration file, clients -can now register for Matrix accounts. -.It -Added the basic form of the user login API. Clients can now -log in to their accounts and generate access tokens to be -used to authenticate requests. -.It -Added the basic form of the user interactive authentication API, -which can be used by any endpoints that the spec says require -it. Currently, it only implements the dummy and password stages, -but more stages, such as the registration token stage, will be -added in future releases. -.It -Added a simple landing page that allows those setting up -.Nm -to quickly verify that it is accessible where it needs to be. -.It -Added the static login page for clients that don't support -regular login. -.El -.Pp -Changes: -.Bl -bullet -.It -Improved HTTP request logging by removing unnecessary -log entries and making errors more specific. -.It -Leaked memory is now hexdump-ed out to the log if the log -level is set to debug. This greatly simplifies debugging, -because developers can now easily see exactly what the -contents of the leaked memory are. Note that in some -circumstances, this memory may contain sensitive data, -such as access tokens, usernames, or passwords. However, -.Nm -should not be leaking memory at all, so if you encounter -any leaks, please report them. -.It -Refactored a lot of the code and accompanying documentation -to be more readable and maintainable. -.El -.Pp -Bug fixes: -.Pp -.Bl -bullet -.It -Fixed a memory leak that would occur when parsing an invalid -JSON object. -.It -Fixed an edge case where HTTP response headers were being -sent before they were properly set, causing the server to -report a status of 200 even when that wasn't the desired -status. -.It -Fixed a few memory leaks in the HTTP parameter decoder that -would occur in some edge cases. -.It -Fixed an "off-by-one" error in the HTTP server request -parser that prevented GET parameters from being parsed. -.It -Fixed the database file name generator to prevent directory -traversal attacks by replacing special characters with -safer ones. -.It -Fixed a memory leak that would occur when closing a -database that contains cached objects. -.It -Fixed a memory leak that would occur when deleting database -objects. -.It -Fixed a few non-fatal memory warnings that would show up -as a result of passing a constant string into certain functions. -.El -.Pp -Misc: -.Bl -bullet -.It -Fixed a bug in -.Xr td 1 -that caused -.Xr cvs 1 -to be invoked in the wrong directory when tagging a new release. -.It -Added support for environment variable substitution in all site -files. This makes it easier to release -.Nm -versions. -.It -Fix whitespace issues in various shell scripts. -.It -Fixed the debug log output so that it only shows the file name, -not the entire file path in the repository. -.It -Updated the copyright year in the source code and compiled output. -.It -Switch the -std=c89 flag to -ansi instead, as -ansi might be more -supported. -.It -Fixed the -v flag. It now sets the log level to debug as soon -as possible to allowe debugging the configuration file parsing -if necessary. -.El -.Pp -\&... And many more bug fixes and feature additions! Too much -has changed to make a comprehensive change log. A lot of things -have been done under the hood to make -.Nm -easier to develop in the future. Please test the current -functionality, and report bugs to the Matrix rooms. -.Pp -The following platforms have been known to compile and run -.Nm : -.Bl -bullet -.It -OpenBSD -.It -Linux (GNU and non-GNU) -.It -Windows (via Cygwin) -.It -FreeBSD -.It -NetBSD -.It -DragonFlyBSD -.It -Haiku OS -.It -Android (via Termux) -.El -.Pp -.Nm -is about being portable; if you compile it on an obscure -operating system, do let me know about it! -.Sh v0.1.0 -.Pp -Tuesday, December 13, 2022 -.Pp -This is the first public release of -.Nm -so there are no changes to report. Future releases will -have a complete change log entry here. -.Pp -This is a symbolic release targeted at developers, so there's nothing -useful to ordinary users yet. Stay tuned for future releases though! From ee62d31c68e40738e6d998023403745c3b74b78e Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 20:23:40 -0400 Subject: [PATCH 03/28] Add documentation home page. --- docs/README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..94002ae --- /dev/null +++ b/docs/README.md @@ -0,0 +1,25 @@ +# Telodendria Documentation + +Here you will find all of the documentation for Telodendria. If you +find that some documentation is missing or incorrect, please open an +issue, and, even better, a pull request to fix the issue. + +## User Documentation + +- [System Requirements](user/requirements.md) +- [Install](user/install.md) +- [Command Line Options](user/cmd.md) +- [Set Up](user/setup.md) +- [Configuration Options](user/config.md) +- [Administrator API](user/admin.md) + +## Developer Documentation + +- [Contributing Guidelines](CONTRIBUTING.md) +- [Porting Guidelines](dev/ports.md) + +## Miscellaneous + +- [Change Log](CHANGELOG.md) +- [Project Road Map](ROADMAP.md) + From 93e6582db513a096de3ebe58670897f2ba605cb9 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 21:10:46 -0400 Subject: [PATCH 04/28] Add usage and install documentation. --- docs/README.md | 3 ++- docs/user/install.md | 51 +++++++++++++++++++++++++++++++++++ docs/user/usage.md | 64 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 docs/user/install.md create mode 100644 docs/user/usage.md diff --git a/docs/README.md b/docs/README.md index 94002ae..e927e8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ issue, and, even better, a pull request to fix the issue. - [System Requirements](user/requirements.md) - [Install](user/install.md) -- [Command Line Options](user/cmd.md) +- [Usage & Running](user/usage.md) - [Set Up](user/setup.md) - [Configuration Options](user/config.md) - [Administrator API](user/admin.md) @@ -20,6 +20,7 @@ issue, and, even better, a pull request to fix the issue. ## Miscellaneous +- [Matrix Specification](https://spec.matrix.org) ([Mirror](https://telodendria.io/spec.matrix.org)) - [Change Log](CHANGELOG.md) - [Project Road Map](ROADMAP.md) diff --git a/docs/user/install.md b/docs/user/install.md new file mode 100644 index 0000000..56a8f30 --- /dev/null +++ b/docs/user/install.md @@ -0,0 +1,51 @@ +# Installation + +There are multiple methods of installing Telodendria. Choose the one +best suited to your use case. + +## Package Manager Or System Ports + +This is the recommended way to install Telodendria. If your operating +system has an official package or port of Telodendria, you should +prefer to use that instead of the other methods documented here, +because your operating system or software distribution will have +already figured out how to best integrate Telodendria with your system. + +Consult your operating system or software distribution's system +manual for instructions on how to install packages. Also consult the +official repository of your distribution to see if a package is +available. If a package exists but it is too out of date for your +tastes, please contact the package's maintainer to notify them, or +offer to update the package yourself using the +[porting instructions](../dev/ports.md). + +If you are maintaining a port or package for an operating system or +software distribution, open a pull request to include your +platform-specific instructions as a subheader of this section. +Eventually, this section should contain basic instructions for the +operating systems that have packages or ports. +See [Ports](../dev/ports.md) for the project's distribution +philosophy. + +## Container + +At this time, Telodendria does not have any officially recommended +procedure for running in a container such as Docker or Vagrant. You +may find helpful files in the [`contrib/`](../../contrib) directory, +however. + +If you are publishing container images, please open a pull request to +add your source files to `contrib/`, as well as to add documentation +under this section explaining how to get set started. + +## Release Binary + +At this time, Telodendria does not publish any official binaries that +can be downloaded. The tentative plan is to eventually provide binaries +with each release for a number of supported platforms. When that +happens, instructions will be provided here for dealing with the +binaries. + +## From Source + +**TODO:** Update this section before #19 is closed. diff --git a/docs/user/usage.md b/docs/user/usage.md new file mode 100644 index 0000000..8fcd604 --- /dev/null +++ b/docs/user/usage.md @@ -0,0 +1,64 @@ +# Usage + +This document provides general documentation on how to use the +`telodendria` server binary, as well as details on how it behaves. +The details here will be useful for setting up init systems, running +Telodendria in a container, or manually executing the binary for +testing or debugging purposes. + +## Command Line Options + +Typically, Telodendria is controlled via the +[Administrator API](admin.md), but the Telodendria binary does include +a few command line options, which can be used in init scripts or for +debugging purposes. + +The command line arguments are as follows: + +- **`-d `** Specify the data directory to use. All persistent +storage that Telodendria requires is saved to and loaded from here. +- **`-V`** Only print the version information header and then quit +with a success exit code. +- **`-v`** Verbose mode. This overrides the configuration and sets the +log level to `debug`. It also enables additional logging of memory +operations, which can be useful for debugging. + +Before proposing additional command line arguments, consider whether or +not the functionality requested can be provided via a (potentially new +and as of yet uncreated) administrator API endpoint. + +## Environment + +Telodendria does not read any environment variables. All configuration +should be done via the [Configuration API](config.md). + +## Signals + +Telodendria recognizes and responds to a number of signals: + +- **`PIPE`:** This signal is ignored, because all I/O errors should +already be handled properly. +- **`USR1`:** Perform a soft restart by shutting down the HTTP servers +and resetting the program state. Note that the daemon process does +not exit. +- **`TERM`:** Perform a clean shutdown after all existing connections +are closed. +- **`INT`:** Same as `TERM`. + +Any other signals are not explicitly handled, so they have the +default behavior as defind by the operating system. + +## Exit Status + +Telodendria exits with a non-0 exit code if the configuration file is +invalid, or one or more of required paths or files is inaccessible. +Telodendria will print an error to the log and then terminate +abnormally. + +Telodendria exits with a code of 0 if the configuration file is valid, +all paths and files required are accessible, and the HTTP listener +starts as intended. If Telodendria is sent a signal that it catches +after it begins servicing requests, it will still exit normally after +it safely shuts down, because the bootstrap process completed +successfully, and by all accounts, it ran normally and exitted +normally. From 3cb04417ffd3cd93b6aad3a98c76072933b40d44 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 21:53:22 -0400 Subject: [PATCH 05/28] Add porting instructions. --- docs/dev/ports.md | 94 ++++++++++++++++++++++++++++++++ man/man7/porting.7 | 119 ----------------------------------------- man/man8/telodendria.8 | 73 ------------------------- 3 files changed, 94 insertions(+), 192 deletions(-) create mode 100644 docs/dev/ports.md delete mode 100644 man/man7/porting.7 delete mode 100644 man/man8/telodendria.8 diff --git a/docs/dev/ports.md b/docs/dev/ports.md new file mode 100644 index 0000000..5154106 --- /dev/null +++ b/docs/dev/ports.md @@ -0,0 +1,94 @@ +## Ports + +Telodendria is distributed primarily as source code, and the project +itself does not offer a convenient install process such as in the form +of a shell script. This is intentional; the Telodendria project is +primarily concerned with developing Telodendria itself, not packaging +it for the hundreds of different operating systems and linux +distributions that exist. It is my firm belief that distributing an +open source project is not the job of the open source developer; that +is the reason software distributions exist: to collect and +*distribute* software. + +It would be impossible to single-handedly package Telodendria for +every platform, because each platform has very different expectations +and conventions for software. Even different Linux distributions have +different conventions for where manual pages, binaries, and +configuration files go. + +That being said, this document aims to assist those who want to +package Telodendria for their operating system or software +distribution. + +--- + +Before attempting to package Telodendria, make sure that you can build +it and that it builds cleanly on your target platform. See +[Install → From Source](../user/install.md#from-source) +for general build instructions. + +To package Telodendria, you should collect the following files, and +figure out where they should be installed on your system: + +- The `telodendria` server binary itself, located at +`build/telodendria`. +- All manual pages in the `man/` directory. These should be prefixed +with `telodendria-`. You may also wish to ship the `docs/` directory +so that the user can read the documentation offline, and ensure that +they are reading the correct documentation for the installed version. +- An init script. People that wish to install Telodendria on their +system using your package are going to expect it to be integrated +enough that Telodendria can easily be started at boot and otherwise +managed by the system's daemon tools, be it `systemd` or another +init system. Consult your system's documentation for writing an init +script. **Note:** Telodendria *does not* fork itself to the background; +the init script should do that. + +You may wish to optionally create a dedicated user under which +Telodendria should run. Telodendria can be directly started as that +user, or start as root and be configured to automatically drop to that +user. Additionally, it might be helpful to provide a default +configuration, which can be placed in the samples directory on your +platform, or in a default location that Telodendria will load from. +A good default directory that you may wish to provide for configuration, +data, and logs could perhaps be `/var/telodendria` on Unix-like systems. + +Once you have collected the necessary files and directories that need +to be installed, make sure your package performs the following tasks +on install: + +- If necessary and depending on the configuration used, create a new +system user for the Telodnedria daemon to run as. +- If conventional for your system, enable the Telodendria init script +so that Telodendria is started on system boot. +- Instruct the user to carefully read the [Setup](../user/setup.md) +(`docs/user/setup.md`) instructions and the +[Configuration](../user/config.md) (`docs/user/config.md`) instructions +before starting Telodendria. + +The goal of a package should be to get everything as ready-to-run as +possible. The user should be able to start Telodendria right away and +begin configuring it. + +Remember to publicly document the setup of Telodendria on your platform +if there are additional steps required that are not mentioned in the +official Telodendria documentation. This ensures that users can get +up and running quickly and easily. If you're packaging Telodendria +for a container system such as Docker, you can omit the things that +containers typically do not have, such as the init scripts and +documentation. + +Also remember that your port should feel like it belongs on your target +system. Follow all of your system's conventions when placing files +on the filesystem, so your users know what to expect. The goal is not +necessarily to have a unified experience across all operating systems, +rather, you should cater to the opinions of your operating system. +Telodendria is architected in such a way that it does not impose the +developer's opinions of where things should go, and since the +configuration lives in the database, it is fairly self contained. + +If there are any changes necessary to the upstream code or build +system that would make your job in porting Telodendria easier, do not +hesitate to get involved by opening an issue and/or submitting a pull +request. + diff --git a/man/man7/porting.7 b/man/man7/porting.7 deleted file mode 100644 index 2f24195..0000000 --- a/man/man7/porting.7 +++ /dev/null @@ -1,119 +0,0 @@ -.Dd $Mdocdate: April 24 2023 $ -.Dt PORTING 7 -.Os Telodendria Project -.Sh NAME -.Nm porting -.Nd Some guidelines for packaging Telodendria for your operating system. -.Sh DESCRIPTION -.Pp -Telodendria is distributed at source code, and does not offer a -convenient install process. This is intentional; the Telodendria -project is primarily concerned with developing Telodendria itself, -not packaging it for the hundreds of different operating systems -and Linux distributions that exist. It is my firm belief that -distributing an open source project is not the job of the open -source developer; that's the reason software distributions exist, -to collect and distribute software. -.Pp -It would be impossible to single-handedly package Telodendria for -every platform, because each platform has very different expectations -for software. Even different Linux distributions have different -conventions for where manual pages, binaries, and configuration -files go. -.Pp -That being said, this page aims to assist those who want to package -Telodendria for their operating system or software distribution. -.Pp -See -.Xr td 1 -for instructions on how to build Telodendria. Only proceed with -packaging Telodendria after you have successfully built it on your -operating system. -.Pp -To package Telodendria, you should collect the following files, and -figure out where they should be installed for your system: -.Bl -bullet -.It -The telodendria server binary itself: -.Pa build/telodendria -.It -All manual pages in the -.Pa man/ -directory that are prefixed with "telodendria". These are the user -documentation pages. All pages that do not have the "telodendria" -prefix are intended only for developers, and so do not need to be -installed to the system. -.It -An init script. People that wish to install Telodendria to their -system expect it to be integrated enough that Telodendria can be -easily started at boot, and otherwise managed by the system's daemon -tools, be it systemd, or another init system. Consult your system's -documentation for writing an init script. Do note that Telodendria -does not fork itself to the background; the init script should do -that. Note that the init script probably requires a few things: -.Bl -bullet -.It -A dedicated system user under which Telodendria should run. -Telodendria can either be started as that user, or started as -root and configured to automatically drop to that user. -.It -A default data directory, in which all Telodendria data, including -the configuration and logs, will be stored. A good default on -Unix-like system is probably -.Pa /var/telodendria . -.El -.El -.Pp -Optionally, it may be helpful to provide these as well: -.Bl -bullet -.It -A sample Telodendria configuration. This should be placed in the -examples directory on your -system, if such a directory exists. You can use or adapt any of the -configuration files in -.Pa contrib/ , -or write your own specifically for your package. -.El -.Pp -Once you have collected the files that need to be installed, make -sure your package performs the following tasks on install: -.Bl -bullet -.It -If necessary, depending on the config used, create a new system -user for the Telodendria daemon to run as. -.It -If conventional for your system, enable the Telodendria init script -so that Telodendria is started on system boot. -.It -Insruct the user to carefully read the -.Xr telodendria-setup 7 , -.Xr telodendria-admin 7 , -and -.Xr telodendria-config 7 -manual pages before starting Telodendria. -.El -.Pp -The goal of a package should be to get everything as ready-to-run -as possible. The user should be able to start Telodendria -right away and begin configuring it. -.Pp -Remember to publicly document the setup of Telodendria on your -platform so that users can easily get things running. If you're -packaging Telodendria for a containerization system such as Docker, -you can omit the things that containers typically do not have, such -as the init script and man pages. -.Pp -Also remember that your port should feel like it belongs on your -target system. Follow all of your system's conventions when placing -files on the filesystem, so your users know what to expect. The -goal is not necessarily to have a unified experience across all -operating systems, rather, you should cater to the opinions of -your operating system. Telodendria is architected in such a way -that it does not impose the developers opinions of where things -should go, and since the configuration lives in the database, -it is fairly self-contained. -.Pp -.Sh SEE ALSO -.Xr telodendria-contributing 7 , -.Xr td 1 , -.Xr telodendria 7 diff --git a/man/man8/telodendria.8 b/man/man8/telodendria.8 deleted file mode 100644 index 303703f..0000000 --- a/man/man8/telodendria.8 +++ /dev/null @@ -1,73 +0,0 @@ -.Dd $Mdocdate: April 30 2023 $ -.Dt TELODENDRIA 8 -.Os Telodendria Project -.Sh NAME -.Nm telodendria -.Nd Daemon command line manual for Telodendria administrators. -.Sh SYNOPSIS -.Nm -.Op Fl nVv -.Op Fl f Ar file -.Sh DESCRIPTION -.Nm -is a Matrix homeserver written entirely from scratch in ANSI C. -It is designed to be lightweight and simple, yet functional. -.sp -The options are as follows: -.Bl -tag -width Ds -.It Fl d Ar dir -Specify the data directory to use. All persistant storage that -Telodendria requires is saved and loaded here. -.It Fl V -Only print the version information header and then quit. -.It Fl v -Verbose mode. This overrides the configuration file and sets the -log level to -.Em LOG_DEBUG . -It also enables extra logging of memory operations, which can -be useful for debugging. -.El -.Sh ENVIRONMENT -.Nm -does not read any environment variables. All configuration should -be done via the configuration file. -.Sh FILES -Just the data directory. Telodendria does not read any files outside -of its data directory, with the exception of TLS files if configured. -.Sh SIGNALS -Telodendria recognizes a number of signals that it handles: -.Bl -tag -width Ds -.It PIPE -This signal is ignored, because all I/O errors should be handled -properly. -.It USR1 -Perform a soft restart by shutting down the HTTP servers and resetting -all program state. However, the daemon process does not exit. -.It TERM -Perform a clean shutdown after all existing connections are closed. -.It INT -Perform a clean shutdown after all existing connections are closed. -.El -.Pp -Any other signals are not explicitly handled, so they have the -default behavior defined by the operating system. -.Sh EXIT STATUS -.Nm -exits with a non-0 exit code if the configuration file is invalid, or -one or more required paths is inaccessible. -.Nm -will print an error to the log and then terminate abnormally. -.Pp -.Nm -exits with a code of 0 if the configuration file is valid, all -paths and files required are accessible, and the HTTP listener starts -as intended. If -.Nm -is sent a signal that it catches after it begins servicing requests, it -will still exit with a code of 0 after it safely shuts down, because -the bootstrap process completed successfully, and by all accounts, -it ran normally and exitted normally. -.Sh SEE ALSO -.Xr telodendria 7 , -.Xr telodendria-setup 7 , -.Xr telodendria-admin 7 From f6c54cbc7f442ddf295e9cfd88c7d4bc31e24cdd Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 11:58:54 -0400 Subject: [PATCH 06/28] Add setup documentation. --- docs/README.md | 2 +- docs/user/setup.md | 60 +++++++++++++++++++++++++++++ man/man7/telodendria-setup.7 | 75 ------------------------------------ 3 files changed, 61 insertions(+), 76 deletions(-) create mode 100644 docs/user/setup.md delete mode 100644 man/man7/telodendria-setup.7 diff --git a/docs/README.md b/docs/README.md index e927e8f..801b57d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ issue, and, even better, a pull request to fix the issue. - [System Requirements](user/requirements.md) - [Install](user/install.md) - [Usage & Running](user/usage.md) -- [Set Up](user/setup.md) +- [Initial Set Up](user/setup.md) - [Configuration Options](user/config.md) - [Administrator API](user/admin.md) diff --git a/docs/user/setup.md b/docs/user/setup.md new file mode 100644 index 0000000..ac0ebdf --- /dev/null +++ b/docs/user/setup.md @@ -0,0 +1,60 @@ +# Initial Set Up + +While Telodendria strives to be extremely simple to deploy and run, +in most circumstances a few basic setup steps will be necessary. +Telodendria does not have a traditional configuration file like most +daemons. Instead, its configuration lives in its database; as such, +all configuration happens through the administrator API. This design +decision makes Telodendria extremely flexible, because it is possible +to re-configure Telodendria without having to manually edit files on +the filesystem, thus allowing administrators to secure their server +better. + +Please follow the instructions followed here carefully in the order +they are presented for the best results. + +This document assumes that you have installed Telodendria using any +of the instructions found in [Install](install.md). After installation, +follow these steps: + +1. Start Telodendria. If you installed it via a package or container, +consult your operating system or container system's documentation. If +you are running Telodendria from a release binary or have built it from +source, execute the binary directly. If needed, consult the +[Usage](usage.md) page for details on how to run Telodendria. +1. Assuming that Telodendria started properly, it will spin up and +initialize its database directly with a simple—and, importantly, +safe—default configuration, as well as a randomly generated, +single-use registration token that grants a user all privileges +documented in the [Administrator API](admin.md) documentation. +Consult the log file for this administrator registration token. By +default, the log file is located in the data directory, and is named +`telodendria.log`. +1. Use the registration token to register for an account on the +server. This account will be the administrator account. You can do this +using the client of your choice, or using tools such as `curl` or +`http`, following the Matrix specification for registering accounts. +The administrator account behaves just like a normal local account +that an ordinary user would have registered on the server, except that +it also has all privileges granted to it, so it can make full use of +the Administrator API. +1. Using the access token granted for the administrator account via +the login process, configure Telodendria as descibed in +[Configuration](config.md). See the [Administrator API](admin.md) +documentation for the configuration endpoint details. + +This is the recommended way to set up Telodendria. However, if you +wish to bypass the account creation step and want to configure +Telodendria by directly writing a configuration file instead of using +the administrator API, you can manually create the configuration file +in the database before starting Telodendria. Simply create `config.json` +following the description in [Configuration](config.md), then start +Telodendria. + +While this alternative method may seem simpler and more convenient +to some administrators, it is only so in the short-term. Note that this +method is not supported, because it gives no access to the +administrator API whatsoever, unless you manually modify the database +further to give a user admin privileges, which is error-prone and +bypasses some of Telodendria's safety mechanisms. + diff --git a/man/man7/telodendria-setup.7 b/man/man7/telodendria-setup.7 deleted file mode 100644 index e49456a..0000000 --- a/man/man7/telodendria-setup.7 +++ /dev/null @@ -1,75 +0,0 @@ -.Dd $Mdocdate: April 20 2023 $ -.Dt TELODENDRIA-SETUP 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-setup -.Nd First-time setup instructions for Telodendria. -.Sh DESCRIPTION -.Pp -While Telodendria strives to be extremely simple to deploy, in most -circumstances a few basic setup steps will be necessary. Telodendria -does not have a traditional configuration file like most daemons. -Instead, its configuration lives in its database; as such, all -configuration happens through the administrator API. This design -decision makes Telodendria extremely flexible, because it is possible -to re-configure Telodendria without having to manually edit files -on the filesystem. It is also why the setup instructions provided -here are in the order they are. Please follow them carefully for the -best results. -.Pp -This page assumes that you have installed Telodendria in the way -prescribed by your operating system. Immediately following installation, -perform these steps, in this order: -.Bl -enum -width Ds -.It -Start Telodendria. Consult your operating system's documentation. If -you are running Telodendria directly from the source code directory, -use -.Xr td 8 . -.It -Assuming Telodendria started properly, it will spin up and initialize -its database directory with a simple\(emand importantly, -safe\(emdefault configuration, and a randomly-generated, single-use -registration token that grants a user all privileges documented in -.Xr telodendria-admin 7. -Consult the log file for this administrator registration token. The -log file is located in the data directory, and is named -.Pa telodendria.log . -.It -Use the registration token to register the administrator account. You -can do this using the client of your choice, or using tools such as -.Xr curl 1 -or -.Xr http 1 . -The administrator account functions just like a normal local account, -except that it has all privileges granted to it, so it can make full -use of the administrator API. -.It -Using the access token for the administrator account, authenticate -with the administrator API and configure Telodendria as described -in -.Xr telodendria-config 7. -See -.Xr telodendria-admin 7 -for the configuration endpoint details. -.El -.Pp -This is the recommended way to set up Telodendria. However, if you -wish to bypass the account creation step, and want to configure -Telodendria by directly writing a configuration file instead of using -the administrator API, you can manually create the configuration file -in the database before starting Telodendria. Simply create -.Pa config.json -following the description in -.Xr telodendria-config 7 , -then start Telodnedria. -.Pp -While this alternative method may seem simpler and more convenient to -some administrators, it is only so in the short-term. Note that this -method is not supported, because it gives no access to the -administrator API whatsoever, unless you manually modify the database -to give a user admin privileges, which is error-prone and bypasses -some of Telodendria's safety mechanisms. -.Sh SEE ALSO -.Xr telodendria-admin 7 , -.Xr telodendria-config 7 From 7033a1f0b14c541d0fef565aa52f59063a4d4c1d Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 12:12:07 -0400 Subject: [PATCH 07/28] Add repository structure documentation. --- README.txt | 64 ------------------------------------------------ docs/README.md | 1 + docs/dev/repo.md | 17 +++++++++++++ 3 files changed, 18 insertions(+), 64 deletions(-) delete mode 100644 README.txt create mode 100644 docs/dev/repo.md diff --git a/README.txt b/README.txt deleted file mode 100644 index a580af8..0000000 --- a/README.txt +++ /dev/null @@ -1,64 +0,0 @@ - .= -=- - :.:+ .=:. - .=+-==. :. - .+- =. - .+ :+. - ==. -+: - =++==--:: =+. - .:::--=+=: :+= - :==. -=: - ===----=-. ... :+. - :==+=======: .-+-::-+-=+= - .==*%#======= :+- .. - .:--=-===+=========-. :+: - .=++=::..:============-+=-=- -:+=: :=+-: .-=========-. . - =+++: .:=+-: .:--. .--:==: - ::---:.. :=+: == - ++. .+- - =+ .+- ...: - +- -+-:-+=::+: - :=-....:-=: .--: =- - -++=:.:::.. - -======================================================= -|_ _|__| | ___ __| | ___ _ __ __| |_ __(_) __ _ - | |/ _ \ |/ _ \ / _` |/ _ \ '_ \ / _` | '__| |/ _` | - | | __/ | (_) | (_| | __/ | | | (_| | | | | (_| | - |_|\___|_|\___/ \__,_|\___|_| |_|\__,_|_| |_|\__,_| -======================================================= -Copyright (C) 2023 Jordan Bancino <@jordan:bancino.net> - -This is the source code for Telodendria, a Matrix homeserver written -in C. All of the documentation is available as man pages in the -man/ directory, or online at https://telodendria.io - -If information is missing from the documentation, please feel free -to reach out to #telodendria-general:bancino.net on Matrix. - -This file documents the directory structure of the source code -repository. - -Telodendria/ - contrib/ - Supplemental files, such as example configs. - man/ - The official documentation as man pages. - proposals/ - Proposals for new features or fixes, as man pages. - site/ - The official website. - src/ - The C source code for Telodendria. - include/ - Header files for the source code. - Routes/ - Where Matrix API endpoints are implemented. - Static/ - Endpoints that just generate static HTML pages. - tests/ - Unit and integration tests will eventually go here. - tools/ - Development environment and tools. - -To cut a new release for Telodendria, perform the following -steps. This is just a reference for me so I don't mess it up. - - - Update tools/bin/td to declare the next version number. - - Make sure man/man7/telodendria-changelog.7 is up to date. - with the latest information. (Be sure to set the date - correctly) - - Commit all changes. - - Run the release recipe: td release - - Deploy the site: td site - diff --git a/docs/README.md b/docs/README.md index 801b57d..248f5fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,6 +15,7 @@ issue, and, even better, a pull request to fix the issue. ## Developer Documentation +- [Repository Structure](dev/repo.md) - [Contributing Guidelines](CONTRIBUTING.md) - [Porting Guidelines](dev/ports.md) diff --git a/docs/dev/repo.md b/docs/dev/repo.md new file mode 100644 index 0000000..c77fac4 --- /dev/null +++ b/docs/dev/repo.md @@ -0,0 +1,17 @@ +# Repository Structure + +This document describes the filesystem layout of the Telodendria source +code repository. + +- `Telodendria/` + - `Cytoplasm/`: The source code for Cytoplasm, Telodendria's + general-purpose support library that provides core functionality. + - `contrib/`: Supplemental files, such as example configurations. + - `docs/`: All user and developer documentation as Markdown. + - `site/`: The official website source code as HTML. + - `src/': The C source code and headers for Telodendria. + - `Routes/`: Where the Matrix API endpoints are implemented. + - `Static/`: Endpoints that just generate static HTML pages. + - `include/`: Header files. + - `tools/`: Development environment and tools. + From fa3b5e95bd229bf077b2424e44703e844c3b0e16 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 16:04:48 -0400 Subject: [PATCH 08/28] Add a nice README which will serve as the basis for the website. --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 116 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b54e321..f2a0d33 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,120 @@ # [Telodendria](https://telodendria.io) -**Telodendria** is an open source Matrix homeserver implementation written from scratch in ANSI C and designed to be lightweight and simple, yet functional. +Telodendria is an extremely powerful, yet lightweight and portable +chat server designed to be easy to install and configure. Powered by +the [Matrix](https://matrix.org) protocol, Telodendria empowers +everyone to run their own chat server on ordinary hardware, including +old and embedded devices. Whether you want a simple chat server just +for you and your friends and family, or want to talk to users on other +Matrix homeservers but don't want to go through all the hastle of +hosting a complicated, high-maintenance homeserver or joining an +existing homeserver for privacy or other reasons, then Telodendria +might be for you. -**Important:** This project is not developed on GitHub or CVS anymore, but instead on a dedicated [Gitea forge](https://git.telodendria.io/Telodendria/telodendria). +## What is Matrix? + +Matrix is an **open standard** for *interoperable*, *decentralized*, +*secure*, and *real-time* communication over the internet. + +Matrix can be thought of as the successor to email, but it works +very similar to iMessage, Discord, or direct messaging on most +social media networks. The primary difference between Matrix and these +other services, however, is that Matrix doesn't depend on one central +authority, and is designed in such a way to respect your privacy. +Matrix has proven itself over the last few +years to be a reliable communication tool, and has only gotten more +user-friendly over the course of its development. Matrix is capable +enough that it can—and should—totally replace any other +means of digital communication, and it offers a much higher degree +of security, simplicity, and functionality. + +Strictly speaking, Matrix itself is just the *protocol* by which +clients and servers communicate. In order to use Matrix, we need +implementations of both clients and servers. Telodendria is a server +implementation of the Matrix protocol. + +## Why Telodendria? + +- **Lightweight:** Written in the C programming language, Telodendria +is automatically lighter and faster than other self-hosted chat servers. +It has very few external dependencies and is as self-contained as +possible. +- **Fully-Featured:** Most lightweight chat solutions compromise on +features. Telodendria is built on the fully-featured Matrix protocol, +which provides a chat experience that most normal users are familiar +with. +- **Portable:** You can run Telodendria on just about everything, +including more traditional options like a personal home server or VPS, +but also more obscure platforms like Raspberry Pis or retro computers. +Telodendria can run on a broad number of operating systems, which means +that no matter which platform and OS you prefer, there is a good chance +you can add Telodendria without much difficulty. It is also extremely +easy to migrate a Telodendria instance between platforms; just copy the +data directory to a new device. +- **Simple:** Telodendria is designed to be a simple, no-frills +chat server. It is easy to install, easy to configure, and easy to +maintain. +- **Stable:** Other Matrix homeservers develop at the pace of the +Matrix specification itself, which is to say quite rapidly. Changes are +always being made, and a version shipped 6 months ago is already +incredibly outdated. Telodendria, on the other hand, aims to be stable. +It should *just work* for long periods of time between upgrades, and +you should never feel like Telodendria is going to change significantly +between upgrades. + +[Read Technical Rationale →](docs/dev/rationale.md) + +## Get Started + +Check out the [Documentation](docs/README.md) to get started with +Telodendria. + +## Status + +## Sponsorship + +Telodendria is maintained by a loosely-knit band of volunteers. The +project currently has no sponsors and thus no source of income to +pay for infrastructure costs and developer time. To ensure +Telodendria's long-term success, please consider sponsoring the +project. + +You can make a recurring donation to Telodendria using +[LiberaPay](https://bancino.net/Telodendria/donate). You can also make +one-time donations using +[Stripe](https://donate.stripe.com/8wM29AfF5bRJc48eUU). If you would +like to make a recurring donation larger than that allowed by +LiberaPay, please contact Jordan Bancino over Matrix at +`@jordan:bancino.net` or email at `jordan@bancino.net`. + +### Benefits + +While there are no set sponsorship tiers at this time, sponsoring +Telodendria is a mutually beneficial relationship. Depending on the +amount you donate, you can get your name, logo, and website links +on the [Sponsors](docs/SPONSORS.md) page, the project `README`, or the +main website. + +## License + +All of the code and documentation for Telodendria is licensed under a +modified MIT license. The MIT license is an extremely permissive +license that has very few restrictions. Please consult the +[`LICENSE.txt`](LICENSE.txt) file for the actual license text. It is +important to note that the Telodendria license text differs from the +original MIT license in the following ways: + +- Where the MIT license states that the copyright notice and permission +notice shall be included in all copies or *substantial* portions of the +software, the Telodendria requires the copyright notice and +permission notice be included with *all* portions, regardless of the +size, by omitting the word *substantial*. + +The Telodendria logo in all its forms, including the ASCII +representation, belongs solely to the Telodendria project. It must be +used only to represent the official Telodendria project. You are free +to use the logo in any way as long as it represents or links to the +official project. If Telodendria is forked, the logo must be removed +completely from the project, and optionally replaced by a different +one. -Please see the `README.txt` file for the actual project `README`, which simply details the repository structure a little bit. All of **Telodendria**'s user and developer documentation is available as `man` pages, or online. From d50372a91ab0cca8032c330d61dd5e0719dc8022 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 16:34:27 -0400 Subject: [PATCH 09/28] Add technical rationale document. --- README.md | 15 +++++++++++++ docs/dev/rationale.md | 50 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 docs/dev/rationale.md diff --git a/README.md b/README.md index f2a0d33..7a2e9d0 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ hosting a complicated, high-maintenance homeserver or joining an existing homeserver for privacy or other reasons, then Telodendria might be for you. +> **Note:** Telodendria still in development. See [Status](#status). + ## What is Matrix? Matrix is an **open standard** for *interoperable*, *decentralized*, @@ -71,6 +73,19 @@ Telodendria. ## Status +Telodendria is in the very early stages of development. As such, it may +not yet deliver on all of its promises. Currently, Telodendria is not +ready for end-users yet. While it features very basic user +authentication, it does not actually work as a chat server yet. + +We are hoping to ship Telodendria `v0.4.0` by May of 2024. This +release should be usable for communication between **local users** +only. Additional features, including federation with other Matrix +homeservers will be added in future releases. + +You can help speed up development by [sponsoring](#sponsorship) +Telodendria or [getting involved](docs/CONTRIBUTING.md). + ## Sponsorship Telodendria is maintained by a loosely-knit band of volunteers. The diff --git a/docs/dev/rationale.md b/docs/dev/rationale.md new file mode 100644 index 0000000..5358bc2 --- /dev/null +++ b/docs/dev/rationale.md @@ -0,0 +1,50 @@ +# Rationale + +This document seeks to answer the question of "why Telodendria?" from +a technical perspective by comparing it to existing Matrix homservers. +Telodendria is written entirely from scratch in ANSI C. It is designed +to be lightweight, simple, and functional. Telodendria differentiates +itself from other homeserver implementations because it: + +- Is written C, a stable, low-level programming language with a long +history, low build and runtime overhead, and wide compatibility. +- Is written with minimalism as a primary design goal. Whenever possible +and practical, no third-party libraries are pulled into the code. +Everything Telodnedria needs is custom written. As a result, Telodendria +depends only on a standard C compiler and a POSIX C library to be +built, both of which should come with any good Unix-style operating +system already, which means you shouldn't have to install anything +additional to use Telodendria. +- Uses a flat-file directory structure to store data instead of a +real database. This has a number of advantages: + - It make setup and mainenance much easier. + - It allows Telodendria to run on systems with fewer resources. +- Is packaged as a single small, statically-linked and highly-optimized +binary that can be run just about anywhere. It is designed to be +extremely easy to set up and consume as few resources as possible. +- Is permissively licensed. Telodendria is licensed under a modified +MIT license, which imposes very few restrictions on what you can do +with it. + +## What about [Conduit](https://conduit.rs)? + +At this point, you may be wondering why one would prefer Telodendria +over Conduit, a Matrix homeserver that could also say pretty much +everything this document has said so far. After all, Conduit is older +and thus better established, and written in Rust, a Memory Safe™ +programming language. + +In this section, we will discuss some additional advantages of +Telodendria that Conduit lacks. + +### Small Dependency Chain + +**TODO:** See #30. + +### Standardized + +**TODO:** See #30. + +### Portable + +**TODO:** See #30. From e4a217550ffaad6c8856b7b12f11c5097ced5eeb Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 16:40:33 -0400 Subject: [PATCH 10/28] Add logo and center title. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a2e9d0..f8efe63 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# [Telodendria](https://telodendria.io) +

+

Telodendria

Telodendria is an extremely powerful, yet lightweight and portable chat server designed to be easy to install and configure. Powered by From c78d075a93336942db63672fd003f6638187ae21 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 17:22:24 -0400 Subject: [PATCH 11/28] Add admin documentation home page. --- docs/CHANGELOG.md | 4 +- docs/README.md | 7 +- docs/user/admin/README.md | 22 ++++ docs/user/setup.md | 4 +- docs/user/usage.md | 2 +- man/man7/telodendria.7 | 221 -------------------------------------- 6 files changed, 33 insertions(+), 227 deletions(-) create mode 100644 docs/user/admin/README.md delete mode 100644 man/man7/telodendria.7 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 151ba19..15bb2ce 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -70,7 +70,7 @@ to add support for. a TLS port and a non-TLS port, for example. - Moved all program configuration to the data directory and added an administrator API endpoint to manage it. It is now no longer recommended to manually update the -configuration file. Consult the [Administrator API](user/admin.md) documentation +configuration file. Consult the [Administrator API](user/admin/README.md) documentation and the [Configuration](user/config.md) documentation. - Added an administrator API endpoint for process control. Telodendria can now be restarted or shutdown via API endpoint. @@ -242,4 +242,4 @@ This is the first public release of Telodendria so there are no changes to repor Future releases will have a complete change log entry here. This is a symbolic release targeted at developers, so there's nothing useful to -ordinary users yet. Stay tuned for future releases though! \ No newline at end of file +ordinary users yet. Stay tuned for future releases though! diff --git a/docs/README.md b/docs/README.md index 248f5fe..6d004b4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,11 @@ Here you will find all of the documentation for Telodendria. If you find that some documentation is missing or incorrect, please open an issue, and, even better, a pull request to fix the issue. +You are also welcome to join the +[`#telodendria-general:bancino.net`](https://matrix.to/#/#telodendria-general:bancino.net) +matrix room, where you can discuss Telodnedria with others and ask +questions. + ## User Documentation - [System Requirements](user/requirements.md) @@ -11,7 +16,7 @@ issue, and, even better, a pull request to fix the issue. - [Usage & Running](user/usage.md) - [Initial Set Up](user/setup.md) - [Configuration Options](user/config.md) -- [Administrator API](user/admin.md) +- [Administrator API](user/admin/README.md) ## Developer Documentation diff --git a/docs/user/admin/README.md b/docs/user/admin/README.md new file mode 100644 index 0000000..39f00d5 --- /dev/null +++ b/docs/user/admin/README.md @@ -0,0 +1,22 @@ +# Administrator API + +Telodendria provides an administrator API as an extension to the +Matrix specification that allows for administrator control over the +homeserver. This includes profiling and examining the state of +running instances, as well as managing users and media. + +Like Synapse, Telodendria supports designating specific local users as +administrators. However, unlike Synapse, Telodendria uses a more +fine-grained privilege model that allows a server administrator to +delegate specific administration tasks to other users while not +compromising and granting them full administrative access to the server. + +To authenticate with the administrator API, simply use your login +access token just like you would authenticate any other Matrix client +request. + +- [Privileges](privileges.md) +- [Configuration](config.md) +- [Server Statistics](stats.md) +- [Process Control(proc.md) + diff --git a/docs/user/setup.md b/docs/user/setup.md index ac0ebdf..ac1e336 100644 --- a/docs/user/setup.md +++ b/docs/user/setup.md @@ -26,7 +26,7 @@ source, execute the binary directly. If needed, consult the initialize its database directly with a simple—and, importantly, safe—default configuration, as well as a randomly generated, single-use registration token that grants a user all privileges -documented in the [Administrator API](admin.md) documentation. +documented in the [Administrator API](admin/README.md) documentation. Consult the log file for this administrator registration token. By default, the log file is located in the data directory, and is named `telodendria.log`. @@ -40,7 +40,7 @@ it also has all privileges granted to it, so it can make full use of the Administrator API. 1. Using the access token granted for the administrator account via the login process, configure Telodendria as descibed in -[Configuration](config.md). See the [Administrator API](admin.md) +[Configuration](config.md). See the [Administrator API](admin/README.md) documentation for the configuration endpoint details. This is the recommended way to set up Telodendria. However, if you diff --git a/docs/user/usage.md b/docs/user/usage.md index 8fcd604..838cc5d 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -9,7 +9,7 @@ testing or debugging purposes. ## Command Line Options Typically, Telodendria is controlled via the -[Administrator API](admin.md), but the Telodendria binary does include +[Administrator API](admin/README.md), but the Telodendria binary does include a few command line options, which can be used in init scripts or for debugging purposes. diff --git a/man/man7/telodendria.7 b/man/man7/telodendria.7 deleted file mode 100644 index 9dee9dc..0000000 --- a/man/man7/telodendria.7 +++ /dev/null @@ -1,221 +0,0 @@ -.Dd $Mdocdate: March 10 2023 $ -.Dt TELODENDRIA 7 -.Os Telodendria Project -.Sh NAME -.Nm Telodendria -.Nd Start here. This page contains the project introduction, and provides information about it, such as its status, how to contact the developers, and what the source code license is. -.Sh DESCRIPTION -.Nm -is an open source Matrix homeserver written entirely from scratch in ANSI C and -designed to be lightweight and simple, yet functional. -.Pp -.Nm -differentiates itself from the other Matrix homeserver -implementations because it: -.Bl -bullet -.It -Is written in C, a stable, low-level programming language with a -long history, low build and runtime overhead, and wide compatibility. -.It -Is written with minimalism as a primary design goal. Whenever possible -and practical, no third-party libraries are pulled into the source code. -Everything -.Nm -needs is custom written. As a result, -.Nm -depends only on a standard C compiler and a POSIX C library to be built, -both of which should come with any good Unix-style operating system already, -which means you shouldn't have to install anything extra. -.It -Uses a flat-file directory structure to store data instead of a database. -This has a number of advantages: -.Bl -bullet -.It -It makes setup and maintenance much easier. -.It -It allows -.Nm -to run on systems with fewer resources. -.El -.It -Is packaged as a single small, statically-linked and highly-optimized binary -that can be run just about anywhere. It is designed to be extremely easy to -set up and consume as few resources as possible. -.It -Is permissively licensed. -.Nm -is licensed under a modified MIT license, which imposes very few restrictions -on what you can do with it. -.El -.Pp -.Nm -is on Matrix! Check out the official Matrix rooms: -.Pp -.TS -box tab(;); -ll. -#telodendria:bancino.net;The public "space" room. -#telodendria-releases:bancino.net;Get notified of new releases. -#telodendria-general:bancino.net;General discussion and support. -#telodendria-newsletter:bancino.net;Periodic status updates. -#telodendria-issues:bancino.net;Report bugs and issues. -#telodendria-patches:bancino.net;Submit code patches to the project. -#telodendria-ports:bancino.net;Discussion about porting and packaging. -.TE -.Pp -.Nm -is designed to be fairly straightforward, but that doesn't mean there -won't be hiccups along the way. If you're struggling to get -.Nm -up and running, you're more than welcome to reach out for support. Just -hop into the appropriate Matrix rooms and talk to me! -.Sh RATIONALE -I want a lightweight Matrix homeserver designed specifically for OpenBSD, -and other Unix-like operating systems. I want a homeserver that can be -developed and compiled with built-in tools. I want it to function entirely -on a base OS install without having to install any packages whatsoever. I've -found that as far as these goals are concerned, the existing homeserver -implementations fall short. This project aims to prove that Matrix homeservers -can be lightweight and written in such a way that very few, if any, third-party -libraries need to be pulled in. -.Pp -I also want to learn how Matrix works, and I want to understand the code I'm -running on my server, which is why I'm writing every component from scratch, -even the HTTP server and router. -.Pp -The advantage of using a flat-file database instead of a real database is that -your data remains in a format that is incredibly easy to digest. Backups are -incredibly easy as well\(emjust -.Xr tar 1 -up the data directory and you're good to go. -.Sh PROJECT GOALS -The goals of this project are generally divided into user goals and developer -goals, depending on who they impact the most. This isn't an exaustive list -of the project's goals, but it is a list of things that I want to prioritize, -because other server implementations lack them. -.Pp -The user goals are as follows: -.Bl -bullet -.It -To implement the latest Matrix specification as fully and completely as possible. -All features defined by the specification should eventually be present in -.Nm . -.It -To be as privacy-friendly as possible. -.Nm -should not store any information it does not absolutely need to function as a -Matrix homeserver. While -.Nm -strives to be feature-complete, it should not implement anything not explicitly -defined in the Matrix specification. -.It -To be a production-ready Matrix server capable of working in constrained environments, -such as embedded devices, cheap VPSs, or a peer-to-peer device. -.Nm -should also work on traditional setups as well, and be able to handle a decent -amount of users. It should work well for personal Matrix homeservers that also -host a few friends and/or family members. -.It -To be easier to get up and running, and yet also be more configurable than other -Matrix homeserver implementations. The configuration file should be flexible, -well-documented, and easy to understand and modify. An intuitive command-line -tool for administrative tasks should also be available. -.El -.Pp -The developer goals are as follows: -.Bl -bullet -.It -To have as few build and runtime dependencies as possible. It should be possible -to compile and run -.Nm -on any POSIX operating system right out of the box. -.Nm -should be fully statically-linked, so it can run under a -.Xr chroot 3 . -Furthermore, it should be possible to read all the documentation offline, and -without any overly complicated tools. You'll notice that this documentation is -a collection of -.Xr man 1 -pages, not HTML or Markdown, to remove the dependency on a browser or Markdown -parser. Any Unix-like system has a manual page viewer, which makes the -documentation more accessible, even on remote systems that have no graphical -interface to read the documentation. This ensures that you can read the -documentation for the installed version of -.Nm -without having to go online. -.It -To have a simple yet elegant workflow, and not depend on any large or complex -development tools such as code forges. The entire development workflow should -be able to be successfully and efficiently completed on a base OpenBSD install. -Of course, you don't have to use OpenBSD for development, but the point is that -the workflow should require fairly standardized and simple tools. -.It -To write clean, elegant, well-tested, and well-documented code. The goal is to build -a Matrix homeserver from the ground up, not just because I don't like the way existing -homeservers are implemented, but also because I want to learn how Matrix works, -make it more accessible, and potentially teach others a little bit along the way. -.It -To foster a welcoming community. Many big communities such as Linux and OpenBSD -have hostile leaders. -.Nm -shouldn't have a hostile leader. I want to be as understanding as I can, and talk -through issues politely and in a civil manner. If I'm failing in this way, don't -be afraid to call me out! -.El -.Sh SEE ALSO -.Xr telodendria 8 , -.Xr telodendria.conf 5 , -.Xr td 1 -.Sh STANDARDS -The installed version of -.Nm -conforms to the latest Matrix specification available at the time -of its release. -.Sh HISTORY -.Pp -.Nm -was started in early July of 2022. For a change log of this -project, see -.Xr telodendria-changelog 7 . -.Sh AUTHORS -.Nm -was started by and is almost exclusively developed by -Jordan Bancino <@jordan:bancino.net>. Contributions to the code, -website, documentation, or other components of this project have -been made by various open source developers. -.Sh LICENSE -All of the code and documentation for -.Nm -is licensed under a modified MIT license. Please consult the -.Pa LICENSE.txt -file for the actual license text. The -.Nm -license text differs from the MIT license in the following ways: -.Bl -bullet -.It -Where the MIT license states that the copyright notice and permission -notice shall be included in all copies or -.Pa substantial -portions of the software, the -.Nm -license requires the copyright notice and permission notice be included -with -.Pa all -portions, regardless of the size, of the software by omitting the word -.Pa substantial . -.El -.Pp -The -.Nm -logo in all forms, including the ASCII representation, belongs solely -to the -.Nm -project. It must only be used to represent the official -.Nm -project, and may only appear in official -.Nm -media. If -.Nm -is forked, the logo must be removed completely from the project, and -optionally replaced with a different one. The logo may not be modified -in any way or for any purpose. From 9e2f047e82241bb7208a4b6e3dbc381b40d7db04 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 17:23:06 -0400 Subject: [PATCH 12/28] Fix typo in docs/user/admin/README.md --- docs/user/admin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/admin/README.md b/docs/user/admin/README.md index 39f00d5..de5f617 100644 --- a/docs/user/admin/README.md +++ b/docs/user/admin/README.md @@ -18,5 +18,5 @@ request. - [Privileges](privileges.md) - [Configuration](config.md) - [Server Statistics](stats.md) -- [Process Control(proc.md) +- [Process Control](proc.md) From 043c2e9e3338c102ae0ed856a4fa4b321f7c81db Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 23:26:47 -0400 Subject: [PATCH 13/28] Add privileges documentation. --- docs/user/admin/README.md | 14 ++++ docs/user/admin/privileges.md | 141 ++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 docs/user/admin/privileges.md diff --git a/docs/user/admin/README.md b/docs/user/admin/README.md index de5f617..827ef10 100644 --- a/docs/user/admin/README.md +++ b/docs/user/admin/README.md @@ -20,3 +20,17 @@ request. - [Server Statistics](stats.md) - [Process Control](proc.md) +## API Conventions + +Unless otherwise indicated, HTTP response codes that are not `200 Ok` +will be accompanied by a standard Matrix API error. Consult the Matrix +specification for the format of these errors. The following error +conditions are assumed to be possible for all API endpoints listed +in the Administrator API documentation: + +| Response Code | Description | +|---------------|-------------| +| 400 | The user is not authenticated, did not provide a valid JSON object, or provided a JSON object with invalid or missing parameters.| +| 403 | The user does not have the privileges necessary to carry out the requested action.| +| 500 | A fatal server error occurred. Check the logs for more information.| + diff --git a/docs/user/admin/privileges.md b/docs/user/admin/privileges.md new file mode 100644 index 0000000..35dea36 --- /dev/null +++ b/docs/user/admin/privileges.md @@ -0,0 +1,141 @@ +# Administrator API: Privileges + +This document describes the privilege model and the API endpoints that +allow administrators to modify privileges for users. + +## List Of Privileges + +A local user can have any of the following privileges. Unless otherwise +indicated, these privileges only grant access to certain parts of the +administrator API; the regular Matrix API is unaffected. + +- **DEACTIVATE:** Allows a user to deactivate any other local users. +- **ISSUE_TOKENS:** Allows a user to create, modify, and delete +registration tokens. +- **CONFIG:** Allows a user to modify the Telodendria server daemon's +configuration. +- **GRANT_PRIVILEGES:** Allows a user to modify his or her own +privileges or the privileges of other local users. +- **ALIAS:** Allows a user to modify room aliases created by other +users. By default, users can only manage their own room aliases, but +an administrator may wish to take over an alias or remove an offensive +alias. +- **PROC_CONTROL:** Allows a user to get statistics on the running +process, as well as shutdown and resetart the Telodendria daemon +itself. Typically this will pair well with **CONFIG**, because there +are certain configuration options that require the process to be +restarted to take full effect. + +There is also a special "pseudo-privilege": + +- **ALL:* Grants a user all of the aforementioned privileges, as well +as privileges that do not yet exist. That is, if an update to +Telodendria adds more privileges, users with this privilege will +automatically gain those new privileges in addition to having all the +existing privileges. This privilege should only be used with +fully-trusted users. It is typical for a server administrator to not +fully trust anyone else, and be the only one that holds an account with +this privilege level. + +## API Endpoints + +The following API endpoints are implemented for managing privileges. + +### **GET** `/_telodendria/admin/privileges/[localpart]` + +Retrieve the permissions for a user. If the localpart is omitted, then +retrieve the privileges for the user that owns the access token being +used. Note that the owner of the access token must have the +**GRANT_PRIVILEGES** privilege to use this endpoint. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully retrieved.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **POST** `/_telodendria/admin/privileges/[localpart]` + +Update the privileges of a local user by replacing the privileges array +with the one specified in the request. Like the **GET** version of this +endpoint, the localpart can be omitted to operate on the user that +owns the access token. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully replaced.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **PUT** `/_telodendria/admin/privileges/[localpart] + +Update the privileges of a local user by adding the privileges +specified in the request to the users existing privileges. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully added.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +### **DELETE** `/_telodendria/admin/privileges/[localpart]` + +Update the privileges of a local user by removing the privileges +specified in the request from the user's existing privileges. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The privileges were successfully removed.| + +#### Request Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| + From 6d6fd1645c4a2356b2f6e9f7eda1a9f60fa8da67 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 23:27:14 -0400 Subject: [PATCH 14/28] Fix typo in privileges.md. --- docs/user/admin/privileges.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/admin/privileges.md b/docs/user/admin/privileges.md index 35dea36..f098f35 100644 --- a/docs/user/admin/privileges.md +++ b/docs/user/admin/privileges.md @@ -28,7 +28,7 @@ restarted to take full effect. There is also a special "pseudo-privilege": -- **ALL:* Grants a user all of the aforementioned privileges, as well +- **ALL:** Grants a user all of the aforementioned privileges, as well as privileges that do not yet exist. That is, if an update to Telodendria adds more privileges, users with this privilege will automatically gain those new privileges in addition to having all the From 09023089f5ea11d7b6d9886602a77c97495d7493 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 23:27:55 -0400 Subject: [PATCH 15/28] Another typo. --- docs/user/admin/privileges.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/admin/privileges.md b/docs/user/admin/privileges.md index f098f35..8bbf143 100644 --- a/docs/user/admin/privileges.md +++ b/docs/user/admin/privileges.md @@ -89,7 +89,7 @@ owns the access token. |-------|------|-------------| | `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.| -### **PUT** `/_telodendria/admin/privileges/[localpart] +### **PUT** `/_telodendria/admin/privileges/[localpart]` Update the privileges of a local user by adding the privileges specified in the request to the users existing privileges. From a672c051127afbfedfc6d00f0770fc64d784112a Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 00:03:09 -0400 Subject: [PATCH 16/28] Finish moving over current Administrator API documentation. --- docs/user/admin/config.md | 42 ++++ docs/user/admin/proc.md | 49 ++++ docs/user/admin/stats.md | 24 ++ man/man7/telodendria-admin.7 | 421 ----------------------------------- 4 files changed, 115 insertions(+), 421 deletions(-) create mode 100644 docs/user/admin/config.md create mode 100644 docs/user/admin/proc.md create mode 100644 docs/user/admin/stats.md delete mode 100644 man/man7/telodendria-admin.7 diff --git a/docs/user/admin/config.md b/docs/user/admin/config.md new file mode 100644 index 0000000..0466403 --- /dev/null +++ b/docs/user/admin/config.md @@ -0,0 +1,42 @@ +# Administrator API: Configuration + +As mentioned in [Setup](../setup.md), Telodendria's configuration is +intended to be managed via the configuration API. Consult the +[Configuration](../config.md) document for a complete list of supported +configuration options. This document simply describes the API used to +update the configuration. + +## API Endpoints + +### **GET** `/_telodendria/admin/config` + +Retrieve the current configuration. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The current configuration was successfully retrieved.| + +### **POST** `/_telodendria/admin/config` + +Installs a new configuration. This endpoint validates the request body, +ensuring it is a proper configuration, then it replaces the existing +configuration with the new one. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The new configuration was successfully installed.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `restart_required` | `Boolean` | Whether or not the process needs to be restarted to finish applying the configuration. If this is `true`, then the restart endpoint should be used at a convenient time to apply the configuration. + diff --git a/docs/user/admin/proc.md b/docs/user/admin/proc.md new file mode 100644 index 0000000..4db33ec --- /dev/null +++ b/docs/user/admin/proc.md @@ -0,0 +1,49 @@ +# Administrator API: Process Control + +This document describes the administrator APIs that allow a server +administrator to manage the Telodendria process itself. + +## API Endpoints + +### **POST** `/_telodendria/admin/restart` + +Restart the Telodendria daemon cleanly. This endpoint will respond +immediately after signaling to the daemon that it should be restarted +as soon as possible. Note that the restart wmay not happen +instantaneously, as Telodendria will finish processing all current +requests before restarting. Also note that this is not a true restart; +the process does not exit and restart, rather, Telodendria simply tears +down all its state and then jumps back to the beginning of its code and +starts over. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The restart request was successfully sent.| + +On success, this endpoint simply returns an empty JSON object. + +### **POST** `/_telodendria/admin/shutdown` + +Shut down the Telodendria process cleanly. This endpoint will respond +immediately after signalling to the daemon that it should be shut +down as soon as possible. Note that the shutdown may not happen +instantaneously, as Telodendria will finish processing all current +requests before shutting down. Also note that once shut down, Telodendria +may be automatically restarted by the system's service manager. +Otherwise, it will have to be manually restarted. This is a true +shutdown; the Telodendria process exits as soon as possible. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The shutdown request was successfully sent.| + +On success, this endpoint simply returns an empty JSON object. + diff --git a/docs/user/admin/stats.md b/docs/user/admin/stats.md new file mode 100644 index 0000000..af421f8 --- /dev/null +++ b/docs/user/admin/stats.md @@ -0,0 +1,24 @@ +# Administrator API: Server Statistics + +The administrator API allows users with the proper privileges to get +information about how the server process is performing. + +## API Endpoints + +### **GET** `/_telodendria/admin/stats` + +Retrieve basic statistics about the currently running Telodendria +process. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +| 200 | The server statistics were successfully retrieved.| + +#### 200 Response Format + +| Field | Type | Description | +| `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.| +| `version` | `String` | The current version of Telodendria.| diff --git a/man/man7/telodendria-admin.7 b/man/man7/telodendria-admin.7 deleted file mode 100644 index 2fd0964..0000000 --- a/man/man7/telodendria-admin.7 +++ /dev/null @@ -1,421 +0,0 @@ -.Dd $Mdocdate: August 9 2023 $ -.Dt TELODENDRIA-ADMIN 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-admin -.Nd Administrator API documention. -.Sh DESCRIPTION -.Pp -Telodendria provides an administrator API that allows for administrator control -over the homeserver. This includes profiling and examining the state of Telodendria, -as well as managing users and media. -.Pp -Like Synapse, Telodendria supports designating specific users as administrators. -However, unlike Synapse, it uses a more finely-grained privilege model that allows -a server administrator to designate specific administration tasks to other users -while not compromising and granting them full administrative access to the server. -.Pp -To authenticate with the administrator API, simply use a regular -access token. -.Ss Privileges -.Pp -Here are all of the privileges a local user can have. Unless otherwise specified, -these privileges only grant access to certain parts of the administrator API; the -regular Matrix API is unaffected. -.Bl -tag -width -Ds -.It Dv DEACTIVATE -Allows a user to deactivate any other local users. -.It Dv ISSUE_TOKENS -Allows a user to create, modify, and delete registration tokens. -.It Dv CONFIG -Allows a user to modify the Telodendria server daemon's configuration. -.It Dv GRANT_PRIVILEGES -Allows a user to modify his or her own privileges or the privileges of other -local users. -.It Dv ALIAS -Allows a user to modify room aliases created by other users. By default, users -can only manage their own room aliases, but an administrator may wish to take -over an alias or remove an offensive alias. -.It Dv PROC_CONTROL -Allows a user to get statistics on the running process, as well as shutdown and -restart the Telodendria daemon itself. Typically this will pair well with -.Dv CONFIG , -because there are certain configuration options that require the process to be -restarted. -.El -.Pp -There is also a special ``pseudo-privilege'': -.Bl -tag -width Ds -.It Dv ALL -Grants a user all of the aforementioned privileges, as well as privileges that -do not yet exist. That is, if an update to Telodendria adds more privileges, -users with this privilege will automatically gain those new privileges in -addition to having all of the existing privileges. -.Pp -This privilege should only be used with fully-trusted users. It is typical for -a server administrator to not fully trust anyone else, and be the only one that -holds an account with this privilege level. -.El -.Sh API ENDPOINTS -.Pp -The following API endpoints are implemented for the installed version of -Telodendria. -.Pp -Unless otherwise indicated, HTTP response codes that are not 200 Ok -will be accompanied by a standard Matrix API error. Consult the Matrix specification -for the format of these errors. The following error conditions are assumed to be -possible for all of the endpoints listed here: -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -400;T{ -The user is not authenticated, did not provide a valid JSON object, -or provided a JSON object with invalid parameters. -T} -403;T{ -The user does not have the privileges necessary to carry out the -specified action. -T} -500;T{ -A fatal server error occured. Check the logs for more information. -T} -.TE -.Ss Sy GET No /_telodendria/admin/privileges/[localpart] -.Pp -Retrieve the permissions for a user. If the localpart is -omitted, then retrieve the privileges for the user that owns -the access token being used. Note that the owner of the -access token must have the -.Dv GRANT_PRIVILEGES -privilege. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The privileges were successfully retrieved. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy POST No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by replacing the -privileges array with the one specified in the request. -Like the -.Sy GET -version of this endpoint, the localpart can be omitted to -operate on the user that owns the access token. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The privileges were successfully replaced. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy PUT No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by adding the privileges -specified in the request to the user's existing privileges. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The requested privileges were successfully added. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy DELETE No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by removing the privileges -specified in the request from the user's existing privileges. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The requested privileges were successfully removed. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy POST No /_telodendria/admin/config -.Pp -Installs a new configuration. It validates the request body, ensuring it is a -proper configuration, then replaces the existing configuration with the new one. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token; Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The new configuration was successfully installed. -T} -.TE -.Pp -Consult the -.Xr telodendria-config 7 -manual page for a full description of the configuration object that should -be submitted. That page lists all the fields, and notes which ones are -required. -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -restart_required;Boolean;T{ -Whether or not the process needs to be restarted to finish applying the -configuration. If this is true, the restart endpoint may be used. -T} -.TE -.Ss Sy GET No /_telodendria/admin/config -.Pp -Retrieve the current configuration. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The current configuration was successfully retrieved. -T} -.TE -.Pp -Consult the -.Xr telodendria-config 7 -manual page for a full description of the configuration object that -is returned. Note that this is the same object that was submitted -using the -.Sy POST -version of this endpoint, otherwise it is the default configuration. -.Ss Sy GET No /_telodendria/admin/stats -.Pp -Retrieve statistics about the currently running Telodendria process. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The server statistics were successfully retrieved. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -memory_allocated;Integer;T{ -The total amount of memory allocated, measured in bytes. -T} -version;String;T{ -The current version of Telodendria. -T} -.TE -.Ss Sy POST No /_telodendria/admin/restart -.Pp -Restart the Telodendria daemon cleanly. This endpoint will respond immediately -after signaling to the daemon that it should be restarted as soon as possible. -Note that the restart may not happen instantaneously, as Telodendria will finish -processing all current requests before restarting. Also note that this is not a -``true'' restart; the process does not exit and restart, rather, Telodendria -simply tears down its state, and then jumps back to the beginning of its code -and starts over. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The restart request was successfully sent. -T} -.TE -.Pp -On success, this endpoint simply returns an empty JSON object. -.Ss Sy POST No /_telodendria/admin/shutdown -.Pp -Shut down the Telodendria process cleanly. This endpoint will respond immediately -after signaling to the daemon that it should be shut down as soon as possible. -Note that the shutdown may not happen instantaneously, as Telodnedria will -finish processing all current requests before shutting down. Also note that once -shut down, Telodendria may be automatically restarted by the system's service -manager, otherwise, it will have to be manually restarted. This is a ``true'' -shutdown, the Telodendria process exits as soon as possible. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The shutdown request was successfully sent. -T} -.TE -.Pp -On success, this endpoint simply returns an empty JSON object. -.Sh SEE ALSO -.Xr telodendria-config 7 , -.Xr telodendria-setup 7 From 61f7ab10409b572b4b4db8030b95ba26381384a3 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 00:11:32 -0400 Subject: [PATCH 17/28] Fix table rendering in stats.md --- docs/user/admin/stats.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user/admin/stats.md b/docs/user/admin/stats.md index af421f8..49eef5e 100644 --- a/docs/user/admin/stats.md +++ b/docs/user/admin/stats.md @@ -20,5 +20,6 @@ process. #### 200 Response Format | Field | Type | Description | +|-------|------|-------------| | `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.| | `version` | `String` | The current version of Telodendria.| From ac3582ddeb775d9b7b02efe6b2527b05ce70291b Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 00:11:32 -0400 Subject: [PATCH 18/28] Fix table rendering in stats.md --- docs/user/admin/stats.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/user/admin/stats.md b/docs/user/admin/stats.md index af421f8..bbebb7f 100644 --- a/docs/user/admin/stats.md +++ b/docs/user/admin/stats.md @@ -15,10 +15,12 @@ process. | Yes | Yes | | Response Code | Description | +|---------------|-------------| | 200 | The server statistics were successfully retrieved.| #### 200 Response Format | Field | Type | Description | +|-------|------|-------------| | `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.| | `version` | `String` | The current version of Telodendria.| From 08594e0fb1f74a5451fc8c0017cb2ccc47e65ac0 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 15:28:33 -0400 Subject: [PATCH 19/28] Add Gitea issue templates. --- .gitea/issue_template/bug_report.yaml | 47 ++++++++++++++++++++++ .gitea/issue_template/config.yaml | 7 ++++ .gitea/issue_template/feature_request.yaml | 18 +++++++++ 3 files changed, 72 insertions(+) create mode 100644 .gitea/issue_template/bug_report.yaml create mode 100644 .gitea/issue_template/config.yaml create mode 100644 .gitea/issue_template/feature_request.yaml diff --git a/.gitea/issue_template/bug_report.yaml b/.gitea/issue_template/bug_report.yaml new file mode 100644 index 0000000..8f468ad --- /dev/null +++ b/.gitea/issue_template/bug_report.yaml @@ -0,0 +1,47 @@ +name: Bug Report +about: File a bug report regarding Telodendria, its website, or its documentation. +body: + - type: markdown + attributes: + value: | + You are submitting a bug report. Please be sure to fill out the + title with a brief description of the bug. + - type: dropdown + attributes: + label: Type + description: Select the type of issue. + options: + - Memory Leak + - Crash + - Unexpected Error Message + - Documentation + - Website + - Other + validations: + required: true + - type: textarea + attributes: + label: Description + description: | + Please give a thorough and detailed description of the bug you + are reporting. Provide all the information you have, and do + some investigating to ensure you are providing a legitimate + issue report that is well thought out. + validations: + required: true + - type: textarea + attributes: + label: Log Output + description: | + Please copy and paste the relevant sections of the log output, + or the entire log if it is not unreasonably large. The logs + will be automatically formatted, no code block is necessary. + render: shell + validations: + required: true + - type: markdown + attributes: + value: | + Please attach any additional files that may aid in our + investigation of this issue, including screenshots, debugging + session stack traces and dumps, etc. diff --git a/.gitea/issue_template/config.yaml b/.gitea/issue_template/config.yaml new file mode 100644 index 0000000..2f86391 --- /dev/null +++ b/.gitea/issue_template/config.yaml @@ -0,0 +1,7 @@ +blank_issues_enabled: true +contact_links: + - name: General Matrix Room + - url: https://matrix.to/#/#telodendria-general:bancino.net + - about: | + General discussion on Telodendria happens in this Matrix room. You + may get quicker feedback from there. diff --git a/.gitea/issue_template/feature_request.yaml b/.gitea/issue_template/feature_request.yaml new file mode 100644 index 0000000..db9a188 --- /dev/null +++ b/.gitea/issue_template/feature_request.yaml @@ -0,0 +1,18 @@ +name: Feature Request +about: Request a new feature or enhancement be added to Telodendria. +title: "[Feature] " +body: + - type: markdown + attributes: + value: | + You are submitting a feature request. Please be sure to fill + out the title with a brief description of the feature you are + requesting. + - type: textarea + attributes: + label: Description + description: | + Please give a thorough and detailed description of the feature + you are requesting. + validations: + required: true From 1a009e87c37a5fd2b98bff5ea2e767296db30fdd Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 15:32:43 -0400 Subject: [PATCH 20/28] Fix a few small bugs in Gitea templates. --- .gitea/issue_template/bug_report.yaml | 4 ++-- .gitea/issue_template/config.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.gitea/issue_template/bug_report.yaml b/.gitea/issue_template/bug_report.yaml index 8f468ad..4374549 100644 --- a/.gitea/issue_template/bug_report.yaml +++ b/.gitea/issue_template/bug_report.yaml @@ -27,8 +27,8 @@ body: are reporting. Provide all the information you have, and do some investigating to ensure you are providing a legitimate issue report that is well thought out. - validations: - required: true + validations: + required: true - type: textarea attributes: label: Log Output diff --git a/.gitea/issue_template/config.yaml b/.gitea/issue_template/config.yaml index 2f86391..16465fe 100644 --- a/.gitea/issue_template/config.yaml +++ b/.gitea/issue_template/config.yaml @@ -3,5 +3,5 @@ contact_links: - name: General Matrix Room - url: https://matrix.to/#/#telodendria-general:bancino.net - about: | - General discussion on Telodendria happens in this Matrix room. You - may get quicker feedback from there. + General discussion on Telodendria happens in this Matrix room. You + may get quicker feedback from there. From 419017bcc986c653a9b5424b01ac6922641fd57d Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 15:36:58 -0400 Subject: [PATCH 21/28] Don't allow blank issues. --- .gitea/issue_template/bug_report.yaml | 4 +++- .gitea/issue_template/config.yaml | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.gitea/issue_template/bug_report.yaml b/.gitea/issue_template/bug_report.yaml index 4374549..5763976 100644 --- a/.gitea/issue_template/bug_report.yaml +++ b/.gitea/issue_template/bug_report.yaml @@ -26,7 +26,9 @@ body: Please give a thorough and detailed description of the bug you are reporting. Provide all the information you have, and do some investigating to ensure you are providing a legitimate - issue report that is well thought out. + issue report that is well thought out. **Include details on + how to reproduce the issue, or explicitly state that you were + unable to reproduce it.** validations: required: true - type: textarea diff --git a/.gitea/issue_template/config.yaml b/.gitea/issue_template/config.yaml index 16465fe..5c7fb3b 100644 --- a/.gitea/issue_template/config.yaml +++ b/.gitea/issue_template/config.yaml @@ -1,4 +1,4 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - name: General Matrix Room - url: https://matrix.to/#/#telodendria-general:bancino.net From 9e8523d92e192a68580095b4e675324e8d55b7a2 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 15:39:12 -0400 Subject: [PATCH 22/28] Fix issue config. --- .gitea/issue_template/config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitea/issue_template/config.yaml b/.gitea/issue_template/config.yaml index 5c7fb3b..30ef6e4 100644 --- a/.gitea/issue_template/config.yaml +++ b/.gitea/issue_template/config.yaml @@ -1,7 +1,7 @@ blank_issues_enabled: false contact_links: - name: General Matrix Room - - url: https://matrix.to/#/#telodendria-general:bancino.net - - about: | + url: "https://matrix.to/#/#telodendria-general:bancino.net" + about: | General discussion on Telodendria happens in this Matrix room. You may get quicker feedback from there. From 7a091c5b93c3482130edbc6036e258c12baa04df Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 16:50:38 -0400 Subject: [PATCH 23/28] Add contributing documentation. --- .gitea/pull_request_template.md | 25 +++ docs/CONTRIBUTING.md | 161 +++++++++++++++++ docs/user/install.md | 11 +- man/man7/telodendria-contributing.7 | 268 ---------------------------- 4 files changed, 196 insertions(+), 269 deletions(-) create mode 100644 .gitea/pull_request_template.md create mode 100644 docs/CONTRIBUTING.md delete mode 100644 man/man7/telodendria-contributing.7 diff --git a/.gitea/pull_request_template.md b/.gitea/pull_request_template.md new file mode 100644 index 0000000..24cea71 --- /dev/null +++ b/.gitea/pull_request_template.md @@ -0,0 +1,25 @@ + +--- + +Please review the developer certificate of origin: + +1. The contribution was created in whole or in part by me, and I have +the right to submit it under the open source licenses of the +Telodendria project; or +1. The contribution is based upon a previous work that, to the best of +my knowledge, is covered under an appropriate open source license and +I have the right under that license to submit that work with +modifications, whether created in whole or in part by me, under the +Telodendria project license; or +1. The contribution was provided directly to me by some other person +who certified (1), (2), or (3), and I have not modified it. +1. I understand and agree that this project and the contribution are +made public and that a record of the contribution—including all +personal information I submit with it—is maintained indefinitely +and may be redistributed consistent with this project or the open +source licenses involved. + +- [ ] I have read the Telodendria Project development certificate of +origin, and I certify that I have permission to submit this patch +under the conditions specified in it. + diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..23ed244 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,161 @@ +# Contributing + +Telodendria is a fully open source project. As such, it welcomes +contributions. There are many ways you can contribute, and any way you +can is greatly appreciated. This document details the ways you can +contribute, and how to go about contributing. + +## Sponsoring Telodendria + +If you would like to sponsor Telodendria, see the +[Sponsorship](../README.md#sponsorship) section on the main project +page. Donations of any size are greatly appreciated. + +## Reporting Issues + +An important way to get involved is to just report issues you find with +Telodendria during experimentation or normal use. To report an issue, +go to [Issues](/Telodendria/telodendria/issues) → +[New Issue](/Telodendria/telodendria/issues/new) and follow the +instructions. + +> **Note:** GitHub issues are not accepted. Issues may only be +> submitted to the official [Gitea](https://git.telodendria.io) +> instance. + +### Feature Requests + +Feature requests are allowed, but note that they are low-priority in +comparison to existing issues and features. That being said, don't +hesitate to submit feature requests. Just select the "Feature Request" +option when submitting an issue. + +## Developing + +If you want to write code for Telodendria, either to fix an issue or +add a new feature, you're in the right place. Please follow all the +guidelines in this document to ensure the contribution workflow goes +as smoothly as possible. + +### Who can develop Telodendria? + +Everyone is welcome to contribute code to Telodendria, provided that +they are willing to license their contributions under the same license +as the project itself. + +The primary language used to write Telodendria code is ANSI C. Other +languages you'll find in the Telodendria repository include shell +scripts, `mdoc`, a little bit of HTML and CSS, and `Makefiles`. +Experience with any of these is preferred, but if you want to use +Telodendria to learn, that's okay too! Telodendria's code base should +hopefully be a good learning tool, and if you are serious about +submitting quality work, we'll guide you through the process and +offer suggestions. + +### What do I need? + +You'll need a couple of things to develop Telodendria: + +- A Unix-like operating system that provides standard POSIX behavior, +or the Windows Subsystem for Linux (WSL), Cygwin, or Msys2 if you are +running Windows. +- A C compiler capable of compiling ANSI C89 code (pretty much all of +them do—pick your favorite, and if you find it doesn't work, +open an issue!). +- `make` for building the project. +- `git` for managing your changes. + +Optionally, you may also find these tools helpful: + +- `indent` for formatting code. +- `valgrind` for debugging particularly nasty issues. + +### Getting The Code + +Telodendria is developed using Git. The easiest way to contribute +changes is to fork the main repository, and then creating a pull +request to ask us to pull your changes into our repo. + +1. If you don't have an account on the +[Gitea instance](https://git.telodendria.io), create one and sign in. +1. Fork this repository. +1. In your development environment, clone your fork: + ```shell + git clone https://git.telodendria.io/[YOUR_USERNAME]/telodendria.git + cd telodendria + ``` + + Please base your changes on the `master` branch. If you need help + getting started with Git, that is beyond the scope of this + document, but you can find many good tutorials on the web. + +### Building & Running + +Telodendria uses the `make` build system. + +**TODO:** Update this section before #19 is closed. Provide quick +make, run, and install directions (maybe just redirect to Porting for +install directions), then list all the `make` recipes. Shouldn't be +as many as were in `td`. + +### Pull Requests + +> **Note:** Telodendria does not accept GitHub pull requests at this +> time. Please submit your pull requests via Gitea. + +Telodendria follows the standard pull request procedures. Once you have +made your changes, committed them, and pushed to your fork, you should +be able to open a pull request on the main repository. When you do, you +will be prompted to write a description + +### Code Style + +In general, these are the conventions used by the code base. This +guide may be slightly outdated or subject to change, but it should be +a good start. The source code itself is always the absolute source of +truth, so as long as you make your code look like the code surrounding +it, you should be fine. + +- All function, enumeration, structure, and header names are +`CamelCase`. This is preferred to `snake_case` because it is more +compact. +- All variable names are `lowerCamelCase`. This is preferred to +`snake_case` because it is more compact. One exception to this rule is +if a variable name, such as a member of a struct, directly represents +a JSON key in an object specified by the Matrix specification, which +may be in `snake_case`. +- Enumerations and structures are always `typedef`-ed to their same +name. The `typedef` should occur in the public API header, and the +actual declaration should live in the implementation file, unless +the enumeration or structure is intended to be made fully public. +- A feature of the code base lives in a single C source file that has a +matching header. The header file should only export public symbols; +everything else in the C source should be static. +- Except where absolutely necessary, global variables are forbidden +to prevent problems with threads and whatnot. Every variable a +function needs should be passed to it either through a structure, or +as a separate argument. +- Anywhere that C allows curly braces to be optional, there still must +be curly braces. This makes it easier to read the code by making it +less ambiguous, and it makes it easier to add on to the code later. + +As far as actually formatting the code goes, such as where to put +brackets, and whether or not to use tabs or spaces, use `indent` to +take care of that. The repository contains a `.indent.pro` that should +automatically be loaded by `indent` to set the correct rules. If you +don't have a working `indent`, then just indicate in your pull +request that I should run my `indent` on the code. + +### Documentation + +This project places a strong emphasis on documentation. Well-documented +code is fundamental to a successful project, so when you are writing +code, please also make sure that it is documented appropriately. + +- If you are adding a header, make sure you add the necessary comments +detailing the header and the functions in it. +- If you are adding a function, make sure you add the necessary +comments to the appropriate header. + +If your pull request does not also include proper documentation, it +will likely be rejected. diff --git a/docs/user/install.md b/docs/user/install.md index 56a8f30..7d955bd 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -48,4 +48,13 @@ binaries. ## From Source -**TODO:** Update this section before #19 is closed. +If you would like to build Telodendria from source, you can download +the latest release code from the +[Releases](/Telodendria/telodendria/releases) page. After extracting +the tarball, read +[Contributing → Developing → Building & Running](../CONTRIBUTING#building-and-running) +for details on how to build Telodendria. + +If all goes well, you will find the server binary in the `build/` +directory. If an error occured, and you didn't modify the code, +please open an issue. diff --git a/man/man7/telodendria-contributing.7 b/man/man7/telodendria-contributing.7 deleted file mode 100644 index 1aceb96..0000000 --- a/man/man7/telodendria-contributing.7 +++ /dev/null @@ -1,268 +0,0 @@ -.Dd $Mdocdate: March 10 2023 $ -.Dt TELODENDRIA-CONTRIBUTING 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-contributing -.Nd Guide to contributing to the Telodendria project. -.Sh DESCRIPTION -Telodendria is an open source project. As such, it welcomes -contributions. There are many ways you can contribute, and any -way you can is greatly appreciated. This page contains some of -the ways you can help out. -.Sh REPORTING ISSUES -Please reach out to the Matrix rooms mentioned at the top of -.Xr telodendria 7 . -All issue tracking takes place in those rooms. Start by reaching -out to the general room, and if you think there's a legitimate -problem with Telodendria itself, then stick the issue in the -issues room, where it can be discussed further. Issues usually -remain in the Matrix rooms, but severe enough issues may be put -in a -.Pa TODO -file in the -.Xr cvs 1 -repository so that they don't get lost. -.Sh DEVELOPING -The primary language used to write Telodendria code is ANSI C. -Other languages you'll find in the Telodendria repository include -shell scripts, -.Xr mdoc 7 , -and a little bit of HTML and CSS. If you have any experience with -any of these languages, your contributions are valuable! Please follow -the guidelines on this page to ensure the contribution workflow goes -as smoothly as possible. -.Ss Getting the Code -If you'd like to hack on Telodendria, you'll need the following tools -in addition to a C compiler and POSIX shell: -.Bl -tag -.It Xr cvs 1 -For checking out and updating your local copy of the source code. -.It Xr indent 1 -For formatting your code before generating patches. -.It Xr patch 1 -For applying patches to your local copy of the source code. -.El -.sp -All of these tools are built into OpenBSD. While you don't have to -use OpenBSD to develop Telodendria, it may make the process a bit -easier. In fact, these tools where chosen precisely because they -were built into my operating system of choice. -.sp -You can download an official release tarball from the website if -you would really like, but the preferred way to get the source -code for development is to check it out from CVS. This makes generating -patches a lot easier. -.Bd -literal -offset indent -$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria -$ cd Telodendria -.Ed -.sp -If you already checked out the code previously, make sure you update -your local copy before you start developing: -.Bd -literal -offset indent -$ cvs -q update -dP -.Ed -.sp -You should now have the latest source code. Follow the -.Sx CODE STYLE -as you make your changes. If the -.Xr cvs 1 -command fails with a "Connection refused" error message, try setting -the -.Ev CVS_RSH -environment variable to "ssh", like this: -.Bd -literal -offset indent -$ export CVS_RSH=ssh -.Ed -.sp -Then run the checkout command again. Some versions of CVS on some -systems don't use SSH to checkout by default, so if yours doesn't, -you might want to put the above line into your shell init script. -.Ss Submitting Patches -Telodendria aims at remaining as minimal as possible. This doesn't just -mean minimal code, it also means a minimal development process, which is -why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead, -the contribution workflow operates on submitting patch files to a public -Matrix room, sort of like the OpenBSD project operates on patch files -sent to a public mailing list. -.sp -If you're not used to manually creating and submitting patches instead of -just opening a "pull request," you should be pleased to hear that submitting -patches is fairly easy to do if you've got the CVS sources checked out. In -fact, I find it easier than having to make a GitHub account, forking a -project's repository, and then making a pull request for it. Once you have -made your changes in your local copy of the code, and you've configured your -environment properly as noted in the manual for -.Xr td 1 , -just run the patch recipe: -.Bd -literal -offset indent -$ td patch -.Ed -.sp -This will automatically generate a patch file for all your changes, and then -open it in your preferred editor. You can also generate a patch file for only -certain files and directories. To do that, set -.Ev PATCHSET , -like this: -.Bd -literal -offset indent -# Only write a patch for README.txt and the files in docs/ -$ PATCHSET="README.txt docs/" td patch -.Ed -.sp -As you'll notice, the top of the patch file should have some email-style -headers that look like this: -.Bd -literal -offset indent -From: Jordan Bancino <@jordan:bancino.net> -Date: Fri Jul 29 03:21:21 PM EDT 2022 -Subject: Document Patch Procedure -.Ed -.sp -As much information should be filled out for you, such as the date. An -attempt to fill out the From header was also made by -.Xr td 1 , -but the information there can be modifed as necessary. Consult the manual -for -.Xr td 1 -for more details. The Subject should very briefly describe what the patch -is about. -.sp -You'll also notice these lines in the patch: -.Bd -literal -offset indent -[ ] I have read the Telodendria Project development certificate of - origin, and certify that I have permission to submit this patch - under the conditions specified in it. -.Ed -.sp -This is a checkbox that tells me whether or not you actually have the -rights to submit your patch, and that once you submit your patch, your -code is bound by the Telodendria project license, which you can and -should view in -.Xr telodendria 7 . -The full text of the developer certificate of origin is as follows: -.Bl -enum -.It -The contribution was created in whole or in part by me, and I have the right -to submit it under the open source licenses of the Telodendria project; or -.It -The contribution is based upon a previous work that, to the best of my knowledge, -is covered under an appropriate open source license and I have the right under -that license to submit that work with modifications, whether created in whole -or in part by me, under the Telodendria project license; or -.It -The contribution whas provided directly to me by some other person who certified -(1), (2), or (3), and I have not modifed it. -.It -I understand and agree that this project and the contribution are made public -and that a record of the contribution\(emincluding all personal information -I submit with it\(emis maintained indefinitely and may be redistributed -consistent with this project or the open source licenses involved. -.El -.sp -If you agree to the above, fill in the square brackets with an 'x', and then after -the headers, but before the checkbox, write a more thorough description of the -patch and why it was created. Then, send the resulting patch file to the public -Matrix room using -.Xr send-patch 1 . -.sp -Try to keep your patches on topic\(emmake one patch file per feature or bug fix -being implemented. It is okay if your patches depend on previous patches, just -indicate that in the patch description. Note that it may take a while for -patches to be committed, and some patches may not be comitted at all. In either -case, all sent patches are queued from the Matrix room into the public patch -directory, so they can be referenced easier in the future. If you want to -reference a submitted patch in a Matrix message, email, or other digital medium, -it might be a good idea to link to it in the public patch directory. -.sp -The public patch directory works as follows: when you send your patch to the -Matrix room, it is downloaded by Telodendria Bot and placed in the -.Pa ingress/ -directory, named as the message ID. Then, it is assigned a patch ID and -copied to the -.Pa p/ -directory as just "%d.patch", where "%d" is obviously the patch ID. This is -a permanent link that will always reference your patch. Then, your patch will -be symlinked into the -.Pa queue/ -directory. I have a script that automatically ingresses patches and queues them -for me, and I use this to review patches. If your patch is accepted, the queue -symlink will be moved to -.Pa accepted/ -and the submitted patch will be committed to the official CVS repository. -If your patch is rejected for some reason, its symlink will be moved to the -.Pa rejected/ -directory. Regardless of the state of your patch, it will always remain -permalinked in the -.Pa p/ -directory, and when it is accepted or rejected, Telodendria Bot will send a -message to the Matrix room. -.sp -You're always welcome to inquire about rejected patches, and request that they -be reviewed again, or you can use them as a starting point for future patches. -.sp -The public patch directory is located at -.Lk https://telodendria.io/patches/ -.Sh CODE STYLE -In general, these are the conventions used by the code base. This guide -may be slightly outdated or subject to change, but it should be a good -start. The source code itself is always the absolute source of truth, so -as long as you make your code look like the code surrounding it, you should -be fine. -.Bl -bullet -.It -All function, enumeration, structure, and header names are CamelCase. This -is preferred to snake_case because it is more compact. -.It -All variable names are lowerCamelCase. This is preferred to snake_case -because it is more compact. -.It -enumerations and structures are always typedef-ed to their same name. The -typedef should occur in the public API header, and the actual declaration -should live in the implementation file. -.It -A feature of the code base lives in a single C source file that has a -matching header. The header file should only export public symbols; -everything else in the C source should be static. -.It -Except where absolutely necessary, global variables are forbidden to -prevent problems with threads and whatnot. Every variable a function -needs should be passed to it either through a structure, or as a -separate argument. -.It -Anywhere curly braces are optional, there still must be curly braces. This -makes it easier to add on to the code later, and just makes things a bit -less ambiguous. -.El -.sp -As far as actually formatting the code goes, such as where to put brackets, -and whether or not to use tabs or spaces, use -.Xr indent 1 -to take care of all of that. The root of the CVS repository has a -.Pa .indent.pro -that should automatically be loaded by -.Xr indent 1 -to set the correct rules. If you don't have a working -.Xr indent 1 , -then just indicate in your patch that I should run my -.Xr indent 1 -on the code after applying it. Although in reality, I'll likely -run my own -.Xr indent 1 -on the code anyway, just to make sure the spacing is consistent, if nothing -else. -.Pp -This project places a strong emphasis on documentation. Well-documented -code is fundamental to a successful project, so when you are writing code, -please also make sure it is documented appropriately. -.Bl -bullet -.It -If you are adding a header, make sure you add a man page that documents -all the functions in the header. -.It -If you're adding a function, make sure you add documentation for it -to the appropriate man page for the header that your function resides -in. Do note that you do not have to document static functions, only -public API functions. -.El -.Pp -If your patch does not also include proper documentation, it will -likely be rejected. From 024482d4e8f01e63bac5acd01f64ce5f15c73cc2 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 16:57:52 -0400 Subject: [PATCH 24/28] Put the finishing touches on `CONTRIBUTING.md`. --- docs/CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 23ed244..0faf4ac 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -16,7 +16,7 @@ page. Donations of any size are greatly appreciated. An important way to get involved is to just report issues you find with Telodendria during experimentation or normal use. To report an issue, go to [Issues](/Telodendria/telodendria/issues) → -[New Issue](/Telodendria/telodendria/issues/new) and follow the +[New Issue](/Telodendria/telodendria/issues/new/choose) and follow the instructions. > **Note:** GitHub issues are not accepted. Issues may only be @@ -106,7 +106,8 @@ as many as were in `td`. Telodendria follows the standard pull request procedures. Once you have made your changes, committed them, and pushed to your fork, you should be able to open a pull request on the main repository. When you do, you -will be prompted to write a description +will be prompted to write a description. Be sure to include the +related issue that you are closing in your description. ### Code Style @@ -159,3 +160,4 @@ comments to the appropriate header. If your pull request does not also include proper documentation, it will likely be rejected. + From 6dcfa7dc025c0e8e72ff10b789383284f247573d Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 16:58:47 -0400 Subject: [PATCH 25/28] Remove `send-patch` and `tp`. See #20. --- man/man1/send-patch.1 | 57 -------------- man/man1/tp.1 | 63 ---------------- tools/bin/send-patch | 167 ------------------------------------------ tools/bin/tp | 148 ------------------------------------- 4 files changed, 435 deletions(-) delete mode 100644 man/man1/send-patch.1 delete mode 100644 man/man1/tp.1 delete mode 100755 tools/bin/send-patch delete mode 100755 tools/bin/tp diff --git a/man/man1/send-patch.1 b/man/man1/send-patch.1 deleted file mode 100644 index c3d665f..0000000 --- a/man/man1/send-patch.1 +++ /dev/null @@ -1,57 +0,0 @@ -.Dd $Mdocdate: April 29 2023 $ -.Dt SEND-PATCH 1 -.Os Telodendria Project -.Sh NAME -.Nm send-patch -.Nd Submit a patch file to the Telodendria Patches Matrix room -.Sh SYNOPSIS -.Nm -.Op patch -.Sh DESCRIPTION -.Nm -is a simple shell script for submitting patch files to Telodendria's patch -room for review. -.Pp -.Nm -takes a single argument, a patch file. It also reads a number of environment -variables, as described in the following section. This script is designed to be -simple; it only pushes files into a hard-coded Matrix room. Thus, as far as -Matrix clients go, this one is a rather minimal one, and that is by design. -.Pp -This script exists so that users who are working on a machine that doesn't have -a Matrix client installed can still submit work to the Telodendria project. The -goal is to make development as accessible as possible. -.Pp -This script only supports password login, so if your homeserver does not -support password login, it will not work. -.Sh ENVIRONMENT -.Pp -.Nm -utilizes the following environment variables: -.Bl -tag -width Ds -.It Ev MXID -Your Matrix ID in the standard format. This is used to connect to your -homeserver to send the message. -.It Ev MXPW -Your Matrix account's password. If not set, you will be prompted for your -password by the script, unless -.Ev ACCESS_TOKEN -is set. -.It Ev ACCESS_TOKEN -If you already have an access token for your account, such as one from an -existing session, then you can set this environment variable to bypass the -password authentication flow. -.El -.Sh FILES -.Pp -.Nm -does utilize the -.Pa .env -file, just like -.Xr td 1 . -Consult that page for the specifics of the -.Pa .env -file. -.Sh SEE ALSO -.Xr td 1 - diff --git a/man/man1/tp.1 b/man/man1/tp.1 deleted file mode 100644 index f2dea09..0000000 --- a/man/man1/tp.1 +++ /dev/null @@ -1,63 +0,0 @@ -.Dd $Mdocdate: April 29 2023 $ -.Dt TP 1 -.Os Telodendria Project -.Sh NAME -.Nm tp -.Nd Manage the official patch queue. -.Sh SYNOPSIS -.Np -.Op action -.Op patch -.Sh DESCRIPTION -.Pp -This script is probably not going to be very useful for anyone other -than the official project managers, but for completeness, this page -documents it. -.Pp -.Nm -is a simple script that is used to manage the patch queue. It offers a -simple way to fetch patches from the patch Matrix room and queue them -in a patch directory, which is then updated as patches are handled. -Contributions to Telodendria are entirely patch-based, so this script -makes dealing with patch files much more convenient. -.Pp -.Nm -doesn't implement a complex command line interface. It simply takes an -action as the first argument, and a patch file ID as the second -argument to some actions. The actions are as follows: -.Bl -tag -width Ds -.It ingress -Download all new patches from the patches room. This action is intended -to be called periodically from -.Xr cron 8 -to fetch new patches. -.It queue -List all the patches in the queue, printing the first three lines of -each one so they can be easily identified. -.It view -View the specified patch. Note that the specified patch must be in -the queue. Once it is applied or rejected, this script offers no -facility for viewing it. -.It apply -Apply the specified patch to the current working directory. -.It reverse -Reverse the specified patch on the current working directory. -.It accept|reject -Accept or reject the specified patch by moving it to the appropriate -directory. These actions also prompt for a message, into which it is -expected that an explanation for why the patch was accepted or rejected -will be placed. -.El -.Sh ENVIRONMENT -.Pp -The following environment variables are read by the -.Nm -script: -.Bl -tag -width Ds -.It Ev TELODENDRIA_PUB -The base directory inside which the patch directory relies. -.It Ev HOMESERVER -The Matrix homeserver to contact for receiving patches. -.It Ev ACCESS_TOKEN -The access token to use to authenticate with the Matrix homeserver. -.El diff --git a/tools/bin/send-patch b/tools/bin/send-patch deleted file mode 100755 index ca4d416..0000000 --- a/tools/bin/send-patch +++ /dev/null @@ -1,167 +0,0 @@ -#!/usr/bin/env sh -# -# send-patch: "The Telodendria Patch Sender" -# -# This is a simple script for posting patch files to -# a single room(generally the Telodendria patch room.) - -. "$(pwd)/tools/lib/common.sh" - -# Path to the patch to send. -PATCHFILE="$1" - -# Tries to decompose the name and the HS from an MXID using -# sed. -UR_NAME="$(echo "$MXID" | sed "s/\@\(.*\)\:\(.*\)/\1/")" -HS_NAME="$(echo "$MXID" | sed "s/\@\(.*\)\:\(.*\)/\2/")" - -# Prompts the user for a password, while disabling echo-ing. -readpwd() { - printf "$1" - stty -echo -ctlecho - read -r "$2" - echo - stty echo ctlecho -} - -# Makes an HTTP request, setting the RETURN variable for the -# actual reply from the server and the ERROR_CODE variable -# for a HTTP error code. -request() { - RETURN=$(http -i "$@" 2>/dev/null) - ERROR_CODE=$(echo "$RETURN" | head -n1 | awk '{print $2}') - RETURN=$(echo "$RETURN" | sed '1,/^[[:space:]]*$/d') -} - -# Prompts user to login and gives out an access token to use -# in the ACCESS_TOKEN variable -matrix_login() { - # Check authentication methods - echo "Checking authentication methods..." - request "$HS_BASE/_matrix/client/v3/login" - AUTH_METHODS=$RETURN - if [ $ERROR_CODE -ne 200 ]; then - echo "Homeserver does not support login." - exit 1 - fi - if ! echo "$AUTH_METHODS" | grep "m.login.password" >/dev/null; then - echo "Homeserver does not support password authentication." - exit 1 - fi - # Homeserver does support password authentication, so request - # them one. - if [ -z "$MXPW" ]; then - readpwd "Enter your Matrix password: " MXPW - fi - # Tries to login using the "Telodendria Patch Script" device - # name - JSON=$( - printf '{' - printf ' "identifier": {' - printf ' "type": "m.id.user",' - printf ' "user": %s' "$(json -e $UR_NAME)" - printf ' },' - printf ' "initial_device_display_name": "Telodendria Patch Script",' - printf ' "type": "m.login.password",' - printf ' "password": %s' "$(json -e "$MXPW")" - printf '}' - ) - request -X POST -d "$JSON" $HS_BASE/_matrix/client/v3/login - LOGIN="$RETURN" - if [ $ERROR_CODE -ne 200 ]; then - echo "Login failed." - echo "$RETURN" - exit 1 - fi - ACCESS_TOKEN=$(echo "$LOGIN" | json -s "access_token->@decode") -} - -# Logs out of Matrix using the ACFESS_TOKEN environment variable -matrix_logout() { - if [ -z "$ACCESS_TOKEN" ]; then - echo "No access token" - exit 1 - fi - request -X POST -H "Authorization: Bearer $ACCESS_TOKEN" "$HS_BASE/_matrix/client/v3/logout" - LOGOUT=$RETURN - if [ $ERROR_CODE -ne 200 ]; then - echo "Logout failed." - echo "$RETURN" - exit 1 - fi - echo "Logged out." -} - -send_patch() { - if [ -z "$ACCESS_TOKEN" ]; then - matrix_login - DO_LOGOUT=1 - fi - # We are sucessfully logged in as our user, now let's - # try to upload and post our patch - echo "$PATCHFILE" - request -X POST \ - -H "Content-Type: text/x-patch" \ - -H "Authorization: Bearer $ACCESS_TOKEN" \ - -d "@$PATCHFILE" \ - "$HS_BASE/_matrix/media/v3/upload" - MXCID=$RETURN - if [ $ERROR_CODE -ne 200 ]; then - echo "Upload failed." - echo "$RETURN" - matrix_logout - exit 1 - fi - MXCID=$(echo "$MXCID" | json -s "content_uri->@decode") - echo "MXC ID: $MXCID" - JSON=$( - base=$(basename "$PATCHFILE") - printf '{' - printf ' "body": %s,' "$(json -e $base)" - printf ' "filename": %s,' "$(json -e $base)" - printf ' "info": {' - printf ' "mimetype": "text/x-patch",' - printf ' "size": %d' $(wc -c "$PATCHFILE" | awk '{print $1}') - printf ' },' - printf ' "msgtype": "m.file",' - printf ' "url": %s' "$(json -e $MXCID)" - printf '}' - ) - http -X PUT -d "$JSON" -H "Authorization: Bearer $ACCESS_TOKEN" \ - "$HS_BASE/_matrix/client/v3/rooms/$PATCHES_ROOM/send/m.room.message/$(date +%s)" \ - 2>/dev/null >/dev/null && echo "Patch sent." - - # Log out if we generated an access token - if [ "$DO_LOGOUT" -eq "1" ]; then - matrix_logout - fi -} - -# Check if the patch file is valid. -if [ "$(basename "$PATCHFILE" .patch)" = "$PATCHFILE" ] || [ ! -f "$PATCHFILE" ]; then - echo "Format: $0 file.patch" - exit 1 -fi -echo "Sending file '$PATCHFILE'" -echo "Checking homeserver's real address using .well-known..." -request "https://$HS_NAME/.well-known/matrix/client" -case "$ERROR_CODE" in - "200") - WELL_KNOWN=$RETURN - if [ -z "$WELL_KNOWN" ]; then - echo "well-known test returned 200 but no correct input was given." - exit 1 - fi - # well-known entry is correct, we can now store our base endpoint - HS_BASE=$(printf "$WELL_KNOWN" | json -s "m.homeserver->base_url->@decode") && send_patch - ;; - *) - echo "$ERROR_CODE" - - echo "well-known test failed." - printf "Please enter your homeserver base URL: " - read -r HS_BASE - echo - send_patch - ;; -esac diff --git a/tools/bin/tp b/tools/bin/tp deleted file mode 100755 index fad2d87..0000000 --- a/tools/bin/tp +++ /dev/null @@ -1,148 +0,0 @@ -#!/usr/bin/env sh -# -# tp: "Telodendria Patch" -# -# This script is used to manage the patch queue. - -. "$(pwd)/tools/lib/common.sh" - -if [ -z "$TELODENDRIA_PUB" ]; then - echo "TELODENDRIA_PUB not set." - exit 1 -fi - -TP_DIR="$TELODENDRIA_PUB/patches" - -if [ ! -d "$TP_DIR" ]; then - echo "$TP_DIR does not exist." - exit 1 -fi - -matrix_send() { - msg="$1" - if [ ! -z "$msg" ]; then - ( - printf '{' - printf '"body":' - json -e "$msg" - printf ',"formatted_body":' - json -e "$msg" - printf ',"format":"org.matrix.custom.html",' - printf '"msgtype":"m.text"' - printf '}' - ) > /tmp/tp-$$ - http -X PUT -d @/tmp/tp-$$ "$HOMESERVER/client/v3/rooms/$PATCHES_ROOM/send/m.room.message/$(date +%s)?access_token=$ACCESS_TOKEN" - rm /tmp/tp-$$ - fi -} - -case "$1" in - "ingress") - timeline="/tmp/timeline.json" - http "$HOMESERVER/client/v3/sync?access_token=$ACCESS_TOKEN" | - json -s "rooms->join->${PATCHES_ROOM}->timeline" >"$timeline" - - length=$(cat "$timeline" | json -s "events->@length") - - i=0 - while [ $i -lt $length ]; do - content=$(cat "$timeline" | json -s "events[$i]->content->^body->^formatted_body") - i=$((i + 1)) - - type=$(echo "$content" | json -s "msgtype->@decode") - if [ "$type" != "m.file" ]; then - continue - fi - - size=$(echo "$content" | json -s "info->size") - if [ "$size" -gt "$MAX_SIZE" ]; then - continue - fi - - file=$(echo "$content" | json -s "filename->@decode") - ext=$(echo "$file" | rev | cut -d '.' -f 1 | rev) - if [ "$ext" != "patch" ]; then - continue - fi - - url=$(echo "$content" | json -s "url->@decode") - id=$(echo "$url" | cut -d '/' -f 4) - - if [ -f "$TP_DIR/ingress/$id.patch" ]; then - continue - fi - - server=$(echo "$url" | cut -d '/' -f 3) - - if ! http "$HOMESERVER/media/v3/download/$server/$id" > "$TP_DIR/ingress/$id.patch"; then - rm "$TP_DIR/ingress/$id.patch" - echo "Failed to fetch mxc://$server/$id." - echo "Will try again next time." - continue - fi - - count=$(cat "$TP_DIR/count.txt") - count=$((count + 1)) - cp "$TP_DIR/ingress/$id.patch" "$TP_DIR/p/$count.patch" - ( - cd "$TP_DIR/queued" - ln -s "../p/$count.patch" "$count.patch" - ) - - echo "$count" >"$TP_DIR/count.txt" - - matrix_send "Queued $file as #$count" >/dev/null - done - ;; - "queue") - find "$TP_DIR/queued" -name '*.patch' | while IFS= read -r patch; do - n=$(basename "$patch" .patch) - echo "Patch #$n:" - head -n3 "$patch" - echo - done - ;; - "view") - if [ -f "$TP_DIR/queued/$2.patch" ]; then - less "$TP_DIR/queued/$2.patch" - else - echo "Patch #$2 doesn't exist in the queue." - exit 1 - fi - ;; - "apply") - if [ -f "$TP_DIR/queued/$2.patch" ]; then - patch <"$TP_DIR/queued/$2.patch" - else - echo "Patch #$2 doesn't exist in the queue." - exit 1 - fi - ;; - "reverse") - if [ -f "$TP_DIR/queued/$2.patch" ]; then - patch -R <"$TP_DIR/queued/$2.patch" - else - echo "Patch #$2 doesn't exist in the queue." - exit 1 - fi - ;; - "accept" | "reject") - if [ -f "$TP_DIR/queued/$2.patch" ]; then - mv "$TP_DIR/queued/$2.patch" "$TP_DIR/${1}ed/$2.patch" - msg="Patch #$2 was marked as ${1}ed." - msgFile="/tmp/patchmsg-$(date +%s).txt" - $EDITOR "$msgFile" - if [ -f "$msgFile" ]; then - msg="$msg
$(cat $msgFile)
—$DISPLAY_NAME ($MXID)
" - fi - matrix_send "$msg" - else - echo "Patch #$2 doesn't exist in the queue." - exit 1 - fi - ;; - *) - echo "No action specified." - exit 1 - ;; -esac From 0b820b80f75c1e6e52777b348ec4fe45a131ba84 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 17:43:43 -0400 Subject: [PATCH 26/28] Convert configuration documentation. --- docs/user/config.md | 246 ++++++++++++++++++++++++++++++++++ man/man7/telodendria-config.7 | 218 ------------------------------ 2 files changed, 246 insertions(+), 218 deletions(-) create mode 100644 docs/user/config.md delete mode 100644 man/man7/telodendria-config.7 diff --git a/docs/user/config.md b/docs/user/config.md new file mode 100644 index 0000000..f021633 --- /dev/null +++ b/docs/user/config.md @@ -0,0 +1,246 @@ +# Configuration + +Telodendria is designed to be configurable. It is configured using +JSON, which is intended to be submitted to the [Administrator +API](admin/README.md). This document details Telodendria's configuration +JSON format, which is used in both the administrator API and on-disk +in the database. The configuration file on the disk in the databsae +is `config.json`, though that file should not be edited by hand. +Use the API described in +[Administrator API → Configuration](admin/config.md). + +## JSON Format + +Telodendria's configuration is just a JSON object in the standard +key-value form: + +```json +{ + "serverName": "telodendria.io", + "listen": [ + { + "port": 8008, + "tls": false + } + ] + + /* ... */ +} +``` + +Some keys, called *directives* in this document, have values that are +objects themselves. + +## Directives + +Here are the top-level directives: + +- **listen:** `Array` + + An array of listener description objects. Telodendria supports + listening on multiple ports, and each port is configured + independently of the others. A listener object looks like this: + + - **port:** `integer` + + The port to listen on. Telodendria will bind to all interfaces, + so it is recommended to configure your firewall to only allow + access on the desired interfaces. Note that Telodendria offers all + APIs over each port, including the administrator APIs; there is no + way to control which APIs are made available over which ports. If + this is a concern, a reverse-proxy such as `relayd` can be placed + in front of Telodendria to block access to undesired APIs. + + - **tls:** `Object|null|false` + + Telodendria can be compiled with TLS support. If it is, then a + particular listener can be set to use TLS for connections. If + **tls** is not `null` or `false`, then it can be an object with + the following directives: + + - **cert:** `String` + + The full path—or path relative to the data + directory—of the certificate file to load. The certificate + file should be in the format expected by the platform's TLS + library. + + - **key:** `String` + + Same as **cert**, but this should be the private key that matches + the certificate being used. + + - **threads:** `Integer` + + How many worker threads to spin up to handle requests for this + listener. This should generally be less than the total CPU core + count, to prevent overloading the system. The most efficient number + of threads ultimately depends on the configuration of the machine + running Telodendria, so you may just have to play around with + different values here to see which gives the best performance. + + Note that this can be set as low as 0; in that case, the listener + will never respond to requests. Each listener needs to have at + least one thread to be useful. Also note that Telodendria may spin + up additional threads for background work, so the actual total + thread count at any given time may exceed the sum of threads + specified in the configuration. + + This directive is optional. The default value is `4` in the upstream + code, but your software distribution may have patched this to be + different. + + - **maxConnections:** `Integer` + + The maximum number of simultanious connections to allow to the + daemon. This option prevents the daemon from allocating large + amounts of memory in the event that it undergoes a denial of + service attack. It is optional, defaults to `32`, and typically + does not need to be adjusted. + +- **serverName:** `String` + + Configure the domain name of your homeserver. Note that Matrix + servers cannot be migrated to other domains, so once this is set, + it should never change unless you want unexpected things to happen + or you want to start over. **serverName** should be a DNS name that + can be publicly resolved. This directive is required. + +- **baseUrl:** `String` + + Set the server's base URL. **baseUrl** should be a valid URL, + complete with the protocol. It does not need to be the same as the + server name; in fact, it is common for a subdomain of the server name + to be the base URL for the Matrix homeserver. + + This URL is the URL at which Matrix clients will connect to the + server, and is thus served as a part of the `.well-known` + manifest. + + This directive is optional. If unspecified, it is automatically + deduced from the server name. + +- **identityServer:** `String` + + The identity server that clients should use to perform identity + lookups. **identityServer** folows the same rules as **baseUrl**. + It also is optional, and is set to be the same as the **baseUrl** + if left unspecified. + +- **runAs:** `Object` + + The effective Unix user and group to drop to after binding to the + socket and completing any setup that may potentially require + elevated privileges. This directive only takes effect if + Telodendria is started as the root user, and is used as a security + mechanism. If this option is set and Telodendria is started as a + non-privileged user, then a warning is printed to the log if that + user and group do not match what's specified here. This directive + is optional, but should be used as a sanity check even if not + running as `root`, just to make sure you have your permissions + working properly. + + This directive takes an object with the following directives: + + - **uid:** `String` + + The Unix username to switch to. If **runAs** is specified, this + directive is required. + + - **gid:** `String` + + The Unix group to switch to. This directive is optional; if left + unspecified, then the value of **uid** is copied. + +- **federation:** `Boolean` + + Whether or not to enable federation with other Matrix homeservers. + Matrix by its very nature is a federated protocol, but if you just + want to rn your own internal chat server with no contact with the + outside, then you can use this option to disable federation. It is + highly recommended to set this to `true`, however, if you wish to + be able to communicate with users on other Matrix servers. This + directive is required. + +- **registration:** `Boolean` + + Whether or not to enable new user registration or not. For security + and anti-spam reasons, you can set this to `false`. If you do, you + can still allow only certain users to be registered using + registration tokens, which can be managed via the administrator API. + This directive is required. + + In an ideal world, everyone would run their own Matrix homeserver, + so no public registration would ever be required. Unfortunately, + not everyone has the means to run their own homeserver, especially + because of the fact that IPv4 addresses are becoming increasingly + hard to come by. If you would like to provide a service to those + that are unable to run their homeserver, then set this to `true`, + thereby allowing anyone to create an account. + + Telodendria *should* be capable of handling a large amount of users + without difficulty, but it is targetted at smaller deployments. + +- **log:** `Object` + + The logging configuration. Telodendria uses its own logging + facility, which can output logs to standard output, a file, or the + syslog. This directive is required, and it takes an object with the + following directives: + + - **output:** `Enum` + + The log output destination. This can either be `stdout`, `file`, + or `syslog`. If set to `file`, Telodendria will log to + `telodendria.log` inside the data directory. + + - **level:** `Enum` + + The level of messages to log. Each level shows all the levels above + it. The levels are as follows: + + - `error` + - `warning` + - `notice` + - `message` + - `debug` + + For example, setting the level to `error` will show only errors, + while setting the level to `warning` will show both warnings + *and* errors. The `debug` level shows all messages. + + - **timestampFormat:** `Enum` + + If you want to customize the timestamp format shown in the log, + or disable it altogether, you can do so via this option. Acceptable + values are `none`, `default`, or a formatter string as described + by your system's `strftime()` documentation. This option only + applies if **log** is `stdout` or `file`. + + - **color:** `Boolean` + + Whether or not to enable colored output on TTYs. Note that ANSI + color sequences will not be written to a log file, only a real + terminal, so this option only applies if the log is being written + to a standard output which is connected to a terminal. + +- **maxCache:** `Integer` + + The maximum size of the cache. Telodendria relies heavily on caching + for performance reasons. The cache grows as data is loaded from the + data directory. All cache is stored in memory. This option limits the + size of the memory cache. If you have a system with a lot of memory + to spare, you'll get better performance if this option is set higher. + Otherwise, this value should be lowered on systems that have a + minimal amount of memory available. + + +## Examples + +A number of example configuration files are shipped with Telodendria's +source code. They can be found in the `contrib/` directory if you are +viewing the source code directly. Otherwise, if you installed +Telodendria from a package, it is possible that the example +configurations were placed in the default locations for such files on +your operating system. + diff --git a/man/man7/telodendria-config.7 b/man/man7/telodendria-config.7 deleted file mode 100644 index af02990..0000000 --- a/man/man7/telodendria-config.7 +++ /dev/null @@ -1,218 +0,0 @@ -.Dd $Mdocdate: April 20 2023 $ -.Dt TELODENDRIA-CONFIG 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-config -.Nd Telodendria configuration. -.Sh DESCRIPTION -.Pp -Telodendria is designed to be configurable. It is configured using -JSON, which is intended to be submitted via the administrator API. -This page documents Telodendria's configuration JSON format, which -is used both in the administrator API, and on the disk in the -database. The configuration file on the disk in the database is -.Pa config.json , -though that file should not be edited directly. Use the API described -in -.Xr telodendria-admin 7 -instead. -.Sh DIRECTIVES -Here are the top-level directives: -.Bl -tag -width Ds -.It Ic listen Ar listenArr -An array of listener description objects. Telodendria supports -listening on multiple ports, and each port is configured -independently of the others. A listener description object looks -like this: -.Bl -tag -width Ds -.It Ic port Ar port -The port to listen on. Telodendria will bind to all interfaces, so it -is recommended to configure your firewall so you can control what is -allowed to access the Telodendria ports. Note that -Telodendria offers all APIs over each port; there is no way to -control which APIs are available over which ports, although all -APIs should be safe against attacks, so this should not be a -major concern. -.Pp -.Ar port -should be a decimal port number. This directive is required. Common -port numbers are 8008 for non-TLS, and 8448 for TLS. -.It Ic tls Ar tlsObj|null|false -Telodendria can be compiled with TLS support. If it is, then a -particular listener can be set to use TLS for connections. If -.Ic tls -is not -.Ar null -or -.Ar false , -then it can be an object with the following directives: -.Bl -tag -width Ds -.It Ic cert Ar file -A certificate file in the format native to the platform's TLS -library. This can be an absolute path, otherwise it is relative -to the data directory. -.It Ic key Ar file -A key file in the format native to the platform's TLS library. -It follows the same rules as the certificate file. -.El -.El -.It Ic serverName Ar name -Configure the domain name of your homeserver. Note that Matrix servers -cannot be migrated to other domains, so once this is set, it should never -change unless you want unexpected things to happen, or you want to start -over. -.Ar name -should be a DNS name that can be publically resolved. This directive -is required. -.It Ic baseUrl Ar url -Set the server's base URL. -.Ar url -should be a valid URL, complete with the protocol. It does not need to -be the same as the server name; in fact, it is common for a subdomain of -the server name to be the base URL for the Matrix homeserver. -.Pp -This URL is the URL at which Matrix clients will connect to the server, -and is thus served as a part of the -.Pa .well-known -manifest. -.Pp -This directive is optional. If it is not specified, it is automatically -deduced from the server name. -.It Ic identityServer Ar url -The identity server that clients should use to perform identity lookups. -.Pp -.Ar url -follows the same rules as -.Ic baseUrl . -.Pp -This directive is optional. If it is not specified, it is automatically -set to be the same as the base URL. -.It Ic runAs Ar uidObj -The effective UNIX user and group to drop to after binding to the socket -and changing the filesystem root for the process. This only works if -Telodendria is running as the root user, and is used as a security mechanism. -If this option is set and Telodendria is started as a non-priviledged user, -then a warning is printed to the log if that user does not match what's -specified here. This directive is optional, but should be used as a sanity -check, if nothing more, to make sure the permissions are working properly. -.Pp -This directive takes an object with the following directives: -.Bl -tag -width Ds -.It Ic uid Ar user -The UNIX username to drop to. If -.Ic runAs -is specified, this directive is required. -.It Ic gid Ar group -The UNIX group to drop to. This directive is optional; if it is not -specified, then the value of -.Ic uid -is copied. -.El -.Ic log -directive is configured to write to a file, the log file will be written -in the data directory. -.Ar directory -should be an absolute path, under which all Telodendria data will live. -.It Ic federation Ar true|false -Whether to enable federation with other Matrix homeservers or not. Matrix is -by its very nature a federated protocol, but if you just want to run your -own internal chat server with no contact with the outside, then you can use -this option to disable federation. It is highly recommended to set this to -.Ar true , -however, if you wish to be able to communicate with users on other Matrix -servers. This directive is required. -.It Ic registration Ar true|false -Whether or not to enable new user registration or not. For security and anti-spam -reasons, you can set this to -.Ar false . -If you do, you can still add users via the administrator API. In an ideal world, -everyone would run their own homeserver, so no public registration would ever -be required. Unfortunately, not everyone has the means to run their own homeserver, -especially because of the fact that public IPv4 addresses are becoming increasingly -harder to come by. If you would like to provide a service to those that are unable -to run their own homeserver, you can set this to -.Ar true , -which will allow anyone to create an account. Telodendria should be capable of handling -a large amount of users without difficulty or security issues. This directive is -required. -.It Ic log Ar logObj -The log file configuration. Telodendria uses its own logging facility, which can -output logs to standard output, a file, or the syslog. This directive is required, -and it takes an object with the following directives: -.Bl -tag -width Ds -.It Ic output Ar stdout|file|syslog -The lot output destination. If set to -.Ar file , -Telodendria will log to -.Pa telodendria.log -inside the data directory. -.It Ic level Ar error|warning|notice|message|debug -The level of messages to log at. Each level shows all the levels above it. For -example, setting the level to -.Ar error -will show only errors, while setting the level to -.Ar warning -will show warnings and errors. -.Ar notice -shows notices, warnings, and errors, and so on. The -.Ar debug -level shows all messages. -.It Ic timestampFormat Ar format|none|default -If you want to customize the timestamp format shown in the log, or disable it -altogether, you can do so via this option. Acceptable values are -.Ar none , -.Ar default , -or a formatter string as described by your system's -.Xr strftime 3 . -This option only applies if -.Ic log -is "stdout" or "file". -.It Ic color Ar true|false -Whether or not to enable colored output on TTYs. Note that ANSI color sequences -will not be written to a log file, only a real terminal, so this option only -applies if the log is being written to a standard output which is connected to -a terminal. -.Pp -This option only applies if -.Ic log -is "stdout". -.El -.It Ic threads Ar count -How many worker threads to spin up to handle requests. This should generally be -less than the total CPU core count, to prevent overloading the system. The most -efficient number of threads ultimately depends on the configuration of the -machine running Telodendria, so you may just have to play around with different -values here to see which gives the best performance. -.It Ic maxConnections Ar count -The maximum number of simultanious connections to allow to the daemon. This option -prevents the daemon from allocating large amounts of memory in the event that it -undergoes a denial of service attack. It typically does not need to be adjusted. -.It Ic maxCache Ar bytes -The maximum size of the cache. Telodendria relies heavily on caching to speed -things up. The cache grows as data is loaded from the data directory. All cache -is stored in memory. This option limits the size of the memory cache. If you have -a system that has a lot of memory, you'll get better performance if this option -is set higher. Otherwise, this value should be lowered on systems that have -minimal memory available. -.El -.Sh FILES -.Bl -tag -width Ds -.It Pa config.json -The configuration file stored on the filesystem in the data -directory. It is not recommended to edit this directly. -.It Pa /var/telodendria -The recommended data directory. -.El -.Sh EXAMPLES -.Pp -A number of example configuration files are shipped with -Telodendria's source code. They can be found in the -.Pa contrib/ -directory if you are viewing the source code directly. Otherwise, -if you installed Telodendria as a package, it is possible that the -example configurations were placed in the default locations for -such files on your operating system. -.Sh SEE ALSO -.Xr telodendria-setup 7 , -.Xr telodendria-admin 7 -.Xr telodendria 8 From 0172fa083bc978f9a0b651a9abd119281584355f Mon Sep 17 00:00:00 2001 From: LoaD Accumulator Date: Mon, 11 Sep 2023 10:57:16 -0400 Subject: [PATCH 27/28] Fixes issue #33 related to a memory issue, and format some code. (#35) Fixes #33. Co-authored-by: LoaD Accumulator Reviewed-on: https://git.telodendria.io/Telodendria/telodendria/pulls/35 Co-authored-by: LoaD Accumulator Co-committed-by: LoaD Accumulator --- Cytoplasm/src/HttpRouter.c | 8 ++++++-- Cytoplasm/src/Str.c | 1 - src/Routes/RouteUserProfile.c | 5 ++++- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/Cytoplasm/src/HttpRouter.c b/Cytoplasm/src/HttpRouter.c index 87ddae0..bd06c64 100644 --- a/Cytoplasm/src/HttpRouter.c +++ b/Cytoplasm/src/HttpRouter.c @@ -196,7 +196,7 @@ HttpRouterRoute(HttpRouter * router, char *path, void *args, void **ret) char *pathPart; char *tmp; HttpRouteFunc *exec = NULL; - Array *matches; + Array *matches = NULL; size_t i; int retval; @@ -254,14 +254,18 @@ HttpRouterRoute(HttpRouter * router, char *path, void *args, void **ret) { /* pmatch[0] is the whole string, not the first * subexpression */ + char * substr; + regmatch_t cpmatch; for (i = 1; i < REG_MAX_SUB; i++) { + cpmatch = pmatch[i]; + substr = StrSubstr(pathPart, cpmatch.rm_so, cpmatch.rm_eo); if (pmatch[i].rm_so == -1) { break; } - ArrayAdd(matches, StrSubstr(pathPart, pmatch[i].rm_so, pmatch[i].rm_eo)); + ArrayAdd(matches, substr); } } } diff --git a/Cytoplasm/src/Str.c b/Cytoplasm/src/Str.c index 98dea0b..2f4c665 100644 --- a/Cytoplasm/src/Str.c +++ b/Cytoplasm/src/Str.c @@ -147,7 +147,6 @@ StrSubstr(const char *inStr, size_t start, size_t end) } len = end - start; - outStr = Malloc(len + 1); if (!outStr) { diff --git a/src/Routes/RouteUserProfile.c b/src/Routes/RouteUserProfile.c index 0c99338..5b795c2 100644 --- a/src/Routes/RouteUserProfile.c +++ b/src/Routes/RouteUserProfile.c @@ -172,7 +172,10 @@ ROUTE_IMPL(RouteUserProfile, path, argp) } finish: ConfigUnlock(config); - Free(username); + + /* Username is handled by the router, freeing it *will* cause issues + * (see #33). I honestly don't know how it didn't come to bite us sooner. + Free(username); */ Free(entry); UserIdFree(userId); UserUnlock(user); From 6247085df165dee8b5bdeab6cd180db6be2174bc Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Mon, 11 Sep 2023 11:01:50 -0400 Subject: [PATCH 28/28] Add change log entry for #35. --- docs/CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 15bb2ce..a1b9bf2 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -19,6 +19,11 @@ The following endpoints were added: - **POST** `/_matrix/client/v3/user/{userId}/filter` - **GET** `/_matrix/client/v3/user/{userId}/filter/{filterId}` +### Bug Fixes + +- Fixed a double-free in `RouteUserProfile()` that would cause errors with certain +Matrix clients. (#35) + ## v0.3.0 **Saturday, June 10, 2023**