Remove Http3StreamType

Author: st0o0

docs/superpowers/specs/2026-04-21-protocol-agnostic-transport-design.md

@@ -0,0 +1,104 @@
+# Protocol-Agnostic QUIC Transport Layer
+
+## Goal
+
+Remove all HTTP/3 protocol knowledge from the QUIC transport layer. Replace `QuicStreamKind` enum with opaque `long streamTypeValue` flowing through transport. The transport distinguishes only bidirectional (request) vs unidirectional (typed) streams. Protocol interpretation happens exclusively in `Http30ConnectionStage`.
+
+## Core Concepts
+
+- **Request streams**: bidirectional, identified by `streamTypeValue = -1` (sentinel)
+- **Typed streams**: unidirectional, identified by their wire byte value (opaque `long`)
+- **TypedStreamDescriptor**: configuration record passed to transport at construction — `(long StreamTypeValue, long SyntheticStreamId)`
+- Transport opens typed streams eagerly from configuration, without knowing what the values mean
+
+## New Transport Type
+
+```csharp
+internal readonly record struct TypedStreamDescriptor(long StreamTypeValue, long SyntheticStreamId);
+```
+
+Http3 layer provides at construction:
+```csharp
+[new(0x00, -2), new(0x02, -3)]  // Control, QpackEncoder — transport doesn't know names
+```
+
+## Typed Stream State
+
+Replaces the six hardcoded fields (`_controlHandle`, `_encoderHandle`, `_pendingControlItems`, `_pendingEncoderItems`, `_controlStreamId`, `_encoderStreamId`):
+
+```csharp
+private sealed class TypedStreamState
+{
+    public ConnectionHandle? Handle;
+    public readonly Queue<NetworkBuffer> PendingItems = new();
+    public long StreamId;
+}
+```
+
+Stored in `Dictionary<long, TypedStreamState> _typedStreams` keyed by `streamTypeValue`.
+
+## File-by-File Changes
+
+### Delete
+
+- `QuicStreamKind.cs` — enum and `QuicStreamKindMapper` removed entirely
+
+### QuicConnectionHandle
+
+- `OpenStreamAsLeaseAsync(bool bidirectional)` — no stream type knowledge, just direction
+- `InboundStream(ConnectionLease, long StreamTypeValue, long StreamId)` — raw wire value
+- `AcceptInboundStreamAsLeaseAsync` — reads wire byte, returns as `long`, no interpretation, accepts all streams
+- Remove `MapStreamKind` — replace with `bidirectional ? Bidirectional+GetStream : WriteOnly+GetUnidirectional`
+
+### IQuicTransportEvent
+
+- `TypedLeaseAcquired(ConnectionLease, long StreamTypeValue, long StreamId)`
+- `InboundStreamReady` carries `InboundStream` which now has `long StreamTypeValue`
+
+### QuicPumpManager
+
+- `StartInboundPump(handle, long streamTypeValue, key, gen, streamId)`
+- `PumpAsync`: sets `h3Buf.StreamTypeValue = streamTypeValue` instead of `ApplyToBuffer`
+- Close signal: only for request streams (`streamTypeValue < 0`)
+
+### QuicStreamRouter
+
+- `RouteTaggedItem(buffer, long streamTypeValue, Dictionary<long, TypedStreamState> typedStreams)` — looks up by value, falls through to request routing for unknown/request type
+- Remove `QuicStreamKind` from all method signatures
+
+### QuicTransportStateMachine
+
+- Constructor receives `TypedStreamDescriptor[]`, initializes `_typedStreams` dictionary
+- Remove constants `ControlStreamSyntheticId`, `QpackEncoderStreamSyntheticId`, `QpackDecoderStreamSyntheticId`
+- `OnRequestLeaseAcquired` — iterates descriptors to open typed streams
+- `OnTypedLeaseAcquired(lease, long streamTypeValue, long streamId)` — looks up in `_typedStreams`
+- `OnInboundStreamReady` — maps `streamTypeValue` to synthetic ID via descriptors (or real stream ID for unconfigured types)
+- `HandlePush` — reads `StreamTypeValue` from buffer for routing instead of `Http3StreamType`
+
+### Http3NetworkBuffer (Internal/Messages.cs)
+
+- Add `public long StreamTypeValue { get; set; } = -1;`
+- `Http3StreamType StreamType` stays as plain settable property (no auto-conversion)
+- Transport only touches `StreamTypeValue`; protocol layer uses both
+
+### Http30ConnectionStage (Protocol Layer)
+
+- **Inbound**: maps `StreamTypeValue` to `Http3StreamType` in `HandleTaggedStreamData`
+- **Outbound**: sets `StreamTypeValue` on buffers (0x00 for Control, 0x02 for Encoder, 0x03 for Decoder)
+- This is the single place where wire values get protocol meaning
+
+### QpackStreamHandler
+
+- Sets `StreamTypeValue` on outbound buffers (instead of / alongside `StreamType`)
+
+## What Stays the Same
+
+- `Http3StreamType` enum stays (protocol-internal concern)
+- `Http3NetworkBuffer.StreamType` stays (used by protocol layer)
+- Synthetic stream IDs stay (configured instead of hardcoded)
+- All buffering/flush logic stays (same patterns, keyed by `long` instead of enum)
+
+## Test Impact
+
+- Transport specs (`QuicPumpManagerSpec`, `QuicStreamRouterSpec`, `QuicStreamRouterEnhancedSpec`, `QuicTransportStateMachineSpec`, `QuicTransportStateMachineLifecycleSpec`, `QuicConnectionHandleSpec`, `QuicConnectionManagerSpec`) — update to use `long` values instead of `QuicStreamKind`
+- Protocol specs using `Http3StreamType` — unchanged

