Merge pull request #16 from element-hq/kegan/pcap

Add pcap support in settings

Author: kegsay

features/preferences/impl/src/main/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsEvents.kt

@@ -15,4 +15,7 @@ sealed interface DeveloperSettingsEvents {
     data class ChangeBrandColor(val color: Color?) : DeveloperSettingsEvents
     data object ClearCache : DeveloperSettingsEvents
     data object VacuumStores : DeveloperSettingsEvents
+
+    /** Start the federation pcap capture if idle, or stop it if running. */
+    data object ToggleNeutrinoCapture : DeveloperSettingsEvents
 }

features/preferences/impl/src/main/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsPresenter.kt

@@ -31,6 +31,7 @@ import io.element.android.libraries.architecture.runCatchingUpdatingState
 import io.element.android.libraries.core.data.ByteUnit
 import io.element.android.libraries.matrix.api.analytics.GetDatabaseSizesUseCase
 import io.element.android.libraries.matrix.api.core.SessionId
+import io.element.android.services.neutrino.api.CaptureResult
 import io.element.android.services.neutrino.api.NeutrinoService
 import kotlinx.collections.immutable.ImmutableMap
 import kotlinx.collections.immutable.toImmutableMap
@@ -63,6 +64,14 @@ class DeveloperSettingsPresenter(
         var showColorPicker by remember {
             mutableStateOf(false)
         }
+        // Seed the capture toggle from the running server so the switch reflects
+        // reality when the screen (re)opens.
+        var neutrinoCapturing by remember {
+            mutableStateOf(neutrinoService.isCapturing())
+        }
+        var neutrinoCaptureStatus by remember {
+            mutableStateOf<String?>(null)
+        }
         LaunchedEffect(Unit) {
             computeDatabaseSizes(databaseSizes)
         }
@@ -90,6 +99,27 @@ class DeveloperSettingsPresenter(
                 DeveloperSettingsEvents.VacuumStores -> coroutineScope.launch {
                     vacuumStoresUseCase()
                 }
+                DeveloperSettingsEvents.ToggleNeutrinoCapture -> {
+                    if (neutrinoCapturing) {
+                        val path = neutrinoService.stopCapture()
+                        neutrinoCapturing = false
+                        // The service reports the short Downloads location on stop.
+                        neutrinoCaptureStatus = path?.let { "Saved to $it" } ?: "Not capturing"
+                    } else {
+                        when (val result = neutrinoService.startCapture()) {
+                            is CaptureResult.Started -> {
+                                neutrinoCapturing = true
+                                // Don't surface the long working path — the file
+                                // lands in Downloads on stop.
+                                neutrinoCaptureStatus = "Capturing… saved to Downloads on stop"
+                            }
+                            is CaptureResult.Failed -> {
+                                neutrinoCapturing = false
+                                neutrinoCaptureStatus = "Failed: ${result.reason}"
+                            }
+                        }
+                    }
+                }
             }
         }
 
@@ -102,6 +132,8 @@ class DeveloperSettingsPresenter(
             isEnterpriseBuild = enterpriseService.isEnterpriseBuild,
             showColorPicker = showColorPicker,
             neutrinoServerName = neutrinoService.serverName(),
+            neutrinoCapturing = neutrinoCapturing,
+            neutrinoCaptureStatus = neutrinoCaptureStatus,
             eventSink = ::handleEvent,
         )
     }

features/preferences/impl/src/main/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsState.kt

@@ -23,6 +23,12 @@ data class DeveloperSettingsState(
     // The embedded Neutrino homeserver's federation server_name (its node id), or
     // null until the server has started and resolved its identity.
     val neutrinoServerName: String?,
+    // Whether a federation pcap capture is currently running (drives the toggle).
+    val neutrinoCapturing: Boolean,
+    // A human-readable status line for the capture toggle: where it is writing
+    // while on, where the file was saved after stopping, or the failure reason.
+    // Null before the toggle has been used this session.
+    val neutrinoCaptureStatus: String?,
     val eventSink: (DeveloperSettingsEvents) -> Unit
 ) {
     val showLoader = clearCacheAction is AsyncAction.Loading

features/preferences/impl/src/main/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsStateProvider.kt

@@ -31,6 +31,10 @@ open class DeveloperSettingsStateProvider : PreviewParameterProvider<DeveloperSe
                 //  at io.mhssn.colorpicker.pickers.ClassicColorPickerKt$ClassicColorPicker$1$1.invokeSuspend(ClassicColorPicker.kt:53)
                 showColorPicker = false,
             ),
