mirror of
https://github.com/AThilenius/axum-connect.git
synced 2024-11-24 06:19:46 +00:00
Update readme with a bit more info and thoughts
This commit is contained in:
parent
e8b0bd2b1a
commit
9f017696e5
2 changed files with 32 additions and 4 deletions
3
.vscode/settings.json
vendored
3
.vscode/settings.json
vendored
|
@ -1,10 +1,13 @@
|
|||
{
|
||||
"cSpell.words": [
|
||||
"Buf's",
|
||||
"bufbuild",
|
||||
"codegen",
|
||||
"concat",
|
||||
"DTLS",
|
||||
"impls",
|
||||
"pbjson",
|
||||
"println",
|
||||
"prost",
|
||||
"proto",
|
||||
"protobuf",
|
||||
|
|
33
README.md
33
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 🌜
|
||||
|
|
Loading…
Reference in a new issue