trackdown 0.3.0 → 0.4.0

data/lib/trackdown/providers/base_provider.rb

@@ -2,9 +2,24 @@
 
 require 'countries'
 
+require_relative '../location_result'
+
 module Trackdown
   module Providers
     class BaseProvider
+      # What a CDN may legitimately send as a coordinate: a plain decimal number,
+      # and nothing else. Ruling the rest out here rather than after converting
+      # rejects hexadecimal ("0x10" is a perfectly good latitude of 16.0 to
+      # Kernel#Float), underscored digits, and the "NaN"/"Infinity" literals.
+      #
+      # The digit and exponent limits are not arbitrary: no WGS-84 coordinate
+      # exceeds 180, so three integer digits is already generous, and staying this
+      # side of Float's range means converting a forged header can never overflow.
+      # Ruby warns about an overflowing conversion in verbose mode, and untrusted
+      # input must not be able to make a library talk into someone's logs.
+      # https://www.rfc-editor.org/rfc/rfc5870#section-3.4.2
+      DECIMAL_COORDINATE_PATTERN = /\A[+-]?\d{1,3}(?:\.\d+)?(?:[eE][+-]?\d{1,2})?\z/
+      private_constant :DECIMAL_COORDINATE_PATTERN
       # Returns true if this provider can handle the given request/context
       def self.available?(request: nil)
         raise NotImplementedError, "#{self} must implement .available?"
@@ -18,21 +33,72 @@ module Trackdown
         raise NotImplementedError, "#{self} must implement .locate"
       end
 
-      protected
+      # How a result names this provider: the same symbol you'd set as
+      # `config.provider`, so `result.provider_name == :cloudflare` lines up with
+      # `config.provider = :cloudflare`.
+      def self.provider_name
+        raise NotImplementedError, "#{self} must implement .provider_name"
+      end
+
+      # Where this provider's answers physically come from, e.g.
+      # :cloudflare_request_headers or :maxmind_local_database.
+      def self.provider_source
+        raise NotImplementedError, "#{self} must implement .provider_source"
+      end
+
+      # The provenance a request-backed provider stamps on every result.
+      #
+      # The trust state is :unverified unless the host's own verifier vouches for
+      # the request. Trackdown never reads trust out of the headers themselves —
+      # anyone who can reach an unprotected origin can send those.
+      def self.request_provenance(request)
+        source_was_verified = Trackdown.configuration.request_came_through_trusted_cdn_path?(
+          request,
+          provider_name: provider_name
+        )
+
+        {
+          provider_name: provider_name,
+          provider_source: provider_source,
+          source_trust: source_was_verified ? :host_verified : :unverified
+        }
+      end
 
       # Helper to get emoji flag from country code
       def self.get_emoji_flag(country_code)
-        country_code ? country_code.tr('A-Z', "\u{1F1E6}-\u{1F1FF}") : "🏳️"
+        return LocationResult::UNKNOWN_FLAG unless country_code.is_a?(String)
+        return LocationResult::UNKNOWN_FLAG unless /\A[A-Za-z]{2}\z/.match?(country_code)
+
+        normalized_code = country_code.upcase
+        normalized_code.tr('A-Z', "\u{1F1E6}-\u{1F1FF}")
       end
 
       # Helper to extract country name from country code using countries gem
       def self.get_country_name(country_code)
-        return 'Unknown' unless country_code
+        return LocationResult::UNKNOWN unless country_code
 
         country = ISO3166::Country.new(country_code)
-        country&.iso_short_name || country&.name || 'Unknown'
+        country&.iso_short_name || country&.name || LocationResult::UNKNOWN
       rescue StandardError
-        'Unknown'
+        LocationResult::UNKNOWN
+      end
+
+      # Parse an untrusted coordinate: a plain decimal within the given WGS-84
+      # bounds, or nothing. The range check also settles NaN and Infinity, since
+      # a Range covers neither.
+      # https://www.rfc-editor.org/rfc/rfc5870#section-3.4.2
+      def self.parse_coordinate(value, range:)
+        return nil unless value.is_a?(String)
+
+        decimal = value.strip
+        return nil unless DECIMAL_COORDINATE_PATTERN.match?(decimal)
+
+        coordinate = decimal.to_f
+        range.cover?(coordinate) ? coordinate : nil
+      end
+
+      class << self
+        protected :get_emoji_flag, :get_country_name, :parse_coordinate
       end
     end
   end

