trackdown 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bef9cf45c5eb0f1cebf958c00d8b655d0840b07fe3ae3bca3732e0bdd25e2f8
+  data.tar.gz: ac99be87d20b6795d7ce156bc9ae50af70e0b4506fa61c00851f5c1abb690e39
+SHA512:
+  metadata.gz: e69d703884469e3880eb06472182e00d356884a92089074a9e4ea916b8709d22bb34de22c8d5d37e16d8aada028099f96e22a2bc2a88c6aa10610a99f04c208b
+  data.tar.gz: 18c3f1641bcec2facfbefc038d715f434e8a2f9bf5e53b1d83d85ed12d38fa008460bbe936cf47654de2686f6bdb2412fc6a90d2836107e573783e8a9fec435a

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## [0.1.0] - 2024-10-29
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# 📍 `trackdown` - Ruby gem to geolocate IPs (MaxMind BYOK)
+
+`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.
+
+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/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'trackdown'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Setup
+
+First, run the installation 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:
+
+```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'
+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`:
+
+```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.
+
+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:
+    class: TrackdownDatabaseRefreshJob
+    queue: default
+    schedule: every day 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:
+
+```ruby
+Trackdown.update_database
+```
+
+## Usage
+
+To geolocate an IP address:
+
+```ruby
+Trackdown.locate('8.8.8.8').country
+# => 'United States'
+```
+
+You can also 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')
+
+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.flag_emoji      # => '🇺🇸'
+result.emoji           # => '🇺🇸' (alias for flag_emoji)
+result.country_flag    # => '🇺🇸' (alias for flag_emoji)
+```
+
+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
+result.country_info.alpha3          # => "USA"
+result.country_info.currency_code   # => "USD"
+result.country_info.continent       # => 'North America'
+result.country_info.nationality     # => 'American'
+result.country_info.iso_long_name   # => 'The United States of America'
+```
+
+If you prefer, you can also get all the information as a hash:
+```ruby
+result.to_h
+# => {
+#      country_code: 'US',
+#      country_name: 'United States',
+#      city: 'Mountain View',
+#      flag_emoji: '🇺🇸',
+#      country_info: { ... }
+#    }
+```
+
+To manually update the MaxMind IP database:
+```ruby
+Trackdown.update_database
+```
+
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/trackdown. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/lib/generators/trackdown/install_generator.rb

@@ -0,0 +1,25 @@
+module Trackdown
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template 'trackdown.rb', 'config/initializers/trackdown.rb'
+      end
+
+      def create_database_refresh_job
+        template 'trackdown_database_refresh_job.rb', 'app/jobs/trackdown_database_refresh_job.rb'
+      end
+
+      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 "\nEnjoy `trackdown`!", :green
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Trackdown.configure do |config|
+  # Required: Your MaxMind credentials
+  config.maxmind_account_id = Rails.application.credentials.dig(:maxmind, :account_id)
+  config.maxmind_license_key = Rails.application.credentials.dig(:maxmind, :license_key)
+
+  # Optional: Configure 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: Configure IP validation (defaults to true)
+  # config.reject_private_ips = true  # Reject private/local IP addresses
+end

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

@@ -0,0 +1,7 @@
+class TrackdownDatabaseRefreshJob < ApplicationJob
+  queue_as :default
+
+  def perform(*args)
+    Trackdown.update_database
+  end
+end

data/lib/trackdown/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Trackdown
+  class Configuration
+    attr_accessor :maxmind_license_key, :maxmind_account_id, :database_path,
+                  :timeout, :pool_size, :pool_timeout, :memory_mode,
+                  :reject_private_ips
+
+    def initialize
+      @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
+      @reject_private_ips = true
+    end
+
+    def validate!
+      missing = []
+      missing << 'maxmind_license_key' if maxmind_license_key.nil?
+      missing << 'maxmind_account_id' if maxmind_account_id.nil?
+
+      raise Error, "Missing required configuration: #{missing.join(', ')} – Please set these in your config/initializers/trackdown.rb initializer." unless missing.empty?
+
+      validate_paths!
+      validate_timeouts!
+    end
+
+    def reject_private_ips?
+      @reject_private_ips
+    end
+
+    private
+
+    def validate_paths!
+      unless database_path && !database_path.empty?
+        raise Error, "database_path cannot be empty"
+      end
+    end
+
+    def validate_timeouts!
+      raise Error, "timeout must be positive" unless timeout.positive?
+      raise Error, "pool_timeout must be positive" unless pool_timeout.positive?
+      raise Error, "pool_size must be positive" unless pool_size.positive?
+    end
+  end
+end

data/lib/trackdown/database_updater.rb

