chore: new HttpProtocolException

Author: st0o0

docs/superpowers/plans/2026-05-13-h11-decoder-pipe-migration.md

@@ -0,0 +1,169 @@
+# H/1.1 Decoder Pipe Migration Design
+
+**Date:** 2026-05-13  
+**Scope:** `TurboHTTP.Protocol.Http11` — `Decoder`, `ServerRequestDecoder`, `ServerStateMachine`, `StateMachine`  
+**Status:** Approved
+
+## Goal
+
+Remove the `DecoderTestExtensions` shim and `ServerRequestDecoder.TryDecode`'s synchronous `ByteArrayContent` accumulation. Move the `PipedStreamContent`/pipe lifecycle into the decoders themselves so no caller ever constructs a `Pipe` or `PipedStreamContent` externally. Tests and StateMachines use a single `TryDecode` entry point.
+
+## Background
+
+### Current state (legacy)
+
+- `DecoderTestExtensions.TryDecode` — extension method on `Decoder` that wraps `TryDecodeHeaders` + `FeedBody` into a synchronous "collect all responses" API. Uses a static `Dictionary<int, PendingResponse>` keyed by `RuntimeHelpers.GetHashCode` (memory leak risk). ~50 test files depend on it.
+- `ServerRequestDecoder.TryDecode` — real method on the decoder that synchronously accumulates body bytes into `ByteArrayContent` before returning. Does not match production `StateMachine` behavior.
+- Both `ServerStateMachine` and `StateMachine` (H/1.1) create `RequestBodyHandle`/`ResponseBodyHandle` externally, then attach `new PipedStreamContent(handle.Reader)` to the request/response.
+
+### Target state
+
+All pipe lifecycle is owned by the decoder. StateMachines orchestrate only; decoders produce ready-to-consume messages with `PipedStreamContent` already attached.
+
+## API Shape
+
+### `ServerRequestDecoder`
+
+**Single public entry point:**
+
+```csharp
+public bool TryDecode(ReadOnlyMemory<byte> data, out HttpRequestMessage? request)
+```
+
+Behaviour:
+- Returns `true` + populated `request` when headers are complete (once per inbound request)
+- `request.Content` is set to `PipedStreamContent` when a body is expected; `null` when no body
+- Subsequent calls with body data return `false` — body bytes are written into the internal pipe
+- When body completes, pipe writer is closed; `request.Content.ReadAsStringAsync()` resolves
+- After body completion the decoder immediately tries the next header block from the remainder (pipelining)
+
+**Convenience overload for tests and pipelining loops:**
+
+```csharp
+public bool TryDecode(ReadOnlyMemory<byte> data, out IReadOnlyList<HttpRequestMessage> requests)
+```
+
+Wraps the single-request overload in a loop, collecting all complete requests from one data chunk. For pipelined data, after each request is returned, the loop continues with `ReadOnlyMemory<byte>.Empty` so the decoder drains its remainder buffer. Body data for each request is fed and the pipe completed before the decoder advances to the next request's headers.
+
+**Abort surface:**
+
+```csharp
+public void AbortBody(Exception reason)
+```
+
+Called by `StateMachine` on timeout or connection close. Completes the internal pipe writer with the exception so any awaiting consumer receives a clean error.
+
+**Removed from public surface:** `TryDecodeHeaders`, `FeedBody`, `Phase` property.
+
+---
+
+### `Decoder` (H/1.1 response, client-side)
+
+Same treatment:
+
+```csharp
+public bool TryDecode(ReadOnlyMemory<byte> data, out HttpResponseMessage? response)
+public bool TryDecode(ReadOnlyMemory<byte> data, out IReadOnlyList<HttpResponseMessage>? responses)
+public void AbortBody(Exception reason)
+```
+
+`TryDecodeHead` and `TryDecodeConnect` become overloads or named methods on `Decoder` directly (not on `DecoderTestExtensions`).  
+`TryDecodeEof` remains — it has distinct semantics (no `data` parameter, reads from internal remainder for close-delimited responses).  
+`FeedBody`, `TryDecodeHeaders`, `Phase` removed from public surface.
+
+## StateMachine Changes
+
+### `ServerStateMachine`
+
+**Removed:**
+- `RequestBodyHandle? _activeBody` field
+- `if (_decoder.Phase == DecoderPhase.Body && _activeBody is not null)` block
+- `new RequestBodyHandle(...)` construction
+- `new PipedStreamContent(handle.Reader)` assignment
+
+**New `DecodeClientData`:**
+
+```csharp
+public void DecodeClientData(ITransportInbound data)
+{
+    if (data is not TransportData { Buffer: var buffer }) return;
+
+    while (_decoder.TryDecode(buffer.Memory, out var request))
+    {
+        if (_pendingResponseCount >= _maxPipelinedRequests)
+        {
+            ShouldComplete = true;
+            buffer.Dispose();
+            return;
+        }
+
+        _ops.OnCancelTimer(RequestHeadersTimeoutKey);
+        _ops.OnScheduleTimer(KeepAliveTimeoutKey, _keepAliveTimeout);
+        CheckConnectionClose(request!);
+        _pendingResponseCount++;
+        _ops.OnRequest(request!);
+        buffer = TransportBuffer.Empty;
+    }
+
+    buffer.Dispose();
+}
+```
+
+Timeout and connection-close paths call `_decoder.AbortBody(reason)` where they previously called `_activeBody.Abort(...)`.
+
+### `StateMachine` (client-side)
+
+Same simplification: `ResponseBodyHandle? _responseBody` removed; loop calls `_decoder.TryDecode(data, out var response)`.
+
+### `RequestBodyHandle` / `ResponseBodyHandle`
+
+Moved to `internal` — they become implementation details of the respective decoder. No external type references them after the refactor.
+
+## Test Migration
+
+### Tests using `ServerRequestDecoder.TryDecode(data, out IReadOnlyList<HttpRequestMessage>)`
+
+The convenience overload preserves this signature. **No test changes required** for simple single-request tests.
+
+The only observable difference: `request.Content` is now `PipedStreamContent` instead of `ByteArrayContent`. All existing tests already use `await request.Content.ReadAsStringAsync(...)` — this continues to work because the pipe is completed synchronously when all data arrives in one chunk.
+
+### Tests using `DecoderTestExtensions.TryDecode`
+
+Same: `Decoder` gains a `TryDecode(ReadOnlyMemory<byte>, out IReadOnlyList<HttpResponseMessage>?)` convenience overload. The ~50 test files remain **unchanged**.
+
+Exceptions requiring manual updates:
+- Tests calling `TryDecodeHead` / `TryDecodeConnect` → equivalent methods move to `Decoder` directly
+- Tests asserting `decoder.Phase` directly → rewrite to assert behavioural outcomes (request returned or not)
+- Benchmark files `Http11DecoderBenchmark` and `Http11ChunkedDecoderBenchmark` → updated to call `TryDecode`
+
+### `DecoderTestExtensions.cs`
+
+**Deleted.** The static `_pendingResponses` dictionary and all shim logic disappears entirely.
+
+## Deletion Candidates
+
+| What | Location | Replacement |
+|---|---|---|
+| `DecoderTestExtensions.cs` | `Tests/Http11/` | Overloads on `Decoder` |
+| `Decoder.TryDecodeHeaders` (public) | `Protocol/Http11/Decoder.cs` | `TryDecode` |
+| `Decoder.FeedBody` (public) | `Protocol/Http11/Decoder.cs` | internal |
+| `Decoder.Phase` (public) | `Protocol/Http11/Decoder.cs` | internal |
+| `ServerRequestDecoder.TryDecodeHeaders` (public) | `Protocol/Http11/ServerRequestDecoder.cs` | `TryDecode` |
+| `ServerRequestDecoder.FeedBody` (public) | `Protocol/Http11/ServerRequestDecoder.cs` | internal |
+| `ServerRequestDecoder.Phase` (public) | `Protocol/Http11/ServerRequestDecoder.cs` | internal |
+| `RequestBodyHandle` as external type | `Protocol/Http11/` | internal in decoder |
+| `_activeBody` field in `ServerStateMachine` | `Protocol/Http11/ServerStateMachine.cs` | removed |
+
+## Risks
+
+**Pipelining sequencing:** The new `TryDecode` loop must feed all of request N's body before decoding request N+1's headers from the remainder. This sequencing currently lives in `StateMachine`; it must be replicated correctly inside the decoder. Covered by existing `Http11RoundTripPipeliningSpec` tests.
+
+**`TryDecodeEof`:** Remains as a separate method. Close-delimited response handling is distinct — no data parameter, reads from internal remainder. Not affected by this refactor.
+
+**`AbortBody` coverage:** Every timeout/disconnect path in `ServerStateMachine` that previously called `_activeBody.Abort(...)` must be updated to call `_decoder.AbortBody(reason)`. Requires careful audit of the `StateMachine` timeout paths.
+
+**Benchmark breakage:** `Http11DecoderBenchmark` and `Http11ChunkedDecoderBenchmark` call `TryDecodeHeaders`/`FeedBody` directly. These must be updated as part of the implementation.
+
+## Out of Scope (future work)
+
+H/1.0, H/2, and H/3 `StateMachine` classes also build pipes externally and should receive the same treatment. Deferred until H/1.1 refactor is complete and patterns are proven.

