From 9ca55a4d4061ff54c15933539d4ed670fdd0c078 Mon Sep 17 00:00:00 2001 From: kalarina Date: Wed, 14 Oct 2026 11:03:35 +0000 Subject: [PATCH] Simpler server list format, document adding servers in CONTRIBUTING --- CONTRIBUTING.md | 40 +++++++++++++++--- .../cc/skysparkle/sparkledns/Providers.kt | 41 ++++++++----------- servers/servers.txt | 22 ++++------ 3 files changed, 58 insertions(+), 45 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 520c17d..222d994 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,8 @@ Issues and pull requests go to the repository on [Gitea](https://git.skysparkle. ## Ways to help - **Report a bug** — use the *Bug report* template. -- **Suggest a DoH server or blocklist** — use the *DoH server or blocklist* template. +- **Add a DoH server** — add one line to [`servers/servers.txt`](servers/servers.txt), see [Adding a DoH server](#adding-a-doh-server). +- **Suggest a blocklist** — use the *DoH server or blocklist* template. - **Suggest a feature** — use the *Feature request* template; check [Out of scope](#out-of-scope) first. - **Fix a translation** — use the *Translation fix* template or send a pull request. - **Write code** — see [Pull requests](#pull-requests). @@ -35,12 +36,41 @@ These will not be accepted: - Logging, uploading or sharing users' DNS queries. - Features that require Google Play Services or a proprietary SDK. -## DoH servers and blocklists +## Adding a DoH server -- **DoH servers** must be public, support RFC 8484 and publish a privacy policy. -- **Blocklists** must be public, actively maintained and licensed for this kind of use. +The server list lives in [`servers/servers.txt`](servers/servers.txt). The app downloads it when the user taps **Update server list**, so a new server reaches users without a new release. -Include links to the server's documentation or the list's homepage in the request. +To add a server, open the file on Gitea, click **Edit**, add one line at the end and send it as a pull request: + +``` +Name | DoH URL | Privacy policy | h3 +``` + +- **Name** — how the server appears in the app, up to 40 characters. +- **DoH URL** — the full `https://` address of the DoH endpoint. +- **Privacy policy** — an `https://` link to the operator's privacy policy. Lines without one are ignored. +- **h3** — optional. Add it only if the server supports HTTP/3. + +Example: + +``` +Example DNS | https://dns.example.org/dns-query | https://example.org/privacy | h3 +``` + +The server must: + +- be public and free, without an account; +- support RFC 8484; +- publish what it logs, and not sell or share query data; +- be run by a non-profit, a community or an individual rather than a large company. + +Before sending, check that it works: in the app choose **Custom server**, enter the URL and tap **Test server**. + +Please don't change the lines of the servers that ship with the app (SkySparkle, Quad9, Digitale Gesellschaft, UncensoredDNS, Freifunk München): the app always keeps their built-in addresses. If you are unsure whether a server fits, open an issue with the *DoH server or blocklist* template instead. + +## Blocklists + +Blocklist presets must be public, actively maintained and licensed for this kind of use. Use the *DoH server or blocklist* template and include a link to the list's homepage. ## Translations diff --git a/app/src/main/java/cc/skysparkle/sparkledns/Providers.kt b/app/src/main/java/cc/skysparkle/sparkledns/Providers.kt index 5097d28..883c9e8 100644 --- a/app/src/main/java/cc/skysparkle/sparkledns/Providers.kt +++ b/app/src/main/java/cc/skysparkle/sparkledns/Providers.kt @@ -21,6 +21,7 @@ data class DohProvider( object Providers { const val CUSTOM_ID = "custom" + const val DEFAULT_ID = "skysparkle" // Shipped with the app and used until the list from the repository is downloaded val builtIn = listOf( @@ -50,7 +51,8 @@ object Providers { val list: List get() = ServerList.servers.value - val default: DohProvider get() = list.first() + // The project's own server stays the default whatever order the list uses + val default: DohProvider get() = list.firstOrNull { it.id == DEFAULT_ID } ?: list.first() fun byId(id: String): DohProvider = list.firstOrNull { it.id == id } ?: default } @@ -61,7 +63,6 @@ object ServerList { private const val FILE = "servers.txt" private const val MAX_BYTES = 64 * 1024 private const val MAX_SERVERS = 50 - private val ID = Regex("[a-z0-9][a-z0-9_-]{0,31}") private val _servers = MutableStateFlow(Providers.builtIn) val servers: StateFlow> = _servers @@ -110,9 +111,9 @@ object ServerList { return parsed.size } - // Format per line: id | name | DoH URL | bootstrap IPs | h3 | privacy policy URL + // Format per line: Name | DoH URL | privacy policy URL | h3 (optional). See CONTRIBUTING.md. fun parse(text: String): List { - val builtInById = Providers.builtIn.associateBy { it.id } + val builtInByHost = Providers.builtIn.associateBy { it.url.toHttpUrlOrNull()?.host } val seen = HashSet() val result = ArrayList() for (raw in text.lineSequence()) { @@ -120,31 +121,21 @@ object ServerList { if (line.isEmpty() || line.startsWith("#")) continue val cols = line.split('|').map { it.trim() } if (cols.size < 3) continue - val id = cols[0].lowercase() - if (!ID.matches(id) || id == Providers.CUSTOM_ID || !seen.add(id)) continue - // Shipped servers keep their address, so an edited list cannot redirect them - val pinned = builtInById[id] - if (pinned != null) { - result += pinned - } else { - val name = cols[1].take(40) - val url = cols[2] - if (name.isEmpty() || url.toHttpUrlOrNull()?.isHttps != true) continue - val bootstrap = parseIps(cols.getOrElse(3) { "" }).filter(::isIpLiteral) - val http3 = cols.getOrElse(4) { "" }.equals("h3", ignoreCase = true) - val policy = cols.getOrElse(5) { "" }.takeIf { it.toHttpUrlOrNull()?.isHttps == true } - result += DohProvider(id, name, url, bootstrap, http3, policy) - } + val name = cols[0].take(40) + val url = cols[1].toHttpUrlOrNull() + val policy = cols[2].takeIf { it.toHttpUrlOrNull()?.isHttps == true } + if (name.isEmpty() || url == null || !url.isHttps) continue + // Shipped servers keep their address and id, so an edited list cannot redirect them + val pinned = builtInByHost[url.host] + val server = pinned + ?: if (policy == null) continue + else DohProvider(url.host, name, cols[1], http3 = cols.getOrElse(3) { "" }.equals("h3", ignoreCase = true), policy = policy) + if (!seen.add(server.id)) continue + result += server if (result.size >= MAX_SERVERS) break } return result } - - private val IPV4 = Regex("\\d{1,3}(\\.\\d{1,3}){3}") - private val IPV6 = Regex("[0-9a-fA-F:.]+") - - private fun isIpLiteral(value: String): Boolean = - IPV4.matches(value) || (value.contains(':') && IPV6.matches(value)) } private fun java.io.InputStream.readNBytesCompat(limit: Int): ByteArray { diff --git a/servers/servers.txt b/servers/servers.txt index 35a05d8..45fff86 100644 --- a/servers/servers.txt +++ b/servers/servers.txt @@ -1,16 +1,8 @@ -# SparkleDNS server list -# The app downloads this file when you tap "Update server list". -# -# Format: id | name | DoH URL | bootstrap IPs | h3 | privacy policy URL -# - id: lowercase letters, digits, - or _. Never change it: the app remembers the chosen server by id. -# - DoH URL and privacy policy must use https:// -# - bootstrap IPs: optional, comma-separated -# - h3: write h3 only if the server supports HTTP/3 -# Servers that ship with the app (skysparkle, quad9, digitale-gesellschaft, uncensoreddns, ffmuc) -# always keep their built-in address, so editing their URL here has no effect. +# SparkleDNS server list. How to add a server: see CONTRIBUTING.md +# Name | DoH URL | Privacy policy | h3 (optional) -skysparkle | SkySparkle | https://blog.skysparkle.cc/dns-query | | h3 | https://skysparkle.cc/privacy?lang=en -quad9 | Quad9 | https://dns.quad9.net/dns-query | 9.9.9.9, 149.112.112.112 | | https://quad9.net/service/privacy/ -digitale-gesellschaft | Digitale Gesellschaft | https://dns.digitale-gesellschaft.ch/dns-query | 185.95.218.42, 185.95.218.43 | h3 | https://www.digitale-gesellschaft.ch/dns/ -uncensoreddns | UncensoredDNS | https://anycast.uncensoreddns.org/dns-query | 91.239.100.100 | | https://blog.uncensoreddns.org/faq/ -ffmuc | Freifunk München | https://doh.ffmuc.net/dns-query | 5.1.66.255, 185.150.99.255 | h3 | https://ffmuc.net/dns-privacy/ +SkySparkle | https://blog.skysparkle.cc/dns-query | https://skysparkle.cc/privacy?lang=en | h3 +Quad9 | https://dns.quad9.net/dns-query | https://quad9.net/service/privacy/ +Digitale Gesellschaft | https://dns.digitale-gesellschaft.ch/dns-query | https://www.digitale-gesellschaft.ch/dns/ | h3 +UncensoredDNS | https://anycast.uncensoreddns.org/dns-query | https://blog.uncensoreddns.org/faq/ +Freifunk München | https://doh.ffmuc.net/dns-query | https://ffmuc.net/dns-privacy/ | h3