Skip to content

Commit cdc1547

Browse files
committed
Send UDP as QUIC DATAGRAMs, and keep the packet boundaries
Section 9's arithmetic has been checked against the specification's own fixture since before there was a connection to use it on. What was missing was the transport: nothing had ever put one of those frames on a wire. Now a UDP packet crosses as a DATAGRAM, a packet too large for the path is fragmented and reassembled, and three packets arrive as three packets. The echo comes from a service on the Portal's loopback, which this device cannot reach, so a packet that returns has crossed the carrier and nothing else. The fragmenting case derives its size from what ngtcp2 reports for the current path rather than from a constant — a constant that happened to fit would exercise the unfragmented path and pass, which is the failure the case exists to avoid. UDP needed an interface it did not have. Over TLS a packet is length-prefixed inside a byte stream and the caller does the framing; over QUIC each packet is its own DATAGRAM, unreliable and unordered, which is what UDP is. Expressing that as "some bytes" would frame it twice — once for a stream that is not being used and once for the datagram that is. So PacketFlow exists, UdpRelay asks for one, and falls back to framing when it does not get one. The opening write changed with it. A UDP flow's control stream carries the FlowHeader and the Target and stops there; the first packet leaves as a DATAGRAM once the Portal has answered, because that is what section 9 says and because bytes after the Target would be read as a second one. Row 15 is closed, and by construction rather than by a check: the reassembler refuses payload until markReady, and the carrier calls it only when a Portal has answered a flow. A datagram arriving before any flow exists is discarded rather than queued for one that may never open. A UDP flow over a connection whose peer did not enable RFC 9221 is refused. The alternative — quietly using the TLS carrier's framing on a QUIC stream — would be framing nobody is listening for. One defect, and it is a Kotlin one. NowhereSession wrapped every flow in `Flow by delegate` to release its id on close, and that implements exactly Flow: a PacketFlow handed through came out the other side as an ordinary flow, so the caller framed the packet for a stream it was not using. Every datagram case failed on "a QUIC UDP flow must take packets". There are two wrappers now, and the reason is in the comment on them. L3: nineteen covered, one partly, seven blocked. All seven now wait on the same two things — split flows and a physical device. Gates green; device suite 43 cases.
1 parent 7e60475 commit cdc1547

10 files changed

Lines changed: 975 additions & 17 deletions