docs/superpowers/specs/2026-05-13-h11-decoder-pipe-migration-design.md

@@ -18,7 +18,7 @@ public TestConnectionStageBuilder AutoConnect(ConnectionInfo? info = null)
 
     public TestConnectionStageBuilder AutoDisconnect()
     {
-        return OnOutbound<DisconnectTransport>((msg, ctx) 
+        return OnOutbound<DisconnectTransport>((msg, ctx)
             => ctx.Push(new TransportDisconnected(msg.Reason)));
     }
 
@@ -39,7 +39,7 @@ public TestConnectionStageBuilder WithActivityLog(ActivityLog log)
 
     public TestConnectionStage Build()
     {
-        var stage = new TestConnectionStage([.._handlers], _activityLog);
+        var stage = new TestConnectionStage([.. _handlers], _activityLog);
 
         if (_autoConnect)
         {

src/Servus.Akka.TestKit/TestConnectionStageBuilder.cs

@@ -29,7 +29,7 @@ public static async Task<IReadOnlyList<TOut>> RunManyAsync<TIn, TOut>(
         IMaterializer materializer,
         TimeSpan? timeout = null,
         CancellationToken ct = default)
-    {       
+    {
         var result = Source.From(inputs)
             .Via(flow)
             .Take(expectedCount)

src/Servus.Akka.TestKit/TestPipeline.cs

@@ -99,13 +99,13 @@ void ITransportOperations.OnSignalPullOutbound()
             }
         }
 
-        void ITransportOperations.OnCompleteStage() 
+        void ITransportOperations.OnCompleteStage()
             => CompleteStage();
 
         void ITransportOperations.OnScheduleTimer(string key, TimeSpan delay)
             => ScheduleOnce(key, delay);
 
-        void ITransportOperations.OnCancelTimer(string key) 
+        void ITransportOperations.OnCancelTimer(string key)
             => CancelTimer(key);
 
         ILoggingAdapter ITransportOperations.Log => Log;

src/Servus.Akka/Transport/Quic/Client/QuicConnectionStage.cs

@@ -7,6 +7,6 @@ public readonly record struct StreamTarget(long Value)
     public override string ToString() => Value.ToString();
 
     public static implicit operator StreamTarget(long value) => new(value);
-    public static implicit operator StreamTarget(int value) =>  new(value);
+    public static implicit operator StreamTarget(int value) => new(value);
     public static implicit operator long(StreamTarget target) => target.Value;
 }

src/Servus.Akka/Transport/StreamTarget.cs

@@ -32,10 +32,10 @@ protected override bool TryComputeLength(out long length)
 
         protected override Task<Stream> CreateContentReadStreamAsync()
         {
-            return _tcs.Task.ContinueWith(t =>
+            return _tcs.Task.ContinueWith(Stream (t) =>
             {
                 var ms = new MemoryStream(t.Result);
-                return (Stream)ms;
+                return ms;
             }, TaskScheduler.Default);
         }
     }

src/TurboHTTP.Tests/Caching/Stages/CacheBidiAsyncBodySpec.cs

@@ -0,0 +1 @@
+global using HttpProtocolException = TurboHTTP.Protocol.HttpProtocolException;

src/TurboHTTP.Tests/GlobalUsings.cs

@@ -1,6 +1,5 @@
 using System.Net;
 using System.Text;
-using TurboHTTP.Protocol;
 using Decoder = TurboHTTP.Protocol.Http10.Decoder;
 
 namespace TurboHTTP.Tests.Http10;
@@ -133,8 +132,7 @@ public void Http10DecoderBodySpec_should_throw_decoder_exception()
         var decoder = new Decoder();
         var data = BuildRawResponse("HTTP/1.0 200 OK", "Content-Length: -1");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(data, out _));
-        Assert.Equal(HttpDecoderError.InvalidContentLength, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(data, out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -144,8 +142,7 @@ public void Http10DecoderBodySpec_should_throw_multiple_content_length()
         var decoder = new Decoder();
         const string raw = "HTTP/1.0 200 OK\r\nContent-Length: 3\r\nContent-Length: 5\r\n\r\nHello";
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.MultipleContentLengthValues, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]

src/TurboHTTP.Tests/Http10/DecoderBodySpec.cs

@@ -1,5 +1,4 @@
 using System.Text;
-using TurboHTTP.Protocol;
 using Decoder = TurboHTTP.Protocol.Http10.Decoder;
 
 namespace TurboHTTP.Tests.Http10;
@@ -58,9 +57,8 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_header_too_large()
         var bigValue = new string('X', 200);
         var raw = BuildRawResponse("HTTP/1.0 200 OK", $"X-Big: {bigValue}\r\nContent-Length: 0");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
 
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
         Assert.Contains("X-Big", ex.Message);
         Assert.Contains("100", ex.Message);
     }
@@ -90,8 +88,7 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_header_too_large_2()
         var decoder = new Decoder(maxHeaderSize: limit);
         var raw = BuildRawResponse("HTTP/1.0 200 OK", $"X: {value}\r\nContent-Length: 0");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -123,9 +120,8 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_total_headers_too_large()
         sb.Append("Content-Length: 0");
         var raw = BuildRawResponse("HTTP/1.0 200 OK", sb.ToString());
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
 
-        Assert.Equal(HttpDecoderError.TotalHeadersTooLarge, ex.DecodeError);
         Assert.Contains("200", ex.Message);
     }
 
