trackdown 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 675d77c9715d2b1de76e4d385b95960b82f45355edb57689d2cf243197f19324
-  data.tar.gz: 061e61803019b00dd99e2d186f3c3ccbe73cf5ee9a750b513e1dfc11c46c0859
+  metadata.gz: 78637df00207906a24e8553f69a16536a402d59af543c531613b9b3b881bad2c
+  data.tar.gz: 21c3fc9d6845db2322bfe85cd1a85d87539c16b211c12a3f3c9dc4de3bc4dd12
 SHA512:
-  metadata.gz: 5394b49ff9c641ae941675b2bc18da7e92d934effab2f771707ded19179ea4f019a5c18533dc059e5e8f12e7cf6ff0847d0e3dd91586e1e218bb7f0f3d96c139
-  data.tar.gz: bddbc1ea728846d08dd1ca75033c3a9b3eb95144fdbec641089593c8f1e177e3ac52eb9cb495b2a14bbc118d99d23a504f2ecbe37578017629f9344e13faf0d7
+  metadata.gz: '08cc2f24e4339a74690c74a9adfb687fb9db337c4215911f7673cf2c9583054e8325b8250c9ab219f7c878a80b8ba2287e238cf7776b61fe475830ef54203a07'
+  data.tar.gz: dfbff6a70b8d6ecbd8b18b191d0b6a819af2e72aad179e8ee9c007f8511af5a22a9531d80a698c87f33759f27ec48905aec23ffa6282b13b44ca1bb9cf021400

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.3.1] - 2026-02-24
+
+- Fix incorrect Cloudflare geolocation when an upstream proxy sits before Cloudflare
+- In `:auto` mode, compare `CF-Connecting-IP` with the target IP and fall back to MaxMind on mismatch
+- Normalize compared IPs with `IPAddr` so equivalent IPv6 / IPv4-mapped forms are treated as matches
+- Add tests covering matching and mismatching `CF-Connecting-IP` scenarios
+
 ## [0.3.0] - 2026-02-08
 
 - Add 8 new geolocation fields: `region`, `region_code`, `continent`, `timezone`, `latitude`, `longitude`, `postal_code`, `metro_code`

data/README.md

@@ -1,5 +1,7 @@
 # 📍 `trackdown` - Ruby gem to geolocate IPs
 
+[![Gem Version](https://badge.fury.io/rb/trackdown.svg)](https://badge.fury.io/rb/trackdown) [![Build Status](https://github.com/rameerez/trackdown/workflows/Tests/badge.svg)](https://github.com/rameerez/trackdown/actions)
+
 > [!TIP]
 > **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=trackdown)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=trackdown)!
 
@@ -132,7 +134,7 @@ production:
   refresh_trackdown_database:
     class: TrackdownDatabaseRefreshJob
     queue: default
-    schedule: every Saturday at 4am US/Pacific
+    schedule: every Saturday at 4am
 ```
 
 > [!NOTE]
@@ -297,6 +299,74 @@ Trackdown reads these headers directly from the request with zero overhead — n
 Downloads the [GeoLite2-City](https://dev.maxmind.com/geoip/docs/databases/city-and-country/) database to your server and performs local lookups using connection pooling for performance. All fields (`country`, `city`, `region`, `continent`, `timezone`, `latitude`, `longitude`, `postal_code`, `metro_code`) are extracted from the database record.
 
 
+## Docker & Container Deployments
+
+When deploying with Docker, Kubernetes, or similar container orchestration, the MaxMind database file needs special handling since container filesystems are ephemeral.
+
+### Option 1: Persistent Volume (Recommended)
+
+Mount a persistent volume for the database file so it survives container restarts and deployments.
+
+**Kamal (`config/deploy.yml`):**
+```yaml
+volumes:
+  - "trackdown_data:/rails/db/geodata"
+```
+
+Then configure the database path:
+```ruby
+# config/initializers/trackdown.rb
+config.database_path = Rails.root.join('db', 'geodata', 'GeoLite2-City.mmdb').to_s
+```
+
+**Docker Compose:**
+```yaml
+services:
+  app:
+    volumes:
+      - trackdown_data:/rails/db/geodata
+
+volumes:
+  trackdown_data:
+```
+
+### Option 2: Download on Container Start
+
+If you prefer not to use volumes, download the database when the container starts. Add to your entrypoint or a post-deploy hook:
+
+```bash
+# In your entrypoint.sh or deploy hook
+bin/rails runner "Trackdown.update_database unless File.exist?(Trackdown.configuration.database_path)"
+```
+
+Or create a job that runs on boot:
+
+```ruby
+# config/initializers/trackdown_boot.rb
+Rails.application.config.after_initialize do
+  if Rails.env.production? && !File.exist?(Trackdown.configuration.database_path)
+    Trackdown.update_database
+  end
+end
+```
+
+> [!WARNING]
+> Option 2 adds startup time (~10-30 seconds) on fresh deploys and requires network access during boot. A persistent volume is more reliable for production.
+
+### Background Jobs Consideration
+
+When using background job processors (Sidekiq, SolidQueue, GoodJob), geolocation lookups in jobs **cannot use Cloudflare headers** since there's no HTTP request. These jobs will fall back to MaxMind automatically when using `:auto` provider.
+
+Make sure MaxMind is properly configured if you're doing geolocation in background jobs:
+
+```ruby
+# This works in controllers (has request)
+Trackdown.locate(ip, request: request)  # Uses Cloudflare if available
+
+# This works in background jobs (no request)
+Trackdown.locate(ip)  # Falls back to MaxMind
+```
+
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake test` to run the Minitest tests.

