feat(quic): step 1 of RFC 9002 retransmit — RecoveryToken + SentPacket types

First step of `quic/plans/2026-05-04-control-frame-retransmit.md`. Pure type definitions, no behavior change yet — sets up the data shape the next steps will populate from the writer (step 2) and drain from ACK / loss-detection paths (steps 3–6). RecoveryToken: sealed class mirroring neqo's neqo-transport/src/recovery/token.rs:21 StreamRecoveryToken. - Ack (singleton object): tracked but never retransmitted, so the sent-packet map invariant ("every retained entry has at least one token") holds for ACK-only packets too - MaxStreamsUni / MaxStreamsBidi: receive-side stream-id cap extension (RFC 9000 §19.11) — the frame whose loss tripped the moq-rs cliff - MaxData: connection-level data cap extension (§19.9) - MaxStreamData: per-stream data cap extension (§19.10) SentPacket: data class mirroring neqo's neqo-transport/src/recovery/sent.rs::Packet. Held in a per-pn-space map on QuicConnection (step 2 wires this up). Carries packet number, send time, ack-eliciting flag, on-wire size, and the token list to dispatch on loss. Tests: 6 token tests (data-class equality, sealed-hierarchy exhaustiveness, Ack singleton-ness) + 6 SentPacket tests (equality across fields, copy semantics, ACK-only-with-Ack-token convention, multi-token packet shape). All pass; full :quic test suite still passes — types are purely additive. Out of scope as documented in the plan: STREAM data retransmit, CRYPTO retransmit, RESET_STREAM/STOP_SENDING/etc, congestion control, 0-RTT. Those are separate follow-ups. https://claude.ai/code/session_01PYYez8a6sjiakyjAxsfCEQ
2026-05-04 22:31:07 +00:00
parent c24630513f
commit 9e6fa3d3f0
4 changed files with 441 additions and 0 deletions
@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
+
+/**
+ * Type-level invariants for [RecoveryToken]: equality + hashCode
+ * correctness across data-class variants, the singleton [Ack] object,
+ * and the typed-token shape required by the dispatcher in step 6 of
+ * `quic/plans/2026-05-04-control-frame-retransmit.md`.
+ *
+ * No connection state is exercised here — these are unit tests on
+ * the type itself.
+ */
+class RecoveryTokenTest {
+    @Test
+    fun ack_isSingleton() {
+        val a: RecoveryToken = RecoveryToken.Ack
+        val b: RecoveryToken = RecoveryToken.Ack
+        // `data object Ack` ⇒ same reference, same hash.
+        assertTrue(a === b)
+        assertEquals(a, b)
+        assertEquals(a.hashCode(), b.hashCode())
+    }
+
+    @Test
+    fun maxStreamsUni_equalityByValue() {
+        val t1 = RecoveryToken.MaxStreamsUni(maxStreams = 150L)
+        val t2 = RecoveryToken.MaxStreamsUni(maxStreams = 150L)
+        val t3 = RecoveryToken.MaxStreamsUni(maxStreams = 200L)
+
+        assertEquals(t1, t2)
+        assertEquals(t1.hashCode(), t2.hashCode())
+        assertNotEquals(t1, t3)
+    }
+
+    @Test
+    fun maxStreamsBidi_distinctFromUni() {
+        val uni: RecoveryToken = RecoveryToken.MaxStreamsUni(maxStreams = 100L)
+        val bidi: RecoveryToken = RecoveryToken.MaxStreamsBidi(maxStreams = 100L)
+        assertNotEquals(uni, bidi)
+    }
+
+    @Test
+    fun maxData_equalityByValue() {
+        val t1 = RecoveryToken.MaxData(maxData = 1_000_000L)
+        val t2 = RecoveryToken.MaxData(maxData = 1_000_000L)
+        val t3 = RecoveryToken.MaxData(maxData = 2_000_000L)
+
+        assertEquals(t1, t2)
+        assertNotEquals(t1, t3)
+    }
+
+    @Test
+    fun maxStreamData_equalityByPair() {
+        val t1 = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L)
+        val t2 = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L)
+        val differentStream = RecoveryToken.MaxStreamData(streamId = 4L, maxData = 1024L)
+        val differentValue = RecoveryToken.MaxStreamData(streamId = 0L, maxData = 2048L)
+
+        assertEquals(t1, t2)
+        assertNotEquals(t1, differentStream)
+        assertNotEquals(t1, differentValue)
+    }
+
+    @Test
+    fun whenDispatch_isExhaustive() {
+        // Compile-time assertion that the sealed hierarchy is fixed and
+        // an exhaustive `when` actually compiles. If a new variant is
+        // added without updating the dispatcher, this test stops
+        // compiling — caught at build time, not at runtime.
+        val tokens: List<RecoveryToken> =
+            listOf(
+                RecoveryToken.Ack,
+                RecoveryToken.MaxStreamsUni(150L),
+                RecoveryToken.MaxStreamsBidi(150L),
+                RecoveryToken.MaxData(1_000_000L),
+                RecoveryToken.MaxStreamData(streamId = 0L, maxData = 1024L),
+            )
+        val labels =
+            tokens.map {
+                when (it) {
+                    RecoveryToken.Ack -> "ack"
+                    is RecoveryToken.MaxStreamsUni -> "msu:${it.maxStreams}"
+                    is RecoveryToken.MaxStreamsBidi -> "msb:${it.maxStreams}"
+                    is RecoveryToken.MaxData -> "md:${it.maxData}"
+                    is RecoveryToken.MaxStreamData -> "msd:${it.streamId}:${it.maxData}"
+                }
+            }
+        assertEquals(
+            listOf(
+                "ack",
+                "msu:150",
+                "msb:150",
+                "md:1000000",
+                "msd:0:1024",
+            ),
+            labels,
+        )
+    }
+}
@@ -0,0 +1,144 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quic.connection.recovery
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotEquals
+import kotlin.test.assertTrue
+
+/**
+ * Schema-level invariants for [SentPacket]: data-class equality
+ * mirrors [RecoveryTokenTest], plus the convention that ACK-only
+ * packets carry a non-empty `tokens` list with `RecoveryToken.Ack`
+ * (so the sent-packet map's invariant — every retained entry has at
+ * least one token to dispatch — holds uniformly across packet types).
+ */
+class SentPacketTest {
+    @Test
+    fun equality_byAllFields() {
+        val a =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 1_700_000_000_000L,
+                ackEliciting = true,
+                sizeBytes = 128,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val b =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 1_700_000_000_000L,
+                ackEliciting = true,
+                sizeBytes = 128,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        assertEquals(a, b)
+        assertEquals(a.hashCode(), b.hashCode())
+    }
+
+    @Test
+    fun equality_byPacketNumber() {
+        val a =
+            SentPacket(
+                packetNumber = 7L,
+                sentAtMillis = 0L,
+                ackEliciting = false,
+                sizeBytes = 16,
+                tokens = listOf(RecoveryToken.Ack),
+            )
+        val differentPn = a.copy(packetNumber = 8L)
+        assertNotEquals(a, differentPn)
+    }
+
+    @Test
+    fun equality_byTokenList() {
+        val a =
+            SentPacket(
+                packetNumber = 1L,
+                sentAtMillis = 0L,
+                ackEliciting = true,
+                sizeBytes = 64,
+                tokens = listOf(RecoveryToken.MaxData(1_000L), RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val swapped = a.copy(tokens = listOf(RecoveryToken.MaxStreamsUni(150L), RecoveryToken.MaxData(1_000L)))
+        // List equality is order-sensitive — these are different.
+        assertNotEquals(a, swapped)
+    }
+
+    @Test
+    fun ackOnlyPacket_carriesAckToken() {
+        // ACK-only packet: not ack-eliciting (RFC 9000 §13.2.1) but
+        // we still record a single Ack token so the sent-packet map's
+        // "every entry has a token" invariant holds.
+        val ackOnly =
+            SentPacket(
+                packetNumber = 42L,
+                sentAtMillis = 0L,
+                ackEliciting = false,
+                sizeBytes = 24,
+                tokens = listOf(RecoveryToken.Ack),
+            )
+        assertTrue(ackOnly.tokens.isNotEmpty())
+        assertEquals(RecoveryToken.Ack, ackOnly.tokens.single())
+    }
+
+    @Test
+    fun ackEliciting_packetCanCarryMultipleControlTokens() {
+        // A real outbound packet that bumps both flow-control caps
+        // simultaneously (e.g. publisher session with sustained
+        // stream churn) carries two tokens. Loss declaration walks
+        // both; ACK drops both.
+        val multi =
+            SentPacket(
+                packetNumber = 100L,
+                sentAtMillis = 0L,
+                ackEliciting = true,
+                sizeBytes = 80,
+                tokens =
+                    listOf(
+                        RecoveryToken.MaxStreamsUni(maxStreams = 1_500_000L),
+                        RecoveryToken.MaxData(maxData = 64L * 1024L * 1024L),
+                    ),
+            )
+        assertEquals(2, multi.tokens.size)
+        assertEquals(RecoveryToken.MaxStreamsUni(1_500_000L), multi.tokens[0])
+        assertEquals(RecoveryToken.MaxData(64L * 1024L * 1024L), multi.tokens[1])
+    }
+
+    @Test
+    fun copy_preservesUntouchedFields() {
+        val base =
+            SentPacket(
+                packetNumber = 5L,
+                sentAtMillis = 1L,
+                ackEliciting = true,
+                sizeBytes = 100,
+                tokens = listOf(RecoveryToken.MaxStreamsUni(150L)),
+            )
+        val onlyTimeChanged = base.copy(sentAtMillis = 2L)
+        assertEquals(base.packetNumber, onlyTimeChanged.packetNumber)
+        assertEquals(base.ackEliciting, onlyTimeChanged.ackEliciting)
+        assertEquals(base.sizeBytes, onlyTimeChanged.sizeBytes)
+        assertEquals(base.tokens, onlyTimeChanged.tokens)
+        assertNotEquals(base.sentAtMillis, onlyTimeChanged.sentAtMillis)
+    }
+}