Skip to content

Commit 47de871

Browse files
committed
chore: update arch doc
1 parent 9600ef4 commit 47de871

File tree

1 file changed

+34
-16
lines changed

1 file changed

+34
-16
lines changed

docs/guide/architecture.md

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -114,36 +114,54 @@ Error details follow the Connect protocol's structured error format, serialized
114114

115115
## Handler Wrappers
116116

117-
These implement `axum::handler::Handler` for each RPC pattern:
117+
The library uses a unified handler wrapper that supports all RPC patterns:
118118

119119
| Wrapper | Use Case |
120120
|---------|----------|
121-
| `ConnectHandlerWrapper<F>` | Unified: unary, server/client/bidi streaming (auto-detected) |
122-
| `ConnectStreamHandlerWrapper<F>` | Server streaming (explicit) |
123-
| `ConnectClientStreamHandlerWrapper<F>` | Client streaming (explicit) |
124-
| `ConnectBidiStreamHandlerWrapper<F>` | Bidirectional streaming (explicit) |
121+
| `ConnectHandlerWrapper<F>` | Unified: unary, server/client/bidi streaming with optional extractors |
125122
| `TonicCompatibleHandlerWrapper<F>` | Tonic-style unary with axum extractors |
126123
| `TonicCompatibleStreamHandlerWrapper<F>` | Tonic-style server streaming with axum extractors |
127124
| `TonicCompatibleClientStreamHandlerWrapper<F>` | Tonic-style client streaming with axum extractors |
128125
| `TonicCompatibleBidiStreamHandlerWrapper<F>` | Tonic-style bidi streaming with axum extractors |
129126

127+
### Handler Functions
128+
129+
Two functions create method routers from handlers:
130+
131+
| Function | HTTP Method | Use Case |
132+
|----------|-------------|----------|
133+
| `post_connect(f)` | POST | Unary and streaming RPCs |
134+
| `get_connect(f)` | GET | Idempotent unary RPCs (query param encoding) |
135+
130136
### How Handler Wrappers Work
131137

132-
`ConnectHandlerWrapper<F>` is a newtype that wraps a user function `F`. It has multiple `impl Handler<T, S>` blocks, each with different `where` bounds on `F`:
138+
`ConnectHandlerWrapper<F>` is a newtype that wraps a user function `F`. It has multiple `impl Handler<T, S>` blocks, each with different `where` bounds on `F`. The compiler selects the appropriate impl based on the handler signature:
139+
140+
**Unary handlers:**
141+
```rust
142+
// Basic: (ConnectRequest<Req>) -> ConnectResponse<Resp>
143+
// With extractors: (State<T>, ConnectRequest<Req>) -> ConnectResponse<Resp>
144+
```
145+
146+
**Server streaming handlers:**
147+
```rust
148+
// Basic: (ConnectRequest<Req>) -> ConnectResponse<StreamBody<St>>
149+
// With extractors: (State<T>, ConnectRequest<Req>) -> ConnectResponse<StreamBody<St>>
150+
```
151+
152+
**Client streaming handlers:**
153+
```rust
154+
// Basic: (ConnectRequest<Streaming<Req>>) -> ConnectResponse<Resp>
155+
// With extractors: (State<T>, ConnectRequest<Streaming<Req>>) -> ConnectResponse<Resp>
156+
```
133157

158+
**Bidi streaming handlers:**
134159
```rust
135-
// When F returns ConnectResponse<Resp> (not StreamBody)
136-
impl<F, ...> Handler<(ConnectRequest<Req>,), ()> for ConnectHandlerWrapper<F>
137-
where F: Fn(ConnectRequest<Req>) -> Fut,
138-
Fut: Future<Output = Result<ConnectResponse<Resp>, ConnectError>>, ...
139-
140-
// When F returns ConnectResponse<StreamBody<St>>
141-
impl<F, ...> Handler<(ConnectRequest<Req>, StreamBody<St>), ()> for ConnectHandlerWrapper<F>
142-
where F: Fn(ConnectRequest<Req>) -> Fut,
143-
Fut: Future<Output = Result<ConnectResponse<StreamBody<St>>, ConnectError>>, ...
160+
// Basic: (ConnectRequest<Streaming<Req>>) -> ConnectResponse<StreamBody<St>>
161+
// With extractors: (State<T>, ConnectRequest<Streaming<Req>>) -> ConnectResponse<StreamBody<St>>
144162
```
145163

146-
The compiler inspects `F`'s signature (input types + return type) and selects the impl whose `where` bounds match. The `T` parameter in `Handler<T, S>` acts as a discriminator tag - it's not used at runtime, only for impl selection.
164+
The `T` parameter in `Handler<T, S>` acts as a discriminator tag for impl selection. Separate macro-generated implementations handle extractors for each streaming pattern.
147165

148166
## Builder Pattern
149167

0 commit comments

Comments
 (0)