+            aDeveloperSettingsState(
+                neutrinoCapturing = true,
+                neutrinoCaptureStatus = "Capturing… saved to Downloads on stop",
+            ),
         )
 }
 
@@ -40,6 +44,8 @@ fun aDeveloperSettingsState(
     isEnterpriseBuild: Boolean = false,
     showColorPicker: Boolean = false,
     neutrinoServerName: String? = "a1b2c3d4e5f6",
+    neutrinoCapturing: Boolean = false,
+    neutrinoCaptureStatus: String? = null,
     eventSink: (DeveloperSettingsEvents) -> Unit = {},
 ) = DeveloperSettingsState(
     appDeveloperSettingsState = appDeveloperSettingsState,
@@ -49,5 +55,7 @@ fun aDeveloperSettingsState(
     isEnterpriseBuild = isEnterpriseBuild,
     showColorPicker = showColorPicker,
     neutrinoServerName = neutrinoServerName,
+    neutrinoCapturing = neutrinoCapturing,
+    neutrinoCaptureStatus = neutrinoCaptureStatus,
     eventSink = eventSink,
 )

features/preferences/impl/src/main/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsView.kt

@@ -81,6 +81,18 @@ fun DeveloperSettingsView(
                 },
                 onClick = onNeutrinoPeersClick,
             )
+            ListItem(
+                headlineContent = {
+                    Text("Capture federation traffic")
+                },
+                supportingContent = state.neutrinoCaptureStatus?.let { status ->
+                    { Text(status) }
+                },
+                trailingContent = ListItemContent.Switch(
+                    checked = state.neutrinoCapturing,
+                ),
+                onClick = { state.eventSink(DeveloperSettingsEvents.ToggleNeutrinoCapture) },
+            )
         }
 
         if (state.isEnterpriseBuild) {

features/preferences/impl/src/test/kotlin/io/element/android/features/preferences/impl/developer/DeveloperSettingsPresenterTest.kt

@@ -26,6 +26,7 @@ import io.element.android.libraries.matrix.api.analytics.GetDatabaseSizesUseCase
 import io.element.android.libraries.matrix.api.analytics.SdkStoreSizes
 import io.element.android.libraries.matrix.api.core.SessionId
 import io.element.android.libraries.matrix.test.A_SESSION_ID
+import io.element.android.services.neutrino.api.CaptureResult
 import io.element.android.services.neutrino.api.NeutrinoService
 import io.element.android.tests.testutils.WarmUpRule
 import io.element.android.tests.testutils.lambda.lambdaRecorder
@@ -156,6 +157,49 @@ class DeveloperSettingsPresenterTest {
         }
     }
 
