fix Docs

Author: st0o0

CLAUDE.md

@@ -8,34 +8,41 @@ TurboHttp is a high-performance HTTP client library for .NET built on Akka.Strea
 
 ## Build Commands
 
+> **Note:** All commands run from the **repository root** (`d:\GIT\Akka.Streams.Http\`).
+> `dotnet test --project` paths are relative to `src/` (where `global.json` with MTP runner lives).
+> `dotnet restore`/`build`/`run` use full paths from root.
+
 ```bash
 # Restore and build
 dotnet restore ./src/TurboHttp.sln
 dotnet build --configuration Release ./src/TurboHttp.sln
 
-# Run all tests
-dotnet test ./src/TurboHttp.sln
+# Run all tests (includes integration tests — requires network)
+dotnet test --project TurboHttp.sln
+
+# Run unit tests only
+dotnet test --project TurboHttp.Tests/TurboHttp.Tests.csproj
 
-# Run specific test class (xUnit v3 MTP filter — note: args after --)
-dotnet test ./src/TurboHttp.Tests/TurboHttp.Tests.csproj -- --filter-class "TurboHttp.Tests.RFC9113.Http2DecoderBasicFrameTests"
+# Run specific test class (xUnit v3 direct runner — -class flag)
+dotnet run --project TurboHttp.Tests/TurboHttp.Tests.csproj -- -class "TurboHttp.Tests.RFC9113.Http2DecoderErrorCodeTests"
 
 # Run specific RFC section (by namespace)
-dotnet test ./src/TurboHttp.Tests/TurboHttp.Tests.csproj -- --filter-namespace "TurboHttp.Tests.RFC9113"
+dotnet test --project TurboHttp.Tests/TurboHttp.Tests.csproj -- --filter-namespace "TurboHttp.Tests.RFC9113"
 
 # Run integration tests (H10/H11/H2/H3/TLS — requires network)
-dotnet test ./src/TurboHttp.IntegrationTests/TurboHttp.IntegrationTests.csproj
+dotnet test --project TurboHttp.IntegrationTests/TurboHttp.IntegrationTests.csproj
 
 # Run integration tests for one HTTP version
-dotnet test ./src/TurboHttp.IntegrationTests/TurboHttp.IntegrationTests.csproj -- --filter-namespace "TurboHttp.IntegrationTests.H11"
+dotnet test --project TurboHttp.IntegrationTests/TurboHttp.IntegrationTests.csproj -- --filter-namespace "TurboHttp.IntegrationTests.H11"
 
 # Run Akka.Streams stage tests
-dotnet test ./src/TurboHttp.StreamTests/TurboHttp.StreamTests.csproj
+dotnet test --project TurboHttp.StreamTests/TurboHttp.StreamTests.csproj
 
 # Run stage tests for one RFC section
-dotnet test ./src/TurboHttp.StreamTests/TurboHttp.StreamTests.csproj -- --filter-namespace "TurboHttp.StreamTests.RFC9113"
+dotnet test --project TurboHttp.StreamTests/TurboHttp.StreamTests.csproj -- --filter-namespace "TurboHttp.StreamTests.RFC9113"
 
 # Run benchmarks
-dotnet run --configuration Release ./src/TurboHttp.Benchmarks/TurboHttp.Benchmarks.csproj
+dotnet run --configuration Release --project TurboHttp.Benchmarks/TurboHttp.Benchmarks.csproj
 ```
 
 ### Documentation Site (requires Node.js 20+)

docs/.vitepress/config.ts

@@ -5,10 +5,10 @@ export default defineConfig({
     description: 'High-performance HTTP client library for .NET built on Akka.Streams — HTTP/1.0, HTTP/1.1, and HTTP/2 with automatic retries, caching, cookies, and connection pooling.',
     base: '/',
     head: [
-        ['link', { rel: 'icon', type: 'image/png', href: '/TurboHttp/logo/icon.png' }],
+        ['link', { rel: 'icon', type: 'image/png', href: '/logo/icon.png' }],
     ],
     themeConfig: {
-        logo: '/logo/logo_small.png',
+        logo: '/logo/icon.png',
         search: {
             provider: 'local',
         },

docs/architecture/index.md

@@ -15,26 +15,40 @@ Your Request
     ↓
 [Enricher] — applies default headers, base address
     ↓
+[Tracing] — starts an activity span for observability
+    ↓
+[Handlers] — runs any custom middleware you registered
+    ↓
+[Redirects] — tracks redirect chain; follows on response side
+    ↓
 [Cookies] — injects matching cookies from the cookie jar
     ↓
-[Cache] — checks if response is cached; returns immediately if fresh
+[Retry] — attaches retry context; re-sends on transient failures
+    ↓
+[Expect-Continue] — holds large bodies until server confirms readiness
+    ↓
+[Cache] — returns immediately if response is cached and fresh
+    ↓
+[Content Encoding] — compresses request body / decompresses response
     ↓
 [Protocol Encoder] — converts to HTTP/1.0, 1.1, 2, or 3 bytes
     ↓
 [Network] — sends over TCP or QUIC
     ↓
 [Protocol Decoder] — parses response bytes
     ↓
-[Decompression] — decompresses gzip/deflate/brotli
+[Content Encoding] — decompresses gzip/deflate/brotli
     ↓
-[Cookies] — stores Set-Cookie headers
-    ↓
-[Cache] — caches the response if cacheable
+[Cache] — stores response if cacheable
     ↓
 [Retry] — re-sends on transient errors or 503/429
     ↓
+[Cookies] — stores Set-Cookie headers
+    ↓
 [Redirects] — follows 301-308 automatically
     ↓
+[Tracing] — closes the activity span
+    ↓
 Your Response
 ```
 
@@ -45,10 +59,10 @@ Each stage does one thing well. Most of the time you don't think about them —
 - **Automatic**: Cookies, caching, retries, redirects all work out of the box
 - **Efficient**: HTTP/2 and HTTP/3 multiplexing, keep-alive connection reuse, lock-free data movement
 - **Correct**: Follows HTTP specifications for freshness, method rewriting, retry idempotency
-- **Observable**: See exactly what happens at each stage
+- **Observable**: See exactly what happens at each stage via built-in tracing
 
 ## Learn More
 
 - [**Pipeline Details**](./pipeline) — All stages and how they interact
 - [**Scenarios**](./scenarios) — End-to-end walkthroughs for HTTP/1.0, 1.1, 2, and 3
-- [**Connection Pooling**](../guide/connection-pooling) — How connections are reused
+- [**Connection Pooling**](../guide/connection-pooling) — How connections are reused

docs/architecture/pipeline.md

@@ -15,25 +15,33 @@ Each `HttpRequestMessage` passes through the following stages before reaching th
 | # | Stage | What it does |
 |---|-------|--------------|
 | 1 | Request Enrichment (`RequestEnricherStage`) | Applies your `BaseAddress`, default HTTP version, and default headers to every request |
-| 2 | Cookie Injection (`CookieBidiStage`) | Looks up matching cookies for the target domain and path and adds a `Cookie` header |
-| 3 | Cache Lookup (`CacheBidiStage`) | Checks the in-memory cache; on a **cache hit**, returns the cached response immediately — stages 4–5 are skipped entirely |
-| 4 | Version Router (`Engine`) | Routes the request to the correct protocol handler based on the requested HTTP version |
-| 5 | Protocol Encoder *(per version)* | Serialises the request to bytes and sends it over the network connection |
+| 2 | Tracing (`TracingBidiStage`) | Starts an activity span for observability; records request method, URL, timing, and final status code |
+| 3 | User Handlers (`HandlerBidiStage`) | Runs any custom middleware you registered — zero or more, applied outermost-first |
+| 4 | Redirect (`RedirectBidiStage`) | Tracks the redirect chain; on a `301`–`308` response, re-enters the pipeline at the Cookie stage so new-URL cookies are injected |
+| 5 | Cookie Injection (`CookieBidiStage`) | Looks up matching cookies for the target domain and path and adds a `Cookie` header |
+| 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) |
+| 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 |
+| 8 | Cache Lookup (`CacheBidiStage`) | Checks the in-memory cache; on a **cache hit**, returns the cached response immediately — stages 9–10 are skipped entirely |
+| 9 | Content Encoding (`ContentEncodingBidiStage`) | Compresses the request body if a compression policy is configured; on the response side, transparently decompresses `gzip`, `deflate`, or Brotli |
+| 10 | Version Router (`Engine`) | Routes the request to the correct protocol handler based on the requested HTTP version |
+| 11 | Protocol Encoder *(per version)* | Serialises the request to bytes and sends it over the network connection |
 
 ---
 
 ## Response Chain (right to left / bottom to top)
 
