Add structured resolver scan results

Parse optional scan telemetry such as latency, attempts, and rejection reason while keeping older WD_SCAN lines compatible.

Persist structured scan observations beside the legacy plain resolver file, rank successful results by score, and write recommended_resolvers.txt for future profile selection and diagnostics.

Add focused tests for scan telemetry enrichment, resolver scoring, ranking, and JSON serialization.

Author: AmirrezaFarnamTaheri

app/src/main/java/shop/whitedns/client/scan/ResolverScanResult.kt

@@ -0,0 +1,95 @@
+package shop.whitedns.client.scan
+
+import org.json.JSONObject
+
+object ResolverScanResultStatus {
+    const val Valid = "valid"
+    const val Rejected = "rejected"
+}
+
+data class ResolverScanResult(
+    val resolver: String,
+    val status: String,
+    val sourceName: String = "",
+    val serverDomain: String = "",
+    val latencyMillis: Int? = null,
+    val attempts: Int? = null,
+    val reason: String = "",
+    val observedAtMillis: Long = 0L,
+) {
+    val isValid: Boolean
+        get() = status == ResolverScanResultStatus.Valid
+
+    val score: Int
+        get() = resolverScanScore(this)
+}
+
+fun resolverScanScore(result: ResolverScanResult): Int {
+    if (!result.isValid) {
+        return 0
+    }
+    val latencyPenalty = when (val latency = result.latencyMillis) {
+        null -> 12
+        else -> (latency / 25).coerceIn(0, 48)
+    }
+    val attemptPenalty = ((result.attempts ?: 1) - 1).coerceAtLeast(0) * 6
+    val confidenceBonus = when {
+        result.latencyMillis != null && result.attempts != null -> 18
+        result.latencyMillis != null -> 12
+        result.attempts != null -> 6
+        else -> 0
+    }
+    return (100 + confidenceBonus - latencyPenalty - attemptPenalty).coerceIn(1, 100)
+}
+
+fun rankResolverScanResults(results: Iterable<ResolverScanResult>): List<ResolverScanResult> {
+    return results
+        .filter { it.isValid && it.resolver.isNotBlank() }
+        .groupBy { it.resolver }
+        .values
+        .map { resolverResults ->
+            resolverResults.maxWith(
+                compareBy<ResolverScanResult> { it.score }
+                    .thenByDescending { it.observedAtMillis },
+            )
+        }
+        .sortedWith(
+            compareByDescending<ResolverScanResult> { it.score }
+                .thenBy { it.latencyMillis ?: Int.MAX_VALUE }
+                .thenByDescending { it.observedAtMillis }
+                .thenBy { it.resolver },
+        )
+}
+
+fun ResolverScanResult.toJsonObject(): JSONObject {
+    return JSONObject()
+        .put("resolver", resolver)
+        .put("status", status)
+        .put("sourceName", sourceName)
+        .put("serverDomain", serverDomain)
+        .put("latencyMillis", latencyMillis)
+        .put("attempts", attempts)
+        .put("reason", reason)
+        .put("observedAtMillis", observedAtMillis)
+        .put("score", score)
+}
+
+fun resolverScanResultFromJson(json: JSONObject): ResolverScanResult {
+    return ResolverScanResult(
+        resolver = json.optString("resolver"),
+        status = json.optString("status"),
+        sourceName = json.optString("sourceName"),
+        serverDomain = json.optString("serverDomain"),
+        latencyMillis = json.optionalPositiveInt("latencyMillis"),
+        attempts = json.optionalPositiveInt("attempts"),
+        reason = json.optString("reason"),
+        observedAtMillis = json.optLong("observedAtMillis", 0L),
+    )
+}
+
+private fun JSONObject.optionalPositiveInt(name: String): Int? {
+    if (!has(name) || isNull(name)) {
+        return null
+    }
+    return optInt(name).takeIf { it > 0 }
+}

app/src/main/java/shop/whitedns/client/scan/StormDnsScanTelemetry.kt

