From d5df12fd5e9bd5a5bb7cd3000c458f9d8f1a9a39 Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Wed, 28 May 2025 05:31:44 +0000 Subject: [PATCH] Update additional docs and legacy references. Signed-off-by: Jason Volk --- CONTRIBUTING.md | 12 ++--- docs/deploying/arch-linux.md | 20 +++---- docs/deploying/freebsd.md | 7 +-- docs/deploying/generic.md | 87 +++++++++++++++--------------- docs/deploying/kubernetes.md | 8 +-- docs/deploying/nixos.md | 31 +++++------ docs/development.md | 34 ++++++------ docs/development/hot_reload.md | 22 ++++---- docs/development/testing.md | 6 +-- docs/introduction.md | 4 +- docs/maintenance.md | 26 ++++----- docs/turn.md | 8 +-- src/api/client/membership/knock.rs | 4 +- src/api/client/membership/leave.rs | 2 +- src/api/router/auth.rs | 2 +- 15 files changed, 136 insertions(+), 137 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 838d68ad..15b8028a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing guide -This page is for about contributing to conduwuit. The +This page is for about contributing to Tuwunel. The [development](./development.md) page may be of interest for you as well. If you would like to work on an [issue][issues] that is not assigned, preferably @@ -40,7 +40,7 @@ If you'd like to run Complement locally using Nix, see the ### Writing documentation -conduwuit's website uses [`mdbook`][mdbook] and deployed via CI using GitHub +Tuwunel's website uses [`mdbook`][mdbook] and deployed via CI using GitHub Pages in the [`documentation.yml`][documentation.yml] workflow file with Nix's mdbook in the devshell. All documentation is in the `docs/` directory at the top level. The compiled mdbook website is also uploaded as an artifact. @@ -78,7 +78,7 @@ applies here. ### Creating pull requests -Please try to keep contributions to the GitHub. While the mirrors of conduwuit +Please try to keep contributions to the GitHub. While the mirrors of Tuwunel allow for pull/merge requests, there is no guarantee I will see them in a timely manner. Additionally, please mark WIP or unfinished or incomplete PRs as drafts. This prevents me from having to ping once in a while to double check the status @@ -87,7 +87,7 @@ of it, especially when the CI completed successfully and everything so it If you open a pull request on one of the mirrors, it is your responsibility to inform me about its existence. In the future I may try to solve this with more -repo bots in the conduwuit Matrix room. There is no mailing list or email-patch +repo bots in the Tuwunel Matrix room. There is no mailing list or email-patch support on the sr.ht mirror, but if you'd like to email me a git patch you can do so at `maintainer@tuwunel.chat`. @@ -95,11 +95,11 @@ Direct all PRs/MRs to the `main` branch. By sending a pull request or patch, you are agreeing that your changes are allowed to be licenced under the Apache-2.0 licence and all of your conduct is -in line with the Contributor's Covenant, and conduwuit's Code of Conduct. +in line with the Contributor's Covenant, and Tuwunel's Code of Conduct. Contribution by users who violate either of these code of conducts will not have their contributions accepted. This includes users who have been banned from -conduwuit Matrix rooms for Code of Conduct violations. +Tuwunel Matrix rooms for Code of Conduct violations. ### Branch Policy diff --git a/docs/deploying/arch-linux.md b/docs/deploying/arch-linux.md index 7436e5bf..dd4b893a 100644 --- a/docs/deploying/arch-linux.md +++ b/docs/deploying/arch-linux.md @@ -1,15 +1,15 @@ -# conduwuit for Arch Linux +# Tuwunel for Arch Linux -Currently conduwuit is only on the Arch User Repository (AUR). +Currently Tuwunel is only on the Arch User Repository (AUR). -The conduwuit AUR packages are community maintained and are not maintained by -conduwuit development team, but the AUR package maintainers are in the Matrix +The Tuwunel AUR packages are community maintained and are not maintained by +Tuwunel development team, but the AUR package maintainers are in the Matrix room. Please attempt to verify your AUR package's PKGBUILD file looks fine before asking for support. -- [conduwuit](https://aur.archlinux.org/packages/conduwuit) - latest tagged -conduwuit -- [conduwuit-git](https://aur.archlinux.org/packages/conduwuit-git) - latest git -conduwuit from `main` branch -- [conduwuit-bin](https://aur.archlinux.org/packages/conduwuit-bin) - latest -tagged conduwuit static binary +- [tuwunel](https://aur.archlinux.org/packages/tuwunel) - latest tagged +tuwunel +- [tuwunel-git](https://aur.archlinux.org/packages/tuwunel-git) - latest git +tuwunel from `main` branch +- [tuwunel-bin](https://aur.archlinux.org/packages/tuwunel-bin) - latest +tagged tuwunel static binary diff --git a/docs/deploying/freebsd.md b/docs/deploying/freebsd.md index 65b40204..63ffc37c 100644 --- a/docs/deploying/freebsd.md +++ b/docs/deploying/freebsd.md @@ -1,5 +1,6 @@ -# conduwuit for FreeBSD +# Tuwunel for FreeBSD -conduwuit at the moment does not provide FreeBSD builds or have FreeBSD packaging, however conduwuit does build and work on FreeBSD using the system-provided RocksDB. +Tuwunel at the moment does not provide FreeBSD builds or have FreeBSD packaging, however Tuwunel does +build and work on FreeBSD using the system-provided RocksDB. -Contributions for getting conduwuit packaged are welcome. +Contributions for getting Tuwunel into ports are welcome. diff --git a/docs/deploying/generic.md b/docs/deploying/generic.md index a07da560..e02135c9 100644 --- a/docs/deploying/generic.md +++ b/docs/deploying/generic.md @@ -2,11 +2,10 @@ > ### Getting help > -> If you run into any problems while setting up conduwuit, ask us in -> `#conduwuit:puppygock.gay` or [open an issue on -> GitHub](https://github.com/girlbossceo/conduwuit/issues/new). +> If you run into any problems while setting up Tuwunel [open an issue on +> GitHub](https://github.com/matrix-construct/tuwunel/issues/new). -## Installing conduwuit +## Installing Tuwunel ### Static prebuilt binary @@ -14,12 +13,10 @@ You may simply download the binary that fits your machine architecture (x86_64 or aarch64). Run `uname -m` to see what you need. Prebuilt fully static musl binaries can be downloaded from the latest tagged -release [here](https://github.com/girlbossceo/conduwuit/releases/latest) or +release [here](https://github.com/matrix-construct/tuwunel/releases/latest) or `main` CI branch workflow artifact output. These also include Debian/Ubuntu packages. -Binaries are also available on my website directly at: - These can be curl'd directly from. `ci-bins` are CI workflow binaries by commit hash/revision, and `releases` are tagged releases. Sort by descending last modified for the latest. @@ -37,49 +34,49 @@ for performance. ### Compiling Alternatively, you may compile the binary yourself. We recommend using -Nix (or [Lix](https://lix.systems)) to build conduwuit as this has the most +Nix to build tuwunel as this has the most guaranteed reproducibiltiy and easiest to get a build environment and output going. This also allows easy cross-compilation. You can run the `nix build -L .#static-x86_64-linux-musl-all-features` or `nix build -L .#static-aarch64-linux-musl-all-features` commands based on architecture to cross-compile the necessary static binary located at -`result/bin/conduwuit`. This is reproducible with the static binaries produced +`result/bin/tuwunel`. This is reproducible with the static binaries produced in our CI. If wanting to build using standard Rust toolchains, make sure you install: - `liburing-dev` on the compiling machine, and `liburing` on the target host - LLVM and libclang for RocksDB -You can build conduwuit using `cargo build --release --all-features` +You can build Tuwunel using `cargo build --release --all-features` -## Adding a conduwuit user +## Adding a Tuwunel user -While conduwuit can run as any user it is better to use dedicated users for +While Tuwunel can run as any user it is better to use dedicated users for different services. This also allows you to make sure that the file permissions are correctly set up. -In Debian, you can use this command to create a conduwuit user: +In Debian, you can use this command to create a Tuwunel user: ```bash -sudo adduser --system conduwuit --group --disabled-login --no-create-home +sudo adduser --system tuwunel --group --disabled-login --no-create-home ``` For distros without `adduser` (or where it's a symlink to `useradd`): ```bash -sudo useradd -r --shell /usr/bin/nologin --no-create-home conduwuit +sudo useradd -r --shell /usr/bin/nologin --no-create-home tuwunel ``` ## Forwarding ports in the firewall or the router Matrix's default federation port is port 8448, and clients must be using port 443. If you would like to use only port 443, or a different port, you will need to setup -delegation. conduwuit has config options for doing delegation, or you can configure +delegation. Tuwunel has config options for doing delegation, or you can configure your reverse proxy to manually serve the necessary JSON files to do delegation (see the `[global.well_known]` config section). -If conduwuit runs behind a router or in a container and has a different public +If Tuwunel runs behind a router or in a container and has a different public IP address than the host system these public ports need to be forwarded directly or indirectly to the port mentioned in the config. @@ -94,19 +91,19 @@ on the network level, consider something like NextDNS or Pi-Hole. ## Setting up a systemd service -Two example systemd units for conduwuit can be found +Two example systemd units for Tuwunel can be found [on the configuration page](../configuration/examples.md#debian-systemd-unit-file). -You may need to change the `ExecStart=` path to where you placed the conduwuit -binary if it is not `/usr/bin/conduwuit`. +You may need to change the `ExecStart=` path to where you placed the Tuwunel +binary if it is not `/usr/bin/tuwunel`. On systems where rsyslog is used alongside journald (i.e. Red Hat-based distros and OpenSUSE), put `$EscapeControlCharactersOnReceive off` inside `/etc/rsyslog.conf` to allow color in logs. If you are using a different `database_path` other than the systemd unit -configured default `/var/lib/conduwuit`, you need to add your path to the +configured default `/var/lib/tuwunel`, you need to add your path to the systemd unit's `ReadWritePaths=`. This can be done by either directly editing -`conduwuit.service` and reloading systemd, or running `systemctl edit conduwuit.service` +`tuwunel.service` and reloading systemd, or running `systemctl edit tuwunel.service` and entering the following: ``` @@ -114,11 +111,11 @@ and entering the following: ReadWritePaths=/path/to/custom/database/path ``` -## Creating the conduwuit configuration file +## Creating the Tuwunel configuration file -Now we need to create the conduwuit's config file in -`/etc/conduwuit/conduwuit.toml`. The example config can be found at -[conduwuit-example.toml](../configuration/examples.md). +Now we need to create the Tuwunel's config file in +`/etc/tuwunel/tuwunel.toml`. The example config can be found at +[tuwunel-example.toml](../configuration/examples.md). **Please take a moment to read the config. You need to change at least the server name.** @@ -127,20 +124,20 @@ RocksDB is the only supported database backend. ## Setting the correct file permissions -If you are using a dedicated user for conduwuit, you will need to allow it to +If you are using a dedicated user for Tuwunel, you will need to allow it to read the config. To do that you can run this: ```bash -sudo chown -R root:root /etc/conduwuit -sudo chmod -R 755 /etc/conduwuit +sudo chown -R root:root /etc/tuwunel +sudo chmod -R 755 /etc/tuwunel ``` If you use the default database path you also need to run this: ```bash -sudo mkdir -p /var/lib/conduwuit/ -sudo chown -R conduwuit:conduwuit /var/lib/conduwuit/ -sudo chmod 700 /var/lib/conduwuit/ +sudo mkdir -p /var/lib/tuwunel/ +sudo chown -R tuwunel:tuwunel /var/lib/tuwunel/ +sudo chmod 700 /var/lib/tuwunel/ ``` ## Setting up the Reverse Proxy @@ -150,7 +147,7 @@ For other software, please refer to their respective documentation or online gui ### Caddy -After installing Caddy via your preferred method, create `/etc/caddy/conf.d/conduwuit_caddyfile` +After installing Caddy via your preferred method, create `/etc/caddy/conf.d/tuwunel_caddyfile` and enter this (substitute for your server name). ```caddyfile @@ -158,7 +155,7 @@ your.server.name, your.server.name:8448 { # TCP reverse_proxy reverse_proxy 127.0.0.1:6167 # UNIX socket - #reverse_proxy unix//run/conduwuit/conduwuit.sock + #reverse_proxy unix//run/tuwunel/tuwunel.sock } ``` @@ -174,15 +171,15 @@ As we would prefer our users to use Caddy, we will not provide configuration fil You will need to reverse proxy everything under following routes: - `/_matrix/` - core Matrix C-S and S-S APIs -- `/_conduwuit/` - ad-hoc conduwuit routes such as `/local_user_count` and +- `/_tuwunel/` - ad-hoc Tuwunel routes such as `/local_user_count` and `/server_version` You can optionally reverse proxy the following individual routes: - `/.well-known/matrix/client` and `/.well-known/matrix/server` if using -conduwuit to perform delegation (see the `[global.well_known]` config section) -- `/.well-known/matrix/support` if using conduwuit to send the homeserver admin +Tuwunel to perform delegation (see the `[global.well_known]` config section) +- `/.well-known/matrix/support` if using Tuwunel to send the homeserver admin contact and support page (formerly known as MSC1929) -- `/` if you would like to see `hewwo from conduwuit woof!` at the root +- `/` if you would like to see `hewwo from tuwunel woof!` at the root See the following spec pages for more details on these files: - [`/.well-known/matrix/server`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixserver) @@ -200,25 +197,25 @@ header, making federation non-functional. If a workaround is found, feel free to If using Apache, you need to use `nocanon` in your `ProxyPass` directive to prevent httpd from messing with the `X-Matrix` header (note that Apache isn't very good as a general reverse proxy and we discourage the usage of it if you can). -If using Nginx, you need to give conduwuit the request URI using `$request_uri`, or like so: +If using Nginx, you need to give Tuwunel the request URI using `$request_uri`, or like so: - `proxy_pass http://127.0.0.1:6167$request_uri;` - `proxy_pass http://127.0.0.1:6167;` Nginx users need to increase `client_max_body_size` (default is 1M) to match -`max_request_size` defined in conduwuit.toml. +`max_request_size` defined in tuwunel.toml. ## You're done -Now you can start conduwuit with: +Now you can start Tuwunel with: ```bash -sudo systemctl start conduwuit +sudo systemctl start tuwunel ``` Set it to start automatically when your system boots with: ```bash -sudo systemctl enable conduwuit +sudo systemctl enable tuwunel ``` ## How do I know it works? @@ -230,10 +227,10 @@ You can also use these commands as a quick health check (replace `your.server.name`). ```bash -curl https://your.server.name/_conduwuit/server_version +curl https://your.server.name/_tuwunel/server_version # If using port 8448 -curl https://your.server.name:8448/_conduwuit/server_version +curl https://your.server.name:8448/_tuwunel/server_version # If federation is enabled curl https://your.server.name:8448/_matrix/federation/v1/version diff --git a/docs/deploying/kubernetes.md b/docs/deploying/kubernetes.md index d7721722..2e0f5a21 100644 --- a/docs/deploying/kubernetes.md +++ b/docs/deploying/kubernetes.md @@ -1,8 +1,8 @@ -# conduwuit for Kubernetes +# Tuwunel for Kubernetes -conduwuit doesn't support horizontal scalability or distributed loading +Tuwunel doesn't support horizontal scalability or distributed loading natively, however a community maintained Helm Chart is available here to run -conduwuit on Kubernetes: +Tuwunel on Kubernetes: Should changes need to be made, please reach out to the maintainer in our -Matrix room as this is not maintained/controlled by the conduwuit maintainers. +Matrix room as this is not maintained/controlled by the Tuwunel maintainers. diff --git a/docs/deploying/nixos.md b/docs/deploying/nixos.md index 3c5b0e69..12fbbbcc 100644 --- a/docs/deploying/nixos.md +++ b/docs/deploying/nixos.md @@ -1,16 +1,18 @@ -# conduwuit for NixOS +_This file may be out of date. Please help us update it_ -conduwuit can be acquired by Nix (or [Lix][lix]) from various places: +# Tuwunel for NixOS + +Tuwunel can be acquired by Nix from various places: * The `flake.nix` at the root of the repo * The `default.nix` at the root of the repo -* From conduwuit's binary cache +* From Tuwunel's binary cache -A community maintained NixOS package is available at [`conduwuit`](https://search.nixos.org/packages?channel=unstable&show=conduwuit&from=0&size=50&sort=relevance&type=packages&query=conduwuit) +A community maintained NixOS package is available at [`tuwunel`](https://search.nixos.org/packages?channel=unstable&show=tuwunel&from=0&size=50&sort=relevance&type=packages&query=tuwunel) ### Binary cache -A binary cache for conduwuit that the CI/CD publishes to is available at the +A binary cache for Tuwunel that the CI/CD publishes to is available at the following places (both are the same just different names): ``` @@ -37,13 +39,13 @@ conduwuit.cachix.org-1:MFRm6jcnfTf0jSAbmvLfhO3KBMt4px+1xaereWXp8Xg= ``` If specifying a Git remote URL in your flake, you can use any remotes that -are specified on the README (the mirrors), such as the GitHub: `github:girlbossceo/conduwuit` +are specified on the README (the mirrors), such as the GitHub: `github:matrix-construct/tuwunel` ### NixOS module The `flake.nix` and `default.nix` do not currently provide a NixOS module (contributions welcome!), so [`services.matrix-conduit`][module] from Nixpkgs can be used to configure -conduwuit. +Tuwunel. ### Conduit NixOS Config Module and SQLite @@ -54,13 +56,13 @@ Make sure that you are using the RocksDB backend before migrating! There is a [tool to migrate a Conduit SQLite database to RocksDB](https://github.com/ShadowJonathan/conduit_toolbox/). -If you want to run the latest code, you should get conduwuit from the `flake.nix` +If you want to run the latest code, you should get Tuwunel from the `flake.nix` or `default.nix` and set [`services.matrix-conduit.package`][package] -appropriately to use conduwuit instead of Conduit. +appropriately to use Tuwunel instead of Conduit. ### UNIX sockets -Due to the lack of a conduwuit NixOS module, when using the `services.matrix-conduit` module +Due to the lack of a Tuwunel NixOS module, when using the `services.matrix-conduit` module a workaround like the one below is necessary to use UNIX sockets. This is because the UNIX socket option does not exist in Conduit, and the module forcibly sets the `address` and `port` config options. @@ -84,24 +86,23 @@ disallows the namespace from accessing or creating UNIX sockets and has to be en systemd.services.conduit.serviceConfig.RestrictAddressFamilies = [ "AF_UNIX" ]; ``` -Even though those workarounds are feasible a conduwuit NixOS configuration module, developed and +Even though those workarounds are feasible a Tuwunel NixOS configuration module, developed and published by the community, would be appreciated. ### jemalloc and hardened profile -conduwuit uses jemalloc by default. This may interfere with the [`hardened.nix` profile][hardened.nix] -due to them using `scudo` by default. You must either disable/hide `scudo` from conduwuit, or +Tuwunel uses jemalloc by default. This may interfere with the [`hardened.nix` profile][hardened.nix] +due to them using `scudo` by default. You must either disable/hide `scudo` from Tuwunel, or disable jemalloc like so: ```nix let - conduwuit = pkgs.unstable.conduwuit.override { + tuwunel = pkgs.unstable.tuwunel.override { enableJemalloc = false; }; in ``` -[lix]: https://lix.systems/ [module]: https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit [package]: https://search.nixos.org/options?channel=unstable&query=services.matrix-conduit.package [hardened.nix]: https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/profiles/hardened.nix#L22 diff --git a/docs/development.md b/docs/development.md index fa7519c0..fbfd3fe5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -4,9 +4,9 @@ Information about developing the project. If you are only interested in using it, you can safely ignore this page. If you plan on contributing, see the [contributor's guide](./contributing.md). -## conduwuit project layout +## Tuwunel project layout -conduwuit uses a collection of sub-crates, packages, or workspace members +Tuwunel uses a collection of sub-crates, packages, or workspace members that indicate what each general area of code is for. All of the workspace members are under `src/`. The workspace definition is at the top level / root `Cargo.toml`. @@ -14,11 +14,11 @@ members are under `src/`. The workspace definition is at the top level / root The crate names are generally self-explanatory: - `admin` is the admin room - `api` is the HTTP API, Matrix C-S and S-S endpoints, etc -- `core` is core conduwuit functionality like config loading, error definitions, +- `core` is core Tuwunel functionality like config loading, error definitions, global utilities, logging infrastructure, etc - `database` is RocksDB methods, helpers, RocksDB config, and general database definitions, utilities, or functions -- `macros` are conduwuit Rust [macros][macros] like general helper macros, logging +- `macros` are Tuwunel Rust [macros][macros] like general helper macros, logging and error handling macros, and [syn][syn] and [procedural macros][proc-macro] used for admin room commands and others - `main` is the "primary" sub-crate. This is where the `main()` function lives, @@ -35,7 +35,7 @@ if you truly find yourself needing to, we recommend reaching out to us in the Matrix room for discussions about it beforehand. The primary inspiration for this design was apart of hot reloadable development, -to support "conduwuit as a library" where specific parts can simply be swapped out. +to support "Tuwunel as a library" where specific parts can simply be swapped out. There is evidence Conduit wanted to go this route too as `axum` is technically an optional feature in Conduit, and can be compiled without the binary or axum library for handling inbound web requests; but it was never completed or worked. @@ -52,7 +52,7 @@ the said workspace crate(s) must define the feature there in its `Cargo.toml`. So, if this is adding a feature to the API such as `woof`, you define the feature in the `api` crate's `Cargo.toml` as `woof = []`. The feature definition in `main`'s -`Cargo.toml` will be `woof = ["conduwuit-api/woof"]`. +`Cargo.toml` will be `woof = ["tuwunel-api/woof"]`. The rationale for this is due to Rust / Cargo not supporting ["workspace level features"][9], we must make a choice of; either scattering @@ -68,36 +68,36 @@ do this if Rust supported workspace-level features to begin with. ## List of forked dependencies -During conduwuit development, we have had to fork +During Tuwunel development, we have had to fork some dependencies to support our use-cases in some areas. This ranges from things said upstream project won't accept for any reason, faster-paced -development (unresponsive or slow upstream), conduwuit-specific usecases, or +development (unresponsive or slow upstream), Tuwunel-specific usecases, or lack of time to upstream some things. -- [ruma/ruma][1]: - various performance +- [ruma/ruma][1]: - various performance improvements, more features, faster-paced development, better client/server interop hacks upstream won't accept, etc -- [facebook/rocksdb][2]: - liburing +- [facebook/rocksdb][2]: - liburing build fixes and GCC debug build fix -- [tikv/jemallocator][3]: - musl +- [tikv/jemallocator][3]: - musl builds seem to be broken on upstream, fixes some broken/suspicious code in places, additional safety measures, and support redzones for Valgrind - [zyansheep/rustyline-async][4]: - - tab completion callback and -`CTRL+\` signal quit event for conduwuit console CLI + - tab completion callback and +`CTRL+\` signal quit event for Tuwunel console CLI - [rust-rocksdb/rust-rocksdb][5]: - - [`@zaidoon1`][8]'s fork + - [`@zaidoon1`][8]'s fork has quicker updates, more up to date dependencies, etc. Our fork fixes musl build issues, removes unnecessary `gtest` include, and uses our RocksDB and jemallocator forks. -- [tokio-rs/tracing][6]: - Implements +- [tokio-rs/tracing][6]: - Implements `Clone` for `EnvFilter` to support dynamically changing tracing envfilter's alongside other logging/metrics things ## Debugging with `tokio-console` [`tokio-console`][7] can be a useful tool for debugging and profiling. To make a -`tokio-console`-enabled build of conduwuit, enable the `tokio_console` feature, +`tokio-console`-enabled build of Tuwunel, enable the `tokio_console` feature, disable the default `release_max_log_level` feature, and set the `--cfg tokio_unstable` flag to enable experimental tokio APIs. A build might look like this: @@ -109,7 +109,7 @@ RUSTFLAGS="--cfg tokio_unstable" cargo +nightly build \ --features=systemd,element_hacks,gzip_compression,brotli_compression,zstd_compression,tokio_console ``` -You will also need to enable the `tokio_console` config option in conduwuit when +You will also need to enable the `tokio_console` config option in Tuwunel when starting it. This was due to tokio-console causing gradual memory leak/usage if left enabled. diff --git a/docs/development/hot_reload.md b/docs/development/hot_reload.md index 65fd4adf..ad16c4a3 100644 --- a/docs/development/hot_reload.md +++ b/docs/development/hot_reload.md @@ -5,7 +5,7 @@ guaranteed to work at this time. ### Summary -When developing in debug-builds with the nightly toolchain, conduwuit is modular +When developing in debug-builds with the nightly toolchain, Tuwunel is modular using dynamic libraries and various parts of the application are hot-reloadable while the server is running: http api handlers, admin commands, services, database, etc. These are all split up into individual workspace crates as seen @@ -42,7 +42,7 @@ library, macOS, and likely other host architectures are not supported (if other architectures work, feel free to let us know and/or make a PR updating this). This should work on GNU ld and lld (rust-lld) and gcc/clang, however if you happen to have linker issues it's recommended to try using `mold` or `gold` -linkers, and please let us know in the [conduwuit Matrix room][7] the linker +linkers, and please let us know in the [Tuwunel Matrix room][7] the linker error and what linker solved this issue so we can figure out a solution. Ideally there should be minimal friction to using this, and in the future a build script (`build.rs`) may be suitable to making this easier to use if the capabilities @@ -52,13 +52,13 @@ allow us. As of 19 May 2024, the instructions for using this are: -0. Have patience. Don't hesitate to join the [conduwuit Matrix room][7] to +0. Have patience. Don't hesitate to join the [Tuwunel Matrix room][7] to receive help using this. As indicated by the various rustflags used and some of the interesting issues linked at the bottom, this is definitely not something the Rust ecosystem or toolchain is used to doing. 1. Install the nightly toolchain using rustup. You may need to use `rustup - override set nightly` in your local conduwuit directory, or use `cargo + override set nightly` in your local Tuwunel directory, or use `cargo +nightly` for all actions. 2. Uncomment `cargo-features` at the top level / root Cargo.toml @@ -85,14 +85,14 @@ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.rustup/toolchains/nightly-x86_64-unknown Cargo should only rebuild what was changed / what's necessary, so it should not be rebuilding all the crates. -9. In your conduwuit server terminal, hit/send `CTRL+C` signal. This will tell - conduwuit to find which libraries need to be reloaded, and reloads them as +9. In your Tuwunel server terminal, hit/send `CTRL+C` signal. This will tell + Tuwunel to find which libraries need to be reloaded, and reloads them as necessary. 10. If there were no errors, it will tell you it successfully reloaded `#` modules, and your changes should now be visible. Repeat 7 - 9 as needed. -To shutdown conduwuit in this setup, hit/send `CTRL+\`. Normal builds still +To shutdown Tuwunel in this setup, hit/send `CTRL+\`. Normal builds still shutdown with `CTRL+C` as usual. Steps 1 - 5 are the initial first-time steps for using this. To remove the hot @@ -101,7 +101,7 @@ reload setup, revert/comment all the Cargo.toml changes. As mentioned in the requirements section, if you happen to have some linker issues, try using the `-fuse-ld=` rustflag and specify mold or gold in all the `rustflags` definitions in the top level Cargo.toml, and please let us know in -the [conduwuit Matrix room][7] the problem. mold can be installed typically +the [Tuwunel Matrix room][7] the problem. mold can be installed typically through your distro, and gold is provided by the binutils package. It's possible a helper script can be made to do all of this, or most preferably @@ -136,7 +136,7 @@ acyclic graph. The primary rule is simple and illustrated in the figure below: **no crate is allowed to call a function or use a variable from a crate below it.** -![conduwuit's dynamic library setup diagram - created by Jason +![Tuwunel's dynamic library setup diagram - created by Jason Volk](assets/libraries.png) When a symbol is referenced between crates they become bound: **crates cannot be @@ -147,7 +147,7 @@ by using an `RTLD_LOCAL` binding for just one link between the main executable and the first crate, freeing the executable from all modules as no global binding ever occurs between them. -![conduwuit's reload and load order diagram - created by Jason +![Tuwunel's reload and load order diagram - created by Jason Volk](assets/reload_order.png) Proper resource management is essential for reliable reloading to occur. This is @@ -196,5 +196,5 @@ The initial implementation PR is available [here][1]. [4]: https://github.com/rust-lang/rust/issues/28794#issuecomment-368693049 [5]: https://github.com/rust-lang/cargo/issues/12746 [6]: https://crates.io/crates/hot-lib-reloader/ -[7]: https://matrix.to/#/#conduwuit:puppygock.gay +[7]: https://matrix.to/#/#tuwunel:tuwunel.chat [8]: https://crates.io/crates/libloading diff --git a/docs/development/testing.md b/docs/development/testing.md index a577698a..1aee8667 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -5,7 +5,7 @@ Have a look at [Complement's repository][complement] for an explanation of what it is. -To test against Complement, with Nix (or [Lix](https://lix.systems) and +To test against Complement, with Nix and [direnv installed and set up][direnv] (run `direnv allow` after setting up the hook), you can: * Run `./bin/complement "$COMPLEMENT_SRC"` to build a Complement image, run @@ -24,8 +24,8 @@ and run the script. If you're on macOS and need to build an image, run `nix build .#linux-complement`. We have a Complement fork as some tests have needed to be fixed. This can be found -at: +at: -[ci-workflows]: https://github.com/girlbossceo/conduwuit/actions/workflows/ci.yml?query=event%3Apush+is%3Asuccess+actor%3Agirlbossceo +[ci-workflows]: https://github.com/matrix-construct/tuwunel/actions/workflows/ci.yml?query=event%3Apush+is%3Asuccess+actor%3Ajevolk [complement]: https://github.com/matrix-org/complement [direnv]: https://direnv.net/docs/hook.html diff --git a/docs/introduction.md b/docs/introduction.md index 9d3a294a..c45bcd2a 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,4 +1,4 @@ -# conduwuit +# Tuwunel {{#include ../README.md:catchphrase}} @@ -8,7 +8,7 @@ - [Deployment options](deploying.md) -If you want to connect an appservice to conduwuit, take a look at the +If you want to connect an appservice to Tuwunel, take a look at the [appservices documentation](appservices.md). #### How can I contribute? diff --git a/docs/maintenance.md b/docs/maintenance.md index 83475ef9..35579c7b 100644 --- a/docs/maintenance.md +++ b/docs/maintenance.md @@ -1,14 +1,14 @@ -# Maintaining your conduwuit setup +# Maintaining your Tuwunel setup ## Moderation -conduwuit has moderation through admin room commands. "binary commands" (medium +Tuwunel has moderation through admin room commands. "binary commands" (medium priority) and an admin API (low priority) is planned. Some moderation-related config options are available in the example config such as "global ACLs" and blocking media requests to certain servers. See the example config for the moderation config options under the "Moderation / Privacy / Security" section. -conduwuit has moderation admin commands for: +Tuwunel has moderation admin commands for: - managing room aliases (`!admin rooms alias`) - managing room directory (`!admin rooms directory`) @@ -36,7 +36,7 @@ each object being newline delimited. An example of doing this is: ## Database (RocksDB) Generally there is very little you need to do. [Compaction][rocksdb-compaction] -is ran automatically based on various defined thresholds tuned for conduwuit to +is ran automatically based on various defined thresholds tuned for Tuwunel to be high performance with the least I/O amplifcation or overhead. Manually running compaction is not recommended, or compaction via a timer, due to creating unnecessary I/O amplification. RocksDB is built with io_uring support @@ -50,7 +50,7 @@ Some RocksDB settings can be adjusted such as the compression method chosen. See the RocksDB section in the [example config](configuration/examples.md). btrfs users have reported that database compression does not need to be disabled -on conduwuit as the filesystem already does not attempt to compress. This can be +on Tuwunel as the filesystem already does not attempt to compress. This can be validated by using `filefrag -v` on a `.SST` file in your database, and ensure the `physical_offset` matches (no filesystem compression). It is very important to ensure no additional filesystem compression takes place as this can render @@ -70,7 +70,7 @@ they're server logs or database logs, however they are critical RocksDB files related to WAL tracking. The only safe files that can be deleted are the `LOG` files (all caps). These -are the real RocksDB telemetry/log files, however conduwuit has already +are the real RocksDB telemetry/log files, however Tuwunel has already configured to only store up to 3 RocksDB `LOG` files due to generally being useless for average users unless troubleshooting something low-level. If you would like to store nearly none at all, see the `rocksdb_max_log_files` @@ -88,7 +88,7 @@ still be joined together. To restore a backup from an online RocksDB backup: -- shutdown conduwuit +- shutdown Tuwunel - create a new directory for merging together the data - in the online backup created, copy all `.sst` files in `$DATABASE_BACKUP_PATH/shared_checksum` to your new directory @@ -99,9 +99,9 @@ To restore a backup from an online RocksDB backup: if you have multiple) to your new directory - set your `database_path` config option to your new directory, or replace your old one with the new one you crafted -- start up conduwuit again and it should open as normal +- start up Tuwunel again and it should open as normal -If you'd like to do an offline backup, shutdown conduwuit and copy your +If you'd like to do an offline backup, shutdown Tuwunel and copy your `database_path` directory elsewhere. This can be restored with no modifications needed. @@ -110,7 +110,7 @@ directory. ## Media -Media still needs various work, however conduwuit implements media deletion via: +Media still needs various work, however Tuwunel implements media deletion via: - MXC URI or Event ID (unencrypted and attempts to find the MXC URI in the event) @@ -118,17 +118,17 @@ event) - Delete remote media in the past `N` seconds/minutes via filesystem metadata on the file created time (`btime`) or file modified time (`mtime`) -See the `!admin media` command for further information. All media in conduwuit +See the `!admin media` command for further information. All media in Tuwunel is stored at `$DATABASE_DIR/media`. This will be configurable soon. If you are finding yourself needing extensive granular control over media, we recommend looking into [Matrix Media -Repo](https://github.com/t2bot/matrix-media-repo). conduwuit intends to +Repo](https://github.com/t2bot/matrix-media-repo). Tuwunel intends to implement various utilities for media, but MMR is dedicated to extensive media management. Built-in S3 support is also planned, but for now using a "S3 filesystem" on -`media/` works. conduwuit also sends a `Cache-Control` header of 1 year and +`media/` works. Tuwunel also sends a `Cache-Control` header of 1 year and immutable for all media requests (download and thumbnail) to reduce unnecessary media requests from browsers, reduce bandwidth usage, and reduce load. diff --git a/docs/turn.md b/docs/turn.md index 287f2545..d4596b08 100644 --- a/docs/turn.md +++ b/docs/turn.md @@ -1,6 +1,6 @@ # Setting up TURN/STURN -In order to make or receive calls, a TURN server is required. conduwuit suggests +In order to make or receive calls, a TURN server is required. Tuwunel suggests using [Coturn](https://github.com/coturn/coturn) for this purpose, which is also available as a Docker image. @@ -17,9 +17,9 @@ realm= A common way to generate a suitable alphanumeric secret key is by using `pwgen -s 64 1`. -These same values need to be set in conduwuit. See the [example +These same values need to be set in Tuwunel. See the [example config](configuration/examples.md) in the TURN section for configuring these and -restart conduwuit after. +restart Tuwunel after. `turn_secret` or a path to `turn_secret_file` must have a value of your coturn `static-auth-secret`, or use `turn_username` and `turn_password` @@ -34,7 +34,7 @@ If you are using TURN over TLS, you can replace `turn:` with `turns:` in the TURN over TLS. This is highly recommended. If you need unauthenticated access to the TURN URIs, or some clients may be -having trouble, you can enable `turn_guest_access` in conduwuit which disables +having trouble, you can enable `turn_guest_access` in Tuwunel which disables authentication for the TURN URI endpoint `/_matrix/client/v3/voip/turnServer` ### Run diff --git a/src/api/client/membership/knock.rs b/src/api/client/membership/knock.rs index fb500601..db57b411 100644 --- a/src/api/client/membership/knock.rs +++ b/src/api/client/membership/knock.rs @@ -294,7 +294,7 @@ async fn knock_room_helper_local( .supported_room_version(&room_version_id) { return Err!(BadServerResponse( - "Remote room version {room_version_id} is not supported by conduwuit" + "Remote room version {room_version_id} is not supported by tuwunel" )); } @@ -427,7 +427,7 @@ async fn knock_room_helper_remote( .supported_room_version(&room_version_id) { return Err!(BadServerResponse( - "Remote room version {room_version_id} is not supported by conduwuit" + "Remote room version {room_version_id} is not supported by tuwunel" )); } diff --git a/src/api/client/membership/leave.rs b/src/api/client/membership/leave.rs index 84d77c73..dcdf7c91 100644 --- a/src/api/client/membership/leave.rs +++ b/src/api/client/membership/leave.rs @@ -318,7 +318,7 @@ async fn remote_leave_room( let Some(room_version_id) = make_leave_response.room_version else { return Err!(BadServerResponse(warn!( "No room version was returned by {remote_server} for {room_id}, room version is \ - likely not supported by conduwuit" + likely not supported by tuwunel" ))); }; diff --git a/src/api/router/auth.rs b/src/api/router/auth.rs index f8ca4d3f..b2c73678 100644 --- a/src/api/router/auth.rs +++ b/src/api/router/auth.rs @@ -294,7 +294,7 @@ async fn auth_server( if request.parts.uri.to_string().contains('@') { warn!( "Request uri contained '@' character. Make sure your reverse proxy gives \ - conduwuit the raw uri (apache: use nocanon)" + tuwunel the raw uri (apache: use nocanon)" ); }