-After bytes return from TCP, the response passes through these stages:
+After bytes return from the network, the response passes back through the stages in reverse order:
 
 | # | Stage | What it does |
 |---|-------|--------------|
 | 1 | Protocol Decoder *(per version)* | Parses raw bytes into an `HttpResponseMessage` and matches it to the original request |
-| 2 | Decompression (`DecompressionBidiStage`) | Transparently decompresses `gzip`, `deflate`, or Brotli response bodies |
-| 3 | Cookie Storage (`CookieBidiStage`) | Reads `Set-Cookie` headers and stores cookies for future requests |
-| 4 | Cache Storage (`CacheBidiStage`) | Saves cacheable responses so future matching requests can be served from memory |
+| 2 | Content Encoding (`ContentEncodingBidiStage`) | Transparently decompresses `gzip`, `deflate`, or Brotli response bodies |
+| 3 | Cache Storage (`CacheBidiStage`) | Saves cacheable responses so future matching requests can be served from memory |
+| 4 | Expect-Continue (`ExpectContinueBidiStage`) | Processes `100 Continue` responses and unblocks the request body when the server is ready |
 | 5 | Automatic Retry (`RetryBidiStage`) | Re-sends safe (idempotent) requests on transient errors or `503`/`429` responses; respects `Retry-After` delays |