data/lib/trackdown/providers/cloudflare_provider.rb

@@ -10,6 +10,10 @@ module Trackdown
     #
     # Cloudflare must have "IP Geolocation" or "Add visitor location headers" enabled
     # in the dashboard under Network settings or via Managed Transforms
+    # Exact header contract:
+    # https://developers.cloudflare.com/fundamentals/reference/http-headers/
+    # Exact origin-protection guidance:
+    # https://developers.cloudflare.com/ssl/origin-configuration/authenticated-origin-pull/
     class CloudflareProvider < BaseProvider
       COUNTRY_HEADER = 'HTTP_CF_IPCOUNTRY'
       CITY_HEADER = 'HTTP_CF_IPCITY'
@@ -22,30 +26,54 @@ module Trackdown
       METRO_CODE_HEADER = 'HTTP_CF_METRO_CODE'
       POSTAL_CODE_HEADER = 'HTTP_CF_POSTAL_CODE'
 
-      # Special Cloudflare country codes
+      # Cloudflare's XX and T1 pseudo-codes do not name countries. Unicode also
+      # defines ZZ as unknown/invalid territory, so none is treated as a country.
+      # Cloudflare: https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-ipcountry
+      # Unicode ZZ semantics:
+      # https://www.unicode.org/reports/tr35/tr35-78/tr35.html#unicode_region_subtag_validity
       UNKNOWN_CODE = 'XX'
+      UNKNOWN_OR_INVALID_TERRITORY_CODE = 'ZZ'
       TOR_CODE = 'T1'
+      UNAVAILABLE_COUNTRY_CODES = [UNKNOWN_CODE, UNKNOWN_OR_INVALID_TERRITORY_CODE].freeze
+      COUNTRY_CODE_PATTERN = /\A[A-Za-z]{2}\z/
+      LATITUDE_RANGE = (-90.0..90.0)
+      LONGITUDE_RANGE = (-180.0..180.0)
+
+      private_constant :UNAVAILABLE_COUNTRY_CODES,
+                       :COUNTRY_CODE_PATTERN,
+                       :LATITUDE_RANGE,
+                       :LONGITUDE_RANGE
 
       class << self
+        def provider_name
+          :cloudflare
+        end
+
+        def provider_source
+          :cloudflare_request_headers
+        end
+
         # Check if Cloudflare headers are available in the request
         def available?(request: nil)
           return false unless request
 
-          country_code = request.env[COUNTRY_HEADER]
-          !country_code.nil? && !country_code.empty? && country_code != UNKNOWN_CODE
+          !extract_country_code(request).nil?
         end
 
         # Locate IP using Cloudflare headers
         # @param ip [String] The IP address (not used, as Cloudflare already resolved it)
         # @param request [ActionDispatch::Request] Rails request object with Cloudflare headers
         # @return [LocationResult] The location information
-        def locate(ip, request: nil)
+        def locate(_ip, request: nil)
           raise Trackdown::Error, "CloudflareProvider requires a request object with Cloudflare headers" unless request
 
+          provenance = request_provenance(request)
           country_code = extract_country_code(request)
 
           # If no valid country code, return unknown
-          return LocationResult.new(nil, 'Unknown', 'Unknown', '🏳️') if country_code.nil? || country_code == UNKNOWN_CODE
+          if country_code.nil? || country_code == UNKNOWN_CODE
+            return LocationResult.unavailable(:provider_returned_unknown_country, **provenance)
+          end
 
           country_name = get_country_name(country_code)
           city = extract_city(request)
@@ -57,10 +85,18 @@ module Trackdown
             region_code: extract_header(request, REGION_CODE_HEADER),
             continent: extract_header(request, CONTINENT_HEADER),
             timezone: extract_header(request, TIMEZONE_HEADER),