@@ -151,8 +147,7 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_total_headers_too_large_2
         var decoder = new Decoder(maxHeaderSize: 100, maxTotalHeaderSize: 8);
         var raw = BuildRawResponse("HTTP/1.0 200 OK", "X: V\r\nY: WW");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.TotalHeadersTooLarge, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -163,8 +158,7 @@ public void Http10DecoderHeaderLimitsSpec_should_reject_at_custom_limit()
         var raw = BuildRawResponse("HTTP/1.0 200 OK",
             "X-TooLong: this-value-is-way-too-long-for-limit\r\nContent-Length: 0");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -181,8 +175,7 @@ public void Http10DecoderHeaderLimitsSpec_should_reject_at_custom_total_limit()
         sb.Append("Content-Length: 0");
         var raw = BuildRawResponse("HTTP/1.0 200 OK", sb.ToString());
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.TotalHeadersTooLarge, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -194,8 +187,7 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_header_too_large_3()
         const string raw =
             "HTTP/1.0 200 OK\r\nX-Folded: part1\r\n continued-text-that-is-long\r\nContent-Length: 0\r\n\r\n";
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
         Assert.Contains("X-Folded", ex.Message);
     }
 
@@ -208,10 +200,7 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_total_headers_too_large_3
         const string raw =
             "HTTP/1.0 200 OK\r\nX-A: value-a\r\nX-Folded: part1\r\n continuation-that-pushes-total-over\r\nContent-Length: 0\r\n\r\n";
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
-        Assert.True(
-            ex.DecodeError is HttpDecoderError.TotalHeadersTooLarge or HttpDecoderError.HeaderTooLarge,
-            $"Expected HeaderTooLarge or TotalHeadersTooLarge, got {ex.DecodeError}");
+        Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
     }
 
     [Fact(Timeout = 5000)]