@@ -0,0 +1,57 @@
+require 'open-uri'
+require 'zlib'
+require 'rubygems/package'
+
+module Trackdown
+  class DatabaseUpdater
+    DOWNLOAD_URL = "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=%{license_key}&suffix=tar.gz"
+
+    class << self
+      def update
+        download_url = DOWNLOAD_URL % { license_key: Trackdown.configuration.maxmind_license_key }
+
+        options = {
+          http_basic_authentication: [
+            Trackdown.configuration.maxmind_account_id.to_s,
+            Trackdown.configuration.maxmind_license_key.to_s
+          ],
+          ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
+        }
+
+        URI.open(download_url, **options) do |remote_file|
+          Zlib::GzipReader.wrap(remote_file) do |gz|
+            Gem::Package::TarReader.new(gz) do |tar|
+              tar.each do |entry|
+                if entry.full_name.end_with?('.mmdb')
+                  FileUtils.mkdir_p(File.dirname(Trackdown.configuration.database_path))
+
+                  File.open(Trackdown.configuration.database_path, 'wb') do |file|
+                    file.write(entry.read)
+                  end
+                  break
+                end
+              end
+            end
+          end
+        end
+
+        Rails.logger.info("MaxMind database updated successfully") if defined?(Rails)
+        true
+      rescue OpenURI::HTTPError => e
+        message = case e.message
+        when /401/
+          "Authentication failed. Please check your MaxMind account ID and license key."
+        when /403/
+          "Access forbidden. Your MaxMind license may not have access to this database."
+        else
+          "HTTP Error: #{e.message}"
+        end
+        Rails.logger.error("Error updating MaxMind database: #{message}") if defined?(Rails)
+        raise Error, message
+      rescue => e
+        Rails.logger.error("Error updating MaxMind database: #{e.message}") if defined?(Rails)
+        raise Error, "Failed to update database: #{e.message}"
+      end
+    end
+  end
+end

data/lib/trackdown/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Trackdown
+  class Error < StandardError; end
+end

data/lib/trackdown/ip_locator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'maxmind/db'
+require 'connection_pool'
+require_relative 'location_result'
+require_relative 'ip_validator'
+
+module Trackdown
+  class IpLocator
+    class TimeoutError < Trackdown::Error; end
+    class DatabaseError < Trackdown::Error; end
+
+    class << self
+      def locate(ip)
+        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)
+      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
+        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
+end

data/lib/trackdown/ip_validator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Trackdown
+  class IpValidator
+    class InvalidIpError < Trackdown::Error; end
+
+    def self.validate!(ip)
+      return if ip.nil?
+
+      begin
+        IPAddr.new(ip.to_s)
+      rescue IPAddr::InvalidAddressError
+        raise InvalidIpError, "Invalid IP address format: #{ip}"
+      end
+    end
+
+    def self.private_ip?(ip)
+      addr = IPAddr.new(ip.to_s)
+      addr.private? || addr.loopback?
+    end
+  end
+end

data/lib/trackdown/location_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'countries'
+
+module Trackdown
+  class LocationResult
+    attr_reader :country_code, :country_name, :city, :flag_emoji
+
+    def initialize(country_code, country_name, city, flag_emoji)
+      @country_code = country_code
+      @country_name = country_name
+      @city = city
+      @flag_emoji = flag_emoji
+    end
+
+    alias_method :country, :country_name
+    alias_method :emoji, :flag_emoji
+    alias_method :emoji_flag, :flag_emoji
+    alias_method :country_flag, :flag_emoji
+
+    def country_info
+      return nil unless country_code
+      ISO3166::Country.new(country_code)
+    end
+
+    def to_h
+      {
+        country_code: @country_code,
+        country_name: @country_name,
+        city: @city,
+        flag_emoji: @flag_emoji,
+        country_info: country_info&.data || {}
+      }
+    end
+  end
+end

data/lib/trackdown/version.rb

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

data/lib/trackdown.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "trackdown/error"
+require_relative "trackdown/version"
+require_relative "trackdown/configuration"
+require_relative "trackdown/ip_validator"
+require_relative "trackdown/ip_locator"
+require_relative "trackdown/database_updater"
+require_relative "trackdown/location_result"
+
+module Trackdown
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+    configuration.validate!
+  end
+
+  def self.locate(ip)
+    ensure_database_exists!
+    IpLocator.locate(ip)
+  end
+
+  def self.update_database
+    DatabaseUpdater.update
+  end
+
+  def self.database_exists?
+    File.exist?(configuration.database_path)
+  end
+
+  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."
+    end
+  end
+end

data/sig/trackdown.rbs

@@ -0,0 +1,4 @@
+module Trackdown
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: trackdown
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rameerez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-10-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: maxmind-db
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: countries
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+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.
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/trackdown/install_generator.rb
+- lib/generators/trackdown/templates/trackdown.rb
+- lib/generators/trackdown/templates/trackdown_database_refresh_job.rb
+- lib/trackdown.rb
+- lib/trackdown/configuration.rb
+- lib/trackdown/database_updater.rb
+- lib/trackdown/error.rb
+- lib/trackdown/ip_locator.rb
+- lib/trackdown/ip_validator.rb
+- lib/trackdown/location_result.rb
+- lib/trackdown/version.rb
+- sig/trackdown.rbs
+homepage: https://github.com/rameerez/trackdown
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Get country, city, and emoji flag information for IP addresses using a MaxMind
+  database
+test_files: []