trackdown 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07f58b2d8b21b6a7a7a556cb1c5ed24023e751506cc42e630f30fd10c45b1ae4
-  data.tar.gz: b307787b7160c444b8ac7e73883e38c8bcd60f8c7d532bb35a12cb9d0c957472
+  metadata.gz: 3ac258f067b151ee511c897d3460694466ed9ea36e2ff96010cccb5acf106b16
+  data.tar.gz: 1120ed37341b3fe876ed38997440537968e9014a1918b0c2c12acd3d10c36615
 SHA512:
-  metadata.gz: 8e5a9dee06f9c556d10ed33880fef9ab5f1acc4323367a73ba6721dc492790b03d28ec62ec39a405b8d76f46e3f442a1a5459883cdd3ee7b7dd904e58a811279
-  data.tar.gz: 7c2ccb29ec564cd3d70762e2746eb1cc236191687eab91757597f8e6c2074096c91524c1b64bddccef14ac93e712b1f2dbc56854c307f9536b6a24bdfbc1850a
+  metadata.gz: fd9029fb452c671613dcadb3081fc8e036634506f564b354997798d4b59617ac316c19976ae0ea2d9f4cfbc6a6d16a9a7729fc70d60d6a47354a808205bb6106
+  data.tar.gz: 94a789bbd321cb389590c466da2de5c7887812c9362d086a3d35446a428bd2a2a6a398f485d7629f86fec24e7e51a5b26d9871e512a4bb4e49f10edf9de45f7b

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI agents (OpenAI Codex, Claude Code, etc.) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.2.0] - 2026-01-02
+
+- Completely decouple Maxmind from the gem, making it optional
+- Add the provider pattern to support more Geo IP providers than MaxMind
+- Add support for Cloudflare IP headers out of the box
+
 ## [0.1.1] - 2024-10-29
 
 - Fix config validationerror on deployment

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now

data/README.md

@@ -1,13 +1,39 @@
-# 📍 `trackdown` - Ruby gem to geolocate IPs (MaxMind BYOK)
+# 📍 `trackdown` - Ruby gem to geolocate IPs
 
-`trackdown` is a Ruby gem that easily allows you to geolocate IP addresses. It's a simple, convenient wrapper on top of MaxMind. Just bring your own MaxMind keys, and you're good to go. It keeps your MaxMind database updated regularly, and it offers a handy API for Rails applications to fetch country, city, and emoji flag information for any IP address.
+`trackdown` is a Ruby gem that allows you to geolocate IP addresses easily. It works out-of-the-box with **Cloudflare** (zero config!); and it's also a simple, convenient wrapper on top of **MaxMind** (just bring your own MaxMind key, and you're good to go!). `trackdown` offers a clean API for Rails applications to fetch country, city, and emoji flag information for any IP address.
 
 Given an IP, it gives you the corresponding:
 - 🗺️ Country (two-letter country code + country name)
 - 📍 City
 - 🇺🇸 Emoji flag of the country
 