@@ -222,7 +211,7 @@ public void Http10DecoderHeaderLimitsSpec_should_include_header_name()
         var raw = BuildRawResponse("HTTP/1.0 200 OK",
             "X-Offending: this-value-exceeds-the-configured-limit\r\nContent-Length: 0");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
 
         Assert.Contains("X-Offending", ex.Message);
         Assert.Contains("30", ex.Message);
@@ -236,7 +225,7 @@ public void Http10DecoderHeaderLimitsSpec_should_include_total_size()
         var raw = BuildRawResponse("HTTP/1.0 200 OK",
             "X-A: aaaaaaaaaa\r\nX-B: bbbbbbbbbb\r\nContent-Length: 0");
 
-        var ex = Assert.Throws<HttpDecoderException>(() => decoder.TryDecode(Bytes(raw), out _));
+        var ex = Assert.Throws<HttpProtocolException>(() => decoder.TryDecode(Bytes(raw), out _));
 
         Assert.Contains("30", ex.Message);
     }
@@ -252,9 +241,8 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_header_too_large_4()
 
         // Feed all data � TryDecode returns the response with body since headers end is found
         // But the header validation happens during header parsing in TryDecode
-        var ex = Assert.Throws<HttpDecoderException>(() =>
+        var ex = Assert.Throws<HttpProtocolException>(() =>
             decoder.TryDecode(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
     }
 
     [Fact(Timeout = 5000)]
@@ -265,9 +253,8 @@ public void Http10DecoderHeaderLimitsSpec_should_throw_header_too_large_5()
         var bigValue = new string('C', 50);
         var raw = $"HTTP/1.0 200 OK\r\nX-Connect: {bigValue}\r\n\r\n";
 
-        var ex = Assert.Throws<HttpDecoderException>(() =>
+        var ex = Assert.Throws<HttpProtocolException>(() =>
             decoder.TryDecodeConnect(Bytes(raw), out _));
-        Assert.Equal(HttpDecoderError.HeaderTooLarge, ex.DecodeError);
     }
 
     [Fact(Timeout = 5000)]