iparty 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55ee6dbcc7d44397d35c6acbd8f6121cea24496dd1f436053e3aaa74e53a5fef
-  data.tar.gz: a8df1dd41f2c5921004a08b944aa0e764d00e7619a3d7dd335b0729b1d86f049
+  metadata.gz: 5f040fd93232947aa2be967cac0ad59617cc24e4751c14908466e221d4830fc6
+  data.tar.gz: 4b34b52ee226d40b306da7d8dcf7f576ceb37c98d2695c1e2a78db43703ba40a
 SHA512:
-  metadata.gz: 7f14e051fb84488a9fd0afff7a413672c7e84e34cb2f326c42799d4feeefa4b70471ca0f5c6184b0fe5ac6497478a8a2f020c6992c338de4ad03c706ce3538e1
-  data.tar.gz: 9c8c93019f00f2f07165a17f892c2bfc5410d08d2b03eb5e7366f9761eee45c8c7b993f1816c4d6f72f40d353fa0f421f0d1f8ff6a1bc7e97b8fc678df295949
+  metadata.gz: 1f319c5dbfcad4f51192b750a973f1de60dbee54db84f176aa67ed921f883770eaf61fb82f1b32a837e93072eb0a10f562bed4e2743cf5df3a4936e957bcf1b1
+  data.tar.gz: 67f50c5df51c1c1e06266c780d5b27163b9ee5a7bb45c22f8c846c4de8baa6c8f083db174d09690211780b8edcbc13bb0196acc7355e6e8f24ee18f75d0b7e4a

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-05-27
+
+* Include documentation in gem package
+* Automatically set a network for localhost
+* Add config option (proc) transform_result
+* iso_code fallbacks to code and vice versa so you don't have to think about it (continent has code and rest has iso_code).
+  This only applies to method access, `[:code]` does not fallback.
+* Add alias `timezone` for `time_zone`
+* Memoize annotations
+* Add `tag?` helper for annotations
+
+
+
 ## [0.1.1] - 2026-05-26
 
 * Add missing pathname dependency (stdlib)

data/README.md

@@ -1,6 +1,6 @@
 # IParty
 
-## 0.1.0 alpha: risk of party crashers
+## 0.x.x alpha: risk of party crashers
 
 
 Makes (geo) IP fun again! Ain't no party like an IParty, because an IParty don't stop.

data/docs/benchmark.md

@@ -0,0 +1,40 @@
+# IParty
+
+## Benchmark
+
+This is the result of `script/benchmark.rb` on my M1.
+
+```
+RSS-before[uncached]: 30.31 MB
+ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin21]
+Warming up --------------------------------------
+            uncached   145.000 i/100ms
+Calculating -------------------------------------
+            uncached      1.448k (± 1.9%) i/s  (690.59 μs/i) -     14.500k in  10.017464s
+RSS-after[uncached]: 48.75 MB
+
+
+RSS-before[singletons]: 29.77 MB
+ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin21]
+Warming up --------------------------------------
+          singletons   162.000 i/100ms
+Calculating -------------------------------------
+          singletons      1.565k (± 8.0%) i/s  (638.87 μs/i) -     15.552k in  10.006033s
+RSS-after[singletons]: 31.27 MB
+
+
+RSS-before[eager_load]: 30.20 MB
+ruby 3.3.6 (2024-11-05 revision 75015d4c1f) [arm64-darwin21]
+Warming up --------------------------------------
+          eager_load   500.000 i/100ms
+Calculating -------------------------------------
+          eager_load      4.940k (± 4.1%) i/s  (202.43 μs/i) -     49.500k in  10.038651s
+RSS-after[eager_load]: 112.73 MB
+```
+
+### Personal conclusion
+
+I personally would rather not have mmdb-freshness tied to app-boot.
+Hence I personally use no singletons unless I heavily use IParty in which case I would use the
+CurrentAttributes way of caching non-eagerly-loaded instances per request with an additional per-request ipcache.
+See documentation for more details.

data/docs/cli/README.md

