iparty 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d819e6f38465278e0ef5afc147405a67bcf1e7868779dc3a719392301802840
+  data.tar.gz: a09d60d32a690d4ad066503ac81a6462a4750a613b772a2c56b14689a6d44663
+SHA512:
+  metadata.gz: daae7a38a07d47641cfd4ff24e1fce4e07e2100e99a4cb66a9181ece7132a82fe9543f899e2b282bf699639fdd36e4f75e1724a12cab789c0e19be9c53f6a0dc
+  data.tar.gz: dc37d49c82e4eb2f7c4bc0c108654a1b4b8b5f4109d56fdf4531077485f2003efeee0165df152815c05314a4092de5ee1a9bd9670c53331df0653b281446e5c9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-26
+
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sven Pachnit
+
+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,187 @@
+# IParty
+
+## 0.1.0 alpha: risk of party crashers
+
+
+Makes (geo) IP fun again! Ain't no party like an IParty, because an IParty don't stop.
+
+```ruby
+IParty.fetch_db_files! # api key required
+ip = IParty(request.remote_ip)
+
+# all these are true
+ip.country.de?
+ip.country.germany?
+ip.country.in_european_union?
+ip.country.is_a?(Hash)
+ip.country == "Germany" # 🤨
+```
+
+* IParty handles download\* and decoding of, and lookup in, mmdb-files (\* = shelling to curl and tar)
+* IParty lets you annotate IPs/networks with arbitrary helpers, data and tags
+* IParty lets you ignore the MAC address part of an ipv6 address more easily
+* IParty has *no*\* dependencies (\* = stdlib dependencies: fileutils, forwardable, tmpdir, optparse)
+* IParty is essentially a fork/refactor of the [maxminddb](https://github.com/yhirose/maxminddb) gem.
+  The reimaginated implementation details were however too party for a pull request in my opinion.
+* IParty parties hard!
+
+
+## IParty CLI utility
+
+IParty ships with a cli utility `iparty`, refer to [docs/cli/README.md](docs/cli/README.md) for more information.
+
+
+
+## Start partying
+
+### Requirements
+
+```ruby
+spec.required_ruby_version = ">= 3.2.0"
+```
+
+
+### Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add iparty
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install iparty
+```
+
+
+### Configuration
+
+These default settings should or could be changed at "boot" (i.e. in an initializer):
+
+```ruby
+defined?(IParty) && IParty.configure do |config|
+  config.account_id = config.env_value("MAXMIND_ACCOUNT_ID", nil)
+  config.license_key = config.env_value("MAXMIND_LICENSE_KEY", nil)
+end
+```
+
+There are more ways to configure and/or customize IParty.
+You can also change most of these settings via ENV variables.
+
+See [docs/configuration.md](docs/configuration.md) for more information.
+
+
+### Usage
+
+#### Fetching mmdb-files
+
+Note: This requires a unix-oid environment with curl, tar and gzip available.
+      You may change the download process.
+      For more information see [docs/configuration.md](docs/configuration.md) and [docs/mmdb_download.md](docs/mmdb_download.md)
+
+Either in your application startup, and/or in a rake task:
+
+```ruby
+IParty.fetch_db_files! # always download a fresh copy
+IParty.fetch_db_files!(:missing) # only download missing files
+IParty.fetch_db_files!(14 * 24 * 60 * 60) # only download missing or expired files (14.days also works with ActiveSupport)
+```
+
+You may also use the shipped rake tasks for this purpose:
+
+```ruby
+rake iparty:fetch
+rake iparty:fetch[14.days] # or int-seconds without AS
+rake iparty:update
+```
+
+Outside of Rails you need to register them manually in your Rakefile:
+
+```ruby
+require "iparty/rake_task"
+IParty::RakeTask.new
+```
+
+
+#### Basic usage
+
+```ruby
+ip = IParty("1.2.3.4") # shorthand for IParty.normalize
+ip.as_json
+
+# all these are true
+ip.country.de?
+ip.country.germany?
+ip.country.in_european_union?
+ip.country.is_a?(Hash)
+ip.country == "Germany" # 🤨
+ip.country == 123_345 # you may want to read the docs at this point lol
+ip.country.names.de == "Deutschland"
+ip.country.name(:es, fallback_locale: :fr) == "Germany"
+ip.country.dig(:names, :en) == "Germany"
+```
+
+You should definitely take a quick look at the documentation, specifically about the [MaxMine::Result](docs/maxmind_result.md) object.
+It should be intuitive magic but you may scratch your head if you "don't get it".
+
+
+
+## Further reading
+
+  * [docs/benchmark.md](docs/benchmark.md)
+  * [docs/configuration.md](docs/configuration.md)
+  * [docs/exceptions.md](docs/exceptions.md)
+  * [docs/maxmind_result.md](docs/maxmind_result.md)
+  * [docs/mmdb_download.md](docs/mmdb_download.md)
+
+
+
+## Compatibility to maxminddb gem
+
+IParty is somewhat compatible with (read: replacing) maxminddb depending on your usage. Most notably the result data hash is symbolized.
+
+
+
+## Development
+
+* Check out the repository
+* Run `bin/setup` to install dependencies
+* Run `bin/console` to experiment with an interactive irb prompt
+* Run `rake` to run all the tests
+* Run `rake ci` to fetch mmdb-files, then run all the tests (more coverage)
+
+In order to run all the tests you must have API credentials for MaxMind (or a mirror / local copy of the mmdb files for Country, City and ASN).
+The mmdb-files can no longer be distributed or downloaded without API credentials due to licensing. See Configuration.
+
+
+
+## Contributing
+
+Bug reports, ideas, feedback and pull requests are welcome on GitHub at https://github.com/2called-chaos/iparty.
+
+* [Open an issue](https://github.com/2called-chaos/iparty/issues/new)
+
+or
+
+1. [Fork it](http://github.com/2called-chaos/iparty/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Make sure the tests pass and test your changes too (`rake` or `rake ci`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT), see [LICENSE.txt](https://github.com/2called-chaos/iparty/blob/master/LICENSE.txt).
+
+
+
+## Legal
+
+* © 2014, yhirose [maxminddb](https://github.com/yhirose/maxminddb) and contributors
+* © 2026, Sven Pachnit (www.bmonkeys.net) and contributors
+* iparty is licensed under the MIT license

data/Rakefile

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options = ["--fail-level", "W"]
+end
+
+task default: %i[spec rubocop]
+task ci: %i[early_simplecov fetch_mmdb_files default]
+
+desc "load simplecov early"
+task :early_simplecov do
+  require "simplecov"
+  SimpleCov.command_name "early"
+end
+
+desc "download mmdb files for testing"
+task :fetch_mmdb_files do
+  require "iparty"
+  IParty.config.directory = Pathname.new(__dir__).join("spec", "cache")
+  IParty.config.mirror = "https://statics.bmonkeys.net/maxmind/:edition.tar.gz"
+
+  require "iparty/rake_task"
+  IParty::RakeTask.new
+
+  # always fetch one for coverage
+  smallest = IParty.config.directory.join("GeoLite2-ASN.mmdb")
+  smallest.unlink if smallest.exist?
+
+  Rake::Task["iparty:fetch"].invoke
+
+  # invalid file
+  IParty.config.directory.join("GeoLite2-INVALID.mmdb").binwrite("INVALID")
+end
+
+# ---
+
+desc "same as cop:html_open"
+task cop: "cop:html_open"
+
+namespace :cop do
+  desc "Show worst offenders / worst files"
+  task :worst do
+    sh("rubocop -f autogenconf -f worst --fail-level W") {} # ignore non-zero exit code
+  end
+
+  desc "Create rubocop HTML report"
+  task :html do
+    sh("rubocop -f autogenconf -f html -o tmp/rubocop.html") {} # ignore non-zero exit code
+  end
+
+  desc "Create rubocop HTML report and open it"
+  task :html_open do
+    Rake::Task["cop:html"].invoke
+    sh "open tmp/rubocop.html"
+  end
+end

data/exe/iparty

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "irb"
+require "iparty"
+require "iparty/cli/application"
+
+app = IParty::CLI::Application.new(argv: ARGV, argf: ARGF, env: ENV)
+app.dispatch

data/lib/iparty/address.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module IParty
+  class Address < IPAddr
+    extend Forwardable
+
+    attr_accessor :ipv6_significant
+
+    def initialize *args, **kw
+      self.ipv6_significant = kw.fetch(:significant, true)
+      super(*args)
+      self.ipv6_significant = true if force_significant?
+
+      raise IPAddr::AddressFamilyError, "unsupported address family" unless ipv4? || ipv6?
+    end
+
+    def force_significant?
+      @family == Socket::AF_INET6 && @addr == 1
+    end
+
+    def type
+      if @family == Socket::AF_INET
+        :ipv4
+      elsif @family == Socket::AF_INET6
+        :ipv6
+      end
+    end
+
+    def size significant: ipv6_significant
+      if ipv4?
+        2**(32 - prefix)
+      elsif ipv6?
+        if force_significant? || significant || ipv4_mapped? || ipv4_compat?
+          2**(128 - prefix)
+        else
+          2**[0, 128 - prefix - 64].max
+        end
+      end
+    end
+
+    def range? **kw
+      size(**kw) > 1
+    end
+
+    # super but keeping significant option
+    def to_range
+      self.class.new(begin_addr, @family, significant: ipv6_significant)..self.class.new(end_addr, @family, significant: ipv6_significant)
+    end
+
+    def to_long_range **kw
+      range = to_range
+      [range.first.to_i(**kw), range.last.to_i(**kw)]
+    end
+
+    def to_significant
+      self.class.new(@addr, @family, significant: true)
+    end
+
+    def to_insignificant
+      self.class.new(@addr, @family, significant: false)
+    end
+
+    def to_cidr expand_v6: false, default_masks: false, netmask: false, significant: ipv6_significant
+      significant = true if force_significant?
+      cidr = expand_v6 ? to_string(significant:) : to_s(significant:)
+      return cidr if !default_masks && !range?(significant: true) && !(ipv6? && !significant)
+
+      mp = prefix
+      if @family == Socket::AF_INET
+        masklen = 32 - mp
+        mask_addr = ((IN4MASK >> masklen) << masklen)
+      else
+        mp = 64 if !significant && mp > 64
+        masklen = 128 - mp
+        mask_addr = ((IN6MASK >> masklen) << masklen)
+      end
+
+      "#{cidr}/#{netmask ? _to_string(mask_addr) : mp}"
+    end
+
+    def prefix significant: ipv6_significant
+      return super() if force_significant? || significant || !ipv6? || ipv4_mapped? || ipv4_compat? || super() <= 64
+
+      64
+    end
+
+    def to_i significant: ipv6_significant
+      return super() if force_significant? || significant || !ipv6? || ipv4_mapped? || ipv4_compat? || prefix(significant: true) <= 64
+
+      # drop upper 64 bits / host-identifier of ipv6
+      (super() >> 64) & ((1 << 64) - 1)
+    end
+
+    def to_s significant: ipv6_significant
+      return super() if force_significant? || significant || !ipv6? || ipv4_mapped? || ipv4_compat? || prefix(significant: true) <= 64
+
+      mask(64).to_s(significant: true)
+    end
+
+    def to_string significant: ipv6_significant
+      return super() if force_significant? || significant || !ipv6? || ipv4_mapped? || ipv4_compat? || prefix(significant: true) <= 64
+
+      mask(64).to_string(significant: true)
+    end
+
+    def asn
+      defined?(@_asn) ? @_asn : (@_asn = MaxMind.lookup(:ASN, self, result_class: MaxMind::Result::Asn) || MaxMind::Result::Asn.new)
+    end
+
+    def geo_country
+      defined?(@_country) ? @_country : (@_country = MaxMind.lookup(:Country, self, result_class: MaxMind::Result::GeoCountry) || MaxMind::Result::GeoCountry.new)
+    end
+
+    def geo_city
+      defined?(@_city) ? @_city : (@_city = MaxMind.lookup(:City, self, result_class: MaxMind::Result::GeoCity) || MaxMind::Result::GeoCity.new)
+    end
+
+    def geo
+      defined?(@_geo) ? @_geo : (@_geo = geo_city.presence || geo_country.presence || MaxMind::Result::Geo.new)
+    end
+
+    def annotations
+      result = {}
+      IParty.config.annotations&.each do |ipp, adata|
+        next unless ipp.include?(self)
+
+        result.merge!(adata.merge(tags: result.fetch(:tags, []) | adata.fetch(:tags, [])))
+      end
+
+      result unless result.empty?
+    end
+
+    def as_json
+      {
+        type: type,
+        prefix: prefix,
+        address: to_s,
+        cidr: to_cidr,
+        network: nil,
+        annotations: annotations,
+      }.merge(asn.merge(network: nil), geo).compact
+    end
+  end
+end

data/lib/iparty/cli/application/actions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module IParty
+  module CLI
+    class Application
+      module Actions
+        # via --irb/-d irb
+        def dispatch_irb
+          IrbContext.new(self).start
+        end
+
+        # via -h/--help
+        def dispatch_help
+          help_text = colorized_help_text
+          help_text = help_text.map{ decolorize(_1) } unless @opts[:colorize]
+
+          puts help_text, nil, c("The current config directory is #{c @config_path, :magenta}")
+        end
+
+        # via -v/--version
+        def dispatch_appinfo pad: 20
+          parts = if @opts[:debug]
+            %i[runtime cli_opts cli_config formatters iparty_config mmdb_status]
+          else
+            %i[runtime cli_config mmdb_status]
+          end
+
+          parts.each_with_index do |imeth, i|
+            puts unless i.zero?
+            send(:"appinfo_#{imeth}", pad: pad)
+          end
+        end
+
+        def dispatch_info use_argf: read_from_stdin?
+          return dispatch_help if @argv.empty? && !use_argf
+
+          ensure_mmdb_files!
+
+          if use_argf
+            each_line_in_argf_as_addresses do |addresses, index|
+              out << formatter.format_all(addresses, base_index: index){|ip| ip_to_data(ip, colorize: formatter.colorize?) }
+            end
+          else
+            addresses = IParty.expand_hostnames(@argv)
+
+            out << if addresses.length > 1
+              formatter.format_all(addresses){|ip| ip_to_data(ip, colorize: formatter.colorize?) }
+            else
+              formatter.format(addresses[0]){|ip| ip_to_data(ip, colorize: formatter.colorize?) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iparty/cli/application/appinfo.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module IParty
+  module CLI
+    class Application
+      module Appinfo
+        def appinfo_runtime pad: 20
+          puts c("#{"".rjust(pad + 2)}# Runtime", :magenta)
+          puts c("#{"IParty".rjust(pad)}: #{c IParty::VERSION, :blue}")
+          puts c("#{"Ruby".rjust(pad)}: #{c RUBY_DESCRIPTION, :blue}")
+        end
+
+        def appinfo_cli_opts pad: 20
+          puts c("#{"".rjust(pad + 2)}# CLI options", :magenta)
+          @opts.each_pair do |key, value|
+            puts c("#{key.to_s.rjust(pad)}: #{c value.inspect, default_options[key] == value ? :cyan : :blue}")
+          end
+        end
+
+        def appinfo_cli_config pad: 20
+          path_inaccessible = c(" (inaccessible)", :red) if !@config_path.directory? || !@config_path.readable?
+          file_inaccessible = c(" (inaccessible)", :red) if !@config_file.exist? || !@config_file.readable?
+          file_disabled = c(" (disabled)", :red) if @rc_disabled
+
+          puts c("#{"".rjust(pad + 2)}# CLI config", :magenta)
+          puts c("#{"config_path".rjust(pad)}: #{c @config_path.inspect, :blue}#{path_inaccessible}")
+          puts c("#{"config_file".rjust(pad)}: #{c @config_file.inspect, :blue}#{file_disabled || file_inaccessible}")
+        end
+
+        def appinfo_iparty_config pad: 20
+          puts c("#{"".rjust(pad + 2)}# IParty.config", :magenta)
+          IParty.config.each_pair do |key, value|
+            if key == :annotations && value
+              puts c("#{key.to_s.rjust(pad)}:")
+              value.each do |ipp, adata|
+                puts c("  #{"".rjust(pad)}#{ipp.to_cidr}: #{c adata.inspect, :blue}")
+              end
+            else
+              puts c("#{key.to_s.rjust(pad)}: #{c value.inspect, :blue}")
+            end
+          end
+        end
+
+        def appinfo_mmdb_status pad: 20
+          puts c("#{"".rjust(pad + 2)}# MMDB file status", :magenta)
+          IParty.config.editions.map do |edition|
+            file = IParty.config.directory.join("#{edition}.mmdb")
+            reason = IParty::MaxMind.fetch_db_file_reason(file, @opts[:mmdb_fetch_when])
+
+            status = if file.exist?
+              ctime = file.ctime
+              age = (Time.now - ctime)
+              days = (age / (60 * 60 * 24)).floor
+              hours = ((age / (60 * 60)) % 24).floor
+              minutes = ((age / 60) % 60).floor
+              age_string = [
+                ("#{days}d" if days > 0),
+                ("%02d:%02d" % [hours, minutes] if hours > 0 || minutes > 0),
+              ].compact.join(" ")
+              age_string = "#{age.floor}s" if age_string.empty?
+
+              if reason
+                "#{c(reason.upcase, :red)} #{c("[age: #{age_string}, ctime: #{ctime}]", :black)} #{file}"
+              else
+                "#{c("OK", :green)} #{c("[age: #{age_string}, ctime: #{ctime}]", :black)} #{file}"
+              end
+            else
+              "#{c("MISSING", :red)} #{file}"
+            end
+
+            puts c("#{edition.to_s.rjust(pad)}: #{status}")
+            !reason
+          end.all?
+        end
+
+        def appinfo_formatters pad: 20
+          pad = -2 if pad.zero?
+
+          puts c("#{"".rjust(pad + 2)}# Available formatters", :magenta)
+          CLI::Formatter.descendants.each do |fmt|
+            name = fmt.to_s
+            source_location = begin
+              if name.start_with?("#<Class:")
+                rest = name.split("::", 2)[1]
+                name = c("<IPARTYRC> ", :red) + c(rest, :blue)
+                singleton_class.const_source_location(rest) if singleton_class.const_defined?(rest)
+              else
+                Object.const_source_location(name)
+              end
+            rescue StandardError => ex
+              ["UNKNOWN(#{ex.class}: #{ex.message})", 0]
+            end || ["UNKNOWN", 0]
+
+            puts [
+              c("#{"".rjust(pad)}* "),
+              c(name, :blue),
+              c("(", :black),
+              c(fmt.id.inspect, :green),
+              c(")", :black),
+              c(" in #{source_location.join(":")}", :black),
+            ].join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iparty/cli/application/irb_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module IParty
+  module CLI
+    class Application
+      class IrbContext
+        attr_reader :app, :formatter
+
+        def initialize(app)
+          @app = app
+        end
+
+        def to_s
+          "IParty::CLI"
+        end
+
+        def help
+          puts "app         # application reference"
+          puts "exit        # exit IRB"
+          puts "ip *ips     # show summary for IPs"
+        end
+
+        def ip *ips
+          addresses = IParty.expand_hostnames(ips)
+          @app.out << if addresses.length > 1
+            app.formatter.format_all(addresses){|ip| app.ip_to_data(ip, colorize: app.formatter.colorize?) }
+          else
+            [app.formatter.format(addresses[0]){|ip| app.ip_to_data(ip, colorize: app.formatter.colorize?) }]
+          end
+
+          nil
+        end
+
+        def start
+          help
+          binding.irb(show_code: false) # rubocop:disable Lint/Debugger -- no comment
+        end
+      end
+    end
+  end
+end