ip_geo_lookup 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52397b7053c8f2c5428972a08b16b488685a7e64da77ae439e818f0514d36edf
+  data.tar.gz: dcc0e4973ef2df48e0757c7aa5b283bae9a9f67806c3791f0a09145b67bbde3a
+SHA512:
+  metadata.gz: f2a3490f5bd62a47a98774019dc7725701480bedf937ed5fb18f216cb64b8f52efcc1fbaf97dc894e5e9a051ff9a9bc882cfda04555d67ed561bdb0f8a7027e7
+  data.tar.gz: 0a8c4db162262c7f61be45d08987e41d71337c15dfd61d4fa2c90245028c3032ad9ea486ffeae2a8426bd32839aa9a274f440b49e42d6614c783611058d0a792

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-30
+
+### Added
+
+- Pure Ruby MMDB reader - reads MaxMind's native binary format with zero external dependencies
+- IPv4 and IPv6 geolocation lookup via `IpGeoLookup.lookup(ip_string)`
+- `Result` with 10 fields: `country_code`, `country_name`, `region`, `city`, `continent_code`, `continent_name`, `latitude`, `longitude`, `time_zone`, `postal_code` - plus `raw` for the full MMDB record
+- `Result` supports object-style (`result.city`), hash-style (`result[:city]`), `to_h`, `to_s`, `Comparable`
+- `IpAddress.parse` for single-pass IP validation and integer conversion; rejects leading-zero octets (`"08.8.8.8"` returns nil)
+- `IpGeoLookup.configure` for custom database path and I/O mode
+- `IpGeoLookup.reload!`, `.close`, `.reset!`, `.metadata`
+- Thread safety via `Mutex` for all shared state
+- Two I/O modes: `:file` (default, `pread`-based, fork-friendly) and `:memory` (loads entire DB into a String)
+- Support for MMDB record sizes 24, 28, and 32
+- IPv4 lookups in IPv6 databases (automatic 96-bit prefix walk)
+- Use-after-close protection (`ClosedError`)
+- GeoLite2-City.mmdb ships with the gem - no setup, no API keys, no downloads
+- CI via GitHub Actions: test matrix (Ruby 2.6, 3.0, 4.0), StandardRB linting, automated gem publishing
+- Dependabot for actions and bundler dependency updates
+
+[Unreleased]: https://github.com/msuliq/ip_geo_lookup/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/msuliq/ip_geo_lookup/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleyman Musayev
+
+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,156 @@
+# IpGeoLookup
+
+A lightweight, **zero-dependency** Ruby gem for resolving IPv4 and IPv6 addresses to geographic locations. Ships with an embedded [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolite2-databases) database and a pure Ruby MMDB reader - no external gems, no API keys, no setup.
+
+## Features
+
+- **Zero dependencies** - pure Ruby MMDB reader, no native extensions, no external gems
+- **IPv4 and IPv6** - resolves to country, region, city, coordinates, timezone, and more
+- **Batteries included** - GeoLite2 City database ships with the gem
+- **Fast** - binary trie traversal over MaxMind's MMDB format
+- **Secure** - no `Marshal.load`, rejects ambiguous IP octets with leading zeros
+- **Thread-safe** - safe for Puma, Sidekiq, and other multi-threaded servers
+- **Fork-friendly** - `:file` mode uses `pread` for shared OS page cache across workers
+- **Configurable** - use the embedded database or point to your own `.mmdb` file
+
+## Installation
+
+```ruby
+gem "ip_geo_lookup"
+```
+
+```sh
+bundle install
+```
+
+That's it - the database is included.
+
+## Usage
+
+### Basic lookup
+
+```ruby
+require "ip_geo_lookup"
+
+result = IpGeoLookup.lookup("8.8.8.8")
+result = IpGeoLookup.lookup("2001:4860:4860::8888")
+```
+
+### Accessing results
+
+```ruby
+result = IpGeoLookup.lookup("8.8.8.8")
+
+# Core fields
+result.country_code  # => "US"
+result.country_name  # => "United States"
+result.region        # => "California"
+result.city          # => "Mountain View"
+
+# Extended fields
+result.continent_code  # => "NA"
+result.continent_name  # => "North America"
+result.latitude        # => 37.386
+result.longitude       # => -122.0838
+result.time_zone       # => "America/Los_Angeles"
+result.postal_code     # => "94035"
+
+# Hash-style access
+result[:country_code]  # => "US"
+
+# Full MMDB record
+result.raw  # => {"country" => {"iso_code" => "US", ...}, ...}
+
+# Conversions
+result.to_h  # => {country_code: "US", country_name: "United States", ...}
+result.to_s  # => "Mountain View, California, United States (US)"
+
+# Sorting
+results = ips.map { |ip| IpGeoLookup.lookup(ip) }.compact.sort
+```
+
+### Handling unknown IPs
+
+Returns `nil` when the IP address is not found or is invalid:
+
+```ruby
+IpGeoLookup.lookup("192.168.1.1")  # => nil  (private range)
+IpGeoLookup.lookup("not_an_ip")    # => nil  (invalid format)
+IpGeoLookup.lookup("08.8.8.8")     # => nil  (leading zeros rejected)
+IpGeoLookup.lookup(nil)            # => nil
+```
+
+### Configuration
+
+```ruby
+IpGeoLookup.configure do |config|
+  config.database_path = "/path/to/GeoLite2-City.mmdb"
+  config.mode = :memory  # optional: load entire DB into memory for single-process apps
+end
+```
+
+### Lifecycle
+
+```ruby
+IpGeoLookup.reload!   # re-reads from disk, respects configured path
+IpGeoLookup.close     # releases file handle / memory
+IpGeoLookup.metadata  # => {"database_type" => "GeoLite2-City", ...}
+```
+
+## How It Works
+
+The gem includes a pure Ruby reader for MaxMind's [MMDB binary format](https://maxmind.github.io/MaxMind-DB/). On lookup:
+
+1. The IP string is validated and converted to an integer in a single pass
+2. The MMDB binary trie is walked (32 bits for IPv4, 128 for IPv6)
+3. The matching record is decoded from the data section
+4. A `Result` object is returned (or `nil` if no match)
+
+Two I/O modes are available:
+
+- **`:file`** (default) - keeps the file open and uses `IO#pread` for reads; the OS page cache shares data across forked workers automatically
+- **`:memory`** - reads the entire file into a Ruby String for fastest lookups in single-process environments
+
+## Compatibility
+
+- Ruby >= 2.6.0
+- Zero external dependencies
+- Thread-safe
+- Linux, macOS, Windows
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+Test fixtures are generated automatically during the test run - no external database file needed.
+
+### Updating the MaxMind database
+
+The embedded GeoLite2 City database lives in `data/GeoLite2-City.mmdb` (gitignored due to size). To update it:
+
+1. Create a free account at [MaxMind](https://www.maxmind.com/en/geolite2/signup)
+2. Download the GeoLite2 City MMDB file
+3. Copy it into the gem:
+   ```sh
+   cp /path/to/GeoLite2-City.mmdb data/GeoLite2-City.mmdb
+   ```
+4. Rebuild the gem: `gem build ip_geo_lookup.gemspec`
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+Available as open source under the [MIT License](LICENSE).
+
+## Attribution
+
+This product includes GeoLite2 data created by MaxMind, available from [https://www.maxmind.com](https://www.maxmind.com).

data/lib/ip_geo_lookup/ip_address.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module IpGeoLookup
+  module IpAddress
+    module_function
+
+    # Returns [integer, version] or nil. Rejects leading-zero octets.
+    def parse(ip_string)
+      return nil unless ip_string.is_a?(String)
+
+      addr = ip_string.strip
+      if addr.include?(":")
+        int = to_i_v6(addr)
+        int ? [int, 6] : nil
+      elsif addr.include?(".")
+        int = to_i(addr)
+        int ? [int, 4] : nil
+      end
+    end
+
+    # IPv4 string to 32-bit integer. Rejects leading-zero octets.
+    def to_i(ip_string)
+      return nil unless ip_string.is_a?(String)
+
+      octets = ip_string.strip.split(".")
+      return nil unless octets.length == 4
+
+      result = 0
+      octets.each do |octet|
+        return nil unless octet.match?(/\A(0|[1-9]\d{0,2})\z/)
+        value = octet.to_i
+        return nil if value > 255
+        result = (result << 8) | value
+      end
+      result
+    end
+
+    # IPv6 string to 128-bit integer. Supports :: shorthand.
+    def to_i_v6(ip_string)
+      return nil unless ip_string.is_a?(String)
+
+      addr = ip_string.strip.downcase
+      return nil if addr.empty? || addr.include?("%")
+
+      if addr.include?("::")
+        return nil if addr.scan("::").length > 1
+
+        left, right = addr.split("::", -1)
+        left_groups = left.empty? ? [] : left.split(":")
+        right_groups = right.empty? ? [] : right.split(":")
+        fill_count = 8 - left_groups.length - right_groups.length
+        return nil if fill_count < 0
+
+        groups = left_groups + Array.new(fill_count, "0") + right_groups
+      else
+        groups = addr.split(":")
+      end
+
+      return nil unless groups.length == 8
+
+      result = 0
+      groups.each do |group|
+        return nil unless group.match?(/\A[0-9a-f]{1,4}\z/)
+        result = (result << 16) | group.to_i(16)
+      end
+      result
+    end
+  end
+end

data/lib/ip_geo_lookup/mmdb.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module IpGeoLookup
+  # Pure Ruby reader for MaxMind's MMDB binary format.
+  class MMDB
+    MODE_MEMORY = :memory
+    MODE_FILE = :file
+
+    METADATA_MARKER = "\xAB\xCD\xEFMaxMind.com".b.freeze
+
+    attr_reader :metadata
+
+    def initialize(path, mode: MODE_MEMORY)
+      raise DatabaseNotFoundError, "Database file not found: #{path}" unless File.exist?(path)
+
+      @closed = false
+
+      case mode
+      when MODE_MEMORY
+        @data = File.binread(path)
+        @use_file = false
+      when MODE_FILE
+        @io = File.open(path, "rb")
+        @file_size = @io.size
+        @use_file = true
+        @has_pread = @io.respond_to?(:pread)
+        @file_mutex = Mutex.new unless @has_pread
+      else
+        raise ArgumentError, "Unknown mode: #{mode}. Use :memory or :file"
+      end
+
+      load_metadata
+    end
+
+    # Returns the MMDB record Hash for the given IP integer, or nil.
+    def find(ip_int, bit_count)
+      raise ClosedError, "Reader is closed" if @closed
+
+      if bit_count == 32 && @ip_version == 6
+        start = ipv4_start_node
+        return nil if start >= @node_count
+        search_tree(ip_int, 32, start)
+      elsif bit_count == 128 && @ip_version == 4
+        nil
+      else
+        search_tree(ip_int, bit_count, 0)
+      end
+    end
+
+    def close
+      @closed = true
+      if @use_file
+        @io&.close
+        @io = nil
+      else
+        @data = nil
+      end
+    end
+
+    private
+
+    def read_bytes(offset, length)
+      if @use_file
+        if @has_pread
+          @io.pread(length, offset)
+        else
+          @file_mutex.synchronize {
+            @io.seek(offset)
+            @io.read(length)
+          }
+        end
+      else
+        @data.byteslice(offset, length)
+      end
+    end
+
+    # --- Metadata ---
+
+    def load_metadata
+      size = @use_file ? @file_size : @data.bytesize
+      search_size = [size, 131_072].min
+      chunk = read_bytes(size - search_size, search_size)
+      pos = chunk.rindex(METADATA_MARKER)
+      raise DatabaseFormatError, "MMDB metadata marker not found" unless pos
+
+      meta_offset = (size - search_size) + pos + METADATA_MARKER.bytesize
+      @metadata, _ = decode(meta_offset)
+      raise DatabaseFormatError, "Invalid metadata" unless @metadata.is_a?(Hash)
+
+      @node_count = @metadata["node_count"] || raise(DatabaseFormatError, "Missing node_count")
+      @record_size = @metadata["record_size"] || raise(DatabaseFormatError, "Missing record_size")
+      @ip_version = @metadata["ip_version"] || raise(DatabaseFormatError, "Missing ip_version")
+
+      unless [24, 28, 32].include?(@record_size)
+        raise DatabaseFormatError, "Unsupported record size: #{@record_size}"
+      end
+
+      @node_byte_size = @record_size / 4
+      @search_tree_size = @node_count * @node_byte_size
+      @data_section_offset = @search_tree_size + 16
+    end
+
+    # --- Search tree ---
+
+    def ipv4_start_node
+      @ipv4_start_node ||= begin
+        node = 0
+        96.times do
+          break if node >= @node_count
+          node, _ = read_node(node)
+        end
+        node
+      end
+    end
+
+    def search_tree(ip_int, bit_count, start_node)
+      node = start_node
+
+      bit_count.times do |i|
+        left, right = read_node(node)
+        record = (((ip_int >> (bit_count - 1 - i)) & 1) == 0) ? left : right
+
+        if record < @node_count
+          node = record
+        elsif record == @node_count
+          return nil
+        else
+          value, _ = decode(@search_tree_size + record - @node_count)
+          return value
+        end
+      end
+
+      nil
+    end
+
+    # Reads one node in a single I/O call, returns [left, right].
+    def read_node(node_number)
+      buf = read_bytes(node_number * @node_byte_size, @node_byte_size)
+
+      case @record_size
+      when 24
+        left = (buf.getbyte(0) << 16) | (buf.getbyte(1) << 8) | buf.getbyte(2)
+        right = (buf.getbyte(3) << 16) | (buf.getbyte(4) << 8) | buf.getbyte(5)
+      when 28
+        mid = buf.getbyte(3)
+        left = ((mid >> 4) << 24) |
+          (buf.getbyte(0) << 16) | (buf.getbyte(1) << 8) | buf.getbyte(2)
+        right = ((mid & 0x0F) << 24) |
+          (buf.getbyte(4) << 16) | (buf.getbyte(5) << 8) | buf.getbyte(6)
+      when 32
+        left, right = buf.unpack("NN")
+      end
+
+      [left, right]
+    end
+
+    # --- Data decoder ---
+
+    def decode(offset)
+      ctrl = read_bytes(offset, 1).getbyte(0)
+      offset += 1
+
+      type = (ctrl >> 5) & 7
+      if type == 0
+        type = read_bytes(offset, 1).getbyte(0) + 7
+        offset += 1
+      end
+
+      return decode_pointer(ctrl, offset) if type == 1
+
+      size, offset = read_payload_size(ctrl, offset)
+
+      case type
+      when 2 then [read_bytes(offset, size).force_encoding("UTF-8"), offset + size]
+      when 3 then [read_bytes(offset, 8).unpack1("G"), offset + 8]
+      when 4 then [read_bytes(offset, size), offset + size]
+      when 5, 6, 9, 10 then decode_uint(size, offset)
+      when 7 then decode_map(size, offset)
+      when 8 then decode_int32(size, offset)
+      when 11 then decode_array(size, offset)
+      when 14 then [size != 0, offset]
+      when 15 then [read_bytes(offset, 4).unpack1("g"), offset + 4]
+      else raise DatabaseFormatError, "Unknown MMDB data type: #{type}"
+      end
+    end
+
+    def read_payload_size(ctrl, offset)
+      size = ctrl & 0x1F
+      if size < 29
+        [size, offset]
+      elsif size == 29
+        [29 + read_bytes(offset, 1).getbyte(0), offset + 1]
+      elsif size == 30
+        buf = read_bytes(offset, 2)
+        [285 + ((buf.getbyte(0) << 8) | buf.getbyte(1)), offset + 2]
+      else
+        buf = read_bytes(offset, 3)
+        [65_821 + ((buf.getbyte(0) << 16) | (buf.getbyte(1) << 8) | buf.getbyte(2)), offset + 3]
+      end
+    end
+
+    def decode_pointer(ctrl, offset)
+      ptr_size = (ctrl >> 3) & 3
+
+      case ptr_size
+      when 0
+        ptr = ((ctrl & 7) << 8) | read_bytes(offset, 1).getbyte(0)
+        offset += 1
+      when 1
+        buf = read_bytes(offset, 2)
+        ptr = (((ctrl & 7) << 16) | (buf.getbyte(0) << 8) | buf.getbyte(1)) + 2048
+        offset += 2
+      when 2
+        buf = read_bytes(offset, 3)
+        ptr = (((ctrl & 7) << 24) | (buf.getbyte(0) << 16) | (buf.getbyte(1) << 8) | buf.getbyte(2)) + 526_336
+        offset += 3
+      when 3
+        buf = read_bytes(offset, 4)
+        ptr = (buf.getbyte(0) << 24) | (buf.getbyte(1) << 16) | (buf.getbyte(2) << 8) | buf.getbyte(3)
+        offset += 4
+      end
+
+      value, _ = decode(@data_section_offset + ptr)
+      [value, offset]
+    end
+
+    def decode_uint(size, offset)
+      return [0, offset] if size == 0
+      buf = read_bytes(offset, size)
+      val = 0
+      size.times { |i| val = (val << 8) | buf.getbyte(i) }
+      [val, offset + size]
+    end
+
+    def decode_map(size, offset)
+      map = {}
+      size.times do
+        key, offset = decode(offset)
+        val, offset = decode(offset)
+        map[key] = val
+      end
+      [map, offset]
+    end
+
+    def decode_array(size, offset)
+      arr = []
+      size.times do
+        val, offset = decode(offset)
+        arr << val
+      end
+      [arr, offset]
+    end
+
+    def decode_int32(size, offset)
+      val, offset = decode_uint(size, offset)
+      val -= (1 << 32) if val >= (1 << 31)
+      [val, offset]
+    end
+  end
+
+  class DatabaseNotFoundError < StandardError; end
+  class DatabaseFormatError < StandardError; end
+  class ClosedError < StandardError; end
+end

data/lib/ip_geo_lookup/result.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module IpGeoLookup
+  class Result
+    include Comparable
+
+    FIELDS = [
+      :country_code, :country_name, :region, :city,
+      :continent_code, :continent_name,
+      :latitude, :longitude, :time_zone, :postal_code
+    ].freeze
+
+    attr_reader :country_code, :country_name, :region, :city,
+      :continent_code, :continent_name,
+      :latitude, :longitude, :time_zone, :postal_code,
+      :raw
+
+    def initialize(country_code:, country_name:, region:, city:,
+      continent_code: nil, continent_name: nil,
+      latitude: nil, longitude: nil,
+      time_zone: nil, postal_code: nil,
+      raw: nil)
+      @country_code = country_code
+      @country_name = country_name
+      @region = region
+      @city = city
+      @continent_code = continent_code
+      @continent_name = continent_name
+      @latitude = latitude
+      @longitude = longitude
+      @time_zone = time_zone
+      @postal_code = postal_code
+      @raw = raw
+    end
+
+    def [](key)
+      case key.to_sym
+      when :country_code then @country_code
+      when :country_name then @country_name
+      when :region then @region
+      when :city then @city
+      when :continent_code then @continent_code
+      when :continent_name then @continent_name
+      when :latitude then @latitude
+      when :longitude then @longitude
+      when :time_zone then @time_zone
+      when :postal_code then @postal_code
+      when :raw then @raw
+      end
+    end
+
+    def to_h
+      {
+        country_code: @country_code,
+        country_name: @country_name,
+        region: @region,
+        city: @city,
+        continent_code: @continent_code,
+        continent_name: @continent_name,
+        latitude: @latitude,
+        longitude: @longitude,
+        time_zone: @time_zone,
+        postal_code: @postal_code
+      }
+    end
+
+    def to_a
+      [@country_code, @country_name, @region, @city,
+        @continent_code, @continent_name,
+        @latitude, @longitude, @time_zone, @postal_code]
+    end
+
+    def members
+      FIELDS.dup
+    end
+
+    def to_s
+      location = [@city, @region, @country_name].reject { |s| s.nil? || s.empty? }.join(", ")
+      if @country_code && !@country_code.empty?
+        location.empty? ? @country_code : "#{location} (#{@country_code})"
+      else
+        location
+      end
+    end
+
+    def inspect
+      "#<IpGeoLookup::Result #{self}>"
+    end
+
+    def <=>(other)
+      return nil unless other.is_a?(Result)
+      [country_code.to_s, region.to_s, city.to_s] <=> [other.country_code.to_s, other.region.to_s, other.city.to_s]
+    end
+
+    # Equality based on to_h; raw is intentionally excluded.
+    def ==(other)
+      return false unless other.is_a?(Result)
+      to_h == other.to_h
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      to_h.hash
+    end
+  end
+end

data/lib/ip_geo_lookup/version.rb

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

data/lib/ip_geo_lookup.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "ip_geo_lookup/version"
+require_relative "ip_geo_lookup/result"
+require_relative "ip_geo_lookup/ip_address"
+require_relative "ip_geo_lookup/mmdb"
+
+module IpGeoLookup
+  DEFAULT_DB_PATH = File.expand_path("../../data/GeoLite2-City.mmdb", __FILE__).freeze
+
+  @mutex = Mutex.new
+
+  class << self
+    # Returns a Result for the given IP string, or nil.
+    def lookup(ip_address)
+      return nil unless ip_address.is_a?(String)
+
+      parsed = IpAddress.parse(ip_address)
+      return nil unless parsed
+
+      ip_int, version = parsed
+      record = reader.find(ip_int, (version == 6) ? 128 : 32)
+      return nil unless record
+
+      build_result(record)
+    end
+
+    def metadata
+      reader.metadata
+    end
+
+    # Reloads from disk; respects configured path.
+    def reload!
+      @mutex.synchronize { @reader = nil }
+    end
+
+    def close
+      @mutex.synchronize do
+        @reader&.close
+        @reader = nil
+      end
+    end
+
+    def configure
+      @mutex.synchronize do
+        yield configuration
+        @reader = MMDB.new(configuration.database_path, mode: configuration.mode)
+      end
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset!
+      @mutex.synchronize do
+        @reader = nil
+        @configuration = nil
+      end
+    end
+
+    private
+
+    def reader
+      @mutex.synchronize do
+        @reader ||= MMDB.new(configuration.database_path, mode: configuration.mode)
+      end
+    end
+
+    def build_result(record)
+      Result.new(
+        country_code: deep_fetch(record, "country", "iso_code"),
+        country_name: deep_fetch(record, "country", "names", "en"),
+        region: deep_fetch(record, "subdivisions", 0, "names", "en"),
+        city: deep_fetch(record, "city", "names", "en"),
+        continent_code: deep_fetch(record, "continent", "code"),
+        continent_name: deep_fetch(record, "continent", "names", "en"),
+        latitude: deep_fetch(record, "location", "latitude"),
+        longitude: deep_fetch(record, "location", "longitude"),
+        time_zone: deep_fetch(record, "location", "time_zone"),
+        postal_code: deep_fetch(record, "postal", "code"),
+        raw: record
+      )
+    end
+
+    def deep_fetch(obj, *keys)
+      keys.each do |key|
+        case obj
+        when Hash then obj = obj[key]
+        when Array then obj = obj[key]
+        else return nil
+        end
+      end
+      obj
+    end
+  end
+
+  class Configuration
+    attr_writer :database_path, :mode
+
+    def database_path
+      @database_path || DEFAULT_DB_PATH
+    end
+
+    def mode
+      @mode || MMDB::MODE_FILE
+    end
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: ip_geo_lookup
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Suleyman Musayev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-30 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight, zero-dependency Ruby gem for resolving IPv4 and IPv6 addresses
+  to country, region, city, coordinates, and more. Ships with an embedded MaxMind
+  GeoLite2 MMDB database and a pure Ruby MMDB reader - no external gems, no API keys,
+  no setup.
+email:
+- slmusayev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ip_geo_lookup.rb
+- lib/ip_geo_lookup/ip_address.rb
+- lib/ip_geo_lookup/mmdb.rb
+- lib/ip_geo_lookup/result.rb
+- lib/ip_geo_lookup/version.rb
+homepage: https://github.com/msuliq/ip_geo_lookup
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/msuliq/ip_geo_lookup
+  source_code_uri: https://github.com/msuliq/ip_geo_lookup
+  changelog_uri: https://github.com/msuliq/ip_geo_lookup/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/msuliq/ip_geo_lookup/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Zero-dependency IPv4/IPv6 geolocation lookup with embedded MaxMind database
+test_files: []