@@ -0,0 +1,132 @@
+# IParty CLI utility
+
+```
+Usage: iparty <IP|host...> [options]
+
+# Application options
+    -a, --[no-]all                         full non-summarized output
+    -f, --format <FORMATTER>               formatter (pretty|json|off) or template string [default: pretty]
+    -l, --language <LANG>                  limit output to language (or all) [default: en]
+    -r, --[no-]resolve                     resolve hosts and include hostnames in data (requires resolv)
+    -o, --only   key,deep.key,*country*    list of key expressions (grep on full key)
+    -e, --except key,deep.key,sub*         list of key expressions (grep_v on full key)
+                                           ** matches .*
+                                            * matches [^.]*
+        --[no-]stdin                       read from stdin (one IP per line)
+
+# (Custom) actions
+    -d, --dispatch ACTION                  Dispatch given action, you may add your own
+        --irb                              IRB repl with iparty context and helpers
+
+# MMDB actions
+        --mmdb-status                      Show mmdb file status
+        --mmdb-fetch                       Fetch missing mmdb-editions
+        --mmdb-update                      Update all mmdb-editions
+
+# General options
+    -h, --help                             Shows this help
+    -v, --version                          Shows version and mmdb info (and config with --debug)
+    -m, --[no-]monochrome                  Don't or do colorize output
+        --[no-]debug                       Enable debug, raise exceptions and print config with -v
+        --no-rc                            Do not eval config.rb
+
+The current config directory is /Users/chaos/.iparty
+```
+
+
+
+## Configuration
+
+IParty CLI attempts to load a config file (`config.rb`) in `ENV.fetch("IPARTY_CFGDIR", "~/.iparty")` by default, `--no-rc` will skip this.
+
+You can configure application defaults or define custom formatters, actions, or do whatever really. The file will be eval'd in the application context.
+
+Also look at the action cookbook in `docs/cli/action_cookbook`.
+
+```ruby
+# Create this file as ~/.iparty/config.rb
+# This file is eval'd in the application object's context after it's initialized!
+
+
+# For IParty options refer to the IParty documentation.
+#     https://github.com/2called-chaos/iparty/blob/master/README.md
+
+IParty.config.annotate "1.1.1.1", "1.0.0.1", tags: %i[cloudflare_dns]
+IParty.config.annotate_tag %i[loopback], "127.0.0.1/8", "::1"
+
+
+# Change defaults (arguments will still override)
+# For CLI options refer to application/options.rb#default_options
+#     https://github.com/2called-chaos/iparty/blob/master/lib/iparty/cli/application/options.rb
+
+# @opts[:summarize] = false
+# @opts[:except] += [
+#   "registered_country",
+#   "subdivisions",
+# ]
+
+
+
+# =================
+# = Custom Action =
+# =================
+# Also look at the action cookbook in `docs/cli/action_cookbook`!
+
+@optparse.separator("\n# Options for --dispatch ban")
+@optparse.on("--reason REASON", String, "ban reason") {|v| @opts[:ban_reason] = v }
+
+# iparty -d ban --reason "they suck" 1.2.3.4 c498:81dd:12bc:b812:a2c4:b003:303d:6707
+def dispatch_ban
+  each_address do |ip|
+    ipp = IParty(ip, significant: false)
+    puts "ban #{ipp} (#{ipp.geo.detailed}) because #{@opts[:reason]}" # @todo ban ip
+  end
+end
+
+
+
+# ====================
+# = Custom Formatter =
+# ====================
+
+# Descendants of CLI::Formatter are accessible by their ::id (compared `fmt.id === input`)
+#   i.e. self.id = "foo" # --format foo
+#   i.e. self.id = /^foo$/
+#   i.e. self.id = ->{ _1 == "foo" }
+# If no id is specified it will default to the class name (unhandy but accessible)
+# You can also list all formatters with `-v --debug`
+
+# The app will call #format for single IPs and #format_all for multiple (or stdin)
+# but you may handle them the same way.
+
+class MyFormatter < IParty::CLI::Formatter
+  # self.id = "my"
+
+  # def setup
+  #   # optional, called at the end of initialize if responds_to?(:setup)
+  # end
+
+  # return an array of put-able things (false will be skipped)
+  def format_all ips, **kw, &to_data
+    ips.map.with_index {|ip, index| format(ip, index: index, **kw, &to_data) }
+  end
+
+  # return a put-able thing (or false to skip output)
+  # to_data will turn an IP into filtered data according to app-args and opts
+  def format ip, index: 0, **kw, &to_data
+    "[#{index}] #{to_data.call(ip)}"
+  end
+end
+
+class MyJsonFormatter < IParty::CLI::Formatter::JsonFormatter
+  self.id = "my_json"
+
+  def format ip, index: 0, **kw, &to_data
+    if @opts[:foo] == "bar"
+      format_all(Array(ip), **kw, &to_data)
+    else
+      super
+    end
+  end
+end
+```

