#geo-ip #http-proxy

app geo302

A simple geoIP-based redirect proxy

5 releases

Uses new Rust 2021

new 0.1.4 Dec 2, 2022
0.1.3 Nov 23, 2022
0.1.2 Nov 23, 2022
0.1.1 Apr 21, 2022
0.1.0 Apr 20, 2022

#50 in HTTP server

Download history 3/week @ 2022-08-21 4/week @ 2022-09-04 2/week @ 2022-09-11 1/week @ 2022-09-18 1/week @ 2022-10-02 1/week @ 2022-11-13 52/week @ 2022-11-20 32/week @ 2022-11-27

85 downloads per month

MIT license

732 lines

geo302 — HTTP redirect proxy with healthcheck

geo302 is not an actual proxy, but a "pathfinder", which responses with 302 Found redirecting the HTTP-client to the actual URL. We use geolite2 geoIP database to determine user's location and select the most suitable upstream for this location. Client's IP is determined using proxy headers like X-FORWARDED-FOR with a fallback to the socket IP address. geo302 performs active health checks against all upstreams pinging them every few seconds.

The main use case of geo302 is redirecting a user to the closest server to minimize download time of large files.



See an example of the configuration in geo302.toml.

Here we present a configuration where the optional entries have the default values:

geolite2 = "<PATH>" # .mmdb geolite2 file, get it from http://dev.maxmind.com
host = "" # address to listen
ip_headers = ["x-forwarded-for"] # optional headers to get client's IP, the first available is used
ip_header_recursive = true # true: get the first ip in the header, false: get the last one
healthckeck_interval = 5 # healthcheck interval in seconds
log_level = "info" # logging level
response_headers = { } # a pairs of header key-values to add to the server reply

# List of mirrors, both upstream and healthcheck keys are required
# If requested URL is <host>/<path>, then redirect URL is <UPSTREAM_URL>/<path>
some_mirror = { upstream = "<UPSTREAM_URL>", healthcheck = "<HEALTHCHECK_URL>" }
another_mirror = { upstream = "<UPSTREAM2_URL>", healthcheck = "<HEALTHCHECK2_URL>" }

# List of locations:
# - some subset of continents
# - the mandatory "default" entry for the cases of unknown/unspecified client location
# For each location the first healthy mirror is used
# Africa = 
# Asia = 
# Europe = 
# NorthAmerica = 
# Oceania = 
# SouthAmerica = 
# Antarctica = 
default = ["<some_mirror>", "<another_mirror>"]


geo302 is a failover and not a load-balancer. Currently geo302 doesn't support an upstream rotation for a single location, but you can specify a list of upstreams: the first available location will be used. If you need a load balancing to optimize a network usage, but do not need geoIP support, consider using another redirect proxy like rlb.

Locations are continent-level only. See https://github.com/hombit/geo302/issues/3 for country-level support

Only GET is supported. See https://github.com/hombit/geo302/issues/4 for HEAD support for health checks

All these limitations are not a part of the design and can be fixed in the future version. Feel free to open an issue or a PR.


MIT licensed.


~198K SLoC