src/Servus.Akka/Servus.Akka.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <Folder Include="IO\QUIC\" />
+      <Folder Include="IO\TCP\" />
+    </ItemGroup>
+
+</Project>

src/TurboHTTP.StreamTests/Http3/Http30ConnectionConcurrencySpec.cs

@@ -30,9 +30,7 @@ private IEnumerable<IInputItem> BuildResponseSequence(params long[] streamIds)
             var buf = Http3NetworkBuffer.Rent(headersBytes.Length);
             headersBytes.AsSpan().CopyTo(buf.FullMemory.Span);
             buf.Length = headersBytes.Length;
-            buf.StreamType = Http3StreamType.Request;
             buf.StreamId = streamId;
-
             yield return buf;
             yield return new QuicCloseItem(QuicCloseKind.RequestStreamComplete, streamId);
         }
@@ -44,7 +42,7 @@ private static Http3NetworkBuffer BuildControlSettings()
         var buf = Http3NetworkBuffer.Rent(settingsBytes.Length);
         settingsBytes.AsSpan().CopyTo(buf.FullMemory.Span);
         buf.Length = settingsBytes.Length;
-        buf.StreamType = Http3StreamType.Control;
+        buf.StreamTypeValue = (long)StreamType.Control;
         return buf;
     }
 
@@ -93,10 +91,10 @@ private static List<long> ExtractRequestStreamIds(IReadOnlyList<IOutputItem> ite
         var result = new List<long>();
         foreach (var item in items)
         {
-            if (item is Http3NetworkBuffer { StreamType: Http3StreamType.Request, StreamId: >= 0 } tagged
-                && seen.Add(tagged.StreamId))
+            if (item is Http3NetworkBuffer { StreamTypeValue: null, StreamId: not null } tagged
+                && seen.Add(tagged.StreamId.Value))
             {
-                result.Add(tagged.StreamId);
+                result.Add(tagged.StreamId.Value);
             }
         }
 

src/TurboHTTP.StreamTests/Transport/QuicPumpManagerSpec.cs

@@ -31,7 +31,7 @@ public void StartInboundPump_should_not_throw()
         var handle = CreateTestHandle();
 
         // Should complete without throwing
-        pumpMgr.StartInboundPump(handle, Http3StreamType.Request, TestEndpoint, connectionGen: 0, streamId: 1);
+        pumpMgr.StartInboundPump(handle, -1, TestEndpoint, connectionGen: 0, streamId: 1);
 
         pumpMgr.StopAll();
     }
@@ -53,8 +53,8 @@ public void StopAll_should_cancel_pumps()
         var handle1 = CreateTestHandle();
         var handle2 = CreateTestHandle();
 
-        pumpMgr.StartInboundPump(handle1, Http3StreamType.Request, TestEndpoint, connectionGen: 0, streamId: 1);
-        pumpMgr.StartInboundPump(handle2, Http3StreamType.Request, TestEndpoint, connectionGen: 0, streamId: 2);
+        pumpMgr.StartInboundPump(handle1, -1, TestEndpoint, connectionGen: 0, streamId: 1);
+        pumpMgr.StartInboundPump(handle2, -1, TestEndpoint, connectionGen: 0, streamId: 2);
 
         // Stop all should complete without throwing
         pumpMgr.StopAll();
@@ -71,7 +71,7 @@ public void Multiple_pumps_can_be_started()
         for (var i = 0; i < 5; i++)
         {
             var handle = CreateTestHandle();
-            pumpMgr.StartInboundPump(handle, Http3StreamType.Request, TestEndpoint, connectionGen: 0, streamId: i);
+            pumpMgr.StartInboundPump(handle, -1, TestEndpoint, connectionGen: 0, streamId: i);
         }
 
         // StopAll should handle all pumps