-`trackdown` is BYOK (Bring Your Own Key) – you'll need your own MaxMind keys for it to work. It's your responsibility to make sure your app complies with the license for the MaxMind database you're using. Get a MaxMind account and license key at [MaxMind](https://www.maxmind.com/).
+## Two ways to use `trackdown`
+
+### Option 1: Cloudflare (recommended, zero config)
+
+If your app is behind Cloudflare, you can use `trackdown` with **zero configuration**:
+- No API keys needed
+- No database downloads
+- No external dependencies
+- Instant lookups from Cloudflare headers
+
+Just enable "IP Geolocation" in your Cloudflare dashboard and you're done! We automatically check for the Cloudflare headers in the context of a `request` and provide you with the IP geo data.
+
+### Option 2: MaxMind (BYOK - Bring Your Own Key)
+
+For apps not behind Cloudflare, offline apps, non-Rails apps, or as a fallback, use MaxMind:
+- Requires MaxMind account and license key
+- Requires downloading and maintaining a local database
+- Works offline once database is downloaded
+- Get started at [MaxMind](https://www.maxmind.com/)
+
+### Option 3: Auto
+
+By default, `trackdown` uses **`:auto` mode** which tries Cloudflare first and falls back to MaxMind automatically.
+
+> [!NOTE]
+> Trackdown fails gracefully. If no provider is available (no Cloudflare headers, no MaxMind database), it returns `'Unknown'` instead of raising an error, so your app doesn't crash due to a missing geolocation provider.
+
 
 ## Installation
 
@@ -15,6 +41,10 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'trackdown'
+
+# Optional: Only needed if using MaxMind provider
+gem 'maxmind-db'        # For MaxMind database access
+gem 'connection_pool'   # For connection pooling
 ```
 
 And then execute:
@@ -25,79 +55,121 @@ bundle install
 
 ## Setup
 
-First, run the installation generator:
+### Quick Start (Cloudflare)
+
+If your app is behind Cloudflare, setup is super simple:
+
+1. **Enable IP Geolocation in Cloudflare**
 
+2. **That's it!** No initializer needed. Just use it:
+
+```ruby
+# In your controller
+Trackdown.locate(request.remote_ip, request: request).country
+# => 'United States'
+```
+
+### Setup with MaxMind
+
+If you want to use `trackdown` with a MaxMind database as the geo IP data provider:
+
+1. **Run the generator**:
 ```bash
 rails generate trackdown:install
 ```
 
-This will create an initializer file at `config/initializers/trackdown.rb`. Open this file and add your MaxMind license key and account ID:
+This will create an initializer file at `config/initializers/trackdown.rb`. Open this file and add your MaxMind license key and account ID next.
 
+2. **Configure your MaxMind credentials** in `config/initializers/trackdown.rb`:
 ```ruby
 Trackdown.configure do |config|
-  # Tip: do not write your plaintext keys in the code, use Rails.application.credentials instead
-  config.maxmind_account_id = 'your_account_id_here'
-  config.maxmind_license_key = 'your_license_key_here'
+  config.provider = :auto  # or :maxmind to use MaxMind exclusively
+
+  # Use Rails credentials (recommended)
+  config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)
+  config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)
 end
 ```
 
 > [!TIP]
 > To get your MaxMind account ID and license key, you need to create an account at [MaxMind](https://www.maxmind.com/) and get a license key.
 
-You can also configure the path where the MaxMind database will be stored. By default, it will be stored at `db/GeoLite2-City.mmdb`:
+3. **Download the database**:
+```ruby
+Trackdown.update_database
+```
+
+You can configure the path where the MaxMind database will be stored. By default, it will be stored at `db/GeoLite2-City.mmdb`:
 
 ```ruby
 config.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s
 ```
 
-The generator also creates a `TrackdownDatabaseRefreshJob` job for regularly updating the MaxMind database. You can just get a database the first time and just keep using it, but the information will get outdated and some IPs will become stale or inaccurate.
+4. **Schedule regular updates** (optional but recommended):
+
+The `trackdown` gem generator creates a `TrackdownDatabaseRefreshJob` job for regularly updating the MaxMind database. You can just get a database the first time and just keep using it, but the information will get outdated and some IPs will become stale or inaccurate.
 
 To keep your IP geolocation accurate, you need to make sure the `TrackdownDatabaseRefreshJob` runs regularly. How you do that, exactly, depends on the queueing system you're using.
 
+
 If you're using `solid_queue` (the Rails 8 default), you can easily add it to your schedule in the `config/recurring.yml` file like this:
+
 ```yaml
 production:
-  refresh_maxmind_database:
+  refresh_trackdown_database:
     class: TrackdownDatabaseRefreshJob
     queue: default
-    schedule: every week at 4am US/Pacific
+    schedule: every Saturday at 4am US/Pacific
 ```
 
-After setting everything up, you can run the following command to update the MaxMind database / get the first fresh copy of it:
+> [!NOTE]
+> MaxMind updates their databases [every Tuesday and Friday](https://dev.maxmind.com/geoip/geoip2/geoip2-update-process/).
+
+## Usage
+
+### With Cloudflare (recommended when available)
 
 ```ruby