@@ -1,8 +1,19 @@
 package shop.whitedns.client.scan
 
 sealed class StormDnsScanTelemetry {
-    data class Valid(val resolver: String) : StormDnsScanTelemetry()
-    data class Rejected(val resolver: String) : StormDnsScanTelemetry()
+    data class Valid(
+        val resolver: String,
+        val latencyMillis: Int? = null,
+        val attempts: Int? = null,
+    ) : StormDnsScanTelemetry()
+
+    data class Rejected(
+        val resolver: String,
+        val reason: String = "",
+        val latencyMillis: Int? = null,
+        val attempts: Int? = null,
+    ) : StormDnsScanTelemetry()
+
     data class Complete(
         val total: Int,
         val valid: Int,
@@ -24,10 +35,23 @@ fun parseStormDnsScanLine(line: String): StormDnsScanTelemetry? {
     return when (fields["event"]) {
         "valid" -> fields["resolver"]
             ?.takeIf(String::isNotBlank)
-            ?.let(StormDnsScanTelemetry::Valid)
+            ?.let { resolver ->
+                StormDnsScanTelemetry.Valid(
+                    resolver = resolver,
+                    latencyMillis = fields.optionalPositiveInt("latency_ms", "latency"),
+                    attempts = fields.optionalPositiveInt("attempts"),
+                )
+            }
         "rejected" -> fields["resolver"]
             ?.takeIf(String::isNotBlank)
-            ?.let(StormDnsScanTelemetry::Rejected)
+            ?.let { resolver ->
+                StormDnsScanTelemetry.Rejected(
+                    resolver = resolver,
+                    reason = fields["reason"].orEmpty(),
+                    latencyMillis = fields.optionalPositiveInt("latency_ms", "latency"),
+                    attempts = fields.optionalPositiveInt("attempts"),
+                )
+            }
         "complete" -> StormDnsScanTelemetry.Complete(
             total = fields["total"].toIntOrZero(),
             valid = fields["valid"].toIntOrZero(),
@@ -41,6 +65,12 @@ private fun String?.toIntOrZero(): Int {
     return this?.toIntOrNull() ?: 0
 }
 
+private fun Map<String, String>.optionalPositiveInt(vararg names: String): Int? {
+    return names.firstNotNullOfOrNull { name ->
+        this[name]?.toIntOrNull()?.takeIf { it > 0 }
+    }
+}
+
 private const val ScanMarker = "WD_SCAN"
 private val ScanFieldRegex = Regex("""(\w+)=([^\s]+)""")
 private val AnsiEscapeRegex = Regex("${27.toChar()}\\[[;?0-9]*[ -/]*[@-~]")

app/src/main/java/shop/whitedns/client/scan/WhiteDnsScanService.kt

@@ -242,6 +242,8 @@ class WhiteDnsScanService : Service() {
                             workerStats = workerStats,
                             validResolvers = validResolvers,
                             rejectedResolvers = rejectedResolvers,
+                            resultSourceName = sourceName,
+                            resultServerDomain = serverProfile.domain,
                             stateLock = stateLock,
                             publishAggregate = ::publishAggregate,
                         )
@@ -295,6 +297,8 @@ class WhiteDnsScanService : Service() {
         workerStats: Array<WorkerScanStats>,
         validResolvers: MutableSet<String>,
         rejectedResolvers: MutableSet<String>,
+        resultSourceName: String,
+        resultServerDomain: String,
         stateLock: Any,
         publishAggregate: (String, String, Boolean) -> Unit,
     ) {
@@ -325,6 +329,18 @@ class WhiteDnsScanService : Service() {
                 if (added) {
                     WhiteDnsScannerResultStore.appendValidResolvers(applicationContext, listOf(resolver))
                 }
+                WhiteDnsScannerResultStore.appendStructuredResult(
+                    applicationContext,
+                    ResolverScanResult(
+                        resolver = resolver,
+                        status = ResolverScanResultStatus.Valid,
+                        sourceName = resultSourceName,
+                        serverDomain = resultServerDomain,
+                        latencyMillis = telemetry.latencyMillis,
+                        attempts = telemetry.attempts,
+                        observedAtMillis = System.currentTimeMillis(),
+                    ),
+                )
                 publishAggregate(WhiteDnsScanStatus.Running, "Found $validCount valid resolvers", false)
             }
             is StormDnsScanTelemetry.Rejected -> {
@@ -334,6 +350,19 @@ class WhiteDnsScanService : Service() {
                         rejectedResolvers += resolver
                     }
                 }
+                WhiteDnsScannerResultStore.appendStructuredResult(
+                    applicationContext,
+                    ResolverScanResult(
+                        resolver = resolver,
+                        status = ResolverScanResultStatus.Rejected,
+                        sourceName = resultSourceName,
+                        serverDomain = resultServerDomain,
+                        latencyMillis = telemetry.latencyMillis,
+                        attempts = telemetry.attempts,
+                        reason = telemetry.reason,
+                        observedAtMillis = System.currentTimeMillis(),
+                    ),
+                )
                 publishAggregate(WhiteDnsScanStatus.Running, "Scanning", false)
             }
             is StormDnsScanTelemetry.Complete -> {
@@ -546,6 +575,11 @@ class WhiteDnsScanService : Service() {
             state.validResolverEntries.joinToString(separator = "\n"),
             Charsets.UTF_8,
         )
+        File(resultsDir, "recommended_resolvers.txt").writeText(
+            WhiteDnsScannerResultStore.readRecommendedResolvers(applicationContext)
+                .joinToString(separator = "\n"),
+            Charsets.UTF_8,
+        )
         File(resultsDir, "rejected_resolvers.txt").writeText(
             state.rejectedResolverEntries.joinToString(separator = "\n"),
             Charsets.UTF_8,

app/src/main/java/shop/whitedns/client/scan/WhiteDnsScannerResultStore.kt

@@ -5,11 +5,13 @@ import android.util.AtomicFile
 import java.io.File
 import java.io.FileOutputStream
 import java.io.IOException
+import org.json.JSONObject
 import shop.whitedns.client.model.ResolverTextValidation
 import shop.whitedns.client.model.validateResolverText
 
 object WhiteDnsScannerResultStore {
     const val ResultFileName = "Scanner result"
+    const val StructuredResultFileName = "scanner_results.jsonl"
     private val ResultFileLock = Any()
 
     fun resultFile(context: Context): File {
@@ -20,6 +22,29 @@ object WhiteDnsScannerResultStore {
         return readValidResolverSet(context).toList()
     }
 
+    fun readRecommendedResolvers(context: Context, limit: Int = 64): List<String> {
+        val structuredResults = readStructuredResults(context)
+        if (structuredResults.isEmpty()) {
+            return readValidResolvers(context).take(limit)
+        }
+        return rankResolverScanResults(structuredResults)
+            .map { it.resolver }
+            .take(limit.coerceAtLeast(1))
+    }
+
+    fun readStructuredResults(context: Context): List<ResolverScanResult> {
+        return runCatching {
+            val file = structuredResultFile(context)
+            if (!file.isFile) {
+                emptyList()
+            } else {
+                file.bufferedReader(Charsets.UTF_8).useLines { lines ->
+                    lines.mapNotNull(::decodeStructuredResultLine).toList()
+                }
+            }
+        }.getOrDefault(emptyList())
+    }
+
     fun readValidResolverSet(context: Context): Set<String> {
         return runCatching {
             val file = resultFile(context)
@@ -61,6 +86,21 @@ object WhiteDnsScannerResultStore {
         }
     }
 
+    fun appendStructuredResult(context: Context, result: ResolverScanResult) {
+        val normalizedResolver = normalizeResolverEntry(result.resolver) ?: return
+        val normalizedResult = result.copy(resolver = normalizedResolver)
+        synchronized(ResultFileLock) {
+            val target = structuredResultFile(context)
+            target.parentFile?.mkdirs()
+            FileOutputStream(target, true).use { stream ->
+                if (target.length() > 0L) {
+                    stream.write("\n".toByteArray(Charsets.UTF_8))
+                }
+                stream.write(normalizedResult.toJsonObject().toString().toByteArray(Charsets.UTF_8))
+            }
+        }
+    }
+
     fun normalizeResolverText(rawText: String): List<String> {
         return normalizeScanResolverText(rawText).normalizedResolvers
     }
@@ -243,6 +283,20 @@ object WhiteDnsScannerResultStore {
         return File(File(context.noBackupFilesDir, "stormdns"), "scan")
     }
 
+    private fun structuredResultFile(context: Context): File {
+        return File(resultDirectory(context), StructuredResultFileName)
+    }
+
+    private fun decodeStructuredResultLine(line: String): ResolverScanResult? {
+        val trimmed = line.trim()
+        if (trimmed.isBlank()) {
+            return null
+        }
+        return runCatching {
+            resolverScanResultFromJson(JSONObject(trimmed))
+        }.getOrNull()
+    }
+
     private fun stripScanResolverPort(resolver: String): String {
         val text = resolver.trim()
         val bracketedMatch = BracketedResolverPortRegex.matchEntire(text)

app/src/test/java/shop/whitedns/client/scan/ResolverScanResultTest.kt

@@ -0,0 +1,78 @@
+package shop.whitedns.client.scan
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ResolverScanResultTest {
+    @Test
+    fun rankResolverScanResultsPrefersLowLatencySuccessfulResults() {
+        val ranked = rankResolverScanResults(
+            listOf(
+                ResolverScanResult(
+                    resolver = "8.8.8.8",
+                    status = ResolverScanResultStatus.Valid,
+                    latencyMillis = 240,
+                    attempts = 2,
+                    observedAtMillis = 10L,
+                ),
+                ResolverScanResult(
+                    resolver = "1.1.1.1",
+                    status = ResolverScanResultStatus.Valid,
+                    latencyMillis = 80,
+                    attempts = 1,
+                    observedAtMillis = 20L,
+                ),
+                ResolverScanResult(
+                    resolver = "9.9.9.9",
+                    status = ResolverScanResultStatus.Rejected,
+                    reason = "timeout",
+                    observedAtMillis = 30L,
+                ),
+            ),
+        )
+
+        assertEquals(listOf("1.1.1.1", "8.8.8.8"), ranked.map { it.resolver })
+        assertTrue(ranked.first().score > ranked.last().score)
+    }
+
+    @Test
+    fun rankResolverScanResultsKeepsBestObservationPerResolver() {
+        val ranked = rankResolverScanResults(
+            listOf(
+                ResolverScanResult(
+                    resolver = "1.1.1.1",
+                    status = ResolverScanResultStatus.Valid,
+                    latencyMillis = 200,
+                    attempts = 2,
+                    observedAtMillis = 10L,
+                ),
+                ResolverScanResult(
+                    resolver = "1.1.1.1",
+                    status = ResolverScanResultStatus.Valid,
+                    latencyMillis = 70,
+                    attempts = 1,
+                    observedAtMillis = 20L,
+                ),
+            ),
+        )
+
+        assertEquals(1, ranked.size)
+        assertEquals(70, ranked.first().latencyMillis)
+    }
+
+    @Test
+    fun resolverScanResultRoundTripsJson() {
+        val result = ResolverScanResult(
+            resolver = "1.1.1.1",
+            status = ResolverScanResultStatus.Valid,
+            sourceName = "Default list",
+            serverDomain = "server.example.com",
+            latencyMillis = 90,
+            attempts = 1,
+            observedAtMillis = 42L,
+        )
+
+        assertEquals(result, resolverScanResultFromJson(result.toJsonObject()))
+    }
+}