From 6e913bfec40e941dc70bad1e4a75bcf77971eeb1 Mon Sep 17 00:00:00 2001
From: Matthias Ahouansou <matthias@ahouansou.cz>
Date: Thu, 2 May 2024 09:27:14 +0100
Subject: [PATCH] docs: delegation

---
 book.toml             |  4 +++
 docs/SUMMARY.md       |  1 +
 docs/configuration.md |  1 +
 docs/delegation.md    | 69 +++++++++++++++++++++++++++++++++++++++++++
 docs/faq.md           | 12 +++++---
 5 files changed, 83 insertions(+), 4 deletions(-)
 create mode 100644 docs/delegation.md

diff --git a/book.toml b/book.toml
index e25746ca..700ecda5 100644
--- a/book.toml
+++ b/book.toml
@@ -16,3 +16,7 @@ git-repository-icon = "fa-git-square"
 
 [output.html.search]
 limit-results = 15
+
+[output.html.code.hidelines]
+json = "~"
+
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index f874bb21..afba3cca 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -3,6 +3,7 @@
 - [Introduction](introduction.md)
 
 - [Configuration](configuration.md)
+- [Delegation](delegation.md)
 - [Deploying](deploying.md)
     - [Generic](deploying/generic.md)
     - [Debian](deploying/debian.md)
diff --git a/docs/configuration.md b/docs/configuration.md
index efa080dc..d903a21e 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -56,6 +56,7 @@ The `global` section contains the following fields:
 | `turn_secret` | `string` | The TURN secret | `""` |
 | `turn_ttl` | `integer` | The TURN TTL in seconds | `86400` |
 | `emergency_password` | `string` | Set a password to login as the `conduit` user in case of emergency | N/A |
+| `well_known` | `table` | Used for [delegation](delegation.md) | See [delegation](delegation.md) |
 
 
 ### TLS
diff --git a/docs/delegation.md b/docs/delegation.md
new file mode 100644
index 00000000..c8e5391c
--- /dev/null
+++ b/docs/delegation.md
@@ -0,0 +1,69 @@
+# Delegation
+
+You can run Conduit on a separate domain than the actual server name (what shows up in user ids, aliases, etc.).
+For example you can have your users have IDs such as `@foo:example.org` and have aliases like `#bar:example.org`,
+while actually having Conduit hosted on the `matrix.example.org` domain. This is called delegation.
+
+## Automatic (recommended)
+
+Conduit has support for hosting delegation files by itself, and by default uses it to serve federation traffic on port 443.
+
+With this method, you need to direct requests to `/.well-known/matrix/*` to Conduit in your reverse proxy.
+
+This is only recommended if Conduit is on the same physical server as the server which serves your server name (e.g. example.org)
+as servers don't always seem to cache the response, leading to slower response times otherwise, but it should also work if you
+are connected to the server running Conduit using something like a VPN.
+
+> **Note**: this will automatically allow you to use [sliding sync][0] without any extra configuration
+
+To configure it, use the following options in the `global.well_known` table:
+| Field | Type | Description | Default |
+| --- | --- | --- | --- |
+| `client` | `String` | The URL that clients should use to connect to Conduit | `https://<server_name>` |
+| `server` | `String` | The hostname and port servers should use to connect to Conduit | `<server_name>:443` |
+
+### Example
+
+```toml
+[global.well_known]
+client = "https://matrix.example.org"
+server = "matrix.example.org:443"
+```
+
+## Manual
+
+Alternatively you can serve static JSON files to inform clients and servers how to connect to Conduit.
+
+### Servers
+
+For servers to discover how to access your domain, serve a response in the following format for `/.well-known/matrix/server`:
+
+```json
+{
+  "m.server": "matrix.example.org:443"
+}
+```
+Where `matrix.example.org` is the domain and `443` is the port Conduit is accessible at.
+
+### Clients
+
+For clients to discover how to access your domain, serve a response in the following format for `/.well-known/matrix/client`:
+```json
+{
+  "m.homeserver": {
+    "base_url": "https://matrix.example.org"
+  }
+}
+```
+Where `matrix.example.org` is the URL Conduit is accessible at.
+
+To ensure that all clients can access this endpoint, it is recommended you set the following headers for this endpoint:
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+Access-Control-Allow-Headers: X-Requested-With, Content-Type, Authorization
+```
+
+If you also want to be able to use [sliding sync][0], look [here](faq.md#how-do-i-setup-sliding-sync).
+
+[0]: https://matrix.org/blog/2023/09/matrix-2-0/#sliding-sync
diff --git a/docs/faq.md b/docs/faq.md
index ce84f818..4c23a25c 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -15,12 +15,16 @@ You can simply stop Conduit, make a copy or file system snapshot of the database
 
 ## How do I setup sliding sync?
 
-You need to add a `org.matrix.msc3575.proxy` field to your `.well-known/matrix/client` response which points to Conduit. Here is an example:
+If you use the [automatic method for delegation](delegation.md#automatic-recommended) or just proxy `.well-known/matrix/client` to Conduit, sliding sync should work with no extra configuration.
+If you don't, continue below.
+
+You need to add a `org.matrix.msc3575.proxy` field to your `.well-known/matrix/client` response which contains a url which Conduit is accessible behind.
+Here is an example:
 ```json
 {
-  "m.homeserver": {
-    "base_url": "https://matrix.example.org"
-  },
+~  "m.homeserver": {
+~    "base_url": "https://matrix.example.org"
+~  },
   "org.matrix.msc3575.proxy": {
     "url": "https://matrix.example.org"
   }