Move relay arch into relayapi and add docs for new endpoints

1 files changed, 134 insertions, 0 deletions

diff --git a/relayapi/ARCHITECTURE.md b/relayapi/ARCHITECTURE.md
new file mode 100644
index 00000000..f4cf529b
--- /dev/null
+++ b/relayapi/ARCHITECTURE.md
@@ -0,0 +1,134 @@
+## Relay Server Architecture
+
+Relay Servers function similar to the way physical mail drop boxes do. 
+A node can have many associated relay servers. Matrix events can be sent to them instead of to the destination node, and the destination node will eventually retrieve them from the relay server. 
+Nodes that want to send events to an offline node need to know what relay servers are associated with their intended destination. 
+Currently this is manually configured in the dendrite database. In the future this information could be configurable in the app and shared automatically via other means.
+
+Currently events are sent as complete Matrix Transactions. 
+Transactions include a list of PDUs, (which contain, among other things, lists of authorization events, previous events, and signatures) a list of EDUs, and other information about the transaction. 
+There is no additional information sent along with the transaction other than what is typically added to them during Matrix federation today. 
+In the future this will probably need to change in order to handle more complex room state resolution during p2p usage.
+
+### Design
+
+```
+                     0                            +--------------------+
+ +----------------------------------------+       |     P2P Node A     |
+ |             Relay Server               |       |     +--------+     |
+ |                                        |       |     | Client |     |
+ |                 +--------------------+ |       |     +--------+     |
+ |                 |  Relay Server API  | |       |          |         |
+ |                 |                    | |       |          V         |
+ |  .--------.   2 |   +-------------+  | |   1   |   +------------+   |
+ | |`--------`| <----- |  Forwarder  | <------------- | Homeserver |   |
+ | | Database |    |   +-------------+  | |       |   +------------+   |
+ | `----------`    |                    | |       +--------------------+
+ |       ^         |                    | |       
+ |       |     4   |   +-------------+  | |  
+ |       `------------ |  Retriever  | <------.   +--------------------+
+ |                 |   +-------------+  | |   |   |     P2P Node B     |
+ |                 |                    | |   |   |     +--------+     |
+ |                 +--------------------+ |   |   |     | Client |     |
+ |                                        |   |   |     +--------+     |
+ +----------------------------------------+   |   |          |         |
+                                              |   |          V         |
+                                            3 |   |   +------------+   |
+                                              `------ | Homeserver |   |
+                                                  |   +------------+   |
+                                                  +--------------------+
+```
+
+-   0: This relay server is currently only acting on behalf of `P2P Node B`. It will only receive, and later forward events that are destined for `P2P Node B`.
+-   1: When `P2P Node A` fails sending directly to `P2P Node B` (after a configurable number of attempts), it checks for any known relay servers associated with `P2P Node B` and sends to all of them.
+    - If sending to any of the relay servers succeeds, that transaction is considered to be successfully sent.      
+-   2: The relay server `forwarder` stores the transaction json in its database and marks it as destined for `P2P Node B`.
+-   3: When `P2P Node B` comes online, it queries all its relay servers for any missed messages.
+-   4: The relay server `retriever` will look in its database for any transactions that are destined for `P2P Node B` and returns them one at a time.
+
+For now, it is important that we don’t design out a hybrid approach of having both sender-side and recipient-side relay servers. 
+Both approaches make sense and determining which makes for a better experience depends on the use case.
+
+#### Sender-Side Relay Servers
+
+If we are running around truly ad-hoc, and I don't know when or where you will be able to pick up messages, then having a sender designated server makes sense to give things the best chance at making their way to the destination. 
+But in order to achieve this, you are either relying on p2p presence broadcasts for the relay to know when to try forwarding (which means you are in a pretty small network), or the relay just keeps on periodically attempting to forward to the destination which will lead to a lot of extra traffic on the network.
+
+#### Recipient-Side Relay Servers
+
+If we have agreed to some static relay server before going off and doing other things, or if we are talking about more global p2p federation, then having a recipient designated relay server can cut down on redundant traffic since it will sit there idle until the recipient pulls events from it.
+
+### API
+
+Relay servers make use of 2 new matrix federation endpoints.
+These are:
+- PUT /_matrix/federation/v1/send_relay/{txnID}/{userID}
+- GET /_matrix/federation/v1/relay_txn/{userID}
+
+#### Send_Relay
+
+The `send_relay` endpoint is used to send events to a relay server that are destined for some other node. Servers can send events to this endpoint if they wish for the relay server to store & forward events for them when they go offline.
+
+##### Request
+
+###### Request Parameters
+
+|  Name  |  Type  |  Description                                        |
+|--------|--------|-----------------------------------------------------|
+| txnID  | string | **Required:** The transaction ID.                   |
+| userID | string | **Required:** The destination for this transaciton. |
+
+###### Request Body
+
+|  Name  |  Type  |  Description                           |
+|--------|--------|----------------------------------------|
+| pdus   | [PDU]  | **Required:** List of pdus. Max 50.    |
+| edus   | [EDU]  | List of edus. May be omitted. Max 100. |
+
+##### Responses
+
+|  Code  |  Reason                                          |
+|--------|--------------------------------------------------|
+| 200    | Successfully stored transaction for forwarding.  |
+| 400    | Invalid userID.                                  |
+| 400    | Invalid request body.                            |
+| 400    | Too many pdus or edus.                           |
+| 500    | Server failed processing transaction.            |
+
+#### Relay_Txn
+
+The `relay_txn` endpoint is used to get events from a relay server that are destined for you. Servers can send events to this endpoint if they wish for the relay server to store & forward events for them when they go offline.
+
+##### Request
+
+**This needs to be changed to prevent nodes from obtaining transactions not destined for them. Possibly by adding a signature field to the request.**
+
+###### Request Parameters
+
+|  Name  |  Type  |  Description                                                   |
+|--------|--------|----------------------------------------------------------------|
+| userID | string | **Required:** The user ID that events are being requested for. |
+
+###### Request Body
+
+|  Name    |  Type  |  Description                           |
+|----------|--------|----------------------------------------|
+| entry_id | int64  | **Required:** The id of the previous transaction received from the relay. Provided in the previous response to this endpoint. |
+
+##### Responses
+
+|  Code  |  Reason                                          |
+|--------|--------------------------------------------------|
+| 200    | Successfully stored transaction for forwarding.  |
+| 400    | Invalid userID.                                  |
+| 400    | Invalid request body.                            |
+| 400    | Invalid previous entry. Must be >= 0             |
+| 500    | Server failed processing transaction.            |
+
+###### 200 Response Body
+
+|  Name          |  Type        |  Description                                                             |
+|----------------|--------------|--------------------------------------------------------------------------|
+| transaction    | Transaction  | **Required:** A matrix transaction.                                      |
+| entry_id       | int64        | An ID associated with this transaction.                                  |
+| entries_queued | bool         | **Required:** Whether or not there are more events stored for this user. |