-            latitude: parse_coordinate(request.env[LATITUDE_HEADER]),
-            longitude: parse_coordinate(request.env[LONGITUDE_HEADER]),
+            latitude: parse_coordinate(request.env[LATITUDE_HEADER], range: LATITUDE_RANGE),
+            longitude: parse_coordinate(request.env[LONGITUDE_HEADER], range: LONGITUDE_RANGE),
             postal_code: extract_header(request, POSTAL_CODE_HEADER),
-            metro_code: extract_header(request, METRO_CODE_HEADER)
+            metro_code: extract_header(request, METRO_CODE_HEADER),
+            # "T1" says the visitor came through Tor, which is precisely a country
+            # Cloudflare could not determine. The code is kept, the claim is not.
+            # Only Cloudflare's own two pseudo-codes are treated this way: a code
+            # we simply haven't heard of (Kosovo's user-assigned "XK", say) is a
+            # real answer, not an unresolved one.
+            # https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-ipcountry
+            unavailable_reason: (:provider_returned_unknown_country if country_code == TOR_CODE),
+            **provenance
           )
         end
 
@@ -68,9 +104,16 @@ module Trackdown
 
         def extract_country_code(request)
           code = request.env[COUNTRY_HEADER]
-          return nil if code.nil? || code.empty? || code == UNKNOWN_CODE
+          return nil unless code.is_a?(String)
+
+          normalized_code = code.upcase
+          return nil if UNAVAILABLE_COUNTRY_CODES.include?(normalized_code)
+          return normalized_code if normalized_code == TOR_CODE
+          return nil unless COUNTRY_CODE_PATTERN.match?(code)
 
-          code.upcase
+          normalized_code
+        rescue StandardError
+          nil
         end
 
         def extract_city(request)
@@ -78,25 +121,19 @@ module Trackdown
 
           # Cloudflare city header might not always be present
           # It requires "Add visitor location headers" Managed Transform
-          return 'Unknown' if city.nil? || city.empty?
+          return 'Unknown' unless city.is_a?(String)
+          return 'Unknown' if city.empty?
 
           city
         end
 
         def extract_header(request, header)
           value = request.env[header]
-          return nil if value.nil? || value.empty?
+          return nil unless value.is_a?(String)
+          return nil if value.empty?
 
           value
         end
-
-        def parse_coordinate(value)
-          return nil if value.nil? || value.empty?
-
-          Float(value)
-        rescue ArgumentError, TypeError
-          nil
-        end
       end
     end
   end