@@ -84,7 +84,7 @@ public void Control_stream_pump_should_not_throw()
         var pumpMgr = new QuicPumpManager(ActorRefs.Nobody);
         var handle = CreateTestHandle();
 
-        pumpMgr.StartInboundPump(handle, Http3StreamType.Control, TestEndpoint, connectionGen: 0);
+        pumpMgr.StartInboundPump(handle, 0x00, TestEndpoint, connectionGen: 0, streamId: -2);
 
         pumpMgr.StopAll();
     }
@@ -95,19 +95,18 @@ public void Encoder_stream_pump_should_not_throw()
         var pumpMgr = new QuicPumpManager(ActorRefs.Nobody);
         var handle = CreateTestHandle();
 
-        pumpMgr.StartInboundPump(handle, Http3StreamType.QpackEncoder, TestEndpoint, connectionGen: 0);
+        pumpMgr.StartInboundPump(handle, 0x02, TestEndpoint, connectionGen: 0, streamId: -3);
 
         pumpMgr.StopAll();
     }
 
     [Fact(Timeout = 5000)]
-    public void StartInboundPump_without_stream_id_should_work()
+    public void StartInboundPump_with_explicit_stream_id_should_work()
     {
         var pumpMgr = new QuicPumpManager(ActorRefs.Nobody);
         var handle = CreateTestHandle();
 
-        // Default streamId = -1 for connection-level streams
-        pumpMgr.StartInboundPump(handle, Http3StreamType.Control, TestEndpoint, connectionGen: 0);
+        pumpMgr.StartInboundPump(handle, 0x00, TestEndpoint, connectionGen: 0, streamId: -2);
 
         pumpMgr.StopAll();
     }
@@ -118,7 +117,7 @@ public void StopAll_can_be_called_multiple_times()
         var pumpMgr = new QuicPumpManager(ActorRefs.Nobody);
         var handle = CreateTestHandle();
 
-        pumpMgr.StartInboundPump(handle, Http3StreamType.Request, TestEndpoint, connectionGen: 0, streamId: 1);
+        pumpMgr.StartInboundPump(handle, -1, TestEndpoint, connectionGen: 0, streamId: 1);
 
         pumpMgr.StopAll();
         pumpMgr.StopAll();
@@ -127,4 +126,4 @@ public void StopAll_can_be_called_multiple_times()
         // Should not throw
         Assert.True(true);
     }
-}
+}

src/TurboHTTP.StreamTests/Transport/QuicStreamRouterEnhancedSpec.cs

@@ -2,6 +2,7 @@
 using System.Threading.Channels;
 using Akka.Actor;
 using TurboHTTP.Internal;
+using TurboHTTP.Protocol.Http3;
 using TurboHTTP.Tests.Shared;
 using TurboHTTP.Transport.Connection;
 using TurboHTTP.Transport.Quic;
@@ -38,15 +39,16 @@ private static (ConnectionHandle Handle, ChannelReader<NetworkBuffer> OutboundRe
     public void RouteTaggedItem_should_route_encoder_to_pending_when_no_handle()
     {
         var (router, ops) = CreateRouter();
-        var pendingEncoder = new Queue<NetworkBuffer>();
 
         var encoderData = Http3NetworkBuffer.Rent(4);
-        encoderData.StreamType = Http3StreamType.QpackEncoder;
+        encoderData.StreamTypeValue = (long)StreamType.QpackEncoder;
         encoderData.Length = 3;
 
-        router.RouteTaggedItem(encoderData, null, new Queue<NetworkBuffer>(), null, pendingEncoder);
+        var encoderState = new TypedStreamState { StreamId = -3 };
+        var typedStreams = new Dictionary<long, TypedStreamState> { [0x02] = encoderState };
+        router.RouteTaggedItem(encoderData, 0x02, typedStreams);
 
-        Assert.Single(pendingEncoder);
+        Assert.Single(encoderState.PendingItems);
         Assert.True(ops.PullInputCount > 0);
     }
 
@@ -57,11 +59,12 @@ public void RouteTaggedItem_should_write_encoder_to_handle_when_available()
         var (encoderHandle, encoderReader) = CreateTestHandle();
 
         var encoderData = Http3NetworkBuffer.Rent(4);
-        encoderData.StreamType = Http3StreamType.QpackEncoder;
+        encoderData.StreamTypeValue = (long)StreamType.QpackEncoder;
         encoderData.Length = 3;
 
-        router.RouteTaggedItem(encoderData, null, new Queue<NetworkBuffer>(), encoderHandle,
-            new Queue<NetworkBuffer>());
+        var encoderState = new TypedStreamState { Handle = encoderHandle, StreamId = -3 };
+        var typedStreams = new Dictionary<long, TypedStreamState> { [0x02] = encoderState };
+        router.RouteTaggedItem(encoderData, 0x02, typedStreams);
 
         Assert.True(encoderReader.TryRead(out _));
     }