data/docs/cli/action_cookbook/show_my_remote_ips.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# within ~/.iparty/config.rb context
+
+# iparty -d me
+# iparty --dispatch me
+def dispatch_me
+  require "net/http"
+
+  get_ip = proc do |url|
+    Net::HTTP.get(URI(url))
+  rescue Socket::ResolutionError
+    formatter.colorize? ? c("SOCKET_ERROR", :red) : :SOCKET_ERROR
+  rescue StandardError
+    formatter.colorize? ? c("ERROR", :red) : :ERROR
+  end
+
+  if the_more_clever_way = true
+    @argv << get_ip["https://api.ipify.org"]
+    @argv << get_ip["https://api6.ipify.org"]
+    dispatch_info
+  else
+    out << formatter.format("my external ips") do
+      onlyexcept_data!(
+        ipv4: get_ip["https://api.ipify.org"],
+        ipv6: get_ip["https://api6.ipify.org"],
+      )
+    end
+  end
+end

data/docs/configuration.md

@@ -0,0 +1,170 @@
+# IParty
+
+## Configuration
+
+You may configure and extend IParty in an initializer or in the init part of your non-rails app.
+For basic usage you only really need MaxMind credentials to download the mmdb files.
+
+```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
+```
+
+
+
+### Easily extend your custom accessors
+
+For more info on extending address or result data look at docs/maxmind_result.md
+
+```ruby
+IParty::MaxMind::Result::Geo.class_eval do
+  define_attr(:best_tenant, export: true) { country.iso_code == "DE" ? :de : :us }
+end
+
+IParty(request.remote_ip).best_tenant # => :us
+```
+
+
+
+### Full config
+
+This config, minus the CurrentAttributes cache is default config. For basic usage you only need account_id/license_key.
+Please also take a look at docs/maxmind_result.md for extending the address and geo results.
+
+```ruby
+defined?(IParty) && IParty.configure do |config|
+  # If set to false drop last half of v6-addresses as they are insignificant for most applications.
+  # The then 64-bit addresses also fit into unsigned bigints allowing for easy range representations.
+  # Each IParty::Address can overwrite this with
+  #   * #ipv6_significant accessors
+  #   * significant: keyword (affected methods only but including new/initialize)
+  config.ipv6_significant = config.env_value("IPARTY_IPV6_SIGNIFICANT", true)
+
+  # Whether to use the low memory file reader or load mmdb into memory as a whole (see docs/benchmark.md)
+  config.eager_load = config.env_value("IPARTY_EAGER_LOAD", false)
+
+  # Use singleton instances of MaxMind::Database readers.
+  # These are lazily initialized so in a threaded environment or with eager load enabled you should pre-init them.
+  # Side Effect: You will have to reboot your app for mmdb changes to take effect.
+  config.singletons = config.env_value("IPARTY_SINGLETONS", false)
+  #config.singletons = {} # lazy load singleton instances, not thread-safe
+  #config.singletons = true # eagerly init all editions (eager_load into memory if enabled, thread-safe after init)
+
+  # alternatively you can do something like this:
+  # * singleton DB instances (lazily memoized) per-request (eager load should be disabled)
+  # * IParty::Address cache (including their geo lookups)
+  if defined?(ActiveSupport::CurrentAttributes)
+    class IPartyCache < ActiveSupport::CurrentAttributes
+      attribute(:databases, default: {})
+
+      # cached IParty addresses, i.e. IPartyCache.ips["1.2.3.4"]
+      # Be wary of mutating (i.e. mask!), use clones
+      attribute(:ips, default: -> { Hash.new{|h, ip| h[ip.to_s] = IParty(ip.to_s) } })
+    end
+    config.singletons = -> { IPartyCache.databases }
+  end
+
+  # An IP that is used instead of local IPs
+  config.local_ip_alias = config.env_value("IPARTY_LOCAL_IP_ALIAS", nil)
+
+  # MaxMind account_id and license_key aka mirror basic-auth
+  config.account_id = config.env_value("MAXMIND_ACCOUNT_ID", nil)
+  config.license_key = config.env_value("MAXMIND_LICENSE_KEY", nil)
+
+  # Mirror to download tar.gz compressed mmdb-files from
+  config.mirror = config.env_value("MAXMIND_MIRROR", "https://download.maxmind.com/geoip/databases/:edition/download?suffix=tar.gz")
+
+  # Editions
+  config.editions = config.env_value("MAXMIND_EDITIONS", "GeoLite2-ASN GeoLite2-Country GeoLite2-City") {|v| v.split(/\s+|,\s*/) }
+
+  # Target directory (for mmdb files, will also create subdirectory for updating)
+  # Note: Must be a pathname
+  config.directory = config.env_value("IPARTY_DIRECTORY", nil) do |dir|
+    if dir && !dir.empty?
+      Pathname.new(dir)
+    elsif defined?(Rails)
+      Rails.root.join("vendor", "maxmind")
+    else
+      Pathname.new(Dir.tmpdir).join("iparty")
+    end
+  end
+
+  # Proc to download mmdb files
+  config.url_to_mmdb = proc do |url, dir, config|
+    auth = %{-u "#{config.account_id}:#{config.license_key}"} if config.account_id && config.license_key
+    curl = %{curl -L -s #{"#{auth} " if auth}"#{url}"}
+    tar = %{tar xz --strip-components 1 --exclude "*.txt" --no-same-owner -C #{dir.to_s.shellescape}}
+    system("#{curl} | #{tar}")
+  end
+
+  # --- following is example code and not default behaviour ---
+
+  # Proc to transform geo result data, by default does nothing.
+  # yields
+  #   data          the result hash
+  #   addr          the looked up address (as IParty or IPAddr)
+  #   result_class  the class that later will get instantiated with data
+  config.transform_result = proc do |data, addr, result_class|
+    if result_class != IParty::MaxMind::Result::Asn && addr.loopback?
+      data[:country] ||= { iso_code: "ZZ", names: { en: "Local" } }
+      data[:continent] ||= { code: "ZZ", names: { en: "Local" } }
+    end
+  end
+
+  # For more info on extending look at docs/maxmind_result.md
+  IParty::Address.define_method(:detailed) do |*args|
+    "#{to_s} -- #{geo.detailed} -- #{asn.detailed}"
+  end
+
+  # You may want to rely on rake task and/or ensure on app boot?
+  #   fetch_when can be
+  #     * :always
+  #     * :missing
+  #     * (Numeric) maxAge (i.e. (int)seconds or (AS::Duration)14.days)
+  IParty.fetch_db_files!(:missing, verbose: true)
+end
+```
+
+
+
+### Annotations
+
+You can annotate IPs or networks with arbitrary data whereas `tags` has special behaviour (they merge).
+IParty CLI will display `name` along `tags` in the summarized view.
+
+```ruby
+defined?(IParty) && IParty.configure do |config|
+  # annotate(*addresses, **data) -- merges data and tags
+  IParty.config.annotate "1.0.0.0/8", tags: %i[foo]
+  IParty.config.annotate "1.2.3.4", tags: %i[bar]
+  IParty.config.annotate "127.0.0.1/8", "::1", name: "loopback", tags: %i[localhost]
+
+  # annotate_tag(tags, *addresses) -- merges tags
+  IParty.config.annotate_tag :one, "1.0.0.0/8"
+  IParty.config.annotate_tag %i[local ipv4], "127.0.0.1/8"
+  IParty.config.annotate_tag %i[local], "127.0.0.1/8", "::1"
+end
+
+IParty("127.1.2.3").annotations # => {:name=>"loopback", :tags=>[:localhost, :local, :ipv4]}
+IParty("127.1.2.3").tag?(:local) # => true
+IParty("69.4.20.0").annotations # => nil
+IParty("69.4.20.0").tag?(:local) # => false
+```
+
+
+
+### Check configuration
+
+You can use the shipped rake tasks to check your effective configuration.
+
+```
+# shows effective IParty config (including license_key)
+rake iparty:config
+rake iparty:config[inspect]
+rake iparty:config[json]
+
+# check mmdb file status
+rake iparty:status
+```