-Trackdown.update_database
+# In your controller - pass the request object
+result = Trackdown.locate(request.remote_ip, request: request)
+result.country
+# => 'United States'
 ```
 
-## Usage
+### With MaxMind or without request object
 
 To geolocate an IP address:
 
 ```ruby
-Trackdown.locate('8.8.8.8').country
+# Works anywhere - just needs the IP
+result = Trackdown.locate('8.8.8.8')
+result.country
 # => 'United States'
 ```
 
-You can also do things like:
+### API Methods
+
+You can do things like:
 ```ruby
 Trackdown.locate('8.8.8.8').emoji
 # => '🇺🇸'
 ```
 
 In fact, there are a few methods you can use:
-```ruby
-result = Trackdown.locate('8.8.8.8')
 
+```ruby
 result.country_code    # => 'US'
 result.country_name    # => 'United States'
 result.country         # => 'United States' (alias for country_name)
-result.country_info    # => # A big hash of information about the country, from the `countries` gem
-result.city            # => 'Mountain View'
+result.city            # => 'Mountain View' (from MaxMind or Cloudflare's "Add visitor location headers")
 result.flag_emoji      # => '🇺🇸'
 result.emoji           # => '🇺🇸' (alias for flag_emoji)
 result.country_flag    # => '🇺🇸' (alias for flag_emoji)
+result.country_info    # => # Rich country data from the `countries` gem
 ```
 
+### Rich country information
+
 For `country_info` we're leveraging the [`countries`](https://github.com/countries/countries) gem, so you get a lot of information about the country, like the continent, the region, the languages spoken, the currency, and more:
 
 ```ruby
@@ -108,7 +180,10 @@ result.country_info.nationality     # => 'American'
 result.country_info.iso_long_name   # => 'The United States of America'
 ```
 
+### Hash data
+
 If you prefer, you can also get all the information as a hash:
+
 ```ruby
 result.to_h
 # => {
@@ -120,15 +195,66 @@ result.to_h
 #    }
 ```
 
-To manually update the MaxMind IP database:
+## Configuration
+
+### Provider Options
+
+```ruby
+Trackdown.configure do |config|
+  # :auto - Try Cloudflare first, fall back to MaxMind (default, recommended)
+  # :cloudflare - Only use Cloudflare headers
+  # :maxmind - Only use MaxMind database
+  config.provider = :auto
+end
+```
+
+### Full Configuration Example
+
+```ruby
+Trackdown.configure do |config|
+  # Provider
+  config.provider = :auto
+
+  # MaxMind settings (only needed if using MaxMind)
+  config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)
+  config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)
+  config.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s
+
+  # Performance tuning (MaxMind only - requires maxmind-db gem)
+  config.timeout = 3
+  config.pool_size = 5
+  config.pool_timeout = 3
+  # config.memory_mode = MaxMind::DB::MODE_MEMORY  # or MODE_FILE to reduce memory
+
+  # General
+  config.reject_private_ips = true  # Reject 192.168.x.x, 127.0.0.1, etc.
+end
+```
+
+### Updating the MaxMind database
+
+Only needed when using the MaxMind provider:
+
 ```ruby
 Trackdown.update_database
 ```
 