@@ -299,12 +302,11 @@ public void RouteTaggedItem_request_with_wrong_stream_id_should_handle_gracefull
         ctx.Handle = handle;
 
         var dataItem = Http3NetworkBuffer.Rent(4);
-        dataItem.StreamType = Http3StreamType.Request;
         dataItem.StreamId = 999; // Different from expected
         dataItem.Length = 3;
 
-        // Should not throw - routing handles mismatched stream IDs gracefully
-        router.RouteTaggedItem(dataItem, null, new Queue<NetworkBuffer>(), null, new Queue<NetworkBuffer>());
+        var typedStreams = new Dictionary<long, TypedStreamState>();
+        router.RouteTaggedItem(dataItem, -1, typedStreams);
 
         // Verify the operation completed without error
         Assert.NotNull(router);

src/TurboHTTP.StreamTests/Transport/QuicStreamRouterSpec.cs

@@ -2,6 +2,7 @@
 using System.Threading.Channels;
 using Akka.Actor;
 using TurboHTTP.Internal;
+using TurboHTTP.Protocol.Http3;
 using TurboHTTP.Tests.Shared;
 using TurboHTTP.Transport.Connection;
 using TurboHTTP.Transport.Quic;
@@ -102,11 +103,11 @@ public void RouteTaggedItem_should_write_to_handle_for_known_request_stream()
         ctx.Handle = handle;
 
         var dataItem = Http3NetworkBuffer.Rent(4);
-        dataItem.StreamType = Http3StreamType.Request;
         dataItem.StreamId = 1;
         dataItem.Length = 3;
 
-        router.RouteTaggedItem(dataItem, null, new Queue<NetworkBuffer>(), null, new Queue<NetworkBuffer>());
+        var typedStreams = new Dictionary<long, TypedStreamState>();
+        router.RouteTaggedItem(dataItem, -1, typedStreams);
 
         Assert.True(outboundReader.TryRead(out _));
     }
@@ -118,11 +119,11 @@ public void RouteTaggedItem_should_enqueue_when_handle_not_ready()
         router.GetOrCreateContext(1);
 
         var dataItem = Http3NetworkBuffer.Rent(4);
-        dataItem.StreamType = Http3StreamType.Request;
         dataItem.StreamId = 1;
         dataItem.Length = 3;
 
-        router.RouteTaggedItem(dataItem, null, new Queue<NetworkBuffer>(), null, new Queue<NetworkBuffer>());
+        var typedStreams = new Dictionary<long, TypedStreamState>();
+        router.RouteTaggedItem(dataItem, -1, typedStreams);
 
         Assert.Single(router.RequestStreams[1].PendingWrites);
         Assert.True(ops.PullInputCount > 0);
@@ -132,15 +133,16 @@ public void RouteTaggedItem_should_enqueue_when_handle_not_ready()
     public void RouteTaggedItem_should_route_control_to_pending_queue_when_no_handle()
     {
         var (router, ops) = CreateRouter();
-        var pendingControl = new Queue<NetworkBuffer>();
+        var controlState = new TypedStreamState { StreamId = -2 };
+        var typedStreams = new Dictionary<long, TypedStreamState> { [0x00] = controlState };
 
         var dataItem = Http3NetworkBuffer.Rent(4);
-        dataItem.StreamType = Http3StreamType.Control;
+        dataItem.StreamTypeValue = (long)StreamType.Control;
         dataItem.Length = 3;
 
-        router.RouteTaggedItem(dataItem, null, pendingControl, null, new Queue<NetworkBuffer>());
+        router.RouteTaggedItem(dataItem, 0x00, typedStreams);
 
-        Assert.Single(pendingControl);
+        Assert.Single(controlState.PendingItems);
         Assert.True(ops.PullInputCount > 0);
     }
 
@@ -149,12 +151,14 @@ public void RouteTaggedItem_should_write_control_to_handle_when_available()
     {
         var (router, _) = CreateRouter();
         var (controlHandle, controlReader) = CreateTestHandle();
+        var controlState = new TypedStreamState { Handle = controlHandle, StreamId = -2 };
+        var typedStreams = new Dictionary<long, TypedStreamState> { [0x00] = controlState };
 
         var dataItem = Http3NetworkBuffer.Rent(4);
-        dataItem.StreamType = Http3StreamType.Control;
+        dataItem.StreamTypeValue = (long)StreamType.Control;
         dataItem.Length = 3;
 
-        router.RouteTaggedItem(dataItem, controlHandle, new Queue<NetworkBuffer>(), null, new Queue<NetworkBuffer>());
+        router.RouteTaggedItem(dataItem, 0x00, typedStreams);
 
         Assert.True(controlReader.TryRead(out _));
     }