Skip to content

Commit 968cbfe

Browse files
st0o0st0o0
committed
docs: update
1 parent 9f4ed18 commit 968cbfe

10 files changed

Lines changed: 161 additions & 256 deletions

File tree

‎docs/architecture/engines.md‎

Lines changed: 22 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Protocol Engines
22

3-
The `Engine` demultiplexes requests by HTTP version and routes each request to the appropriate per-version engine. Each engine is a self-contained Akka.Streams sub-graph composed of a **unified ConnectionStage** (which handles encoding, decoding, and request/response correlation internally) and a **NetworkBufferBatchStage** (which coalesces outbound items into fewer, larger writes). The engine's output connects to a transport stage (`TcpConnectionStage` or `QuicConnectionStage`) that manages the actual network connection.
3+
The `Engine` demultiplexes requests by HTTP version and routes each request to the appropriate per-version engine. Each engine is a self-contained Akka.Streams sub-graph composed of a **unified ConnectionStage** (which handles encoding, decoding, and request/response correlation internally). The engine's output connects to a transport stage (`TcpConnectionStage` or `QuicConnectionStage` from Servus.Akka) that manages the actual network connection.
44

55
---
66

@@ -15,15 +15,14 @@ HTTP/1.0 uses a **close-then-respond** model. Each connection handles exactly on
1515
**Internal composition:**
1616

1717
```
18-
HttpRequestMessage → Http10ConnectionStage → NetworkBufferBatchStage → [TcpConnectionStage] → TCP
18+
HttpRequestMessage → Http10ConnectionStage → [TcpConnectionStage] → TCP
1919
TCP → [TcpConnectionStage] → Http10ConnectionStage → HttpResponseMessage
2020
```
2121

22-
| Component | Role |
23-
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
24-
| `Http10ConnectionStage` | Unified stage: serialises request to wire bytes (sets `Connection: close`), parses the HTTP/1.0 response, and correlates request/response (FIFO, depth 1) |
25-
| `NetworkBufferBatchStage` | Coalesces consecutive outbound network buffers into fewer, larger writes to reduce syscalls |
26-
| `TcpConnectionStage` | TCP transport — acquires a connection lease from the pool, reads/writes bytes |
22+
| Component | Role |
23+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| `Http10ConnectionStage` | Unified stage: serialises request to wire bytes (sets `Connection: close`), parses the HTTP/1.0 response, and correlates request/response (FIFO, depth 1) |
25+
| `TcpConnectionStage` | TCP transport (from Servus.Akka) — acquires a connection lease from the manager actor, reads/writes bytes |
2726

2827
**Notable behaviours:**
2928

@@ -44,21 +43,20 @@ HTTP/1.1 adds **persistent connections** and **keep-alive control**. The unified
4443
**Internal composition:**
4544

4645
```
47-
HttpRequestMessage → Http11ConnectionStage → NetworkBufferBatchStage → [TcpConnectionStage] → TCP
46+
HttpRequestMessage → Http11ConnectionStage → [TcpConnectionStage] → TCP
4847
TCP → [TcpConnectionStage] → Http11ConnectionStage → HttpResponseMessage
4948
```
5049

51-
| Component | Role |
52-
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53-
| `Http11ConnectionStage` | Unified stage: serialises request (adds `Host`, `Connection`, `Transfer-Encoding: chunked` as needed), parses HTTP/1.1 responses (handles chunked decoding), correlates request/response (FIFO, depth > 1 enables pipelining), and evaluates keep-alive signals |
54-
| `NetworkBufferBatchStage` | Coalesces consecutive outbound network buffers into fewer, larger writes — correctly handles interleaved control items (connection reuse signals) by flushing the buffer before forwarding them |
55-
| `TcpConnectionStage` | TCP transport with connection reuse — returns leases to the pool on keep-alive, requests new connections on close |
50+
| Component | Role |
51+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52+
| `Http11ConnectionStage` | Unified stage: serialises request (adds `Host`, `Connection`, `Transfer-Encoding: chunked` as needed), parses HTTP/1.1 responses (handles chunked decoding), correlates request/response (FIFO, depth > 1 enables pipelining), and evaluates keep-alive signals |
53+
| `TcpConnectionStage` | TCP transport with connection reuse (from Servus.Akka) — returns leases to the pool on keep-alive, requests new connections on close |
5654