+    @Test
+    fun `present - toggling Neutrino capture starts then stops it`() = runTest {
+        val presenter = createDeveloperSettingsPresenter(
+            neutrinoService = FakeNeutrinoService(
+                startCaptureResult = { CaptureResult.Started("/sdcard/neutrino.pcap") },
+                stopCaptureResult = "Download/neutrino-fed.pcap",
+            ),
+        )
+        presenter.test {
+            val initialState = awaitItem()
+            assertThat(initialState.neutrinoCapturing).isFalse()
+            assertThat(initialState.neutrinoCaptureStatus).isNull()
+
+            initialState.eventSink(DeveloperSettingsEvents.ToggleNeutrinoCapture)
+            val capturing = awaitItem()
+            assertThat(capturing.neutrinoCapturing).isTrue()
+            assertThat(capturing.neutrinoCaptureStatus).isEqualTo("Capturing… saved to Downloads on stop")
+
+            capturing.eventSink(DeveloperSettingsEvents.ToggleNeutrinoCapture)
+            val stopped = awaitItem()
+            assertThat(stopped.neutrinoCapturing).isFalse()
+            assertThat(stopped.neutrinoCaptureStatus).isEqualTo("Saved to Download/neutrino-fed.pcap")
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+
+    @Test
+    fun `present - a failed capture start surfaces the reason`() = runTest {
+        val presenter = createDeveloperSettingsPresenter(
+            neutrinoService = FakeNeutrinoService(
+                startCaptureResult = { CaptureResult.Failed("permission denied") },
+            ),
+        )
+        presenter.test {
+            val initialState = awaitItem()
+            initialState.eventSink(DeveloperSettingsEvents.ToggleNeutrinoCapture)
+            val failed = awaitItem()
+            assertThat(failed.neutrinoCapturing).isFalse()
+            assertThat(failed.neutrinoCaptureStatus).isEqualTo("Failed: permission denied")
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+
     private fun createDeveloperSettingsPresenter(
         sessionId: SessionId = A_SESSION_ID,
         cacheSizeUseCase: FakeComputeCacheSizeUseCase = FakeComputeCacheSizeUseCase(),

features/preferences/impl/src/test/kotlin/io/element/android/features/preferences/impl/developer/FakeNeutrinoService.kt

@@ -7,13 +7,20 @@
 
 package io.element.android.features.preferences.impl.developer
 
+import io.element.android.services.neutrino.api.CaptureResult
 import io.element.android.services.neutrino.api.DiscoveredPeer
 import io.element.android.services.neutrino.api.NeutrinoService
 
 class FakeNeutrinoService(
     private val serverNameResult: String? = "a1b2c3d4",
     private val discoveredPeersResult: () -> List<DiscoveredPeer> = { emptyList() },
+    private val startCaptureResult: () -> CaptureResult = { CaptureResult.Started(A_CAPTURE_PATH) },
+    // The location stopCapture reports (the real service copies to Downloads, so
+    // this need not match the started path).
+    private val stopCaptureResult: String? = "Download/$A_CAPTURE_NAME",
 ) : NeutrinoService {
+    private var capturing = false
+
     override fun start() = Unit
 
     override suspend fun awaitReady(timeoutMs: Long) = Unit
@@ -23,4 +30,21 @@ class FakeNeutrinoService(
     override fun serverName(): String? = serverNameResult
 
     override fun discoveredPeers(): List<DiscoveredPeer> = discoveredPeersResult()
+
+    override fun startCapture(): CaptureResult = startCaptureResult().also { result ->
+        if (result is CaptureResult.Started) {
+            capturing = true
+        }
+    }
+
+    override fun stopCapture(): String? {
+        if (!capturing) return null
+        capturing = false
+        return stopCaptureResult
+    }
+
+    override fun isCapturing(): Boolean = capturing
 }
+
+private const val A_CAPTURE_NAME = "neutrino-fed.pcap"
+private const val A_CAPTURE_PATH = "/storage/emulated/0/Android/data/pkg/files/$A_CAPTURE_NAME"

gradle/libs.versions.toml

@@ -66,7 +66,7 @@ androidx-test-ext-junit = "1.3.0"
 kover = "0.9.8"
 
 # Neutrino
-neutrino = "0.6.1"
+neutrino = "0.6.3"
 
 [libraries]
 # Project

services/neutrino/api/src/main/kotlin/io/element/android/services/neutrino/api/CaptureResult.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.services.neutrino.api
+
+/**
+ * Outcome of arming a federation pcap capture (see [NeutrinoService.startCapture]).
+ */
+sealed interface CaptureResult {
+    /** Capture is running, writing to [filePath] (an absolute, adb-pullable path). */
+    data class Started(val filePath: String) : CaptureResult
+
+    /** Capture could not be started; [reason] is a human-readable explanation. */
+    data class Failed(val reason: String) : CaptureResult
+}

services/neutrino/api/src/main/kotlin/io/element/android/services/neutrino/api/NeutrinoService.kt

@@ -47,4 +47,25 @@ interface NeutrinoService {
      * server has started.
      */
     fun discoveredPeers(): List<DiscoveredPeer>
+
+    /**
+     * Start mirroring federation datagrams into a Wireshark-readable pcap file in
+     * host-owned external storage (so it can be pulled with `adb pull` without
+     * root). The service owns the path. Re-arming while already capturing rotates
+     * to a fresh file. Returns where it is writing, or why it could not start.
+     */
+    fun startCapture(): CaptureResult
+
+    /**
+     * Stop capturing and flush + close the file, which is ready to `adb pull` the
+     * moment this returns. Returns the finalized file path, or `null` if no
+     * capture was running.
+     */
+    fun stopCapture(): String?
+
+    /**
+     * Whether a federation pcap capture is currently running. Drives the toggle
+     * state in developer settings.
+     */
+    fun isCapturing(): Boolean
 }