File tree

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
// SPDX-License-Identifier: GPL-3.0-only
2+
// Copyright (C) 2026 The Somewhere Authors
3+
4+
package eu.nodepass.somewhere.quic
5+
6+
import androidx.test.ext.junit.runners.AndroidJUnit4
7+
import eu.nodepass.somewhere.protocol.DecodeResult
8+
import eu.nodepass.somewhere.protocol.frame.FlowKind
9+
import eu.nodepass.somewhere.protocol.session.NowhereSession
10+
import eu.nodepass.somewhere.protocol.session.PacketFlow
11+
import eu.nodepass.somewhere.protocol.session.QuicCarrier
12+
import eu.nodepass.somewhere.protocol.target.Target
13+
import eu.nodepass.somewhere.protocol.url.NowhereUrl
14+
import eu.nodepass.somewhere.vpn.E2eEnvironment
15+
import org.junit.Assert.assertArrayEquals
16+
import org.junit.Assert.assertNotNull
17+
import org.junit.Assert.assertTrue
18+
import org.junit.Test
19+
import org.junit.runner.RunWith
20+
import java.net.InetSocketAddress
21+
import kotlin.random.Random
22+
23+
/**
24+
* UDP rides QUIC DATAGRAMs, against a live Portal.
25+
*
26+
* ## What is new here, and what was already true
27+
*
28+
* Section 9's arithmetic — the frame headers, the fragment plan, the
29+
* reassembler's bounds — has been checked against the specification's own
30+
* fixture since before there was a connection to use it on. What was missing
31+
* was the transport: nothing had ever put one of those frames on a wire.
32+
*
33+
* Two things only become real here. `maxDatagram` is a runtime figure ngtcp2
34+
* reports for the current path rather than a parameter a test chooses, so the
35+
* fragment plan is now made against a number the network decided. And the
36+
* echo comes back from a service the **Portal** can reach and this device
37+
* cannot — 127.0.0.1 is the Portal's loopback, not the device's — so a packet
38+
* that returns has crossed the carrier and nothing else.
39+
*/
40+
@RunWith(AndroidJUnit4::class)
41+
class QuicDatagramTest {
42+
@Test
43+
fun aPacketThatFitsMakesTheRoundTrip() {
44+
withUdpFlow { flow ->
45+
val sent = Random(7).nextBytes(512)
46+
flow.sendPacket(sent)
47+
val back = flow.receivePacket(WAIT_MILLIS)
48+
assertNotNull("nothing came back", back)
49+
assertArrayEquals("the echo differs from what was sent", sent, back)
50+
}
51+
}
52+
53+
/**
54+
* A packet too large for one datagram is fragmented and reassembled.
55+
*
56+
* The size is derived from what the connection actually reports rather than
57+
* being a constant: a constant that happened to fit would exercise the
58+
* unfragmented path and pass, which is the failure this case exists to
59+
* avoid.
60+
*/
61+
@Test
62+
fun aPacketTooLargeForOneDatagramIsFragmentedAndComesBackWhole() {
63+
withUdpFlow { flow, connection ->
64+
val maxDatagram = connection.maxDatagramSize()
65+
assertTrue("the peer enabled no datagram extension", maxDatagram > 0)
66+
67+
val sent = Random(11).nextBytes(maxDatagram * 3)
68+
flow.sendPacket(sent)
69+
val back = flow.receivePacket(WAIT_MILLIS)
70+
assertNotNull("the reassembled packet never arrived", back)
71+
assertArrayEquals("reassembly did not reproduce the packet", sent, back)
72+
}
73+
}
74+
75+
@Test
76+
fun severalPacketsKeepTheirBoundaries() {
77+
// The property a stream carrier has to work for and a datagram carrier
78+
// has by construction: three packets are three packets, not a byte
79+
// stream that happens to have been written three times.
80+
withUdpFlow { flow ->
81+
val packets = (1..3).map { Random(it).nextBytes(64 * it) }
82+
packets.forEach { flow.sendPacket(it) }
83+
val received = packets.indices.map { flow.receivePacket(WAIT_MILLIS) }
84+
received.forEachIndexed { index, back ->
85+
assertNotNull("packet $index never arrived", back)
86+
}
87+
assertTrue(
88+
"the packets came back as different bytes",
89+
received.filterNotNull().toSet().size == received.size,
90+
)
91+
}
92+
}
93+
94+
private fun withUdpFlow(body: (PacketFlow) -> Unit) = withUdpFlow { flow, _ -> body(flow) }
95+
96+
private fun withUdpFlow(body: (PacketFlow, QuicConnection) -> Unit) {
97+
val portal = E2eEnvironment.requirePortal()
98+
val url =
99+
when (
100+
val parsed =
101+
NowhereUrl.parse("nowhere://${E2eEnvironment.sharedKey}@$portal?up=udp&down=udp")
102+
) {
103+
is DecodeResult.Ok -> parsed.value
104+
is DecodeResult.Invalid -> throw AssertionError(parsed.reason.detail)
105+
}
106+
107+
QuicConnection
108+
.open(
109+
remote = InetSocketAddress(portal.substringBeforeLast(':'), portal.substringAfterLast(':').toInt()),
110+
alpn = url.alpn,
111+
serverName = null,
112+
protect = { true },
113+
).use { connection ->
114+
connection.completeHandshake()
115+
NowhereSession(
116+
sharedKey = url.sharedKey,
117+
connect = { error("a QUIC session must not dial TLS") },
118+
quicStreams =
119+
QuicCarrier.StreamFactory {
120+
QuicStreamTransport(connection, connection.openStream())
121+
},
122+
quicDatagrams = connection,
123+
).use { session ->
124+
val target = (Target.ofIpv4(byteArrayOf(127, 0, 0, 1), ECHO_PORT) as DecodeResult.Ok).value
125+
val opened = session.openFlow(target, FlowKind.Udp)
126+
val flow =
127+
(opened as? DecodeResult.Ok)?.value
128+
?: throw AssertionError("the UDP flow failed: ${opened.reasonOrNull()?.detail}")
129+
assertTrue("a QUIC UDP flow must take packets", flow is PacketFlow)
130+
flow.use { body(flow as PacketFlow, connection) }
131+
}
132+
}
133+
}
134+
135+
private companion object {
136+
/**
137+
* A UDP echo on the **Portal's** loopback. Nothing listens on the
138+
* device's own, so a packet that comes back cannot have taken another
139+
* route.
140+
*/
141+
const val ECHO_PORT = 28092
142+
const val WAIT_MILLIS = 10_000L
143+
}
144+
}

0 commit comments

Comments
 (0)