plans

Author: st0o0

docs/superpowers/plans/2026-05-13-h2h3-redesign-phase1-multiplexed-core.md

@@ -0,0 +1,236 @@
+# Phase 3: MultiplexedOptions Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Create `MultiplexedOptions` — the shared configuration record for multiplexed protocols (HTTP/2 and HTTP/3).
+
+**Architecture:** A C# `record` with a static `Default` member and a `Validate()` method. Contains `SharedHttpOptions` (from H/1.0 Redesign) plus multiplexed-specific settings. Construction via `with`-expression.
+
+**Tech Stack:** .NET, xUnit v3
+
+**Prerequisite:** Phase 2 complete. `SharedHttpOptions` must exist (from H/1.0 Redesign Phase 3).
+
+---
+
+### Task 1: MultiplexedOptions Record
+
+**Files:**
+- Create: `src/TurboHTTP/Protocol/Multiplexed/Options/MultiplexedOptions.cs`
+- Test: `src/TurboHTTP.Tests/Multiplexed/MultiplexedOptionsSpec.cs`
+
+- [ ] **Step 1: Write the failing tests**
+
+```csharp
+// src/TurboHTTP.Tests/Multiplexed/MultiplexedOptionsSpec.cs
+using TurboHTTP.Protocol.Multiplexed.Options;
+
+namespace TurboHTTP.Tests.Multiplexed;
+
+public sealed class MultiplexedOptionsSpec
+{
+    [Fact(Timeout = 5000)]
+    public void Default_should_have_100_max_concurrent_streams()
+    {
+        var options = MultiplexedOptions.Default;
+        Assert.Equal(100, options.MaxConcurrentStreams);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Default_should_have_16k_max_header_size()
+    {
+        var options = MultiplexedOptions.Default;
+        Assert.Equal(16 * 1024, options.MaxHeaderSize);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Default_should_have_64k_max_total_header_size()
+    {
+        var options = MultiplexedOptions.Default;
+        Assert.Equal(64 * 1024, options.MaxTotalHeaderSize);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Default_should_have_1s_reconnect_backoff()
+    {
+        var options = MultiplexedOptions.Default;
+        Assert.Equal(TimeSpan.FromSeconds(1), options.ReconnectBackoff);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Default_should_have_3_max_reconnect_attempts()
+    {
+        var options = MultiplexedOptions.Default;
+        Assert.Equal(3, options.MaxReconnectAttempts);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_MaxConcurrentStreams_is_zero()
+    {
+        var options = MultiplexedOptions.Default with { MaxConcurrentStreams = 0 };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("MaxConcurrentStreams", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_MaxConcurrentStreams_is_negative()
+    {
+        var options = MultiplexedOptions.Default with { MaxConcurrentStreams = -1 };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("MaxConcurrentStreams", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_MaxHeaderSize_is_zero()
+    {
+        var options = MultiplexedOptions.Default with { MaxHeaderSize = 0 };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("MaxHeaderSize", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_MaxTotalHeaderSize_is_less_than_MaxHeaderSize()
+    {
+        var options = MultiplexedOptions.Default with
+        {
+            MaxHeaderSize = 1024,
+            MaxTotalHeaderSize = 512
+        };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("MaxTotalHeaderSize", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_ReconnectBackoff_is_negative()
+    {
+        var options = MultiplexedOptions.Default with { ReconnectBackoff = TimeSpan.FromSeconds(-1) };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("ReconnectBackoff", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_throw_when_MaxReconnectAttempts_is_negative()
+    {
+        var options = MultiplexedOptions.Default with { MaxReconnectAttempts = -1 };
+        var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+        Assert.Contains("MaxReconnectAttempts", ex.Message);
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_accept_zero_MaxReconnectAttempts()
+    {
+        var options = MultiplexedOptions.Default with { MaxReconnectAttempts = 0 };
+        options.Validate();
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_accept_zero_ReconnectBackoff()
+    {
+        var options = MultiplexedOptions.Default with { ReconnectBackoff = TimeSpan.Zero };
+        options.Validate();
+    }
+
+    [Fact(Timeout = 5000)]
+    public void Validate_should_pass_for_default()
+    {
+        MultiplexedOptions.Default.Validate();
+    }
+
+    [Fact(Timeout = 5000)]
+    public void With_expression_should_create_modified_copy()
+    {
+        var options = MultiplexedOptions.Default with { MaxConcurrentStreams = 50 };
+        Assert.Equal(50, options.MaxConcurrentStreams);
+        Assert.Equal(100, MultiplexedOptions.Default.MaxConcurrentStreams);
+    }
+}
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `dotnet run --project src/TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -class "TurboHTTP.Tests.Multiplexed.MultiplexedOptionsSpec"`
+Expected: Compilation error — `MultiplexedOptions` does not exist.
+
+- [ ] **Step 3: Implement MultiplexedOptions**
+
+```csharp
+// src/TurboHTTP/Protocol/Multiplexed/Options/MultiplexedOptions.cs
+namespace TurboHTTP.Protocol.Multiplexed.Options;
+
+public sealed record MultiplexedOptions
+{
+    public int MaxConcurrentStreams { get; init; } = 100;
+    public int MaxHeaderSize { get; init; } = 16 * 1024;
+    public int MaxTotalHeaderSize { get; init; } = 64 * 1024;
+    public TimeSpan ReconnectBackoff { get; init; } = TimeSpan.FromSeconds(1);
+    public int MaxReconnectAttempts { get; init; } = 3;
+
+    public static MultiplexedOptions Default { get; } = new();
+
+    public void Validate()
+    {
+        if (MaxConcurrentStreams <= 0)
+        {
+            throw new ArgumentException("MaxConcurrentStreams must be greater than zero.", nameof(MaxConcurrentStreams));
+        }
+
+        if (MaxHeaderSize <= 0)
+        {
+            throw new ArgumentException("MaxHeaderSize must be greater than zero.", nameof(MaxHeaderSize));
+        }
+
+        if (MaxTotalHeaderSize < MaxHeaderSize)
+        {
+            throw new ArgumentException("MaxTotalHeaderSize must be greater than or equal to MaxHeaderSize.", nameof(MaxTotalHeaderSize));
+        }
+
+        if (ReconnectBackoff < TimeSpan.Zero)
+        {
+            throw new ArgumentException("ReconnectBackoff must not be negative.", nameof(ReconnectBackoff));
+        }
+
+        if (MaxReconnectAttempts < 0)
+        {
+            throw new ArgumentException("MaxReconnectAttempts must not be negative.", nameof(MaxReconnectAttempts));
+        }
+    }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `dotnet run --project src/TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -class "TurboHTTP.Tests.Multiplexed.MultiplexedOptionsSpec"`
+Expected: All 15 tests PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/TurboHTTP/Protocol/Multiplexed/Options/MultiplexedOptions.cs src/TurboHTTP.Tests/Multiplexed/MultiplexedOptionsSpec.cs
+git commit -m "feat(multiplexed): add MultiplexedOptions record with validation"
+```
+
+---
+
+### Task 2: Run full build and verify phase gate
+
+- [ ] **Step 1: Build the solution**
+
+Run: `dotnet build --configuration Release src/TurboHTTP.slnx`
+Expected: Build succeeds with zero errors.
+
+- [ ] **Step 2: Run all Multiplexed tests**
+
+Run: `dotnet run --project src/TurboHTTP.Tests/TurboHTTP.Tests.csproj -- -namespace "TurboHTTP.Tests.Multiplexed"`
+Expected: All specs PASS — StreamState, StreamTracker, CorrelationMap, ReconnectClassifier, ReconnectBuffer, MultiplexedOptions.
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `dotnet test src/TurboHTTP.Tests/TurboHTTP.Tests.csproj`
+Expected: All tests PASS (existing + new).
+
+- [ ] **Step 4: Commit phase completion**
+
+```bash
+git commit --allow-empty -m "milestone: Phase 3 complete — Multiplexed layer fully implemented (Core, Encoding, Correlation, Reconnect, Options)"
+```
+
+This concludes **Spec 1: Protocol/Multiplexed/**. The shared layer is ready for consumption by HTTP/2 (Phase 4–6) and HTTP/3 (Phase 7–9).