data/docs/exceptions.md

@@ -0,0 +1,22 @@
+# IParty
+
+## Exceptions
+
+These are the exceptions you might encounter using this gem. Only IParty exceptions are added by this gem, the other ones are for your reference.
+
+```ruby
+StandardError
+  SystemCallError
+    Errno::*
+  ArgumentError
+    IPAddr::Error
+      IPAddr::AddressFamilyError
+      IPAddr::InvalidAddressError
+        IPAddr::InvalidPrefixError
+  IParty::Error
+    IParty::MaxMind::Database::Error
+      IParty::MaxMind::Database::InvalidFileFormatError
+```
+
+IParty::Address will generally raise IPAddr exceptions.
+To guard against IP errors, if you do not already rescue broader, you typically want to rescue IPAddr::Error and IParty::Error.

data/docs/maxmind_result.md

@@ -0,0 +1,82 @@
+# IParty
+
+## MaxMind Result
+
+Result is_a?(Hash) with some magic sprinkled in, party!
+
+* Defined attributes can be retrieved via method(chaining)
+* Even without ActiveSupport core_ext, Result(Hash) and Subdivisions(Array) implements blank?/present?/presence (values do not however)
+* Dynamically compares
+  * result == Numeric => geoname_id
+  * result == String => name.en
+* Dynamically inquires
+  * result.us? (2-char checks against code on continent or iso_code otherwise)
+  * result.foo? (!2-char checks against english name (lowercased, underscored))
+
+
+
+### Class Structure
+
+```ruby
+IParty::MaxMind::Result < Hash
+  Asn < Result
+  Geo < Result
+    GeoCountry < Geo
+    GeoCity < Geo
+
+  Subdivisions < Array
+  Location < Result
+  NamedLocation < Result
+    Continent < NamedLocation
+    Country < NamedLocation
+    City < NamedLocation
+    Subdivision < NamedLocation
+  Postal < Result
+  Traits < Result
+```
+
+Note: There's little reason to define attributes on GeoCountry or GeoCity since by default country is the fallback of city lookups.
+You should therefore define attributes on Geo and make sure they work with nil data to preserve safe navigation access.
+
+
+
+### Add methods
+
+You can (in an initializer) add your own representations and helpers to the result classes or address class.
+
+```ruby
+# define_attr is a helper to define accessors on the result data with the following synopsis:
+#   define_attr(
+#     name,                  # The method name
+#     attribute = name,      # The attribute to dig
+#     type: nil,             # sugar for transform ->(v) { type.new(v) }
+#     aliases: nil,          # Symbol or Array[Symbol] of alias method names
+#     memoize: nil,          # Memoize the value (true/false, nil: true if transform block is given)
+#     export: nil,           # True, Symbol or Array[Symbol] of method names to export to Address (def_delegate)
+#                            # Note: Only works on Result/Geo(Country/City)/Asn
+#     &transform             # The value to return, if omitted it's the digged value
+#   )
+
+IParty::MaxMind::Result::Geo.define_attr(:best_tenant, export: true) { continent.eu? ? :eu : :us }
+IParty::MaxMind::Result::Geo.define_attr(:short, export: true) { [continent.code, country.name].compact.join(" / ") }
+IParty::MaxMind::Result::Asn.define_attr(:short, export: :asn_short) { "AS#{number} #{organization}" }
+IParty::Address.define_method(:detailed) { "#{to_s} -- #{geo.detailed} -- #{asn_short}" }
+# IParty(ip).short/asn_short/detailed
+
+# Delegate geo/asn methods so you can do `ip.METHOD` instead of `ip.geo.METHOD`
+IParty::Address.def_delegators(:geo, *%i[registered_country])
+IParty::Address.def_delegators(:asn, *%i[network])
+# Note that some are already exported, namely:
+#   * city
+#   * continent
+#   * country
+#   * in_european_union?
+#   * latitude
+#   * longitude
+#   * time_zone
+#   * postal_code
+#   * (asn) autonomous_system_network
+#   * (asn) autonomous_system_number
+#   * (asn) autonomous_system_organization
+#   * (asn) autonomous_system_detailed
+```

