Geographic Routing

Status: Implemented

Overview

Geographic routing allows tunnel owners to route incoming requests based on the client IP's country of origin using a MaxMind GeoLite2-Country database.

Design

GeoIP Lookup (cli/internal/edge/geoip.go)

• Loads MaxMind GeoLite2-Country database from the JETTY_EDGE_GEOIP_DB_PATH environment variable on first use (lazy singleton).
• Provides LookupCountry(ip string) string returning an ISO 3166-1 alpha-2 country code (e.g. "US", "DE").
• Graceful fallback: if the env var is unset, the file is missing, or the IP cannot be resolved, returns an empty string. Geo rules are silently skipped when the country is unknown.

Protocol Changes (cli/internal/wsproto/proto.go)

Two new fields on RoutingRule:

Edge Routing (cli/internal/edge/edge.go)

New match_type: "geo_match" case in matchRoutingRule:

1. Skip if Countries list is empty.
2. Look up client IP country via LookupCountry.
3. Skip if country is empty (DB not loaded).
4. Check whether the country is in the rule's list.
5. Apply GeoInvert flag: allow-mode (false) matches when country is in the list; block-mode (true) matches when country is NOT in the list.

Bridge Validation (app/Support/TunnelRoutingRulesValidator.php)

• Accepts geo_match as a valid match_type.
• Validates countries is a non-empty array of 2-letter uppercase ISO codes.
• Normalises codes to uppercase and deduplicates.
• Reads optional geo_invert boolean (defaults to false).

Dependencies

• github.com/oschwald/maxminddb-golang v1.13.1 (added to cli/go.mod).
• MaxMind GeoLite2-Country .mmdb file deployed to the edge server and referenced via JETTY_EDGE_GEOIP_DB_PATH.