Public API for Geo

See Release Notes.

Purpose

The main purpose of this service is to resolve geolocation of requester.

New component Geo API will resolve country and region by ip address and can simulate country for testing purposes.

Main idea

The basic idea is to load and store a dictionary with mappings country-ip in memory

Internal infrastructure

Infrastructure looks as follows (the green rectangle - it is one single microservice)

geo api

Startup

On application startup firstly we try to load dictionary from external source and schedule to re-download it later.

Metrics

Grafana dashboard: 'Geo prometheus monitoring'.

There are 3 types of metrics: GAUGE, COUNTER, TIMER (contains 2 dimensions: count and sum)

Custom metrics

cache_size (GAUGE)

ip db cache capacity with internal Model. Tags: name

OpenAPI specification

/api/docs/index.html

Usage logic

On application startup we schedule to load the database from an external source from property ip2location.url with an initial period ip2location.period and initial delay ip2location.delay. On success or failure, we can check logs.

There is property behindProxy that indicates is application is behind proxy or not. This property is used in Ip2Location logic only for /resolve. If behindProxy=true, then we read IP address from header X-Forwarded-for. Else we use ip query param. Then we convert the ip address to a number (ex. 127.0.0.1 to 2130706433) and try to get the floor from the ip map.

Health

If we successfully loaded and parsed Ip2Location db, then we set health to UP. If on startup we have failed to load db from file, then we have health = DOWN, and wait until we load it from the external location (by schedule). If we loaded successful, then we UP. If we successfully loaded db from file, but failed to load from external source, then we still UP, because we had successful download before. '''

Internal Tables/files format

Initial file CSV format is

"17039360","17039615","AU","Australia"
"17039616","17072127","CN","China"

Where:

17039360 - start range,
17039615 - end range,
AU - country code,
Australia - country name;

Available Endpoints

Format

GET /me
Content-Type: application/json
X-Forwarded-For: 103.202.232.0
Host: example.com:8080
HTTP/1.1 200 OK
Content-Type: application/javascript

process({"c":"ES"})
GET /resolve?ip=103.202.232.0
Content-Type: application/json
Host: example.com:8080
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

ES

Whitelisting mechanism

Description

It is the mechanism of whitelisting IP addresses and countries. In request need to send X-Forwarded-for header with IP, and allowedCountry param. If we matched ip from request with ip from config and allowed country is matched from request to config, then we do replace.

Configuration

To allow this matching we need to add IP address to white-list.ips array in the properties and specify allowed countries. If * specified, then all countries are allowed for ip.