[Feature] Neues Modul ipinfo – self-hosted IP/Country/ASN-Lookup ohne MaxMind #17

New Issue

2026-07-21T06:42:36Z

ilvoen commented

2026-07-21 06:42:36 +00:00

Motivation

Aktuell nutze ich für IP-Geolocation (Land, ASN) externe/dritte Lösungen (z.B. ipinfo.tw-Image). Das bedeutet ein zusätzlicher Container, eine zusätzliche Abhängigkeit und MaxMind als Datenquelle (Account, Lizenzbedingungen). Da varde bereits als modularer Hub für genau solche kleinen self-hosted Dienste gedacht ist (WKD, Webhook, …), passt ein IP-Info-Modul konzeptionell besser dorthin als ein separater Container.

Proposal

Ein neues Module in varde, das über HTTP die anfragende Client-IP sowie deren Land und ASN zurückgibt – ohne MaxMind, auf Basis offener, lizenzfreier Datensätze.

Alternatives Considered

Datenquelle

Country: sapics/ip-location-db, user-country-ipv4.csv / -ipv6.csv (Public Domain, kein Attribution-Zwang, GitHub-Releases)
ASN + AS-Name: gleiche Quelle, asn bzw. origin-asn Datensatz
Format: start_ip,end_ip,... – sortierte, nicht überlappende Ranges

Funktionale Anforderungen

Lookup-Engine
- Sortierte In-Memory-Struktur pro Datensatz (Country, ASN), Suche via sort.Search (Binärsuche) auf Start-IP
- Separate Behandlung IPv4 (uint32) / IPv6 (netip.Addr-Vergleich)
- Ladezeit und Speicherbedarf beim Start loggen (Erwartung: < 1s Ladezeit, niedriger zweistelliger MB-Bereich RAM)
HTTP-Endpoints (Namensgebung analog ipinfo.tw, damit bestehende Clients/Skripte kompatibel bleiben)
- GET /ip → Client-IP als Plaintext
- GET /country, /country_code, /country_name
- GET /as, /asn, /as_desc
- GET /json → alle Felder als JSON
- GET / → Plaintext-Kurzübersicht (IP, Land, AS, User-Agent)
Client-IP-Ermittlung
- IP primär aus X-Real-IP-Header (von Traefik gesetzt), Fallback auf RemoteAddr
- Kein Trust von X-Forwarded-For ohne expliziten Trusted-Proxy-Check (Spoofing-Schutz)
Datenaktualisierung
- Periodischer Refresh (Cron, z.B. täglich) analog zum bestehenden Webhook-Modul-Pattern
- Download + Parse in Hintergrund-Goroutine, danach atomarer Swap der Lookup-Struktur (atomic.Pointer) – kein Neustart, keine Downtime während Refresh
- Fehler beim Refresh (Netzwerk, Parse-Fehler) dürfen die laufende, alte Struktur nicht invalidieren – nur loggen und alten Stand behalten
Konfiguration
- Modul optional aktivierbar (Model-B-Pattern, Module-Interface)
- Konfigurierbar: Refresh-Intervall, Pfad/URL der Datenquellen, ggf. lokaler Cache-Pfad für die Rohdaten (Neustart ohne Re-Download)

Nicht-Ziele (out of scope, v1)

Keine City-/Lat-Long-Auflösung (nur Country + ASN)
Keine eigene BGP-Feed-Auswertung, nur die aufbereiteten CSV-Releases
Kein Rate-Limiting speziell für dieses Modul (nutzt vardes globales Rate-Limiting, falls vorhanden)

Offene Fragen

Refresh-Intervall: reicht täglich, oder soll es an bestehenden Cron/Systemd-Timer gekoppelt werden?
Sollen Country- und ASN-Datensatz unabhängig voneinander deaktivierbar sein (z.B. nur Country, kein ASN)?
Soll /build_epoch-Äquivalent (Timestamp der geladenen Daten) mit ausgeliefert werden, um Monitoring zu ermöglichen?

Akzeptanzkriterien

Modul lädt Datensätze beim Start und stellt alle o.g. Endpoints bereit
Ergebnis für bekannte Test-IPs (z.B. eigene öffentliche IP, Google DNS 8.8.8.8) stimmt mit Referenz (ipinfo.tw oder whois) überein
Refresh läuft ohne Downtime/Requests-Fehler während des Swaps
Fallback auf RemoteAddr funktioniert, wenn X-Real-IP fehlt
Speicher- und Startzeit-Overhead dokumentiert (README-Eintrag)