data/lib/trackdown/providers/cloudfront_provider.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative 'base_provider'
+require_relative '../location_result'
+
+module Trackdown
+  module Providers
+    # Provider that uses Amazon CloudFront HTTP headers for IP geolocation.
+    # This is the fastest and most lightweight option when your app is behind
+    # CloudFront (the AWS CDN) — a direct analog to the Cloudflare provider.
+    #
+    # CloudFront resolves the viewer's location at the edge and forwards it to the
+    # origin as CloudFront-Viewer-* headers. To receive them, attach an origin
+    # request policy that forwards the CloudFront geolocation headers.
+    #
+    # Exact AWS viewer-location header contract (names, availability, encoding):
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-viewer-location
+    # Exact AWS managed-policy contents:
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-all-viewer-and-cloudfront
+    #
+    # IMPORTANT: Header presence does not authenticate CloudFront. A custom origin
+    # must reject direct traffic before an application can trust these values. AWS's
+    # exact origin-restriction guidance is:
+    # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-overview.html
+    #
+    # Note: CloudFront does not emit a continent header. We derive #continent from the
+    # country code so it matches the 2-letter code (e.g. "NA") the other providers
+    # return. The countries gem exposes a continent *name* ("North America") but no
+    # code, and its names don't map by initials (Africa/Asia/Antarctica/Australia all
+    # start with "A", and it labels Oceania "Australia"), so an explicit table is the
+    # only reliable mapping.
+    class CloudfrontProvider < BaseProvider
+      # ISO3166 continent name (from the countries gem) => 2-letter code used by the
+      # Cloudflare and MaxMind providers.
+      # countries gem source: https://github.com/countries/countries
+      CONTINENT_CODES = {
+        'Africa' => 'AF',
+        'Antarctica' => 'AN',
+        'Asia' => 'AS',
+        'Europe' => 'EU',
+        'North America' => 'NA',
+        'South America' => 'SA',
+        'Australia' => 'OC' # the countries gem labels Oceania "Australia"
+      }.freeze
+
+      # Rack exposes ordinary HTTP request headers as HTTP_* environment entries:
+      # https://github.com/rack/rack/blob/main/SPEC.rdoc#http_-headers
+      COUNTRY_HEADER = 'HTTP_CLOUDFRONT_VIEWER_COUNTRY'
+      CITY_HEADER = 'HTTP_CLOUDFRONT_VIEWER_CITY'
+      # CloudFront exposes both a region code ("CA") and its full name ("California").
+      # Match the Cloudflare provider's semantics: #region is the name, #region_code the code.
+      REGION_HEADER = 'HTTP_CLOUDFRONT_VIEWER_COUNTRY_REGION_NAME'
+      REGION_CODE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_COUNTRY_REGION'
+      LATITUDE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_LATITUDE'
+      LONGITUDE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_LONGITUDE'
+      TIMEZONE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_TIME_ZONE'
+      POSTAL_CODE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_POSTAL_CODE'
+      METRO_CODE_HEADER = 'HTTP_CLOUDFRONT_VIEWER_METRO_CODE'
+
+      COUNTRY_CODE_PATTERN = /\A[A-Za-z]{2}\z/
+      INDUSTRY_PRACTICE_COUNTRY_CODES = %w[XK].freeze
+      INVALID_PERCENT_ESCAPE_PATTERN = /%(?![0-9A-Fa-f]{2})/
+      PERCENT_ESCAPE_PATTERN = /%([0-9A-Fa-f]{2})/
+      LATITUDE_RANGE = (-90.0..90.0)
+      LONGITUDE_RANGE = (-180.0..180.0)
+
+      private_constant :COUNTRY_CODE_PATTERN,
+                       :INDUSTRY_PRACTICE_COUNTRY_CODES,
+                       :INVALID_PERCENT_ESCAPE_PATTERN,
+                       :PERCENT_ESCAPE_PATTERN,
+                       :LATITUDE_RANGE,
+                       :LONGITUDE_RANGE
+
+      class << self
+        def provider_name
+          :cloudfront
+        end
+
+        def provider_source
+          :cloudfront_request_headers
+        end
+
+        # Check if CloudFront headers are available in the request
+        def available?(request: nil)
+          return false unless request
+
+          !extract_country_code(request).nil?
+        end
+
+        # Locate IP using CloudFront headers
+        # @param ip [String] The IP address (not used, as CloudFront already resolved it)
+        # @param request [#env] Rack-compatible request object with CloudFront headers
+        # @return [LocationResult] The location information
+        def locate(_ip, request: nil)
+          raise Trackdown::Error, 'CloudfrontProvider requires a request object with CloudFront headers' unless request
+
+          provenance = request_provenance(request)
+          country_code = extract_country_code(request)
+
+          # If no valid country code, return unknown
+          return LocationResult.unavailable(:provider_returned_unknown_country, **provenance) if country_code.nil?
+
+          build_location_result(country_code, request, **provenance)
+        end
+
+        private
+
+        def build_location_result(country_code, request, **provenance)
+          LocationResult.new(
+            country_code,
+            get_country_name(country_code),
+            extract_city(request),
+            get_emoji_flag(country_code),
+            region: extract_header(request, REGION_HEADER),
+            region_code: extract_header(request, REGION_CODE_HEADER),
+            continent: continent_code(country_code),
+            timezone: extract_header(request, TIMEZONE_HEADER),
+            latitude: parse_coordinate(request.env[LATITUDE_HEADER], range: LATITUDE_RANGE),
+            longitude: parse_coordinate(request.env[LONGITUDE_HEADER], range: LONGITUDE_RANGE),
+            postal_code: extract_header(request, POSTAL_CODE_HEADER),
+            metro_code: extract_header(request, METRO_CODE_HEADER),
+            **provenance
+          )
+        end
+
+        # Derive the 2-letter continent code from the country code via the countries gem.
+        # Returns nil for unknown countries or continents outside the table.
+        def continent_code(country_code)
+          country = ISO3166::Country.new(country_code)
+          CONTINENT_CODES[country&.continent]
+        rescue StandardError
+          nil
+        end
+
+        def extract_country_code(request)
+          # AWS specifies an ISO 3166-1 alpha-2 value and links the authoritative list:
+          # https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-viewer-location
+          code = request.env[COUNTRY_HEADER]
+          return nil unless code.is_a?(String)
+
+          return nil unless COUNTRY_CODE_PATTERN.match?(code)
+
+          normalized_code = code.upcase
+
+          # Unicode CLDR gives XK (Kosovo) defined industry-practice semantics,
+          # while ZZ explicitly means an unknown or invalid territory. Preserve
+          # XK even though the countries gem's ISO catalog does not contain it;
+          # continue to reject arbitrary unassigned codes such as ZZ.
+          # https://www.unicode.org/reports/tr35/tr35-78/tr35.html#unicode_region_subtag_validity
+          return normalized_code if INDUSTRY_PRACTICE_COUNTRY_CODES.include?(normalized_code)
+
+          country = ISO3166::Country.new(normalized_code)
+          return nil unless country&.alpha2 == normalized_code
+
+          normalized_code
+        rescue StandardError
+          nil
+        end
+
+        def extract_city(request)
+          city = decode_header_value(request.env[CITY_HEADER])
+
+          # The city header is only present when the origin request policy forwards it.
+          return 'Unknown' if city.nil?
+
+          city
+        end
+
+        def extract_header(request, header)
+          decode_header_value(request.env[header])
+        end
+
+        # AWS percent-encodes non-ASCII viewer-location header characters according
+        # to RFC 3986. Decode percent octets—not form data—so a literal "+" remains
+        # a plus. Reject malformed escapes and invalid UTF-8 instead of exposing
+        # ambiguous/binary strings to callers.
+        # AWS: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/adding-cloudfront-headers.html#cloudfront-headers-viewer-location
+        # RFC 3986: https://www.rfc-editor.org/rfc/rfc3986#section-2.1
+        def decode_header_value(value)
+          return nil unless value.is_a?(String)
+          return nil if value.empty?
+
+          encoded_value = value.b
+          return nil if INVALID_PERCENT_ESCAPE_PATTERN.match?(encoded_value)
+
+          decoded_value = encoded_value.gsub(PERCENT_ESCAPE_PATTERN) do
+            Regexp.last_match(1).to_i(16).chr
+          end
+          decoded_value.force_encoding(Encoding::UTF_8)
+          return nil unless decoded_value.valid_encoding?
+
+          decoded_value
+        end
+      end
+    end
+  end
+end

