feat(quic): Phase I-K — HTTP/3, QPACK, WebTransport framing

Layer the WebTransport-over-HTTP/3 stack on top of QUIC: - HTTP/3 frame and stream-type identifiers (RFC 9114) plus the WebTransport draft additions (stream type 0x41 for client-bidi, 0x54 for client-uni). - HTTP/3 Settings frame codec advertising the three settings nests requires: ENABLE_CONNECT_PROTOCOL=1, H3_DATAGRAM=1, ENABLE_WEBTRANSPORT=1. - QPACK static table (RFC 9204 Appendix A — all 99 entries) plus pre-built name→index and (name,value)→index maps for encoder lookup. - QPACK prefixed-integer codec (RFC 7541 §5.1). - QPACK literal-only encoder: indexed-static, literal-with-static-name-ref, and literal-with-literal-name field-line shapes — no dynamic table inserts on the encoder side, so we always emit Required Insert Count = 0 and Delta Base = 0. - QPACK decoder supporting indexed-static + literal-with-static-name-ref + literal-with-literal-name. Throws on dynamic-table references (we advertise QPACK_MAX_TABLE_CAPACITY=0). - QPACK Huffman decoder (RFC 7541 Appendix B); the encoder always emits Huffman=0 literal strings. - WebTransport capsule encoder (WT_CLOSE_SESSION = 0x2843). - WebTransport datagram framing — quarter-stream-id varint prefix per RFC 9297 + draft-ietf-webtrans-http3. - WebTransport stream type prefixes for client-bidi (0x41) and client-uni (0x54), each followed by the quarter session id. - ExtendedConnect builder for the `:method=CONNECT, :protocol=webtransport` request headers and HEADERS frame body. - QuicConnectionDriver wraps a UdpSocket + QuicConnection in coroutines for the read/send loops. Round-trip tests: QPACK encode → decode preserves header lists for all three field-line shapes plus the WebTransport extended CONNECT request. WT datagram framing round-trips with both zero and non-zero session ids. https://claude.ai/code/session_01EC1tfXfap8k8GyKvrxkxZx
2026-04-25 20:56:35 +00:00
parent 52ab84acfe
commit cceb5bfe96
13 changed files with 1137 additions and 0 deletions
@@ -0,0 +1,67 @@
+/*
+ * 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.qpack
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class QpackRoundTripTest {
+    @Test
+    fun static_table_indexed_field_line_round_trip() {
+        val headers = listOf(":method" to "GET", ":scheme" to "https")
+        val encoded = QpackEncoder().encodeFieldSection(headers)
+        val decoded = QpackDecoder().decodeFieldSection(encoded)
+        assertEquals(headers, decoded)
+    }
+
+    @Test
+    fun literal_with_static_name_reference_round_trip() {
+        val headers = listOf(":authority" to "example.com", ":path" to "/moq")
+        val encoded = QpackEncoder().encodeFieldSection(headers)
+        val decoded = QpackDecoder().decodeFieldSection(encoded)
+        assertEquals(headers, decoded)
+    }
+
+    @Test
+    fun literal_with_literal_name_round_trip() {
+        val headers = listOf("x-custom-header" to "deadbeef", "another-one" to "value")
+        val encoded = QpackEncoder().encodeFieldSection(headers)
+        val decoded = QpackDecoder().decodeFieldSection(encoded)
+        assertEquals(headers, decoded)
+    }
+
+    @Test
+    fun mixed_extended_connect_round_trip() {
+        // Mirrors what we'll send for WebTransport extended-CONNECT.
+        val headers =
+            listOf(
+                ":method" to "CONNECT",
+                ":protocol" to "webtransport",
+                ":scheme" to "https",
+                ":authority" to "nostrnests.com",
+                ":path" to "/moq",
+                "authorization" to "Bearer token-abc123",
+            )
+        val encoded = QpackEncoder().encodeFieldSection(headers)
+        val decoded = QpackDecoder().decodeFieldSection(encoded)
+        assertEquals(headers, decoded)
+    }
+}
@@ -0,0 +1,67 @@
+/*
+ * 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.webtransport
+
+import kotlin.test.Test
+import kotlin.test.assertContentEquals
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+
+class WtFramingTest {
+    @Test
+    fun datagram_round_trip() {
+        val payload = "hello moq".encodeToByteArray()
+        val encoded = WtDatagram.encode(connectStreamId = 0L, payload = payload)
+        val decoded = WtDatagram.decode(encoded)
+        assertNotNull(decoded)
+        assertEquals(0L, decoded.sessionStreamId)
+        assertContentEquals(payload, decoded.payload)
+    }
+
+    @Test
+    fun datagram_round_trip_nonzero_session_id() {
+        val payload = byteArrayOf(0x01, 0x02, 0x03)
+        val encoded = WtDatagram.encode(connectStreamId = 4L, payload = payload)
+        val decoded = WtDatagram.decode(encoded)!!
+        assertEquals(4L, decoded.sessionStreamId)
+        assertContentEquals(payload, decoded.payload)
+    }
+
+    @Test
+    fun bidi_stream_prefix_encodes_0x41_then_session_id() {
+        val prefix = encodeWtBidiStreamPrefix(0L)
+        // 0x41 = 65 needs the 2-byte varint form: high byte 0x40, low byte 0x41.
+        // Then session id = 0 in 1-byte varint.
+        assertEquals(0x40.toByte(), prefix[0])
+        assertEquals(0x41.toByte(), prefix[1])
+        assertEquals(0x00.toByte(), prefix[2])
+    }
+
+    @Test
+    fun close_session_capsule_starts_with_2843() {
+        val capsule = encodeCloseSessionCapsule(0, "")
+        // 0x2843 encoded as varint occupies 2 bytes: 0x68, 0x43 (with the 2-byte form prefix).
+        // Verify by parsing.
+        val hi = capsule[0].toInt() and 0xFF
+        // Top two bits of first byte indicate 2-byte varint: 01xxxxxx
+        assertEquals(0x40, hi and 0xC0)
+    }
+}