5755
**Keep-alive handling:**
5856

5957
After decoding each response, `Http11ConnectionStage` evaluates the `Connection` header internally:
6058

61-
- `Connection: keep-alive` (or HTTP/1.1 default) → the connection lease is returned to `ConnectionPool` for reuse
59+
- `Connection: keep-alive` (or HTTP/1.1 default) → the connection lease is returned to the connection manager actor for reuse
6260
- `Connection: close` → the lease is released without returning it to the idle queue; the next request triggers a new connection
6361

6462
**Pipelining:**
@@ -78,15 +76,14 @@ HTTP/2 provides **stream multiplexing** — many logical requests share a single
7876
**Internal composition:**
7977

8078
```
81-
HttpRequestMessage → Http20ConnectionStage → NetworkBufferBatchStage → [TcpConnectionStage] → TCP
79+
HttpRequestMessage → Http20ConnectionStage → [TcpConnectionStage] → TCP
8280
TCP → [TcpConnectionStage] → Http20ConnectionStage → HttpResponseMessage
8381
```
8482

85-
| Component | Role |
86-
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
87-
| `Http20ConnectionStage` | Central unified stage: allocates client stream IDs (1, 3, 5, …), HPACK-encodes request headers and emits `HEADERS` + `DATA` frames, handles frame encoding/decoding (9-byte frame header + payload), manages connection-level frames (`SETTINGS`, `PING`, `WINDOW_UPDATE`, `GOAWAY`), tracks connection and stream-level flow control windows, assembles per-stream `HEADERS` + `DATA` frames into `HttpResponseMessage`, and correlates responses by stream ID |
88-
| `NetworkBufferBatchStage` | Coalesces consecutive outbound frame buffers into fewer, larger writes — reducing syscall count under concurrent multiplexed streams; control items are flushed through immediately to preserve frame ordering |
89-
| `TcpConnectionStage` | TCP transport — emits the HTTP/2 connection preface on first connect |
83+
| Component | Role |
84+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85+
| `Http20ConnectionStage` | Central unified stage: allocates client stream IDs (1, 3, 5, …), HPACK-encodes request headers and emits `HEADERS` + `DATA` frames, handles frame encoding/decoding (9-byte frame header + payload), manages connection-level frames (`SETTINGS`, `PING`, `WINDOW_UPDATE`, `GOAWAY`), tracks connection and stream-level flow control windows, assembles per-stream `HEADERS` + `DATA` frames into `HttpResponseMessage`, and correlates responses by stream ID |
86+
| `TcpConnectionStage` | TCP transport (from Servus.Akka) — emits the HTTP/2 connection preface on first connect |
9087

9188
**HPACK header compression:**
9289

@@ -109,15 +106,14 @@ HTTP/3 runs over **QUIC** instead of TCP. Each request uses an independent QUIC
109106
**Internal composition:**
110107

111108
```
112-
HttpRequestMessage → Http30ConnectionStage → NetworkBufferBatchStage → [QuicConnectionStage] → QUIC
109+
HttpRequestMessage → Http30ConnectionStage → [QuicConnectionStage] → QUIC
113110
QUIC → [QuicConnectionStage] → Http30ConnectionStage → HttpResponseMessage
114111
```
115112

116-
| Component | Role |
117-
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118-
| `Http30ConnectionStage` | Central unified stage: QPACK-encodes request headers, emits `HEADERS` + `DATA` frames over QUIC streams, handles frame encoding/decoding using QUIC variable-length encoding, manages connection-level frames (`SETTINGS`, `GOAWAY`), handles stream multiplexing and lifecycle, assembles per-stream frames into `HttpResponseMessage`, and QPACK-decodes response headers |
119-
| `NetworkBufferBatchStage` | Coalesces consecutive outbound items into fewer, larger writes |
120-
| `QuicConnectionStage` | QUIC transport — acquires a QUIC connection from the pool, writes/reads bytes over QUIC streams |
113+
| Component | Role |
114+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115+
| `Http30ConnectionStage` | Central unified stage: QPACK-encodes request headers, emits `HEADERS` + `DATA` frames over QUIC streams, handles frame encoding/decoding using QUIC variable-length encoding, manages connection-level frames (`SETTINGS`, `GOAWAY`), handles stream multiplexing and lifecycle, assembles per-stream frames into `HttpResponseMessage`, and QPACK-decodes response headers |
116+
| `QuicConnectionStage` | QUIC transport (from Servus.Akka) — acquires a QUIC connection from the manager actor, writes/reads bytes over QUIC streams |
121117