data/lib/trackdown/providers/maxmind_provider.rb

@@ -3,6 +3,7 @@
 require 'timeout'
 require_relative 'base_provider'
 require_relative '../location_result'
+require_relative '../database_fingerprint'
 
 # Conditionally require MaxMind - this is an optional dependency
 begin
@@ -20,10 +21,30 @@ module Trackdown
       class TimeoutError < Trackdown::Error; end
       class DatabaseError < Trackdown::Error; end
 
-      @@reader_pool = nil
-      @@pool_mutex = Mutex.new
+      DatabaseReader = Struct.new(:reader, :fingerprint, keyword_init: true)
+      DatabaseLookup = Struct.new(:record, :fingerprint, keyword_init: true)
+      private_constant :DatabaseReader, :DatabaseLookup
+
+      # MaxMind publishes the accuracy radius as the radius, in kilometres, within
+      # which the address is likely to be, at a 67% confidence level:
+      # https://support.maxmind.com/knowledge-base/articles/maxmind-geolocation-accuracy
+      ACCURACY_RADIUS_CONFIDENCE_PERCENTAGE = 67
+
+      @reader_pool = nil
+      @pool_mutex = Mutex.new
+      @database_fingerprint = nil
+      @database_fingerprints = {}
+      @fingerprint_mutex = Mutex.new
 
       class << self