data/lib/trackdown/providers/auto_provider.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
+
 require_relative 'base_provider'
 require_relative 'cloudflare_provider'
 require_relative 'maxmind_provider'
@@ -9,11 +11,19 @@ module Trackdown
     # Intelligent provider that automatically selects the best available provider
     # Priority order:
     # 1. Cloudflare (fastest, zero overhead, no external dependencies)
-    # 2. MaxMind (fallback when Cloudflare not available)
+    # 2. MaxMind (fallback when Cloudflare not available or IP mismatch)
     #
     # This is the recommended default for most applications
+    #
+    # IMPORTANT: When there's an upstream proxy before Cloudflare (e.g., a legacy
+    # API gateway), Cloudflare's geo headers will reflect the proxy's location,
+    # not the real client. AutoProvider detects this by comparing CF-Connecting-IP
+    # with the passed IP and falls back to MaxMind when they don't match.
     class AutoProvider < BaseProvider
+      CF_CONNECTING_IP_HEADER = 'HTTP_CF_CONNECTING_IP'
+
       @@warned_no_providers = false
+      @@warned_ip_mismatch = false
       @@warn_mutex = Mutex.new
 
       class << self
@@ -29,8 +39,16 @@ module Trackdown
         # @return [LocationResult] The location information
         def locate(ip, request: nil)
           # Try Cloudflare first - it's instant and free!
+          # But only if the IP matches what Cloudflare geolocated
           if CloudflareProvider.available?(request: request)
-            return CloudflareProvider.locate(ip, request: request)
+            if cloudflare_ip_matches?(ip, request)
+              return CloudflareProvider.locate(ip, request: request)
+            else
+              # IP mismatch: there's likely an upstream proxy before Cloudflare
+              # Cloudflare's geo headers are based on the proxy IP, not the real client
+              # Fall back to MaxMind with the correct IP
+              warn_ip_mismatch(ip, request)
+            end
           end
 
           # Fall back to MaxMind if available
@@ -45,6 +63,53 @@ module Trackdown
 
         private
 
+        # Check if the IP we want to geolocate matches what Cloudflare saw as the client
+        # If they don't match, there's an upstream proxy and Cloudflare's geo headers are wrong
+        def cloudflare_ip_matches?(ip, request)
+          return true unless request # No request means we can't check
+
+          cf_connecting_ip = request.env[CF_CONNECTING_IP_HEADER]
+          return true if cf_connecting_ip.nil? || cf_connecting_ip.empty?
+
+          # Normalize IPs for comparison (handle IPv6 formatting differences)
+          normalize_ip(ip) == normalize_ip(cf_connecting_ip)
+        end
+
+        def normalize_ip(ip)
+          return nil if ip.nil?
+
+          value = ip.to_s.strip
+          return nil if value.empty?
+
+          parsed_ip = IPAddr.new(value)
+          parsed_ip = parsed_ip.native if parsed_ip.ipv4_mapped?
+          parsed_ip.to_s.downcase
+        rescue IPAddr::InvalidAddressError
+          # If parsing fails, fall back to string comparison so we still have
+          # deterministic behavior and can trigger MaxMind fallback on mismatch.
+          value.downcase
+        end
+
+        def warn_ip_mismatch(ip, request)
+          return if @@warned_ip_mismatch
+
+          @@warn_mutex.synchronize do
+            return if @@warned_ip_mismatch
+            @@warned_ip_mismatch = true
+
+            cf_ip = request&.env&.dig(CF_CONNECTING_IP_HEADER)
+            message = "[Trackdown] IP mismatch detected: request IP (#{ip}) differs from " \
+                      "CF-Connecting-IP (#{cf_ip}). This usually means there's an upstream " \
+                      "proxy before Cloudflare. Falling back to MaxMind for accurate geolocation."
+
+            if defined?(Rails)
+              Rails.logger.info(message)
+            else
+              warn(message)
+            end
+          end
+        end
+
         def warn_no_providers
           # Only warn once per process to avoid log spam
           return if @@warned_no_providers

data/lib/trackdown/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: trackdown
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-08 00:00:00.000000000 Z
+date: 2026-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: countries