openasn 0.2.0

data/lib/openasn.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# stdlib only (zero-dependency contract). "time" is load-bearing: it
+# provides Time.parse / Time.iso8601 / Time#iso8601 used across the
+# updater, overlay store, and staleness probes — do not assume another
+# library loaded it (bare non-Rails processes won't have it).
+require "time"
+
+require_relative "openasn/version"
+require_relative "openasn/errors"
+require_relative "openasn/ip"
+require_relative "openasn/binary_format"
+require_relative "openasn/special_ranges"
+require_relative "openasn/configuration"
+require_relative "openasn/result"
+require_relative "openasn/overlay_store"
+require_relative "openasn/snapshot"
+require_relative "openasn/classifier"
+require_relative "openasn/dataset"
+require_relative "openasn/http_client"
+require_relative "openasn/cidr_utils"
+require_relative "openasn/parsers"
+require_relative "openasn/tier_b"
+require_relative "openasn/updater"
+require_relative "openasn/middleware"
+require_relative "openasn/railtie" if defined?(Rails::Railtie)
+
+# OpenASN — offline IP origin intelligence.
+#
+#   OpenASN.lookup("203.0.113.42")
+#   # => #<OpenASN::Result 203.0.113.42 verdict=unknown …>
+#
+#   r = OpenASN.lookup(request.remote_ip)
+#   r.verdict          # :residential_isp | :mobile | :business | :hosting |
+#                      # :vpn | :tor_exit | :relay | :enterprise_gateway |
+#                      # :education | :government | :cgnat | :private | :unknown
+#   r.infrastructure?  # verdict in {hosting, vpn, tor_exit} — the honest boolean
+#   r.likely_human?    # verdict in {residential_isp, mobile, relay, cgnat, enterprise_gateway}
+#   r.asn / r.as_org / r.category / r.network_role / r.provider / r.sources
+#
+# Every lookup is local (microseconds, no network). Data ships as a bundled
+# seed and refreshes from OpenASN's nightly releases + Tier B authorities
+# via OpenASN.update! / OpenASN::UpdateJob.
+#
+# REMEMBER WHAT VERDICTS MEAN: a clean/`residential_isp` verdict is absence
+# of evidence, NOT proof of innocence — residential proxies are invisible
+# to any offline dataset. `vpn`/`hosting`/`tor_exit` are high-confidence;
+# treat everything else as a signal, not a sentence. Never hard-block
+# `relay`, `cgnat`, or `mobile`: those are real people.
+module OpenASN
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      # Config affects how snapshots load (data_dir, memory_mode, tier_b…):
+      # drop any snapshot built under the old config. Cheap; lazy reload.
+      @dataset = nil
+    end
+
+    def dataset
+      @dataset ||= Dataset.new(configuration)
+    end
+
+    # Classify an IP (String or IPAddr). Never returns nil; raises
+    # OpenASN::InvalidIPError (an ArgumentError) on unparseable input.
+    def lookup(ip)
+      Classifier.classify(dataset.snapshot, ip)
+    end
+    alias check lookup
+    alias [] lookup
+
+    # Refresh canonical artifacts + Tier B overlays now, atomically
+    # swapping the in-memory dataset on success.
+    # -> :updated | :tier_b_only | :unchanged | :locked
+    def update!(force: false)
+      Updater.new(configuration, dataset).run(force: force)
+    end
+
+    # Load the dataset at boot instead of on first lookup (call from an
+    # initializer in latency-sensitive apps; first lazy load costs ~50-200ms
+    # depending on memory_mode).
+    def eager_load!
+      dataset.eager_load!
+    end
+
+    def dataset_info
+      dataset.info
+    end
+
+    # Cheap "is the on-disk data old?" probe that does NOT load the
+    # dataset. Considers the freshest of data_dir and the bundled seed
+    # (used by the Railtie's boot staleness check).
+    def data_stale_on_disk?(max_age: Dataset::STALE_AFTER)
+      build_ids = [File.join(configuration.data_dir, "manifest.json"),
+                   File.join(Snapshot::SEED_DIR, "manifest.json")].filter_map do |path|
+        next unless File.exist?(path)
+
+        JSON.parse(File.read(path))["build_id"]
+      rescue JSON::ParserError
+        nil
+      end
+      newest = build_ids.filter_map { |id| Time.iso8601(id) rescue nil }.max # rubocop:disable Style/RescueModifier
+      newest.nil? || (Time.now - newest) > max_age
+    end
+
+    # Test/console helper: forget configuration and loaded data.
+    def reset!
+      @configuration = nil
+      @dataset = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: openasn
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- rameerez
+bindir: exe
+cert_chain: []
+date: 2026-07-06 00:00:00.000000000 Z
+dependencies: []
+description: 'OpenASN classifies where an IP address is really coming from — residential
+  ISP, mobile carrier, hosting/datacenter, VPN, Tor exit, iCloud Private Relay, enterprise
+  gateway, business, education, government, CGNAT, or unknown — entirely offline,
+  in microseconds, with zero runtime dependencies and zero API calls. It bundles a
+  seed of the open OpenASN dataset (CC0), refreshes it nightly from GitHub Releases,
+  and layers fast-moving overlays (Tor exits, cloud ranges, Apple Private Relay) fetched
+  by your own server from the original authorities. Verdict-first API with full explainability:
+  every classification is auditable to its source.'
+email:
+- rubygems@rameerez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".simplecov"
+- AGENTS.md
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/openasn/install/install_generator.rb
+- lib/generators/openasn/install/templates/openasn.rb
+- lib/openasn.rb
+- lib/openasn/binary_format.rb
+- lib/openasn/cidr_utils.rb
+- lib/openasn/classifier.rb
+- lib/openasn/configuration.rb
+- lib/openasn/data/seed/fetch-manifest.json
+- lib/openasn/data/seed/manifest.json
+- lib/openasn/data/seed/openasn-ipv4.bin
+- lib/openasn/data/seed/openasn-ipv6.bin
+- lib/openasn/dataset.rb
+- lib/openasn/errors.rb
+- lib/openasn/http_client.rb
+- lib/openasn/ip.rb
+- lib/openasn/middleware.rb
+- lib/openasn/overlay_store.rb
+- lib/openasn/parsers.rb
+- lib/openasn/railtie.rb
+- lib/openasn/result.rb
+- lib/openasn/snapshot.rb
+- lib/openasn/special_ranges.rb
+- lib/openasn/tier_b.rb
+- lib/openasn/update_job.rb
+- lib/openasn/updater.rb
+- lib/openasn/version.rb
+homepage: https://github.com/openasn/openasn-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/openasn/openasn-ruby
+  source_code_uri: https://github.com/openasn/openasn-ruby
+  changelog_uri: https://github.com/openasn/openasn-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'Offline IP origin intelligence: classify IPs as residential, mobile, hosting,
+  VPN, Tor, relay — zero API calls'
+test_files: []