122118
**QPACK header compression:**
123119

‎docs/architecture/handlers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ services.AddTurboHttpClient("myapi", options => { ... })
162162
↓
163163
[AltSvcBidiStage] ← Alt-Svc version upgrade (innermost)
164164
↓
165-
── Engine + ConnectionStage + NetworkBufferBatchStage + Transport ──
165+
── Engine + ConnectionStage + Transport ──
166166
↓
167167
── response returns ──
168168
↓

‎docs/architecture/pipeline.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,11 @@ Each `HttpRequestMessage` passes through the following stages before reaching th
2121
| 5 | Cookie Injection (`CookieBidiStage`) | Looks up matching cookies for the target domain and path and adds a `Cookie` header |
2222
| 6 | Retry (`RetryBidiStage`) | On the request side, attaches retry context; on a transient failure, re-enters below the Cookie stage (same URL, cookies already set) |
2323
| 7 | Expect-Continue (`ExpectContinueBidiStage`) | For requests with large bodies, sends `Expect: 100-continue` and holds the body until the server confirms it will accept it |
24-
| 8 | Cache Lookup (`CacheBidiStage`) | Checks the in-memory cache; on a **cache hit**, returns the cached response immediately — stages 9–12 are skipped entirely |
24+
| 8 | Cache Lookup (`CacheBidiStage`) | Checks the in-memory cache; on a **cache hit**, returns the cached response immediately — stages 9–11 are skipped entirely |
2525
| 9 | Content Encoding (`ContentEncodingBidiStage`) | Compresses the request body if a compression policy is configured; on the response side, transparently decompresses `gzip`, `deflate`, or Brotli |
2626
| 10 | Alt-Svc Discovery (`AltSvcBidiStage`) | Checks for cached Alt-Svc entries and upgrades the request version if a faster protocol is available; captures Alt-Svc headers from responses |
2727
| 11 | Version Router (`Engine`) | Routes the request to the correct protocol handler based on the requested HTTP version |
28-
| 12 | Protocol ConnectionStage _(per version)_ | Unified stage that serialises the request to bytes, parses the response, and correlates request/response — then `NetworkBufferBatchStage` batches the outbound writes and `TcpConnectionStage`/`QuicConnectionStage` handles the network connection |
28+
| 12 | Protocol ConnectionStage _(per version)_ | Unified stage that serialises the request to bytes, parses the response, and correlates request/response — then `TcpConnectionStage`/`QuicConnectionStage` (from Servus.Akka) handles the network connection |
2929

3030
---
3131

@@ -59,7 +59,7 @@ If the cache entry is stale but has an `ETag` or `Last-Modified` validator, `Cac
5959

6060
### 2. Keep-Alive Feedback (HTTP/1.1 only)
6161

62-
After each HTTP/1.1 response, `Http11ConnectionStage` evaluates the `Connection` header internally and decides whether to reuse the TCP connection for the next request or close it and request a new one from the pool.
62+
After each HTTP/1.1 response, `Http11ConnectionStage` evaluates the `Connection` header internally and decides whether to reuse the TCP connection for the next request or close it and request a new one from the connection manager actor.
6363

6464
This loop is invisible to the caller — the `Engine` and higher layers see only a continuous stream of `HttpResponseMessage` objects.
6565

@@ -79,7 +79,7 @@ HTTP/3 uses QPACK for header compression. The server sends decoder table updates
7979

8080
## Connection Management
8181

82-
The pipeline uses a connection pool to reuse TCP (or QUIC for HTTP/3) connections efficiently:
82+
The pipeline uses actor-based connection managers (from Servus.Akka) to reuse TCP (or QUIC for HTTP/3) connections efficiently:
8383

8484
- **HTTP/1.0**: Each request gets a new connection; it's closed after the response
8585
- **HTTP/1.1**: Connections are kept alive and reused for multiple requests to the same host

0 commit comments

Comments
 (0)