+## How It Works
+
+### Cloudflare Provider
+
+When you enable "IP Geolocation" in Cloudflare, they add the `CF-IPCountry` header to every request. If you enable "Add visitor location headers" (via Managed Transforms), you also get `CF-IPCity`.
+
+Trackdown reads these headers directly from the request with zero overhead, and no database lookups.
+
+### MaxMind Provider
+
+Downloads the GeoLite2-City database to your server and performs local lookups using connection pooling for performance.
+
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake test` to run the Minitest tests.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/Rakefile

@@ -1,4 +1,13 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: :test

data/lib/generators/trackdown/install_generator.rb

@@ -21,10 +21,18 @@ module Trackdown
 
       def display_post_install_message
         say "\tThe `trackdown` gem has been successfully installed!", :green
-        say "\nTo complete the setup:"
-        say "  1. Configure your MaxMind credentials in `config/initializers/trackdown.rb`"
-        say "  2. Run 'Trackdown.update_database' to get a fresh MaxMind IP database."
-        say "  3. Make sure you configure your queueing system to run the TrackdownDatabaseRefreshJob regularly so the IP database is updated regularly."
+        say "\nChoose your setup path:"
+        say "\n  Option 1: Cloudflare (Zero Config - Recommended)"
+        say "    1. Ensure your app is behind Cloudflare"
+        say "    2. Enable 'IP Geolocation' in Cloudflare dashboard (Network settings)"
+        say "    3. Use: Trackdown.locate(request.remote_ip, request: request)"
+        say "    That's it! No API keys, no database needed."
+        say "\n  Option 2: MaxMind (BYOK)"
+        say "    1. Configure your MaxMind credentials in `config/initializers/trackdown.rb`"
+        say "    2. Run 'Trackdown.update_database' to download the database"
+        say "    3. Schedule TrackdownDatabaseRefreshJob to run weekly"
+        say "\n  Option 3: Auto (Best of Both)"
+        say "    The default :auto mode tries Cloudflare first, falls back to MaxMind"
         say "\nEnjoy `trackdown`!", :green
       end
 

data/lib/generators/trackdown/templates/trackdown.rb

@@ -1,21 +1,74 @@
 # frozen_string_literal: true
 
 Trackdown.configure do |config|
-  # Required: Your MaxMind credentials
+  # ========================================
+  # Provider Selection
+  # ========================================
+  # Choose your IP geolocation provider:
+  #
+  # :auto (recommended, default)
+  #   - Tries Cloudflare first (instant, zero overhead)
+  #   - Falls back to MaxMind if Cloudflare not available
+  #   - Perfect for hybrid deployments
+  #
+  # :cloudflare
+  #   - Uses Cloudflare CF-IPCountry header
+  #   - Requires: App behind Cloudflare + IP Geolocation enabled
+  #   - Zero additional dependencies!
+  #   - Must pass request object: Trackdown.locate(ip, request: request)
+  #
+  # :maxmind
+  #   - Uses MaxMind GeoLite2 database
+  #   - Requires: maxmind-db and connection_pool gems
+  #   - Requires: MaxMind account and database download
+  #
+  config.provider = :auto
+
+  # ========================================
+  # Cloudflare Setup (for :cloudflare or :auto providers)
+  # ========================================
+  # 1. Ensure your app is behind Cloudflare
+  # 2. In Cloudflare dashboard → Network → Enable "IP Geolocation"
+  #    OR under Rules → Transform Rules → Managed Transforms → Enable "Add visitor location headers"
+  # 3. Use: Trackdown.locate(request.remote_ip, request: request)
+  #
+  # That's it! No gems, no API keys, no database needed.
+
+  # ========================================
+  # MaxMind Setup (for :maxmind or :auto providers)
+  # ========================================
+  # Only needed if using MaxMind provider or as fallback
+  #
+  # 1. Add to Gemfile:
+  #    gem 'maxmind-db'
+  #    gem 'connection_pool'
+  #
+  # 2. Get your MaxMind account: https://www.maxmind.com/
+  #
+  # 3. Configure credentials (using Rails credentials recommended):
   config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)
   config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)
+  #
+  # 4. Run: Trackdown.update_database
+  #
+  # 5. Schedule regular updates (MaxMind updates Tue/Fri):
+  #    Add to config/recurring.yml (for solid_queue):
+  #    refresh_trackdown_database:
+  #      class: TrackdownDatabaseRefreshJob
+  #      schedule: every Saturday at 4am
 
-  # Optional: Configure database location (defaults to db/GeoLite2-City.mmdb)
+  # Optional: Database location (defaults to db/GeoLite2-City.mmdb)
   # config.database_path = Rails.root.join('db', 'GeoLite2-City.mmdb').to_s
 
-  # Optional: Configure timeouts and pooling (defaults shown)
-  # config.timeout = 3        # Timeout for individual lookups
-  # config.pool_size = 5      # Size of the connection pool
-  # config.pool_timeout = 3   # Timeout when waiting for a connection from the pool
-
-  # Optional: Configure memory mode (defaults to MODE_MEMORY)
-  # config.memory_mode = MaxMind::DB::MODE_FILE # Use MODE_FILE to reduce memory usage
+  # Optional: MaxMind performance tuning
+  # config.timeout = 3        # Lookup timeout (seconds)
+  # config.pool_size = 5      # Connection pool size
+  # config.pool_timeout = 3   # Pool wait timeout (seconds)
+  # config.memory_mode = MaxMind::DB::MODE_MEMORY # or MODE_FILE to reduce memory
 
-  # Optional: Configure IP validation (defaults to true)
-  # config.reject_private_ips = true  # Reject private/local IP addresses
+  # ========================================
+  # General Options
+  # ========================================
+  # Reject private/local IP addresses (192.168.x.x, 127.0.0.1, etc.)
+  # config.reject_private_ips = true
 end

data/lib/trackdown/configuration.rb

@@ -1,25 +1,46 @@
 # frozen_string_literal: true
 
+# Conditionally require MaxMind constants if available
+begin
+  require 'maxmind/db'
+  MAXMIND_AVAILABLE = true
+rescue LoadError
+  MAXMIND_AVAILABLE = false
+end
+
 module Trackdown
   class Configuration
-    attr_accessor :maxmind_license_key, :maxmind_account_id, :database_path,
+    attr_accessor :provider, :maxmind_license_key, :maxmind_account_id, :database_path,
                   :timeout, :pool_size, :pool_timeout, :memory_mode,
                   :reject_private_ips
 
+    # Available provider types:
+    # :auto - Try Cloudflare first, fall back to MaxMind (recommended)
+    # :cloudflare - Only use Cloudflare headers
+    # :maxmind - Only use MaxMind database
+    VALID_PROVIDERS = [:auto, :cloudflare, :maxmind].freeze
+
     def initialize
+      @provider = :auto # Intelligent default: try Cloudflare first, fall back to MaxMind
       @maxmind_license_key = nil
       @maxmind_account_id = nil
       @database_path = defined?(Rails) ? Rails.root.join('db', 'GeoLite2-City.mmdb').to_s : 'db/GeoLite2-City.mmdb'
       @timeout = 3 # seconds
       @pool_size = 5
       @pool_timeout = 3 # seconds
-      @memory_mode = MaxMind::DB::MODE_MEMORY
+      @memory_mode = MAXMIND_AVAILABLE ? MaxMind::DB::MODE_MEMORY : nil
       @reject_private_ips = true
     end
 
+    def provider=(value)
+      unless VALID_PROVIDERS.include?(value)
+        raise ArgumentError, "Invalid provider: #{value}. Must be one of: #{VALID_PROVIDERS.join(', ')}"
+      end
+      @provider = value
+    end
+
     def reject_private_ips?
       @reject_private_ips
     end
-
   end
 end

data/lib/trackdown/ip_locator.rb

@@ -1,83 +1,42 @@
 # frozen_string_literal: true
 
-require 'maxmind/db'
-require 'connection_pool'
 require_relative 'location_result'
 require_relative 'ip_validator'
+require_relative 'providers/auto_provider'
+require_relative 'providers/cloudflare_provider'
+require_relative 'providers/maxmind_provider'
 
 module Trackdown
   class IpLocator
-    class TimeoutError < Trackdown::Error; end
-    class DatabaseError < Trackdown::Error; end
-
     class << self
-      def locate(ip)
+      # 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 for Cloudflare provider
+      # @return [LocationResult] The location information
+      def locate(ip, request: nil)
         IpValidator.validate!(ip)
 
         if Trackdown.configuration.reject_private_ips? && IpValidator.private_ip?(ip)
           raise IpValidator::InvalidIpError, "Private IP addresses are not allowed"
         end
 
-        record = fetch_record(ip)
-        return LocationResult.new(nil, 'Unknown', 'Unknown', '🏳️') 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)
-
-        LocationResult.new(country_code, country_name, city, flag_emoji)
+        provider = get_provider
+        provider.locate(ip, request: request)
       end
 
       private
 
-      def fetch_record(ip)
-        Trackdown.ensure_database_exists!
-
-        Timeout.timeout(Trackdown.configuration.timeout) do
-          reader_pool.with do |reader|
-            reader.get(ip)
-          end
+      def get_provider
+        case Trackdown.configuration.provider
+        when :auto
+          Providers::AutoProvider
+        when :cloudflare
+          Providers::CloudflareProvider
+        when :maxmind
+          Providers::MaxmindProvider
+        else
+          raise Trackdown::Error, "Unknown provider: #{Trackdown.configuration.provider}"
         end
-      rescue Timeout::Error
-        raise TimeoutError, "MaxMind database lookup timed out after #{Trackdown.configuration.timeout} seconds"
-      rescue Trackdown::Error => e
-        raise e
-      rescue StandardError => e
-        Rails.logger.error("Error fetching IP data: #{e.message}") if defined?(Rails)
-        raise DatabaseError, "Database error: #{e.message}"
-      end
-
-      def reader_pool
-        @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
-          )
-        end
-      end
-
-      def extract_country_code(record)
-        record&.dig('country', 'iso_code')
-      end
-
-      def extract_country_name(record)
-        record&.dig('country', 'names', 'en') ||
-          (record&.dig('country', 'names')&.values&.first) ||
-          'Unknown'
-      end
-
-      def extract_city(record)
-        record&.dig('city', 'names', 'en') ||
-          (record&.dig('city', 'names')&.values&.first) ||
-          'Unknown'
-      end
-
-      def get_emoji_flag(country_code)
-        country_code ? country_code.tr('A-Z', "\u{1F1E6}-\u{1F1FF}") : "🏳️"
       end
     end
   end

data/lib/trackdown/providers/auto_provider.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base_provider'
+require_relative 'cloudflare_provider'
+require_relative 'maxmind_provider'
+
+module Trackdown
+  module Providers
+    # 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)
+    #
+    # This is the recommended default for most applications
+    class AutoProvider < BaseProvider
+      @@warned_no_providers = false
+      @@warn_mutex = Mutex.new
+
+      class << self
+        # Auto provider is available if at least one provider is available
+        def available?(request: nil)
+          CloudflareProvider.available?(request: request) ||
+            MaxmindProvider.available?(request: request)
+        end
+
+        # Intelligently locate IP using the best available provider
+        # @param ip [String] The IP address to locate
+        # @param request [ActionDispatch::Request, nil] Optional Rails request object
+        # @return [LocationResult] The location information
+        def locate(ip, request: nil)
+          # Try Cloudflare first - it's instant and free!
+          if CloudflareProvider.available?(request: request)
+            return CloudflareProvider.locate(ip, request: request)
+          end
+
+          # Fall back to MaxMind if available
+          if MaxmindProvider.available?(request: request)
+            return MaxmindProvider.locate(ip, request: request)
+          end
+
+          # No providers available - fail gracefully with a warning
+          warn_no_providers
+          LocationResult.new(nil, 'Unknown', 'Unknown', '🏳️')
+        end
+
+        private
+
+        def warn_no_providers
+          # Only warn once per process to avoid log spam
+          return if @@warned_no_providers
+
+          @@warn_mutex.synchronize do
+            return if @@warned_no_providers
+            @@warned_no_providers = true
+
+            message = "[Trackdown] No IP geolocation provider available. Returning 'Unknown' for all lookups. " \
+                      "Configure Cloudflare headers or MaxMind to enable geolocation. " \
+                      "See: https://github.com/rameerez/trackdown"
+
+            if defined?(Rails)
+              Rails.logger.warn(message)
+            else
+              warn(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trackdown/providers/base_provider.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'countries'
+
+module Trackdown
+  module Providers
+    class BaseProvider
+      # Returns true if this provider can handle the given request/context
+      def self.available?(request: nil)
+        raise NotImplementedError, "#{self} must implement .available?"
+      end
+
+      # Locates the IP and returns a LocationResult
+      # @param ip [String] The IP address to locate
+      # @param request [ActionDispatch::Request, nil] Optional Rails request object for header access
+      # @return [LocationResult] The location information
+      def self.locate(ip, request: nil)
+        raise NotImplementedError, "#{self} must implement .locate"
+      end
+
+      protected
+
+      # 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}") : "🏳️"
+      end
+
+      # Helper to extract country name from country code using countries gem
+      def self.get_country_name(country_code)
+        return 'Unknown' unless country_code
+
+        country = ISO3166::Country.new(country_code)
+        country&.iso_short_name || country&.name || 'Unknown'
+      rescue StandardError
+        'Unknown'
+      end
+    end
+  end
+end

data/lib/trackdown/providers/cloudflare_provider.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base_provider'
+require_relative '../location_result'
+
+module Trackdown
+  module Providers
+    # Provider that uses Cloudflare HTTP headers for IP geolocation
+    # This is the fastest and most lightweight option when your app is behind Cloudflare
+    #
+    # Cloudflare must have "IP Geolocation" or "Add visitor location headers" enabled
+    # in the dashboard under Network settings or via Managed Transforms
+    class CloudflareProvider < BaseProvider
+      COUNTRY_HEADER = 'HTTP_CF_IPCOUNTRY'
+      CITY_HEADER = 'HTTP_CF_IPCITY'
+
+      # Special Cloudflare country codes
+      UNKNOWN_CODE = 'XX'
+      TOR_CODE = 'T1'
+
+      class << self
+        # 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
+        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)
+          raise Trackdown::Error, "CloudflareProvider requires a request object with Cloudflare headers" unless 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
+
+          country_name = get_country_name(country_code)
+          city = extract_city(request)
+          flag_emoji = get_emoji_flag(country_code)
+
+          LocationResult.new(country_code, country_name, city, flag_emoji)
+        end
+
+        private
+
+        def extract_country_code(request)
+          code = request.env[COUNTRY_HEADER]
+          return nil if code.nil? || code.empty? || code == UNKNOWN_CODE
+
+          code.upcase
+        end
+
+        def extract_city(request)
+          city = request.env[CITY_HEADER]
+
+          # Cloudflare city header might not always be present
+          # It requires "Add visitor location headers" Managed Transform
+          return 'Unknown' if city.nil? || city.empty?
+
+          city
+        end
+      end
+    end
+  end
+end

data/lib/trackdown/providers/maxmind_provider.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require_relative 'base_provider'
+require_relative '../location_result'
+
+# Conditionally require MaxMind - this is an optional dependency
+begin
+  require 'maxmind/db'
+  require 'connection_pool'
+rescue LoadError
+  # MaxMind gem not available - that's ok, other providers might be used
+end
+
+module Trackdown
+  module Providers
+    # Provider that uses MaxMind GeoLite2 database for IP geolocation
+    # Requires the maxmind-db gem and a downloaded database file
+    class MaxmindProvider < BaseProvider
+      class TimeoutError < Trackdown::Error; end
+      class DatabaseError < Trackdown::Error; end
+
+      @@reader_pool = nil
+      @@pool_mutex = Mutex.new
+
+      class << self
+        # Check if MaxMind database is available
+        def available?(request: nil)
+          return false unless maxmind_available?
+          return false unless Trackdown.database_exists?
+
+          true
+        end
+
+        # Locate IP using MaxMind database
+        # @param ip [String] The IP address to locate
+        # @param request [ActionDispatch::Request, nil] Not used by MaxMind provider
+        # @return [LocationResult] The location information
+        def locate(ip, request: nil)
+          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?
+
+          country_code = extract_country_code(record)
+          country_name = extract_country_name(record)
+          city = extract_city(record)
+          flag_emoji = get_emoji_flag(country_code)
+
+          LocationResult.new(country_code, country_name, city, flag_emoji)
+        end
+
+        private
+
+        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)
+            end
+          end
+        rescue Timeout::Error
+          raise TimeoutError, "MaxMind database lookup timed out after #{Trackdown.configuration.timeout} seconds"
+        rescue Trackdown::Error => e
+          raise e
+        rescue StandardError => e
+          Rails.logger.error("Error fetching IP data: #{e.message}") if defined?(Rails)
+          raise DatabaseError, "Database error: #{e.message}"
+        end
+
+        def reader_pool
+          return @@reader_pool if @@reader_pool
+
+          @@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
+              )
+            end
+          end
+        end
+
+        def extract_country_code(record)
+          record&.dig('country', 'iso_code')
+        end
+
+        def extract_country_name(record)
+          record&.dig('country', 'names', 'en') ||
+            (record&.dig('country', 'names')&.values&.first) ||
+            'Unknown'
+        end
+
+        def extract_city(record)
+          record&.dig('city', 'names', 'en') ||
+            (record&.dig('city', 'names')&.values&.first) ||
+            'Unknown'
+        end
+      end
+    end
+  end
+end

data/lib/trackdown/version.rb

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

data/lib/trackdown.rb

@@ -7,6 +7,10 @@ require_relative "trackdown/ip_validator"
 require_relative "trackdown/ip_locator"
 require_relative "trackdown/database_updater"
 require_relative "trackdown/location_result"
+require_relative "trackdown/providers/base_provider"
+require_relative "trackdown/providers/cloudflare_provider"
+require_relative "trackdown/providers/maxmind_provider"
+require_relative "trackdown/providers/auto_provider"
 
 module Trackdown
   class << self
@@ -21,11 +25,15 @@ module Trackdown
     yield(configuration)
   end
 
-  def self.locate(ip)
-    ensure_database_exists!
-    IpLocator.locate(ip)
+  # 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)
+  # @return [LocationResult] The location information
+  def self.locate(ip, request: nil)
+    IpLocator.locate(ip, request: request)
   end
 
+  # Update the MaxMind database (only needed when using MaxMind provider)
   def self.update_database
     DatabaseUpdater.update
   end
@@ -34,6 +42,8 @@ module Trackdown
     File.exist?(configuration.database_path)
   end
 
+  # Legacy method - kept for backwards compatibility
+  # New code should handle provider-specific errors instead
   def self.ensure_database_exists!
     unless database_exists?
       raise Error, "MaxMind database not found. Please set your MaxMind keys in config/initializers/trackdown.rb as described in the `trackdown` gem README, and then run Trackdown.update_database to download the MaxMind IP geolocation database."

metadata

@@ -1,73 +1,100 @@
 --- !ruby/object:Gem::Specification
 name: trackdown
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - rameerez
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-29 00:00:00.000000000 Z
+date: 2026-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: maxmind-db
+  name: countries
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
-  name: connection_pool
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
-  type: :runtime
+        version: '13.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.4'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: countries
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
-  type: :runtime
+        version: '1.21'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '1.21'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.25'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '5.25'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -81,31 +108,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: maxmind-db
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.21'
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.21'
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 description: Trackdown is a Ruby gem that easily allows you to geolocate IP addresses.
-  It's a simple, convenient wrapper on top of the MaxMind database. Plug your MaxMind
-  license key and you're good to go. It keeps your MaxMind database updated regularly,
-  and it offers a handy API for Rails applications to fetch country, city, and emoji
-  flag information for any IP address.
+  It works out of the box with Cloudflare headers if you're using it, or you can use
+  MaxMind (BYOK). The gem offers a clean API for Rails applications to fetch country,
+  city, and emoji flag information for any IP address. Supports Cloudflare headers
+  (instant, zero overhead) and MaxMind GeoLite2 database (offline capable).
 email:
 - rubygems@rameerez.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -119,6 +162,10 @@ files:
 - lib/trackdown/ip_locator.rb
 - lib/trackdown/ip_validator.rb
 - lib/trackdown/location_result.rb
+- lib/trackdown/providers/auto_provider.rb
+- lib/trackdown/providers/base_provider.rb
+- lib/trackdown/providers/cloudflare_provider.rb
+- lib/trackdown/providers/maxmind_provider.rb
 - lib/trackdown/version.rb
 - sig/trackdown.rbs
 homepage: https://github.com/rameerez/trackdown
@@ -129,7 +176,6 @@ metadata:
   homepage_uri: https://github.com/rameerez/trackdown
   source_code_uri: https://github.com/rameerez/trackdown
   changelog_uri: https://github.com/rameerez/trackdown/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -144,9 +190,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: Get country, city, and emoji flag information for IP addresses using a MaxMind
-  database
+summary: Get country, city, and emoji flag information for IP addresses using Cloudflare
+  or MaxMind
 test_files: []