gera2ld/whois-bridge repository overview

⁠whois bridge

A minimal HTTP service that resolves domain registration data via the WHOIS protocol (port 43) and returns it as JSON. It exists because browsers and React Native clients can't open raw TCP sockets, so WHOIS-only TLDs (e.g. .me, .im) that don't publish RDAP need an HTTP intermediary.

Built on likexian/whois⁠ for server discovery and likexian/whois-parser⁠ for parsing.

⁠Why

• RDAP is mandatory only for ICANN gTLDs; many ccTLDs (.me, .im) are WHOIS-only.
• Both the domain-vault browser extension and mobile app fetch domain data client-side, which cannot reach WHOIS port 43 directly.

⁠Usage

go build -o whois-bridge .
./whois-bridge

⁠Endpoints

⁠GET /api/domain/{domain}

Returns a JSON document shaped like domain-vault's ParsedRDAPData:

{
  "registrar": "GoDaddy.com, LLC",
  "expirationDate": "2027-04-29T17:53:06Z",
  "creationDate": "2008-04-29T17:53:06Z",
  "nameservers": ["pdns07.domaincontrol.com", "pdns08.domaincontrol.com"],
  "status": ["clientDeleteProhibited", "clientTransferProhibited"]
}

Fields that a registry doesn't publish are returned as empty strings / empty arrays, never null, and never cause the request to fail. For example .im often has no registrar or dates.

curl http://localhost:8080/api/domain/example.me

GET /healthz returns 200 {"status":"ok"}.

⁠Environment variables

Requests are tracked per client IP (read from the last X-Forwarded-For hop, as set by Cloudflare). Exceeding the limit within a window returns 429 with a Retry-After header. /healthz is exempt.

⁠Docker

A prebuilt multi-arch image is published to Docker Hub as gera2ld/whois-bridge⁠ (linux/amd64, linux/arm64), built from a multi-stage Dockerfile (static binary, ~14 MB, runs as a non-root user).

docker run --rm -p 8080:8080 -e WHOIS_TIMEOUT=8s -e CACHE_TTL=12h gera2ld/whois-bridge:latest

⁠Caching

Successful lookups are cached in memory with a per-process TTL (default 24h). Lookup/network failures are not cached, so transient errors retry on the next request. The cache is lost on restart and not shared across instances.