IP Blocklist

Fetch, parse, and apply a P2P-format blocklist to the engine's peer filter.

Mosaic can drop peer connections from IPs in a remote blocklist. The classic use case is the emule.nl-style P2P blocklists used historically by the BitTorrent ecosystem, but any source that produces the standard ranges format will work.

What it is

The blocklist is a single URL, fetched on demand. There is no multi-source layering: configure one URL, refresh when you want, or set enabled: false to clear the filter without forgetting the URL.

DTO

{
  url: string;
  enabled: boolean;
  last_loaded_at: number;  // unix seconds, 0 if never
  entries: number;         // line count of the last fetch (rough size signal)
  error?: string;          // last fetch's error string, if any
}

Format

The fetcher accepts the historical “P2P” range format and feeds the bytes to anacrolix’s IP-blocklist parser. Each line is roughly:

Description:1.2.3.4-1.2.3.255

Comments (# lines) and blank lines are ignored.

Fetch model

When you set the URL with enabled: true, or call POST /api/settings/blocklist/refresh:

  1. URL is re-validated against validateFetchURL (http/https only, no private/loopback addresses).
  2. safeHTTPClient GETs the URL with a 30-second timeout.
  3. Body is read into memory with a 50 MiB cap — anything past that is truncated.
  4. Bytes are passed to engine.SetIPBlocklist, which builds the in-memory filter.
  5. BlocklistDTO.last_loaded_at is updated; on error, error is populated and last_loaded_at is left as is.

The 50 MB cap is generous for real-world blocklists — typical lists are 5–20 MB. If your source is bigger, you’ve probably got the wrong format.

Operations

Action Endpoint
Get current state GET /api/settings/blocklist
Set URL + toggle PUT /api/settings/blocklist
Manual refresh POST /api/settings/blocklist/refresh 
curl -k -X PUT https://localhost:8080/api/settings/blocklist \
  -H "Authorization: Bearer $MOSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/lists/level1.p2p","enabled":true}'

# Force a re-fetch
curl -k -X POST https://localhost:8080/api/settings/blocklist/refresh \
  -H "Authorization: Bearer $MOSAIC_API_KEY"

Caveats

  • No periodic auto-refresh. Blocklist refresh is manual or on enable. Re-fetch on a cron via the API if you want it automated.
  • No multi-source merging. One URL.
  • Privacy shouldn’t depend on it. A blocklist is at best heuristic; treat it as a coarse filter, not a security boundary.
  • SSRF-guarded. The URL must be public — Mosaic refuses to dial private/loopback addresses. If you serve a blocklist from a self-hosted server, expose it through your normal LAN/public hostname, not 127.0.0.1.