From 9f017696e518dbb2052c1e2824ebfcab85c5d1cf Mon Sep 17 00:00:00 2001
From: Alec Thilenius <alec@thilenius.com>
Date: Thu, 25 May 2023 17:52:41 -0700
Subject: [PATCH] Update readme with a bit more info and thoughts

---
 .vscode/settings.json |  3 +++
 README.md             | 33 +++++++++++++++++++++++++++++----
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 92b0a94..6e8b06a 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,10 +1,13 @@
 {
   "cSpell.words": [
+    "Buf's",
     "bufbuild",
     "codegen",
+    "concat",
     "DTLS",
     "impls",
     "pbjson",
+    "println",
     "prost",
     "proto",
     "protobuf",
diff --git a/README.md b/README.md
index eb352e0..0e6587c 100644
--- a/README.md
+++ b/README.md
@@ -150,14 +150,39 @@ curl --location 'http://localhost:3030/hello.HelloWorldService/SayHello' \
 From here you can stand up a `connect-web` TypeScript/Go project to call your
 API with end-to-end typed RPCs.
 
+## Request/Response Parts
+
+Both the request and response types are derived in `axum-connect`. This might
+seem redundant at first.
+
+Let's go over the easier one first, `RpcIntoResponse`. Connect RPCs are not
+arbitrary HTML requests, they cannot return arbitrary HTML responses. For
+example, streaming responses MUST return an HTTP 200 regardless of error state.
+Keeping with Axum's (fantastic) paradigm, that is enforced by the type system.
+RPC handler may not return arbitrary HTML, but instead must return something
+that `axum-connect` knows how to turn into a valid Connect response.
+
+Somewhat less intuitively, `axum-connect` derives `RpcFromRequestParts`, which
+is _almost_ identical to Axum's `FromRequestParts`. Importantly though,
+`FromRequestParts` can return back an error of arbitrary HTML responses, which
+is a problem for the same reason.
+
+Axum also allows a `FromRequest` to occupy the last parameter in a handler which
+consumed the remainder of the HTTP request (including the body). `axum-connect`
+needs to handle the response input itself, so there is no equivalent for RPCs
+handlers.
+
 # Roadmap / Stated Non-Goals 🛣️
 
-- Binary proto encoding based on HTTP `content-type`
-- Streaming server RPC responses
-- Bring everything in-line with `connect-web`
+- Explore better typing that `RpcFromRequestParts`
+  - Ideally clients only need to provide an `RpcIntoError`, but I haven't fully
+    thought this problem though. I just know that having to specific both a
+    `FromRequestParts` and an `RpcFromRequestParts` on custom types is a PITA.
+- Rework error responses to allow for multiple errors
 - Version checking between generated and runtime code
 - A plan for forward-compatibility
-- Comprehensive tests
+- Bring everything in-line with `connect-web` and...
+- Comprehensive integration tests
 - A first-stable launch
 
 ## More Distant Goals 🌜