Simpler server list format, document adding servers in CONTRIBUTING

This commit is contained in:
2026-10-14 11:03:35 +00:00
parent 00e30cb858
commit 9ca55a4d40
3 changed files with 58 additions and 45 deletions
+35 -5
View File
@@ -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
@@ -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<DohProvider> 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<List<DohProvider>> = _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<DohProvider> {
val builtInById = Providers.builtIn.associateBy { it.id }
val builtInByHost = Providers.builtIn.associateBy { it.url.toHttpUrlOrNull()?.host }
val seen = HashSet<String>()
val result = ArrayList<DohProvider>()
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 {
+7 -15
View File
@@ -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