+        def provider_name
+          :maxmind
+        end
+
+        def provider_source
+          :maxmind_local_database
+        end
+
         # Check if MaxMind database is available
         def available?(request: nil)
           return false unless maxmind_available?
@@ -32,6 +53,29 @@ module Trackdown
           true
         end
 
+        # The fingerprint used by the most recent successful reader fetch. Results
+        # do not read this global diagnostic: each one retains its reader-bound
+        # fingerprint, so concurrent generations can never mix provenance.
+        def database_fingerprint
+          @fingerprint_mutex.synchronize { @database_fingerprint }
+        end
+
+        # Forget the open database. Call this after replacing the .mmdb file so the
+        # next lookup opens the new one — Trackdown::DatabaseUpdater already does.
+        def reset_database!
+          # Let go of the pool rather than shutting it down: a lookup already in
+          # flight must not fail because a refresh happened underneath it. Ruby
+          # reclaims the old readers once the last lookup lets go of them.
+          @pool_mutex.synchronize do
+            @reader_pool = nil
+            @fingerprint_mutex.synchronize do
+              @database_fingerprint = nil
+              @database_fingerprints = {}
+            end
+          end
+          nil
+        end
+
         # Locate IP using MaxMind database
         # @param ip [String] The IP address to locate
         # @param request [ActionDispatch::Request, nil] Not used by MaxMind provider
@@ -40,13 +84,19 @@ module Trackdown
           raise Trackdown::Error, "MaxMind database not found" unless Trackdown.database_exists?
           raise Trackdown::Error, "maxmind-db gem not installed. Add it to your Gemfile: gem 'maxmind-db'" unless maxmind_available?
 
-          record = fetch_record(ip)
-          return LocationResult.new(nil, 'Unknown', 'Unknown', '🏳️') if record.nil?
+          lookup = fetch_record(ip)
+          record = lookup.record
+          fingerprint = lookup.fingerprint
+          provenance = database_provenance(fingerprint)
+
+          # We looked, in this exact database, and this address simply isn't in it.
+          return LocationResult.unavailable(:address_not_found, **provenance) if record.nil?
 
           country_code = extract_country_code(record)
           country_name = extract_country_name(record)
           city = extract_city(record)
           flag_emoji = get_emoji_flag(country_code)
+          accuracy_radius = record&.dig('location', 'accuracy_radius')
 
           LocationResult.new(
             country_code, country_name, city, flag_emoji,
@@ -57,20 +107,37 @@ module Trackdown
             latitude: record&.dig('location', 'latitude'),
             longitude: record&.dig('location', 'longitude'),
             postal_code: record&.dig('postal', 'code'),
-            metro_code: record&.dig('location', 'metro_code')&.to_s
+            metro_code: record&.dig('location', 'metro_code')&.to_s,
+            accuracy_radius_in_kilometers: accuracy_radius,
+            accuracy_radius_confidence_percentage: (ACCURACY_RADIUS_CONFIDENCE_PERCENTAGE if accuracy_radius),
+            **provenance
           )
         end
 
         private
 
+        # Which database answered, plus how to identify it. The digest is a lambda
+        # so reading it stays optional: an ordinary lookup never re-reads the file.
+        def database_provenance(fingerprint)
+          {
+            provider_name: provider_name,
+            provider_source: provider_source,
+            database_build_epoch: fingerprint&.build_epoch,
+            database_sha256: (-> { fingerprint.sha256 } if fingerprint)
+          }
+        end
+
         def maxmind_available?
           defined?(MaxMind::DB)
         end
 
         def fetch_record(ip)
           Timeout.timeout(Trackdown.configuration.timeout) do
