GameServerWeb.Plugs.GeoCountry (game_server_web v1.0.940)

Copy Markdown

Resolves the client's country and stores it on conn.assigns[:country].

Resolution order (first match wins):

  1. Geolix MMDB lookup — if a GeoLite2-Country (or compatible) database is configured via GEOIP_DB_PATH, the client IP is resolved locally. This is the most accurate and works without any proxy.

  2. Cloudflare CF-IPCountry header — fallback when behind Cloudflare. Cloudflare auto-appends the ISO 3166-1 alpha-2 country code.

  3. nil — when neither source is available (local dev without DB).

Also maintains an in-memory ETS aggregate of request counts by country, bucketed by minute, for the admin dashboard. Supports time-windowed queries (last 1h, 24h, 7d, or all-time).

Emits a :telemetry event [:game_server, :geo, :request] with the country code as metadata for Prometheus export.

Configuration

To enable Geolix lookup, either place the MMDB file under the host-owned default path:

apps/game_server_host/data/GeoLite2-Country.mmdb

or set a custom path in your environment:

GEOIP_DB_PATH=/path/to/GeoLite2-Country.mmdb

Download the free database from: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data

Summary

Functions

cleanup_old_buckets()

Remove minute buckets older than the retention period (10080 minutes). Called periodically by GameServerWeb.GeoCountryCleaner.

country_count(opts \\ [])

Returns the number of distinct countries seen in the given window.

country_stats(opts \\ [])

Returns a sorted list of {country_code, count} tuples, descending by count.

dashboard_stats()

Single-pass dashboard stats. Returns a map with all-time and 1h data in one ETS scan, avoiding multiple tab2list / foldl calls.

geoip_available?()

Returns whether Geolix has a country database loaded.

init_table()

Initialize the ETS table. Call once at application startup.

reset_stats()

Reset all counters (useful from admin panel).

time_series(country, opts \\ [])

Returns a time series of {minute_ts, count} for the given country and window. Useful for sparklines in the UI. Each entry is a Unix minute timestamp.

total_requests(opts \\ [])

Returns the total number of tracked requests across all countries.

Functions

cleanup_old_buckets()

Remove minute buckets older than the retention period (10080 minutes). Called periodically by GameServerWeb.GeoCountryCleaner.

country_count(opts \\ [])

Returns the number of distinct countries seen in the given window.

country_stats(opts \\ [])

Returns a sorted list of {country_code, count} tuples, descending by count.

Options

  • :window — one of :all, :hour, :day, :week (default: :all)

dashboard_stats()

Single-pass dashboard stats. Returns a map with all-time and 1h data in one ETS scan, avoiding multiple tab2list / foldl calls.

Returns:

%{
  stats_all: [{country, count}, ...],
  total_all: integer,
  stats_1h: [{country, count}, ...],
  total_1h: integer
}

geoip_available?()

Returns whether Geolix has a country database loaded.

init_table()

Initialize the ETS table. Call once at application startup.

reset_stats()

Reset all counters (useful from admin panel).

time_series(country, opts \\ [])

Returns a time series of {minute_ts, count} for the given country and window. Useful for sparklines in the UI. Each entry is a Unix minute timestamp.

total_requests(opts \\ [])

Returns the total number of tracked requests across all countries.

Options

  • :window — one of :all, :hour, :day, :week (default: :all)