data/docs/mmdb_download.md

@@ -0,0 +1,84 @@
+# IParty
+
+## Download of mmdb-files
+
+Note: You need to configure valid credentials and/or mirror, see Configuration.
+
+
+---
+
+
+### Download method
+
+By default IParty will use this proc (and you may change it) to turn a URL (to a gz compressed mmdb-file) to a mmdb-file inside the temporary directory.
+
+Note: This requires a unix-oid environment with curl, tar and gzip available.
+
+```ruby
+IParty::MaxMind.download_proc = proc do |url, temp_dir|
+  auth = %{-u "#{account_id}:#{license_key}"} if account_id && license_key
+  curl = %{curl -L -s #{"#{auth} " if auth}"#{url}"}
+  tar = %{tar xz --strip-components 1 --exclude "*.txt" --no-same-owner -C #{temp_dir.to_s.shellescape}}
+  system("#{curl} | #{tar}")
+end
+```
+
+
+The file fetching process will
+
+* download all editions (`IParty::MaxMind.editions`) in sequence, extract them flat into the temporary directory
+  * the MaxMind account_id and license_key are HTTP Basic Auth username and password (this also works for your mirror)
+* move all mmdb files inside the temp directory into the data directory
+  * this is essentially an atomic-ish update and will not nuke your existing files on error
+  * files that failed to download or are no longer requested will remain (no cleanup)
+* remove the temp directory
+
+
+
+### Download
+
+#### Ruby
+
+In your application startup, or in a rake task:
+
+```ruby
+# only download missing or expired files
+IParty.fetch_db_files!(14 * 24 * 60 * 60) # or 14.days
+
+# only download missing files, verbose will print files downloaded to stderr
+IParty.fetch_db_files!(:missing, verbose: true)
+
+# always download a fresh copy
+IParty.fetch_db_files! # (:always)
+```
+
+
+#### Rake tasks
+
+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
+```
+
+There are also these rake tasks
+```ruby
+# prints mmdb file status, expiry check if max_age is provided
+# will exit(1) if any file is missing, invalid or expired
+rake iparty:status
+rake iparty:status[14.days]
+
+# shows effective IParty config (including license_key)
+rake iparty:config
+rake iparty:config[inspect]
+rake iparty:config[json]
+```
+
+Outside of Rails you need to register them manually in your Rakefile:
+
+```ruby
+require "iparty/rake_task"
+IParty::RakeTask.new
+```

data/lib/iparty/address.rb

@@ -122,6 +122,8 @@ module IParty
     end
 
     def annotations
+      return @_annotations if defined?(@_annotations)
+
       result = {}
       IParty.config.annotations&.each do |ipp, adata|
         next unless ipp.include?(self)
@@ -129,7 +131,13 @@ module IParty
         result.merge!(adata.merge(tags: result.fetch(:tags, []) | adata.fetch(:tags, [])))
       end
 
-      result unless result.empty?
+      @_annotations = result.empty? ? nil : result
+    end
+
+    def tag? tag
+      return false unless tags = annotations&.fetch(:tags, nil)
+
+      tags.include?(tag)
     end
 
     def as_json

data/lib/iparty/config.rb

@@ -12,6 +12,7 @@ module IParty
     :local_ip_alias,
     :ipv6_significant,
     :url_to_mmdb,
+    :transform_result,
     :annotations,
     keyword_init: true,
   ) do
@@ -135,6 +136,18 @@ module IParty
           tar = %{tar xz --strip-components 1 --exclude "*.txt" --no-same-owner -C #{dir.to_s.shellescape}}
           system("#{curl} | #{tar}")
         end,
+
+        # Proc to transform geo result data, by default does nothing.
+        # yields
+        #   data          the result hash
+        #   addr          the looked up address (as IParty or IPAddr)
+        #   result_class  the class that later will get instantiated with data
+        # transform_result: proc do |data, addr, result_class|
+        #   if addr.loopback?
+        #     data[:country] ||= { iso_code: "ZZ", names: { en: "Local" } }
+        #     data[:continent] ||= { code: "ZZ", names: { en: "Local" } }
+        #   end
+        # end,
       )
     end
   end

data/lib/iparty/max_mind/database.rb

@@ -49,8 +49,8 @@ module IParty
         addr = IPAddr.new(addr) unless addr.is_a?(IPAddr)
         addr = IParty.config.local_ip_alias if IParty.config.local_ip_alias && addr.loopback?
         addr = IPAddr.new(addr) unless addr.is_a?(IPAddr)
-        addr = addr.ipv4_compat if addr.ipv4?
-        long = addr.is_a?(IParty::Address) ? addr.to_i(significant: true) : addr.to_i
+        compat_addr = addr.ipv4? ? addr.ipv4_compat : addr
+        long = compat_addr.is_a?(IParty::Address) ? compat_addr.to_i(significant: true) : compat_addr.to_i
         node_no = 0
 
         (@start_idx...128).each do |i|
@@ -62,7 +62,12 @@ module IParty
           elsif next_node_no >= @node_count
             pos = (next_node_no - @node_count) - DATA_SECTION_SEPARATOR_SIZE
             result           = decode(@data_section_start, pos)[1]
-            result[:network] = cidr_from_long(long, i) unless result.empty?
+            result[:network] = if !result.empty?
+              cidr_from_long(long, i)
+            elsif addr.loopback?
+              @family == Socket::AF_INET6 ? "::1/128" : "127.0.0.0/8"
+            end
+            IParty.config.transform_result&.call(result, addr, result_class)
             return result_class.new(result)
           else
             node_no = next_node_no

data/lib/iparty/max_mind/result.rb

@@ -41,14 +41,14 @@ module IParty
         define_attr(:latitude)
         define_attr(:longitude)
         define_attr(:metro_code)
-        define_attr(:time_zone)
+        define_attr(:time_zone, aliases: :timezone)
       end
 
       class NamedLocation < Result
-        define_attr(:code)
+        define_attr(:code, memoize: false) {|v| v || self[:iso_code] }
         define_attr(:geoname_id)
         define_attr(:is_in_european_union, aliases: :in_european_union?)
-        define_attr(:iso_code)
+        define_attr(:iso_code, memoize: false) {|v| v || self[:code] }
         define_attr(:names, type: Result)
 
         def name(locale = :en, fallback_locale: :en)
@@ -75,7 +75,7 @@ module IParty
 
         # dynamic inquiry
         define_attr(:inquire_on_name) { name&.downcase&.tr(" ", "_") }
-        define_attr(:inquire_on_code) { (iso_code || code)&.downcase }
+        define_attr(:inquire_on_code) { iso_code&.downcase }
 
         def respond_to_missing? method_name, include_private = false
           method_name.end_with?("?") || super
@@ -170,7 +170,7 @@ module IParty
         define_attr(:latitude, memoize: false, export: true) { location.latitude }
         define_attr(:longitude, memoize: false, export: true) { location.longitude }
         define_attr(:metro_code, memoize: false) { location.metro_code }
-        define_attr(:time_zone, memoize: false, export: true) { location.time_zone }
+        define_attr(:time_zone, memoize: false, aliases: :timezone, export: true) { location.time_zone }
         define_attr(:postal_code, aliases: :zip, export: true, memoize: false) { postal.code }
 
         define_attr(:detailed_parts, memoize: false) { [continent.code, country.name, city.name].compact }

data/lib/iparty/rake_task.rb

@@ -111,7 +111,14 @@ module IParty
             puts IParty.config.inspect
           else
             IParty.config.each_pair do |key, value|
-              puts "#{key.to_s.rjust(16)}: #{value.inspect}"
+              if key == :annotations && value
+                puts "#{key.to_s.rjust(16)}:"
+                value.each do |ipp, adata|
+                  puts "#{"".rjust(16)}  #{ipp.to_cidr}: #{adata.inspect}"
+                end
+              else
+                puts "#{key.to_s.rjust(16)}: #{value.inspect}"
+              end
             end
           end
         end

data/lib/iparty/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iparty
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Sven Pachnit
@@ -91,6 +91,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/benchmark.md
+- docs/cli/README.md
+- docs/cli/action_cookbook/show_my_remote_ips.rb
+- docs/configuration.md
+- docs/exceptions.md
+- docs/maxmind_result.md
+- docs/mmdb_download.md
 - exe/iparty
 - lib/iparty.rb
 - lib/iparty/address.rb