-            reader_pool.with do |reader|
-              reader.get(ip)
+            reader_pool.with do |database_reader|
+              record = database_reader.reader.get(ip)
+              fingerprint = remember_database(database_reader.fingerprint)
+
+              DatabaseLookup.new(record: record, fingerprint: fingerprint)
             end
           end
         rescue Timeout::Error
@@ -83,21 +150,51 @@ module Trackdown
         end
 
         def reader_pool
-          return @@reader_pool if @@reader_pool
+          return @reader_pool if @reader_pool
 
-          @@pool_mutex.synchronize do
-            @@reader_pool ||= ConnectionPool.new(
+          @pool_mutex.synchronize do
+            @reader_pool ||= ConnectionPool.new(
               size: Trackdown.configuration.pool_size,
               timeout: Trackdown.configuration.pool_timeout
             ) do
-              MaxMind::DB.new(
-                Trackdown.configuration.database_path,
-                mode: Trackdown.configuration.memory_mode
-              )
+              open_database_reader
             end
           end
         end
 
+        # Capture the file identity before MaxMind opens it, then bind that exact
+        # identity to the reader for its whole lifetime. If the path changes while
+        # the reader opens, its eventual digest is nil rather than a digest from a
+        # different database generation.
+        def open_database_reader
+          path = Trackdown.configuration.database_path
+          fingerprint = DatabaseFingerprint.new(path: path)
+          reader = MaxMind::DB.new(path, mode: Trackdown.configuration.memory_mode)
+          fingerprint = fingerprint.with_build_epoch(build_epoch_of(reader))
+
+          DatabaseReader.new(reader: reader, fingerprint: canonical_fingerprint(fingerprint))
+        end
+
+        def remember_database(fingerprint)
+          @fingerprint_mutex.synchronize { @database_fingerprint = fingerprint }
+          fingerprint
+        end
+
+        # Reuse one lazy digest for every pooled reader that opened the same path,
+        # file identity, and database build. Readers from different generations
+        # always retain different fingerprint objects.
+        def canonical_fingerprint(fingerprint)
+          @fingerprint_mutex.synchronize do
+            @database_fingerprints[fingerprint.cache_key] ||= fingerprint
+          end
+        end
+
+        def build_epoch_of(reader)
+          reader.metadata&.build_epoch
+        rescue StandardError
+          nil
+        end
+
         def extract_country_code(record)
           record&.dig('country', 'iso_code')
         end
@@ -105,13 +202,13 @@ module Trackdown
         def extract_country_name(record)
           record&.dig('country', 'names', 'en') ||
             (record&.dig('country', 'names')&.values&.first) ||
-            'Unknown'
+            LocationResult::UNKNOWN
         end
 
         def extract_city(record)
           record&.dig('city', 'names', 'en') ||
             (record&.dig('city', 'names')&.values&.first) ||
-            'Unknown'
+            LocationResult::UNKNOWN
         end
 
         def extract_region(record)

data/lib/trackdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trackdown
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/trackdown.rb

@@ -6,9 +6,11 @@ require_relative "trackdown/configuration"
 require_relative "trackdown/ip_validator"
 require_relative "trackdown/ip_locator"
 require_relative "trackdown/database_updater"
+require_relative "trackdown/database_fingerprint"
 require_relative "trackdown/location_result"
 require_relative "trackdown/providers/base_provider"
 require_relative "trackdown/providers/cloudflare_provider"
+require_relative "trackdown/providers/cloudfront_provider"
 require_relative "trackdown/providers/maxmind_provider"
 require_relative "trackdown/providers/auto_provider"
 
@@ -27,7 +29,7 @@ module Trackdown
 
   # Locate an IP address using the configured provider
   # @param ip [String] The IP address to locate
-  # @param request [ActionDispatch::Request, nil] Optional Rails request object (required for Cloudflare provider)
+  # @param request [#env, nil] Optional Rack-compatible request object (required for CDN providers)
   # @return [LocationResult] The location information
   def self.locate(ip, request: nil)
     IpLocator.locate(ip, request: request)