### Motivation Aktuell nutze ich für IP-Geolocation (Land, ASN) externe/dritte Lösungen (z.B. ipinfo.tw-Image). Das bedeutet ein zusätzlicher Container, eine zusätzliche Abhängigkeit und MaxMind als Datenquelle (Account, Lizenzbedingungen). Da varde bereits als modularer Hub für genau solche kleinen self-hosted Dienste gedacht ist (WKD, Webhook, …), passt ein IP-Info-Modul konzeptionell besser dorthin als ein separater Container. ### Proposal Ein neues Module in varde, das über HTTP die anfragende Client-IP sowie deren Land und ASN zurückgibt – ohne MaxMind, auf Basis offener, lizenzfreier Datensätze. ### Alternatives Considered ## Datenquelle - **Country:** [sapics/ip-location-db](https://github.com/sapics/ip-location-db), `user-country-ipv4.csv` / `-ipv6.csv` (Public Domain, kein Attribution-Zwang, GitHub-Releases) - **ASN + AS-Name:** gleiche Quelle, `asn` bzw. `origin-asn` Datensatz - Format: `start_ip,end_ip,...` – sortierte, nicht überlappende Ranges ## Funktionale Anforderungen 1. **Lookup-Engine** - Sortierte In-Memory-Struktur pro Datensatz (Country, ASN), Suche via `sort.Search` (Binärsuche) auf Start-IP - Separate Behandlung IPv4 (`uint32`) / IPv6 (`netip.Addr`-Vergleich) - Ladezeit und Speicherbedarf beim Start loggen (Erwartung: < 1s Ladezeit, niedriger zweistelliger MB-Bereich RAM) 2. **HTTP-Endpoints** (Namensgebung analog ipinfo.tw, damit bestehende Clients/Skripte kompatibel bleiben) - `GET /ip` → Client-IP als Plaintext - `GET /country`, `/country_code`, `/country_name` - `GET /as`, `/asn`, `/as_desc` - `GET /json` → alle Felder als JSON - `GET /` → Plaintext-Kurzübersicht (IP, Land, AS, User-Agent) 3. **Client-IP-Ermittlung** - IP primär aus `X-Real-IP`-Header (von Traefik gesetzt), Fallback auf `RemoteAddr` - Kein Trust von `X-Forwarded-For` ohne expliziten Trusted-Proxy-Check (Spoofing-Schutz) 4. **Datenaktualisierung** - Periodischer Refresh (Cron, z.B. täglich) analog zum bestehenden Webhook-Modul-Pattern - Download + Parse in Hintergrund-Goroutine, danach atomarer Swap der Lookup-Struktur (`atomic.Pointer`) – kein Neustart, keine Downtime während Refresh - Fehler beim Refresh (Netzwerk, Parse-Fehler) dürfen die laufende, alte Struktur nicht invalidieren – nur loggen und alten Stand behalten 5. **Konfiguration** - Modul optional aktivierbar (Model-B-Pattern, `Module`-Interface) - Konfigurierbar: Refresh-Intervall, Pfad/URL der Datenquellen, ggf. lokaler Cache-Pfad für die Rohdaten (Neustart ohne Re-Download) ## Nicht-Ziele (out of scope, v1) - Keine City-/Lat-Long-Auflösung (nur Country + ASN) - Keine eigene BGP-Feed-Auswertung, nur die aufbereiteten CSV-Releases - Kein Rate-Limiting speziell für dieses Modul (nutzt vardes globales Rate-Limiting, falls vorhanden) ## Offene Fragen - Refresh-Intervall: reicht täglich, oder soll es an bestehenden Cron/Systemd-Timer gekoppelt werden? - Sollen Country- und ASN-Datensatz unabhängig voneinander deaktivierbar sein (z.B. nur Country, kein ASN)? - Soll `/build_epoch`-Äquivalent (Timestamp der geladenen Daten) mit ausgeliefert werden, um Monitoring zu ermöglichen? ## Akzeptanzkriterien - [ ] Modul lädt Datensätze beim Start und stellt alle o.g. Endpoints bereit - [ ] Ergebnis für bekannte Test-IPs (z.B. eigene öffentliche IP, Google DNS 8.8.8.8) stimmt mit Referenz (ipinfo.tw oder `whois`) überein - [ ] Refresh läuft ohne Downtime/Requests-Fehler während des Swaps - [ ] Fallback auf `RemoteAddr` funktioniert, wenn `X-Real-IP` fehlt - [ ] Speicher- und Startzeit-Overhead dokumentiert (README-Eintrag)

ilvoen added the enhancement label 2026-07-21 06:42:36 +00:00

ilvoen added this to the v0.1.1 milestone 2026-07-21 06:43:28 +00:00

ilvoen added this to the Varde Backlog v0.1.1 project 2026-07-21 06:43:33 +00:00

ilvoen modified the milestone from v0.1.1 to v0.1.0

2026-07-21 07:53:49 +00:00

ilvoen modified the project from Varde Backlog v0.1.1 to Varde Backlog v0.1.0

2026-07-21 07:53:54 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ilvoen/varde#17