From 5c8cdd073acf7e705d2de6d448de4108140efd5c Mon Sep 17 00:00:00 2001
From: Damian Poddebniak <poddebniak@mailbox.org>
Date: Fri, 27 Oct 2023 18:14:44 +0200
Subject: [PATCH] docs(proxy): Add `README.md`

---
 proxy/README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 proxy/README.md

diff --git a/proxy/README.md b/proxy/README.md
new file mode 100644
index 00000000..fc0bfa29
--- /dev/null
+++ b/proxy/README.md
@@ -0,0 +1,96 @@
+# IMAP Proxy
+
+A proxy that receives, `Debug`-prints, and forwards IMAP messages.
+
+It should™ forward all messages *without changing their semantics*. (See note below.)
+
+Still, ...
+
+> [!WARNING]
+> **Don't use in production yet!**
+
+## Overview
+
+```mermaid  
+graph LR;
+	Client -->|"① parse Command"| Proxy;
+	Proxy  -->|"② change Command (currently no change)"| Proxy;
+	Proxy  -->|"③ serialize Command'"| Server;
+	Server -->|"④ parse Response"| Proxy;
+	Proxy  -->|"⑥ serialize Response'"| Client;
+	Proxy  -->|"⑤ change Response (currently no change)"| Proxy;
+```
+
+> [!NOTE]
+> IMAP is a malleable protocol that allows sending commands "piece-by-piece" using "literals".
+> We generally don't preserve semantically irrelevant information such as casing or optional braces.
+> Further, we abstract literal handling to make the proxy more helpful.
+> Essentially, the proxy presents messages "in one piece", meaning they can be easily exchanged (if so desired).
+> Still, the literal abstraction introduces a (minor) semantic change.
+> While this could be rectified in the future, it should be mostly irrelevant in practice.
+
+# Quickstart
+
+Change into the `proxy` folder and run ...
+
+```shell
+cargo run -- --help
+```
+
+... for an overview of arguments.
+
+**Important**: You must enable tracing (logging) to see a `Debug`-print of exchanged messages.
+
+To do so, set the `RUST_LOG` environment variable.
+
+Use ...
+
+```sh
+RUST_LOG=proxy=trace cargo run
+```
+
+... to start the proxy (using the default `config.toml`), enabling all log messages for the "proxy" module.
+
+## Config
+
+The config consists of multiple "services", and each service looks roughly like this:
+
+```toml
+[[services]]
+name = "A user-defined name"
+bind = { host = "127.0.0.1", port = 1143, security = "Insecure" }
+connect = { host = "imap.example.org", port = 993 }
+```
+
+The `security` field configures TLS. `Insecure` disables TLS encryption and SHOULD NOT be used when proxying to a remote server.
+
+## Features
+
+Thanks to `imap-flow`, the proxy ...
+
+* takes advantage of asynchronous I/O,
+* abstracts away literal handling, and
+* fully supports unsolicited responses,
+
+... making it easy to modify.
+
+# Current purpose
+
+Proxies are a great way to challenge the usability of a network library such as `imap-flow`.
+To implement a proxy, it's required to implement both the server- and client-side, and the tasks require designing the library in a way that allows even fine-grained forwarding.
+Further, a usable proxy would significantly extend the exposure of `imap-codec` to real-world network traces.
+It should be possible to permanently stick the proxy between real-world IMAP sessions, e.g., to track day-to-day email sessions (and ask other contributors to conduct the same test.)
+
+# Future work
+
+The proxy could enrich existing clients' functionality to improve compatibility, performance, and security.
+This could be done by fleshing out the proxy into a configurable framework.
+
+Examples:
+
+* `XOAUTH2` could transparently be added to non-supporting clients
+* Support for "capabilities in greetings" or `LITERAL+` could be transparently added to improve performance
+* Encryption could be transparently added such that emails are always appended in encrypted form and decrypted during fetching
+* Vintage clients could use the proxy as a TLS gateway
+* Messages could be forwarded to other software for analysis
+* Protocol traces could be automatically analyzed for supported features