feat: add TurboHTTP Server

.github/workflows/codeql.yml

@@ -13,7 +13,7 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ "main", feature/*, ]
+    branches: [ "main" ]
     paths:
       - "src/**/*.cs"
       - "src/**/*.csproj"
@@ -82,4 +82,4 @@ jobs:
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@v4
       with:
-        category: "/language:${{matrix.language}}"
+        category: "/language:${{matrix.language}}"

CLAUDE.md

@@ -1,49 +1,52 @@
 # CLAUDE.md
 
-High-performance HTTP client for .NET built on Akka.Streams. Implements HTTP/1.0, 1.1, 2, 3 (QUIC) with full RFC compliance.
+High-performance HTTP client and server for .NET built on Akka.Streams. Implements HTTP/1.0, 1.1, 2, 3 (QUIC) with full RFC compliance.
 
 ## Build & Test
 
-All commands run from `src/` (where `global.json` lives). Restore/build use full paths from repo root.
+All commands run from `src/` (where `global.json` lives).
 
 ```bash
-dotnet restore ./src/TurboHTTP.slnx
-dotnet build --configuration Release ./src/TurboHTTP.slnx
+dotnet restore TurboHTTP.slnx
+dotnet build --configuration Release TurboHTTP.slnx
 
-# Tests (xUnit v3 direct runner)
-dotnet test --project TurboHTTP.Tests/TurboHTTP.Tests.csproj              # unit + stage
-dotnet test --project TurboHTTP.IntegrationTests/TurboHTTP.IntegrationTests.csproj  # integration (network)
+# Tests (xUnit v3 — use dotnet run, not dotnet test)
+dotnet run --project TurboHTTP.Tests/TurboHTTP.Tests.csproj                          # all unit + stage
+dotnet run --project TurboHTTP.IntegrationTests/TurboHTTP.IntegrationTests.csproj    # integration (network)
 
 # Single class (preferred for integration — full suite is slow)
 dotnet run --project TurboHTTP.IntegrationTests/TurboHTTP.IntegrationTests.csproj -- -class "TurboHTTP.IntegrationTests.H2.ConnectionSpec"
 
-# Single method / namespace
-dotnet run --project TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -namespace "TurboHTTP.Tests.RFC9113"
-dotnet run --project TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -class "TurboHTTP.Tests.RFC9113.Http2DecoderErrorCodeTests"
+# Single class / filter
+dotnet run --project TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -class "TurboHTTP.Tests.Protocol.Syntax.Http2.Frames.Http2DecoderErrorCodeSpec"
+
+# Integration tests with specific backend (default: auto-detect Docker, fallback Kestrel)
+$env:TURBOHTTP_TEST_BACKEND = "kestrel"   # force Kestrel (no Docker needed)
+$env:TURBOHTTP_TEST_BACKEND = "docker"    # force Docker (fails if unavailable)
 
 # Benchmarks
 dotnet run --configuration Release --project TurboHTTP.Benchmarks/TurboHTTP.Benchmarks.csproj
 
 # Docs site (Node.js 20+)
-cd docs && npm install && npm run docs:dev
+cd ../docs && npm install && npm run docs:dev
 ```
 
 ## Architecture
 
 ```
-Client Surface  (TurboHTTP/)                — ITurboHttpClient, factory, builder, DI
-Streams Layer   (TurboHTTP/Streams/)        — Engines (Http10/11/20/30Engine), Stages/{Encoding,Decoding,Features,Routing}
-Protocol Layer  (TurboHTTP/Protocol/)       — Http10/, Http11/, Http2/, Http3/, Cookies/, Caching/, Semantics/, AltSvc/
-Transport Layer (TurboHTTP/Transport/)      — Connection/, Tcp/, Quic/
+Client Surface  (TurboHTTP/Client/)          - ITurboHttpClient, factory, builder, DI, options
+Server Surface  (TurboHTTP/Server/)          - TurboServerOptions, TurboHttpContext, Context/
+Server Domains  (TurboHTTP/Server/{domain}/) - Middleware, Routing, Binding, Entity, Hosting, Lifecycle
+Streams Layer   (TurboHTTP/Streams/)         - Engines, Stages/{Client,Server,Features,Internal}
+Protocol Layer  (TurboHTTP/Protocol/)        - Http10/, Http11/, Http2/, Http3/, Semantics/
+Features        (TurboHTTP/Features/)        - Cookies/, Caching/, AltSvc/
 ```
 
 ## Obsidian Vault (`notes/`)
 
 Single source of truth for all non-code knowledge. **Use Obsidian MCP tools** (`search_notes`, `read_note`, `write_note`, `patch_note`) — never `Read`/`Write`/`Edit` on `notes/` files.
 
 - Before RFC work → `search_notes("RFC XXXX")`
-- Before architecture decisions → `search_notes("component name")`
-- Before ending a session → write discoveries via `write_note` or `patch_note`
 
 ### RFC vault structure
 