-| 6 | Redirect Following (`RedirectBidiStage`) | Follows `301`–`308` redirects automatically; rewrites the HTTP method where needed; detects loops and blocks HTTPS→HTTP downgrades |
+| 6 | Cookie Storage (`CookieBidiStage`) | Reads `Set-Cookie` headers and stores cookies for future requests |
+| 7 | Redirect Following (`RedirectBidiStage`) | Follows `301`–`308` redirects automatically; rewrites the HTTP method where needed; detects loops and blocks HTTPS→HTTP downgrades |
+| 8 | Tracing (`TracingBidiStage`) | Closes the activity span, recording the final status code and any errors |
 
 ---
 
@@ -53,11 +61,17 @@ After each HTTP/1.1 response, a signal is sent back to the connection layer indi
 
 This loop is invisible to the caller — the `Engine` and higher layers see only a continuous stream of `HttpResponseMessage` objects.
 
-### 3. Retry / Redirect Re-entry (red)
+### 3. Redirect Re-entry
 
-When `RetryBidiStage` decides a request should be retried, or when `RedirectBidiStage` needs to follow a redirect, the new `HttpRequestMessage` is fed back into the **front of the pipeline** (before `RequestEnricherStage`). This ensures that retry enrichment, cookie injection, and cache lookup all apply again on the new attempt.
+When `RedirectBidiStage` needs to follow a redirect, the new `HttpRequestMessage` re-enters the pipeline at the **Cookie stage** — not at the very beginning. This ensures cookie injection applies for the new URL while skipping the initial enrichment step (default headers are already applied). A redirect hop limit prevents infinite loops.
 
-A maximum retry count and redirect hop limit prevent infinite loops.
+### 4. Retry Re-entry
+
+When `RetryBidiStage` decides a request should be retried, it re-enters the pipeline at the **Expect-Continue stage** — below Cookie injection, since the URL hasn't changed and cookies are already set. A maximum retry count prevents infinite loops.
+
+### 5. QPACK Table Sync (HTTP/3 only)
+
+HTTP/3 uses QPACK for header compression. The server sends decoder table updates on a dedicated QUIC stream; `QpackDecoderFeedbackStage` forwards these updates back to `Http30Request2FrameStage` to keep the encoder and decoder tables in sync.
 
 ---