quic: expose flow-control snapshot for prod cliff investigation

Adds a read-only diagnostic surface that lets a test (or any caller) read the peer's transport parameters, the live connection-level send credit / consumed counters, the current peer-granted MAX_STREAMS_* values, and the total bytes sitting in stream send buffers but not yet handed to STREAM frames. Goal: pin which budget runs out at the production "stream cliff" described in nestsClient/plans/2026-05-01-quic-stream-cliff-investigation.md. The plan flagged three candidates — connection-level MAX_DATA, per- stream MAX_STREAM_DATA, or the relay's MAX_STREAMS_UNI extension policy. The snapshot makes it possible to attribute the stall by reading the diff between the pre-pump, post-pump, and post-grace snapshots from the test's stdout. QuicConnection: - flowControlSnapshot(): suspend, lock-protected, returns QuicFlowControlSnapshot (new data class) — peer TPs + live accounting + sum of enqueued-not-sent bytes across streams. QuicWebTransportSession (jvmAndroid adapter): - quicFlowControlSnapshot() passthrough so the test can downcast its WebTransportSession and read the underlying connection's state without poking through the common transport interface. SendTraceScenario: - Optional flowControlSnapshot lambda parameter; when supplied, logs three checkpoints — fc-pre, fc-post-pump, fc-post-grace — each on a single line with the full snapshot. NostrnestsProdAudioTransmissionTest + NostrNestsSustainedSendOutcomesInteropTest: - withProdSpeakerAndListeners / withHarnessSpeakerAndListeners now yield a snapshot lambda to the scenario block. Every sweep test automatically dumps fc-* lines to the JUnit XML system-out. FlowControlSnapshotTest: - Pre-handshake: peer TP fields are null, counters zero. - Post-handshake: every TP field reflects what the in-process TLS server advertised; sendConnectionFlowCredit equals initial_max_data; consumed = 0. - Post-allocate-and-enqueue: nextLocalUni/BidiIndex advance, totalEnqueuedNotSentBytes sums the buffered chunks, and streamsWithPendingBytes counts only streams with > 0 pending. Reading the production sweep output after this commit: - fc-pre dumps what the relay grants on handshake (initial_max_data, initial_max_stream_data_uni, initial_max_streams_uni). - fc-post-pump shows whether sendConnectionFlowConsumed has plateaued at the cap (peer didn't extend MAX_DATA) or whether bytes are stuck in stream send buffers. - The diff between fc-post-pump and fc-post-grace tells us whether the relay's eventual MAX_DATA / MAX_STREAMS update did or didn't arrive during the 30-60 s grace window.
2026-05-01 14:14:06 +00:00
parent 10ad69f1af
commit a0e5e04964
6 changed files with 406 additions and 4 deletions
@@ -0,0 +1,184 @@
+/*
+ * 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
+
+import com.vitorpamplona.quic.tls.InProcessTlsServer
+import kotlinx.coroutines.runBlocking
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+
+/**
+ * Verifies the diagnostic [QuicConnection.flowControlSnapshot] surface:
+ *
+ *   - Before the handshake, peer-TP fields are null and the credit /
+ *     index counters are zero.
+ *   - After the handshake completes against an [InProcessTlsServer]
+ *     advertising specific transport parameters, the snapshot reflects
+ *     exactly those values.
+ *   - Allocating uni / bidi streams advances the local index counters.
+ *   - Enqueueing bytes to a stream's send buffer (without a writer
+ *     drain) shows up as `totalEnqueuedNotSentBytes`.
+ *
+ * Used by `nestsClient/.../SendTraceScenario` to dump the connection's
+ * flow-control state at known points during a sweep run; the cliff
+ * investigation in
+ * `nestsClient/plans/2026-05-01-quic-stream-cliff-investigation.md`
+ * relies on these fields to localise where data piles up.
+ */
+class FlowControlSnapshotTest {
+    @Test
+    fun snapshot_before_handshake_has_null_peer_tps_and_zero_counters() {
+        runBlocking {
+            val client =
+                QuicConnection(
+                    serverName = "example.test",
+                    config = QuicConnectionConfig(),
+                    tlsCertificateValidator =
+                        com.vitorpamplona.quic.tls
+                            .PermissiveCertificateValidator(),
+                )
+            val snap = client.flowControlSnapshot()
+            assertNull(snap.peerInitialMaxData, "no peer TPs before handshake")
+            assertNull(snap.peerInitialMaxStreamDataUni)
+            assertNull(snap.peerInitialMaxStreamsUni)
+            assertEquals(0L, snap.sendConnectionFlowCredit)
+            assertEquals(0L, snap.sendConnectionFlowConsumed)
+            assertEquals(0L, snap.peerMaxStreamsUniCurrent)
+            assertEquals(0L, snap.peerMaxStreamsBidiCurrent)
+            assertEquals(0L, snap.nextLocalUniIndex)
+            assertEquals(0L, snap.nextLocalBidiIndex)
+            assertEquals(0L, snap.totalEnqueuedNotSentBytes)
+            assertEquals(0, snap.streamsWithPendingBytes)
+            assertEquals(0, snap.totalStreamsTracked)
+        }
+    }
+
+    @Test
+    fun snapshot_after_handshake_reflects_peer_transport_parameters() {
+        runBlocking {
+            val client =
+                QuicConnection(
+                    serverName = "example.test",
+                    config = QuicConnectionConfig(),
+                    tlsCertificateValidator =
+                        com.vitorpamplona.quic.tls
+                            .PermissiveCertificateValidator(),
+                )
+            val serverScid = ConnectionId.random(8)
+            val tlsServer =
+                InProcessTlsServer(
+                    transportParameters =
+                        TransportParameters(
+                            initialMaxData = 1_500_000,
+                            initialMaxStreamDataBidiLocal = 200_000,
+                            initialMaxStreamDataBidiRemote = 250_000,
+                            initialMaxStreamDataUni = 300_000,
+                            initialMaxStreamsBidi = 17,
+                            initialMaxStreamsUni = 19,
+                            initialSourceConnectionId = serverScid.bytes,
+                            originalDestinationConnectionId = client.destinationConnectionId.bytes,
+                        ).encode(),
+                )
+            val pipe =
+                InMemoryQuicPipe(
+                    client = client,
+                    initialDcid = client.destinationConnectionId.bytes,
+                    serverScid = serverScid,
+                    tlsServer = tlsServer,
+                )
+            client.start()
+            pipe.drive(maxRounds = 16)
+            assertEquals(QuicConnection.Status.CONNECTED, client.status)
+
+            val snap = client.flowControlSnapshot()
+            assertEquals(1_500_000L, snap.peerInitialMaxData)
+            assertEquals(300_000L, snap.peerInitialMaxStreamDataUni)
+            assertEquals(250_000L, snap.peerInitialMaxStreamDataBidiRemote)
+            assertEquals(19L, snap.peerInitialMaxStreamsUni)
+            assertEquals(17L, snap.peerInitialMaxStreamsBidi)
+            // Initial credit equals the initial cap until inbound MAX_DATA
+            // raises it — no traffic has been sent yet.
+            assertEquals(1_500_000L, snap.sendConnectionFlowCredit)
+            assertEquals(0L, snap.sendConnectionFlowConsumed)
+            assertEquals(19L, snap.peerMaxStreamsUniCurrent)
+            assertEquals(17L, snap.peerMaxStreamsBidiCurrent)
+            assertEquals(0L, snap.nextLocalUniIndex)
+            assertEquals(0L, snap.nextLocalBidiIndex)
+        }
+    }
+
+    @Test
+    fun snapshot_tracks_enqueued_bytes_and_local_stream_indexes() {
+        runBlocking {
+            val client =
+                QuicConnection(
+                    serverName = "example.test",
+                    config = QuicConnectionConfig(),
+                    tlsCertificateValidator =
+                        com.vitorpamplona.quic.tls
+                            .PermissiveCertificateValidator(),
+                )
+            val serverScid = ConnectionId.random(8)
+            val tlsServer =
+                InProcessTlsServer(
+                    transportParameters =
+                        TransportParameters(
+                            initialMaxData = 1_000_000,
+                            initialMaxStreamDataBidiLocal = 100_000,
+                            initialMaxStreamDataBidiRemote = 100_000,
+                            initialMaxStreamDataUni = 100_000,
+                            initialMaxStreamsBidi = 10,
+                            initialMaxStreamsUni = 10,
+                            initialSourceConnectionId = serverScid.bytes,
+                            originalDestinationConnectionId = client.destinationConnectionId.bytes,
+                        ).encode(),
+                )
+            val pipe =
+                InMemoryQuicPipe(
+                    client = client,
+                    initialDcid = client.destinationConnectionId.bytes,
+                    serverScid = serverScid,
+                    tlsServer = tlsServer,
+                )
+            client.start()
+            pipe.drive(maxRounds = 16)
+            assertEquals(QuicConnection.Status.CONNECTED, client.status)
+
+            val s1 = client.openUniStream()
+            val s2 = client.openUniStream()
+            client.openBidiStream()
+            s1.send.enqueue(ByteArray(100))
+            s2.send.enqueue(ByteArray(50))
+
+            val snap = client.flowControlSnapshot()
+            assertEquals(2L, snap.nextLocalUniIndex)
+            assertEquals(1L, snap.nextLocalBidiIndex)
+            assertTrue(
+                snap.totalStreamsTracked >= 3,
+                "3 client-initiated streams should be tracked, saw ${snap.totalStreamsTracked}",
+            )
+            assertEquals(150L, snap.totalEnqueuedNotSentBytes)
+            assertEquals(2, snap.streamsWithPendingBytes)
+        }
+    }
+}