@@ -53,7 +56,6 @@ Single source of truth for all non-code knowledge. **Use Obsidian MCP tools** (`
 
 - **Do NOT commit** unless the user explicitly asks
 - **Always respond in English** regardless of input language
-- **Write discoveries to Obsidian** after every session
 
 ## Code Style
 
@@ -65,11 +67,12 @@ Single source of truth for all non-code knowledge. **Use Obsidian MCP tools** (`
 - No decorative separator comments (`// ───`, `// ===`, `// ---` section dividers)
 - Allman braces, 4 spaces, `_fieldName` for private fields
 - `var` when type is apparent, `sealed` by default
-- No `#nullable enable` (project-level), no `async void` / `.Result` / `.Wait()`
+- No `#nullable enable` (project-level), no `async void` / `.Result` / `.Wait()` / `.GetAwaiter().GetResult()`
 - Always pass `CancellationToken`, always use braces (even single-line)
 - `Task<T>` not Future, `TimeSpan` not Duration
 - Extend-only public APIs, preserve wire format compatibility
 - Include unit tests with all changes
+- **Size literals**: Always `N * 1024` or `N * 1024 * 1024`, never raw numbers like `65536` or `2_097_152`
 
 ## Performance Patterns
 
@@ -92,6 +95,31 @@ New tests use **component-based folders** (`Http10/`, `Http11/`, `Http2/`, etc.)
 - `[Fact(DisplayName = ...)]` is deprecated — method name IS the documentation
 - Max 500 lines per test class
 
+### Test File Naming Convention
+
+**File name = class name, always.** Pattern: `{ProtocolPrefix?}{ProductionClassName}{TestConcern?}Spec`
+
+- Protocol prefix (`Http2`, `Http3`, `Hpack`, `Qpack`) required when test is under `Protocol/Syntax/{HttpVersion}/` or class name is shared across namespaces
+- Omit prefix when class is globally unique (`CookieJar`, `CacheStore`) or in protocol-agnostic folders (`Client/`, `Features/`)
+- When a SUT has multiple test files, suffix describes **test concern** — never `Part1`/`Part2`/numbered
+- Duplicates disambiguated by test focus, not location
+
+### H2/H3 Test Folder Placement
+
+| Folder | What belongs here | Types under test |
+|--------|------------------|-----------------|
+| **Frames/** | Wire format: serialize, deserialize, parse, validate | `FrameDecoder`, `Http2Frame`/`Http3Frame` subtypes |
+| **Client/** | Client behavioral logic (subfolders at 5+ files) | `*ClientStateMachine`, `FlowController`, `*ClientEncoder`, `*ClientDecoder` |
+| **Server/** | Server behavioral logic (subfolders at 5+ files) | `*ServerStateMachine`, `*ServerEncoder`, `*ServerDecoder` |
+| **Hpack/** / **Qpack/** | Header compression (own RFC) | `HpackEncoder`/`QpackEncoder`, dynamic/static tables |
+| **Security/** | Fuzz, adversarial, resource exhaustion | Any, from attacker perspective |
+| **Stages/** | Akka Streams integration (GraphDsl) | `*ConnectionStage` |
+| **Options/** | Configuration validation stubs | `*Options` types |
+
+**Decision rule**: `FrameDecoder` + frame assertions → Frames/. `*StateMachine`/`*Encoder`/`*Decoder` → Client/ or Server/. Akka Streams graph → Stages/.
+
+Http10/Http11 use flat `Client/` and `Server/` (no subfolders).
+
 ## Stage Port Naming (Quick Reference)
 
 Ports follow `StageName.Direction` or `StageName.Direction.Role` (PascalCase). Drop `Stage` suffix, no protocol prefix, globally unique names.
@@ -114,26 +142,14 @@ Prefer retrieval-led reasoning over pretraining for any .NET work.
 
 ## Sequential Thinking MCP (`mcp__sequential-thinking__sequentialthinking`)
 
-Use for multi-step reasoning where the full scope isn't clear upfront. The tool lets you think
-step-by-step with the ability to revise, branch, and extend as understanding deepens.
+Use for multi-step reasoning where the full scope isn't clear upfront.
 
 **When to use:**
-
 - Complex debugging where the root cause isn't obvious
 - Architecture/design decisions with multiple trade-offs
 - RFC compliance analysis requiring cross-referencing multiple sections
-- Any problem where early assumptions may need revision
-
-**How it works:** Call the tool repeatedly, once per thought step. Each call takes:
-
-- `thought` — your current reasoning step (analysis, revision, hypothesis, verification)
-- `thoughtNumber` / `totalThoughts` — track position; adjust `totalThoughts` up/down as needed
-- `nextThoughtNeeded` — `true` to continue, `false` when done
-- `isRevision` + `revisesThought` — mark a step as reconsidering an earlier thought
-- `branchFromThought` + `branchId` — explore an alternative path without losing the main line
 
-**Pattern:** Analyze → Hypothesize → Verify → Conclude. Revise or branch whenever new
-information contradicts earlier steps. Don't force linear progression — backtrack freely.
+Call repeatedly, one thought per step. Revise or branch freely when new information contradicts earlier steps.
 
 ## Roslyn Navigator — Required Before Commit
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 st0o0
+Copyright (c) 2026 leberkas-org
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/.vitepress/config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
 
 export default defineConfig({
     title: 'TurboHTTP',
-    description: 'High-performance HTTP client library for .NET built on Akka.Streams — HTTP/1.0, HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) with automatic retries, caching, cookies, and connection pooling.',
+    description: 'High-performance HTTP client and server for .NET built on Akka.Streams — HTTP/1.0, HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) with automatic retries, caching, cookies, connection pooling, middleware pipeline, routing, and entity gateway.',
     base: '/',
     head: [
         ['link', { rel: 'icon', type: 'image/png', href: '/logo/icon.png' }],
@@ -15,40 +15,82 @@ export default defineConfig({
 
         nav: [
             { text: 'Home', link: '/' },
-            { text: 'Guide', link: '/guide/' },
+            { text: 'Quick Guide', link: '/quickstart/' },
+            { text: 'Client', link: '/client/' },
+            { text: 'Server', link: '/server/' },
             { text: 'Architecture', link: '/architecture/' },
             { text: 'API', link: '/api/' },
             { text: 'Why TurboHTTP?', link: '/why/' },
         ],
 
         sidebar: {
-            '/guide/': [
+            '/quickstart/': [
+                {
+                    text: 'Quick Guide',
+                    items: [
+                        { text: 'Quick Guide', link: '/quickstart/' },
+                    ],
+                },
+            ],
+            '/client/': [
                 {
                     text: 'Getting Started',
                     items: [
-                        { text: 'Quick Start', link: '/guide/' },
-                        { text: 'Installation & Setup', link: '/guide/installation' },
-                        { text: 'Configuration', link: '/guide/configuration' },
-                        { text: 'Migration from HttpClient', link: '/guide/migration' },
+                        { text: 'Quick Start', link: '/client/' },
+                        { text: 'Installation & Setup', link: '/client/installation' },
+                        { text: 'Configuration', link: '/client/configuration' },
+                        { text: 'Migration from HttpClient', link: '/client/migration' },
                     ],
                 },
                 {
                     text: 'Features',
                     items: [
-                        { text: 'Automatic Retries', link: '/guide/retries' },
-                        { text: 'HTTP Caching', link: '/guide/caching' },
-                        { text: 'Cookie Management', link: '/guide/cookies' },
-                        { text: 'Redirects', link: '/guide/redirects' },
-                        { text: 'Content Encoding', link: '/guide/content-encoding' },
-                        { text: 'Connection Pooling', link: '/guide/connection-pooling' },
-                        { text: 'HTTP/2 & Multiplexing', link: '/guide/http2' },
-                        { text: 'HTTP/3 & QUIC', link: '/guide/http3' },
+                        { text: 'Automatic Retries', link: '/client/retries' },
+                        { text: 'HTTP Caching', link: '/client/caching' },
+                        { text: 'Cookie Management', link: '/client/cookies' },
+                        { text: 'Redirects', link: '/client/redirects' },
+                        { text: 'Content Encoding', link: '/client/content-encoding' },
+                        { text: 'Connection Pooling', link: '/client/connection-pooling' },
+                        { text: 'HTTP/2 & Multiplexing', link: '/client/http2' },
+                        { text: 'HTTP/3 & QUIC', link: '/client/http3' },
+                    ],
+                },
+                {
+                    text: 'Help',
+                    items: [
+                        { text: 'Troubleshooting & FAQ', link: '/client/troubleshooting' },
+                    ],
+                },
+            ],
+            '/server/': [
+                {
+                    text: 'Getting Started',
+                    items: [
+                        { text: 'Quick Start', link: '/server/' },
+                        { text: 'Installation & Setup', link: '/server/installation' },
+                        { text: 'Configuration', link: '/server/configuration' },
+                        { text: 'Hosting & Lifecycle', link: '/server/hosting' },
+                    ],
+                },
+                {
+                    text: 'Features',
+                    items: [
+                        { text: 'Middleware Pipeline', link: '/server/middleware' },
+                        { text: 'Routing', link: '/server/routing' },
+                        { text: 'Entity Gateway', link: '/server/entity-gateway' },
+                    ],
+                },
+                {
+                    text: 'Advanced',
+                    items: [
+                        { text: 'Parameter Binding', link: '/server/binding' },
+                        { text: 'Validation', link: '/server/validation' },
                     ],
                 },
                 {
                     text: 'Help',
                     items: [
-                        { text: 'Troubleshooting & FAQ', link: '/guide/troubleshooting' },
+                        { text: 'Troubleshooting', link: '/server/troubleshooting' },
                     ],
                 },
             ],
@@ -85,7 +127,7 @@ export default defineConfig({
         },
 
         socialLinks: [
-            { icon: 'github', link: 'https://github.com/st0o0/TurboHTTP' },
+            { icon: 'github', link: 'https://github.com/leberkas-org/TurboHTTP' },
         ],
 
         footer: {